Brain Trust MCP

🚀 Ask MCP - 托管式OpenAI MCP服务器 (v0.3.0)

🧠 将你的集成开发环境（IDE）连接到OpenAI，实现智能问答和结构化计划评审。

这是一个托管式的FastMCP服务器，提供3个简单工具，可直接将你的IDE连接到OpenAI，无需本地安装。

🌐 访问 ask-mcp.com - 在浏览器中立即试用，并获取8种以上IDE的设置指南！

---

🎉 v0.1.2版本新增功能

• ⭐ 深度剖析评审级别 - 用于实施规划的技术故障模式与影响分析（FMEA）式分析
• 📊 主评审框架 - 涵盖所有评审级别的10点结构化评估
• 🔍 全面日志记录 - 完整的请求/响应跟踪，支持根据环境对API密钥进行掩码处理
• ✅ 专业测试套件 - 18个pytest测试用例，代码覆盖率达92%
• 🎨 预提交钩子 - 使用black、isort、flake8、mypy实现自动化代码质量检查
• 🐳 增强的Docker配置 - 通过环境变量传递，简化配置过程
• 📖 完整文档 - 日志记录指南、测试指南、头部配置示例

查看版本说明v0.1.2了解完整详情。

---

🎯 什么是brain-trust？

brain-trust是一个模型上下文协议（MCP）服务器，可让你的AI代理直接访问OpenAI，实现以下功能：

• 提问：可选择提供上下文信息
• 评审规划文档：支持多种分析深度
• 获取专家答案：根据你的具体情况提供定制化解答

你可以将其视为需要帮助时的“求助热线”（向OpenAI求助）！

---

✨ 3个简单工具

1. 📞 phone_a_friend

向OpenAI提出任何问题，可选择提供上下文信息以获得更准确的答案。

# 简单问题
phone_a_friend("What is Docker?")

# 带上下文的问题
phone_a_friend(
    question="Should we use microservices?",
    context="Team of 5 engineers, launching MVP in 3 months"
)

2. 📋 review_plan

使用主评审框架（一种结构化的10点评估系统），获得AI驱动的规划文档反馈。

主评审框架维度：

• 结构与组织
• 完整性
• 清晰度
• 假设与依赖关系
• 风险
• 可行性
• 替代方案
• 验证
• 利益相关者
• 长期可持续性

评审级别（逐步深入）：

• quick - 基本检查清单（1 - 2条建议）
• standard - 标准分析（2 - 3个问题）
• comprehensive - 详细覆盖（3 - 5个问题）
• deep_dive - 新增！ 技术FMEA式分析（4 - 6个问题）
• expert - 专业企业级评审（5 - 7个战略问题）

# 深度技术评审
review_plan(
    plan_content="# Q4 2025 Roadmap\n...",
    review_level="deep_dive",  # 新增技术级别
    context="Startup with $500K budget, need to launch in 6 months",
    focus_areas=["scalability", "risks", "timeline"]
)

# 专家企业级评审
review_plan(
    plan_content="# Migration Plan\n...",
    review_level="expert",
    context="Fortune 500 company, 1M+ users"
)

返回结果：

• 总体得分（0.0 - 1.0）
• 优势（列表）
• 劣势（列表）
• 建议（列表）
• 详细反馈（结构化分析）
• 使用的评审级别
• 时间戳

3. ❤️ health_check

检查服务器状态和配置。

health_check()
# 返回结果: {status, timestamp, plan_reviews_count}

---

🚀 快速开始

前提条件

• Python 3.12及以上版本
• OpenAI API密钥
• Docker（可选，但建议使用）

选项1：Docker（推荐）

# 克隆仓库
git clone <repository-url>
cd mcp-ask-questions

# 启动服务器（无需API密钥）
docker-compose up -d

# 查看日志
docker-compose logs -f

服务器将立即启动，无需OpenAI API密钥。在MCP客户端中配置API密钥（见下文）。

选项2：本地Python

# 安装依赖
pip install -r requirements.txt

# 运行服务器
python server.py

---

🔧 在Cursor中配置

快速安装按钮

点击展开Cursor设置

点击按钮进行安装：

或手动安装：

转到Cursor设置 -> MCP -> 添加新的MCP服务器。将其命名为“brain-trust”，使用HTTP传输协议：

• URL：http://localhost:8000/mcp
• 传输协议：http
• 环境变量：添加OPENAI_API_KEY并填入你的OpenAI API密钥

添加到~/.cursor/mcp.json

{
  "mcpServers": {
    "brain-trust": {
      "url": "http://localhost:8000/mcp",
      "transport": "http",
      "env": {
        "OPENAI_API_KEY": "your_openai_api_key_here"
      }
    }
  }
}

工作原理：

• MCP客户端配置中的OPENAI_API_KEY将作为环境变量传递给服务器
• 服务器从环境变量中读取API密钥，并使用它与OpenAI进行身份验证
• 可选：你可以为每个工具调用覆盖模型和最大令牌数

重要提示：在Cursor中使用之前，请确保Docker正在运行且服务器已启动！

---

💻 使用示例

示例1：快速提问

直接向OpenAI提问：

使用 phone_a_friend 询问："Python的最佳实践有哪些？"

示例2：带上下文的提问

根据你的具体情况获取答案：

使用 phone_a_friend，问题为 "我们应该如何构建测试？"，上下文为 "我们使用FastAPI、pytest、SQLAlchemy和Docker"

示例3：计划评审

获取规划文档的反馈：

使用 review_plan 评审文件 plans/compare-options-tool.md，评审级别为 "standard"

示例4：全面计划分析

进行特定重点的深度分析：

使用 review_plan 对 plans/compare-options-tool.md 进行评审，评审级别为 "expert"，上下文为 "2人工程师团队，需要快速构建"，重点关注领域为 ["时间线", "实施", "风险"]

---

🏗️ 架构

┌─────────────────┐
│  Cursor / AI    │
│     Agent       │
└────────┬────────┘
         │ MCP协议（HTTP）
         │
┌────────▼────────┐
│   brain-trust   │
│   MCP Server    │
│  (FastMCP)      │
└────────┬────────┘
         │ OpenAI API
         │
┌────────▼────────┐
│    OpenAI       │
└─────────────────┘

流程：

1. 代理使用MCP客户端配置中的API密钥调用MCP工具
2. brain-trust服务器通过HTTP接收带有API密钥的请求
3. 服务器使用提供的API密钥创建OpenAI客户端
4. 服务器格式化提示信息并调用OpenAI API
5. OpenAI返回AI生成的响应
6. 服务器将结构化响应返回给代理

---

🐳 Docker设置

服务器在Docker中运行，包含以下组件：

• FastMCP服务器：Python 3.12，运行在端口8000
• Nginx：用于HTTP请求的反向代理
• 健康检查：每30秒进行一次
• 非root用户：遵循安全最佳实践

# 启动服务
docker-compose up -d

# 查看日志
docker-compose logs -f

# 检查状态
curl http://localhost:8000/health

# 停止服务
docker-compose down

---

🛠️ 配置

环境变量

服务器支持基于环境变量的配置。创建一个.env文件：

# 服务器配置
ENVIRONMENT=development           # 开发或生产环境
LOG_LEVEL=DEBUG                  # 日志级别：DEBUG、INFO、WARNING、ERROR、CRITICAL
PORT=8000                        # 默认端口：8000

# 可选：仅用于开发/测试
OPENAI_API_KEY=sk-...           # 仅本地测试需要

日志记录模式： 开发环境（DEBUG）：

• 日志中显示完整的API密钥（用于调试）
• 记录所有请求/响应详细信息
• 记录完整的头部信息

生产环境（INFO）：

• 对API密钥进行掩码处理（仅显示前8位和后4位）
• 仅记录必要信息
• 减少敏感数据的日志记录

查看docs/LOGGING.md获取完整的日志记录文档。

注意：生产环境中，OpenAI API密钥无需作为环境变量设置。API密钥将在每次工具调用时直接从MCP客户端传递。

MCP客户端配置（必需）

在MCP客户端设置中配置你的OpenAI API密钥（例如，Cursor的~/.cursor/mcp.json）：

{
  "mcpServers": {
    "brain-trust": {
      "url": "http://localhost:8000/mcp",
      "transport": "http",
      "env": {
        "OPENAI_API_KEY": "your_actual_api_key_here"
      }
    }
  }
}

工作原理：

1. 你在MCP客户端中配置API密钥
2. MCP客户端自动将密钥传递给工具调用
3. 服务器使用该密钥在每个请求中与OpenAI进行身份验证
4. 服务器端不存储API密钥

优点：

• ✅ Docker容器或环境文件中不包含API密钥
• ✅ 通过MCP客户端实现安全的密钥管理
• ✅ 不同客户端可以使用不同的API密钥
• ✅ 每个请求进行身份验证

---

📊 API端点

本地运行时：

• MCP端点：http://localhost:8000/mcp
• 健康检查：http://localhost:8000/health

测试健康端点：

curl http://localhost:8000/health
# 返回结果: {"status":"healthy","timestamp":"...","plan_reviews_count":0}

---

🧪 测试

快速测试

测试服务器是否正常工作：

# 检查健康状态
curl http://localhost:8000/health

# 在Cursor中尝试：
# "使用 phone_a_friend 询问：什么是FastMCP？"

测试套件

运行全面的pytest测试套件：

# 运行所有测试（18个测试用例，约95秒）
pytest tests/

# 运行并生成覆盖率报告（92%覆盖率）
pytest --cov=server --cov-report=term-missing tests/

# 仅运行单元测试（快速，无需API调用）
pytest tests/test_logging.py

# 仅运行集成测试（实际调用OpenAI API）
pytest tests/test_tools.py

# 运行特定测试
pytest tests/test_tools.py::TestPhoneAFriend::test_phone_a_friend_basic -v

测试覆盖率：

• ✅ 共18个测试用例
• ✅ 8个单元测试（日志记录、实用工具）
• ✅ 10个集成测试（实际调用OpenAI API）
• ✅ 代码覆盖率达92%
• ✅ 所有MCP工具均经过测试
• ✅ 所有5个评审级别均经过测试

要求：

• 集成测试需要在.env文件中设置OPENAI_API_KEY
• 单元测试无需API密钥
• 如果API密钥不可用，测试将自动跳过

查看tests/README.md获取完整的测试文档。

---

📁 项目结构

mcp-ask-questions/
├── server.py                    # 包含3个工具的主MCP服务器
├── Dockerfile                   # 容器定义文件
├── docker-compose.yml           # 多容器编排文件
├── nginx.conf                   # 反向代理配置文件
├── requirements.txt             # Python依赖文件
├── pyproject.toml              # 项目配置文件（black、isort、mypy）
├── fastmcp.json                # FastMCP部署配置文件
├── .env.example                # 环境变量模板
├── README.md                   # 本文件
├── docs/                       # 文档目录
│   ├── LOGGING.md             # 全面的日志记录指南
│   ├── HEADER_IMPLEMENTATION.md  # 基于头部的配置指南
│   └── MCP_CLIENT_HEADERS.md  # 客户端配置指南
├── tests/                      # pytest测试套件（92%覆盖率）
│   ├── conftest.py            # 共享测试夹具
│   ├── test_tools.py          # 工具测试（10个测试用例）
│   ├── test_logging.py        # 日志记录测试（8个测试用例）
│   └── README.md              # 测试文档
├── release_notes/             # 版本说明目录
│   ├── RELEASE_NOTES_v0.1.2.md
│   └── RELEASE_NOTES_v0.1.1.md
├── examples/                   # 示例实现目录
│   └── server_with_headers.py # 基于头部配置的示例
└── plans/                      # 规划文档目录
    ├── contextual-qa-mcp-server.md
    ├── technical-implementation.md
    ├── quick-start-guide.md
    └── compare-options-tool.md

---

🔒 安全

• ✅ Docker中不包含API密钥 - API密钥在每个请求中从MCP客户端传递
• ✅ 环境文件中无密钥 - 无需包含API密钥的.env文件
• ✅ 每个请求进行身份验证 - 每个请求使用客户端提供的凭证
• ✅ Docker使用非root用户 - 容器中以mcpuser用户运行
• ✅ 输入验证 - 使用Pydantic模型验证所有输入
• ✅ 错误处理 - 全面的错误处理和日志记录
• ✅ 客户端侧密钥管理 - 由MCP客户端安全管理密钥

---

🐛 故障排除

服务器无法启动

# 检查端口8000是否被占用
lsof -i:8000

# 查看Docker日志
docker-compose logs -f

Cursor无法连接

1. 验证服务器是否正在运行：curl http://localhost:8000/health
2. 检查~/.cursor/mcp.json中的MCP配置
3. 配置更改后重启Cursor
4. 确保MCP客户端配置中设置了OPENAI_API_KEY

OpenAI API错误

1. 验证~/.cursor/mcp.json中的API密钥是否正确且有效
2. 检查OpenAI账户是否有可用信用额度
3. 确保API密钥具有适当的权限
4. 查看日志：docker-compose logs -f

“需要API密钥”错误

API密钥必须在MCP客户端中配置（而非Docker中）：

1. 打开~/.cursor/mcp.json
2. 在env部分添加OPENAI_API_KEY
3. 重启Cursor
4. API密钥将在每次工具调用时自动传递

工具未在Cursor中显示

1. 重启Docker：docker-compose restart
2. 完全重启Cursor
3. 检查MCP设置是否正确

---

🚦 开发

本地开发

# 创建/激活虚拟环境
python3 -m venv venv
source venv/bin/activate  # 在VS Code/Cursor工作区自动激活

# 安装依赖
pip install -r requirements.txt

# 本地运行服务器
python server.py

# 服务器运行在 http://localhost:8000

注意：服务器启动时无需OpenAI API密钥。API密钥将在调用工具时由MCP客户端提供。

代码质量

预提交钩子： 每次提交代码时自动运行代码质量检查：

# 预提交自动运行：
→ black      # 代码格式化
→ isort      # 导入排序
→ flake8     # 代码检查
→ mypy       # 类型检查

如果任何检查失败，提交将被阻止。钩子会自动在.git/hooks/pre-commit中设置。

手动质量检查：

# 格式化代码
black server.py

# 排序导入
isort server.py

# 代码检查
flake8 server.py

# 类型检查
mypy server.py

# 运行所有检查
black server.py && isort server.py && flake8 server.py && mypy server.py

进行更改

1. 创建功能分支
2. 在server.py中进行更改
3. 运行测试：pytest tests/
4. 提交代码时，预提交钩子将自动运行
5. 重建Docker：docker-compose up -d --build
6. 重启Cursor以应用更改

添加新工具

1. 在plans/your-tool-name.md中创建规划文档
2. 在server.py中使用@mcp.tool()装饰器实现工具
3. 在tests/test_tools.py中添加测试用例
4. 更新文档
5. 提交拉取请求

查看plans/compare-options-tool.md获取示例规划文档。

---

📚 文档

核心文档

• README.md（本文件） - 概述和快速开始指南
• docs/LOGGING.md - 全面的日志记录系统指南
• docs/HEADER_IMPLEMENTATION.md - 基于头部的配置指南
• docs/MCP_CLIENT_HEADERS.md - 客户端配置选项
• tests/README.md - 测试文档和示例

版本说明

• release_notes/RELEASE_NOTES_v0.1.2.md - 最新版本（当前）
• release_notes/RELEASE_NOTES_v0.1.1.md - 上一版本

示例

• examples/server_with_headers.py - HTTP头部配置示例

规划文档

• plans/ - 详细的规划文档和提案
  • contextual-qa-mcp-server.md
  • technical-implementation.md
  • quick-start-guide.md
  • compare-options-tool.md

---

⭐ 特性

主评审框架

• 10点结构化评估：用于全面的计划分析
• 5个逐步深入的评审级别：从快速评审到专家评审
• 深度剖析模式下的FMEA式故障分析
• 企业级评审：包含责任分配矩阵（RACI）、总体拥有成本（TCO）、服务级别目标（SLO）

全面日志记录

• 完整的请求/响应跟踪：用于调试
• 基于环境的掩码处理（开发环境与生产环境）
• 每个请求记录5个以上日志事件：以结构化JSON格式输出
• 每一步都进行API密钥验证

专业测试

• 92%的代码覆盖率：通过18个pytest测试用例实现
• 10个集成测试：实际调用OpenAI API
• API密钥不可用时自动跳过测试
• 类型安全：完全符合mypy规范

开发工具

• 预提交钩子：自动强制代码质量检查
• 在VS Code/Cursor工作区自动激活虚拟环境
• Docker支持：便于部署
• 支持HTTP头部配置（可选）

---

🎯 为什么选择brain-trust？

简单

• 只需学习3个工具
• 直接、简单的使用方式
• 无需复杂的上下文管理
• 清晰、全面的文档

强大

• 可使用你喜欢的GPT模型
• 支持上下文感知的答案
• 5个逐步深入的评审级别
• 主评审框架提供10点分析

实用

• 解决实际问题（提问、计划评审）
• 易于与Cursor集成
• 通过Docker实现生产就绪
• 92%的测试覆盖率确保可靠性

可扩展

• 易于添加新工具
• 代码库简洁、易于维护
• 文档完善，便于贡献
• 拥有专业的测试基础设施

---

🤝 贡献

我们欢迎贡献！以下是贡献的方式：

添加新工具

1. 规划：在plans/your-tool-name.md中创建规划文档
2. 实现：在server.py中使用@mcp.tool()装饰器添加工具
3. 测试：在tests/test_tools.py中添加测试用例
4. 文档：更新README并根据需要添加到docs/中
5. 质量：提交代码时，预提交钩子将自动运行
6. 提交：创建拉取请求

查看plans/compare-options-tool.md获取示例规划文档。

代码标准

• Python 3.12及以上版本：使用类型提示
• Black格式化：行长度为88
• isort进行导入排序
• flake8进行代码检查
• mypy进行类型检查
• pytest进行测试：目标覆盖率超过80%
• 使用常规提交规范：编写提交信息

运行测试

# 运行所有测试
pytest tests/

# 运行并生成覆盖率报告
pytest --cov=server tests/

# 预提交钩子将自动运行
git commit -m "feat: add new tool"

文档标准

• 为所有公共函数添加文档字符串
• 面向用户的更改更新README.md
• 为新功能添加示例
• 保持docs/目录最新
• 遵循现有文档风格

---

📄 许可证

本项目采用MIT许可证 - 详情请查看LICENSE文件。

---

🙏 致谢

• 基于FastMCP构建 - 快速、Pythonic的MCP框架
• 受模型上下文协议规范启发
• 使用你喜欢的任何OpenAI模型提供智能响应
• 测试由pytest和pytest-asyncio提供支持
• 日志记录使用structlog
• 代码质量由black、isort、flake8和mypy保证

感谢所有为评审框架和日志记录系统提供反馈的贡献者！

---

📊 项目统计

• 工具数量：3个（phone_a_friend、review_plan、health_check）
• 评审级别：5个（quick、standard、comprehensive、deep_dive、expert）

---

🔗 链接

• 仓库：https://github.com/bernierllc/brain-trust-mcp
• 问题跟踪：https://github.com/bernierllc/brain-trust-mcp/issues
• FastMCP文档：https://gofastmcp.com
• MCP规范：https://modelcontextprotocol.io/

---

有问题？遇到问题？有反馈？ 创建一个问题或联系我们！我们随时提供帮助。🧠✨