SCOUT - 战略首席技术官运营与统一工具平台

个人MCP服务器，通过协调AI团队提升CTO（首席技术官）的生产力。

SCOUT协调专门的人工智能代理（Gemini、OpenAI、Claude、OpenRouter、Grok）来完成复杂的架构设计、分析和战略任务，遵循模型上下文协议（MCP）。

______________________________________________________________________

📋 功能

多供应商AI编排无缝使用5家AI提供商，统一界面
基于团队的执行配置主节点+验证器模型以达成共识
MCP协议原生（或：MCP协议本地）与Claude桌面版和网页版完全兼容
合同优先开发JSON模式定义了严格的工具契约
80%以上的测试覆盖率强制检测确保可靠性
结构化日志记录完整可追溯性，支持请求关联
成本追踪实时监控API使用情况和成本
智能缓存基于Redis的缓存减少了冗余的API调用

______________________________________________________________________

🚀 快速入门

先决条件

Python 3.11及以上版本
Redis（发音类似“雷迪斯”，但通常直接音译为“瑞迪斯”或保持原英文名） （本地或云端）
API密钥 对于至少一家人工智能提供商（Gemini、OpenAI、Anthropic、OpenRouter 或 Grok）

1. 克隆并设置

# Clone repository
git clone 
cd SCOUT

# Create virtual environment
python -m venv .venv

# Activate virtual environment
# Windows
.venv\Scripts\activate
# macOS/Linux
source .venv/bin/activate

# Install dependencies
pip install -e .

# Install development dependencies
pip install -e ".[dev]"

2. 配置环境

# Copy environment template
cp .env.example .env

# Edit .env and add your API keys
# Required: At least one AI provider API key
# Required: REDIS_URL (default: redis://localhost:6379)

所需的最少变量：

# Choose at least one provider
GEMINI_API_KEY=AIza...          # OR
OPENAI_API_KEY=sk-proj-...      # OR
ANTHROPIC_API_KEY=sk-ant-...    # OR
OPENROUTER_API_KEY=sk-or-v1-... # OR
GROK_API_KEY=xai-...

# Infrastructure
REDIS_URL=redis://localhost:6379

3. 设置 Redis

选项A：Docker（推荐）

# Run Redis container
docker run -d \
  --name scout-redis \
  -p 6379:6379 \
  redis:7-alpine

# Verify connection
docker exec scout-redis redis-cli ping
# Expected output: PONG

选项B：本地安装

Windows：

# Install via Chocolatey
choco install redis-64

# Start Redis
redis-server

macOS:

# Install via Homebrew
brew install redis

# Start Redis service
brew services start redis

Linux（Ubuntu/Debian）：

# Install Redis
sudo apt update
sudo apt install redis-server

# Start Redis service
sudo systemctl start redis
sudo systemctl enable redis

选项C：云Redis（Upstash）

在（某网站/平台）创建免费账户 Upstash（注：这是一个专有名词，可能指某个特定的公司、服务或产品名称，在中文中没有直接对应的翻译，因此保持原样。）
创建Redis数据库
复制连接URL到 .env：

   REDIS_URL=redis://default:
@:

4. 测试安装

# Run tests
pytest

# Check coverage
pytest --cov=src/scout --cov-report=html

# Start MCP server (when implemented)
python -m scout

______________________________________________________________________

📁 项目结构

SCOUT/
├── .specify/                   # SpecKit framework
│   ├── memory/
│   │   └── constitution.md     # Project governance (7 principles)
│   └── templates/              # Feature spec/plan/tasks templates
├── src/scout/
│   ├── tools/                  # MCP-exposed tools (chat, planner, analyse, etc.)
│   ├── providers/              # AI provider abstractions
│   │   ├── base.py             # BaseAIProvider interface
│   │   ├── gemini.py           # Google Gemini
│   │   ├── openai.py           # OpenAI (GPT-4o, o3-mini)
│   │   ├── anthropic.py        # Anthropic Claude
│   │   ├── openrouter.py       # OpenRouter aggregator
│   │   ├── grok.py             # X.AI Grok
│   │   └── factory.py          # Provider factory
│   ├── core/
│   │   ├── orchestrator.py     # Tool routing and execution
│   │   ├── team_selector.py    # AI team selection logic
│   │   └── state_manager.py    # Redis state management
│   ├── config/
│   │   ├── loader.py           # YAML configuration loader
│   │   └── models.py           # Pydantic configuration schemas
│   └── utils/
│       ├── cache.py            # Redis caching
│       ├── rate_limiter.py     # Request rate limiting
│       ├── retry.py            # Retry logic with backoff
│       └── logger.py           # Structured logging setup
├── config/
│   └── scout.yaml              # Main configuration (providers, teams, mappings)
├── tests/
│   ├── unit/                   # Unit tests (mocked dependencies)
│   └── integration/            # Integration tests (mocked providers)
├── docs/
│   ├── api/                    # Auto-generated API docs
│   ├── architecture.md         # System architecture
│   └── quickstart.md           # This file
├── pyproject.toml              # Python project metadata & dependencies
├── .env.example                # Environment variables template
└── README.md                   # This file

______________________________________________________________________

🏗️ 建筑学

SCOUT遵循一个 契约优先， 模块化架构 如……中所定义宪法。

┌─────────────────────────────────────────────────────────────┐
│                  Claude Desktop/Web (MCP Client)             │
└─────────────────────┬───────────────────────────────────────┘
                      │ MCP Protocol (STDIO/HTTP+SSE)
┌─────────────────────▼───────────────────────────────────────┐
│                  SCOUT MCP Server                            │
│  ┌────────────────────────────────────────────────────────┐ │
│  │         Tool Router & Orchestrator                      │ │
│  │         (FastMCP + Tool Registry)                       │ │
│  └───┬──────────────────────────────────────────────┬─────┘ │
│      │                                               │       │
│  ┌───▼────────┐  ┌──────────────┐  ┌───────────────▼────┐ │
│  │   Tools    │  │   AI Team    │  │   State Manager    │ │
│  │  Registry  │  │   Selector   │  │   (Redis)          │ │
│  └───┬────────┘  └──────┬───────┘  └───────────────┬────┘ │
│      │                  │                           │       │
│  ┌───▼──────────────────▼───────────────────────────▼────┐ │
│  │            Provider Abstraction Layer                  │ │
│  │   (Unified Interface: Gemini, OpenAI, Claude, etc.)   │ │
│  └───┬──────┬──────┬─────────┬──────────┬───────────────┘ │
└──────┼──────┼──────┼─────────┼──────────┼─────────────────┘
       │      │      │         │          │
   ┌───▼──┐ ┌▼───┐ ┌▼──────┐ ┌▼────────┐ ┌▼────┐
   │Gemini│ │OAI │ │Claude │ │OpenRoute│ │Grok │
   └──────┘ └────┘ └───────┘ └─────────┘ └─────┘

核心原则（摘自宪法）

合同优先开发 - 每个工具均通过MCP架构定义
模块化架构 - 严格的职责分离
强制性检测 - 覆盖率≥80%（不可商量）
自动生成的文档 - 来自模式的文档
强大的错误处理 - 结构化异常处理 + 恢复
结构化日志记录 - 请求关联性 + 可观测性
提供者抽象 - 统一的多模型接口

______________________________________________________________________

🛠️ 配置

SCOUT 使用一种类型安全的YAML配置系统，支持环境变量替换和自动验证。

快速配置

创建 config/scout.yaml 来自示例：

cp config/scout.yaml.example config/scout.yaml

最小配置（单一提供商）：

providers:
  gemini:
    api_key: ${GEMINI_API_KEY}
    models:
      flash:
        id: "gemini-2.0-flash-exp"
        max_tokens: 8192
        temperature: 0.7

teams:
  general:
    description: "General purpose team"
    primary:
      provider: "gemini"
      model: "flash"

tool_team_mapping:
  default: "general"

system:
  default_team: "general"
  request_timeout_seconds: 90
  max_retries: 3
  cache_ttl_seconds: 7200

integrations:
  notion_api_key: null
  tavily_api_key: null

多供应商验证：

providers:
  gemini:
    api_key: ${GEMINI_API_KEY}
    models:
      flash: { id: "gemini-2.0-flash-exp", max_tokens: 8192 }

  openai:
    api_key: ${OPENAI_API_KEY}
    models:
      gpt4o: { id: "gpt-4o", max_tokens: 16384 }

teams:
  architect:
    description: "Architecture team with validation"
    primary:
      provider: "gemini"
      model: "flash"
    validators:
      - provider: "openai"
        model: "gpt4o"
        trigger: "always"  # Validate all responses

tool_team_mapping:
  system_design: "architect"

环境变量替换

必需的： ${VAR} - 必须设置变量
可选： ${VAR:-default} - 未设置时使用默认值

system:
  request_timeout_seconds: ${REQUEST_TIMEOUT:-90}  # Default: 90
  cache_ttl_seconds: ${CACHE_TTL:-7200}            # Default: 7200

配置特性

✅ 类型安全 - Pydantic 验证在启动时捕获错误 ✅（勾选标记，表示正确、确认或完成） 不可变的 - 冻结模型防止运行时修改 ✅ 安全日志/错误中自动对API密钥进行遮蔽处理 ✅ 快 - 加载时间约5毫秒（在50个提供商、100个团队中测试） ✅ 交叉引用验证 - Teams引用现有的提供者/模型 ✅ 环境感知的 - 不同环境下的不同配置

文档

📖 快速入门: specs/001-config-system/quickstart.md
📋 数据模型: specs/001-config-system/data-model.md
📝 示例： config/scout.yaml.example - 5家供应商，3个团队
🔧 JSON Schema（JSON架构）: specs/001-config-system/contracts/config-schema.json

添加新的提供商（\


创建包含以下内容的详细规格说明：

- 用户场景（按优先级排序）
- 需求（功能需求+非功能需求）
- MCP合同（JSON模式）
- 验收标准

### 2. 消除歧义

/speckit.clarify


识别出未明确说明的领域，并提出有针对性的问题。

### 3. 制定实施计划

/speckit.plan


制定分阶段实施计划，包括：

- 技术设计
- 依赖分析
- 风险缓解
- 测试策略

### 4. 生成任务

/speckit.tasks


生成按用户故事组织的、具有依赖关系的检查清单。

### 5. 实施

/speckit.implement


遵循测试驱动开发（Test-Driven Development，TDD）原则执行实施。

### 6. 分析一致性

/speckit.analyze


对规范、计划、任务和代码进行交叉验证，确保一致性。

______________________________________________________________________

## ✅ 测试

### 运行所有测试

Run full test suite

pytest

Run with coverage report

pytest --cov=src/scout --cov-report=term-missing

Run only unit tests

pytest tests/unit -m unit

Run only integration tests

pytest tests/integration -m integration

Run performance benchmarks

pytest -m benchmark


### 编写测试（必做）

每个工具都必须具备：

tests/unit/test_chat.py

import pytest from scout.tools.chat import chat_handler

@pytest.mark.asyncio async def test_chat_valid_input(mock_dependencies): """Test nominal case with valid input.""" result = await chat_handler( message="Hello", **mock_dependencies ) assert "response" in result assert result["metadata"]["cost_usd"] > 0

@pytest.mark.asyncio async def test_chat_invalid_input(): """Test schema validation with invalid input.""" with pytest.raises(ValidationError): await chat_handler(message="") # Empty message

@pytest.mark.asyncio async def test_chat_provider_failure(mock_failing_provider): """Test error handling when provider fails.""" with pytest.raises(ProviderError): await chat_handler( message="Test", provider_factory=mock_failing_provider )


______________________________________________________________________

## 📊 监控与可观测性

### 结构化日志记录

所有日志均使用带有请求关联性的JSON格式：

{ "event": "tool_execution_started", "request_id": "uuid-1234-5678", "tool_name": "analyse", "team": "architect", "timestamp": "2025-10-18T10:30:00Z" }


### 指标（OpenTelemetry）

- `scout.tool.duration_ms` - P50/P95/P99 延迟
- `scout.tool.errors` - 按类型统计的错误数量
- `scout.tool.cost_usd` - 每次工具执行的成本
- `scout.provider.requests` - 每个提供商的请求数量

### 成本追踪

实时追踪成本：

Automatic tracking per tool execution

logger.info( "tool_execution_completed", cost_usd=0.023, tokens={"input": 1200, "output": 800} )


当预算达到每天50美元的阈值时，将触发预算提醒（可配置）。

______________________________________________________________________

## 🔒 安全

### 密钥管理（或“机密管理”）

- **永远不要** 提交（或“确定”、“执行”） `.env` （在 `.gitignore`）
- **永远** 使用环境变量来存储API密钥
- **旋转** API密钥，每90天一次
- **使用** 用于检测秘密的pre-commit钩子：

Install pre-commit hook

pip install pre-commit pre-commit install

Manually scan for secrets

detect-secrets scan


### 输入验证

所有输入均通过 Pydantic 进行验证：

class AnalyseInput(BaseModel): target: constr(max_length=100000) analysis_type: Literal["code_quality", "architecture", "performance"]

@validator('target') def sanitize_target(cls, v): return v.strip()


### 速率限制

自动速率限制防止滥用：

- 每个用户每小时100次请求
- 全球每日1000次请求
- 特定提供者限制（Gemini：每分钟60次请求等）

______________________________________________________________________

## 📚 文档

- **宪法**： [指定/memory/constitution.md（文件路径或指令，根据上下文可理解为“在内存/配置文件中指定constitution.md文件”或类似意思）](.specify/memory/constitution.md)
- **PRD 可以翻译为“民主革命党”（注：这里的翻译是基于政治术语的常见翻译，但具体翻译可能因上下文和语境的不同而有所变化）。然而，在更广泛的语境中，PRD 也可能是一个缩写或代号，代表不同的组织或概念，因此需要根据具体情况进行判断。在没有具体上下文的情况下，最通用的翻译是“民主革命党”**: [PRD.md 翻译为中文是：“产品需求文档（.md 格式）”。其中，“PRD”代表“Product Requirements Document”，即“产品需求文档”，而“.md”是Markdown文件格式的后缀](PRD.md)
- **建筑**: `docs/architecture.md` （即将推出）
- **API 参考文档**： `docs/api/` （自动生成）

______________________________________________________________________

## 🤝 贡献

SCOUT遵循严格的治理原则，通过 [宪法](.specify/memory/constitution.md).

### 拉取请求检查清单

- \[ \] 所有测试通过（`pytest`）
- \[ \] 覆盖率 ≥ 80%（`pytest --cov`)
- \[ \] 没有秘密泄露（`detect-secrets scan`)
- \[ \] 代码已格式化 (`black src/ tests/`）
- \[ \] 代码清理（Linting clean）`ruff check src/ tests/`)
- \[ \] 类型检查通过 (`mypy src/`)
- \[ \] 文档已更新
- \[ \] MCP模式已验证（无破坏性变更）
- \[ \] 公报中提及的宪法原则

### 在提交之前

Format code

black src/ tests/

Lint

ruff check --fix src/ tests/

Type check

mypy src/

Test

pytest --cov=src/scout --cov-fail-under=80

Security scan

bandit -r src/ detect-secrets scan


______________________________________________________________________

## 📈 路线图

### 第一阶段：基础设施核心（第1-2周）

- \[x\] 项目结构
- \[x\] 宪法
- \[x\] **配置系统** ✅（116个测试，覆盖率94.86%）
- \[ \] 提供者抽象层
- \[ \] 球队选择器
- \[ \] 工具注册表

### 第二阶段：首个工具“聊天”（第3-4周）

- \[ \] 聊天工具实现
- \[ \] 状态管理器（Redis）
- \[ \] MCP服务器入口点
- \[ \] 与Claude桌面版的集成

### 第三阶段：必备工具（第5-6周）

- \[ \] apilookup（API查询）
- \[ \] 计划者/规划者
- \[ \] 分析
- \[ \] 深思熟虑

### 第四阶段：高级工具（第7-8周）

- \[ \] 共识
- \[ \] 挑战
- \[ \] secaudit（注：此词可能为特定领域或上下文中的术语，直接翻译为“安全审计”可能不够准确，需根据具体语境调整）
- \[ \] 重构

______________________________________________________________________

## 🆘 故障排除

### Redis 连接失败

**错误**： `redis.exceptions.ConnectionError`

**解决方案**：

Check Redis is running

docker ps | grep redis

Test connection

redis-cli ping

Verify REDIS_URL in .env

echo $REDIS_URL


### 导入错误

**错误**: `ModuleNotFoundError: No module named 'scout'`

**解决方案**:

Install in editable mode

pip install -e .


### API密钥错误

**错误**： `ConfigurationError: Missing API key`

**解决方案**：

Verify .env exists and has keys

cat .env | grep API_KEY

Load environment variables

source .env # macOS/Linux

or reload terminal on Windows


______________________________________________________________________

## 📝 许可证

MIT 许可证 - 版权所有 (c) 2025 Christian Boulet，Boulet Stratégies TI

______________________________________________________________________

## 📧 联系方式

**克里斯蒂安·布勒**

- 电子邮箱：christian@bouletstrategies.com
- 公司：布勒信息技术战略公司

______________________________________________________________________

**版本**0.1.0
**最后更新时间**2025年10月18日

Scout MCP Server

快速接入

详细介绍

SCOUT - 战略首席技术官运营与统一工具平台

📋 功能

🚀 快速入门

先决条件

1. 克隆并设置

2. 配置环境

3. 设置 Redis

4. 测试安装

📁 项目结构

🏗️ 建筑学

核心原则（摘自宪法）

🛠️ 配置

快速配置

环境变量替换

配置特性

文档

添加新的提供商（\

Run full test suite

Run with coverage report

Run only unit tests

Run only integration tests

Run performance benchmarks

tests/unit/test_chat.py

Automatic tracking per tool execution

Install pre-commit hook

Manually scan for secrets

Format code

Lint

Type check

Test

Security scan

Check Redis is running

Test connection

Verify REDIS_URL in .env

Install in editable mode

Verify .env exists and has keys

Load environment variables

or reload terminal on Windows

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP