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/

---

有問題？遇到問題？有反饋？ 創建一個問題或聯繫我們！我們隨時提供幫助。🧠✨