Brain Trust MCP

🚀 Ask MCP - ホスト型OpenAI MCPサーバー (v0.3.0)

🧠 IDEをOpenAIに接続して、インテリジェントな質問応答と構造化された計画レビューを行いましょう。

このホスト型FastMCPサーバーには、IDEを直接OpenAIに接続する3つのシンプルなツールが備わっています。ローカルインストールは不要です。

🌐 ask-mcp.comを訪問 - 8種類以上のIDEのセットアップガイド付きで、ブラウザですぐに試せます！

---

🎉 v0.1.2の新機能

• ⭐ DEEP_DIVEレビューレベル - 実装計画のための技術的なFMEAスタイルの分析
• 📊 マスターレビューフレームワーク - すべてのレビューレベルにわたる10項目の構造化された評価
• 🔍 包括的なロギング - 環境に応じたAPIキーマスキングを伴う完全なリクエスト/レスポンストレーシング
• ✅ プロフェッショナルなテストスイート - 92%のコードカバレッジを持つ18のpytestテスト
• 🎨 プリコミットフック - black、isort、flake8、mypyによる自動コード品質管理
• 🐳 強化されたDocker設定 - 環境変数のパススルーによる簡単な設定
• 📖 完全なドキュメント - ロギングガイド、テストガイド、ヘッダー構成例

詳細はリリースノートv0.1.2を参照してください。

---

🎯 brain-trustとは？

brain-trustは、AIエージェントがOpenAIに直接アクセスできるようにするModel Context Protocol (MCP)サーバーです。

• オプションのコンテキスト付きで質問をする
• 複数の分析深度で計画文書をレビューする
• あなたの特定の状況に合わせた専門家の回答を得る

困ったときに友人（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

マスターレビューフレームワークを使用して、計画文書に対するAIによるフィードバックを得ることができます。これは、構造化された10項目の評価システムです。

マスターレビューフレームワークの次元:

• 構造と組織
• 完全性
• 明瞭性
• 仮定と依存関係
• リスク
• 実現可能性
• 代替案
• 検証
• 利害関係者
• 長期的な持続可能性

レビューレベル (段階的な深度):

• 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キーを必要とせずにすぐに起動します。APIキーはMCPクライアントで構成してください (以下を参照)。

オプション2: ローカルPython

# 依存関係をインストールする
pip install -r requirements.txt

# サーバーを実行する
python server.py

---

🔧 Cursorでの構成

クイックインストールボタン

Cursorのセットアップを展開するにはクリック

ボタンをクリックしてインストールする:

または手動でインストールする:

Cursor Settings -> MCP -> Add new MCP Serverに移動します。名前を"brain-trust"に設定し、HTTPトランスポートを使用します。

• URL: http://localhost:8000/mcp
• Transport: http
• Environment Variables: 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との認証に使用します。
• オプションで、ツール呼び出しごとにモデルとmax_tokensを上書きすることができます。

重要: Cursorで使用する前に、Dockerが実行中でサーバーが起動していることを確認してください！

---

💡 使用例

例1: 簡単な質問

OpenAIに直接質問する:

Use phone_a_friend to ask: "What are Python best practices?"

例2: コンテキストを考慮した質問

あなたの状況に特化した回答を得る:

Use phone_a_friend with the question "How should we structure our tests?"
and context "We use FastAPI with pytest, SQLAlchemy, and Docker"

例3: 計画レビュー

計画文書に対するフィードバックを得る:

Use review_plan to review the file plans/compare-options-tool.md
with review_level "standard"

例4: 包括的な計画分析

特定の焦点を持った深い分析を得る:

Use review_plan on plans/compare-options-tool.md with review_level "expert",
context "Team of 2 engineers, need to build quickly",
and focus_areas ["timeline", "implementation", "risks"]

---

🏗️ アーキテクチャ

┌─────────────────┐
│  Cursor / AI    │
│     Agent       │
└────────┬────────┘
         │ MCP Protocol (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秒ごと
• 非ルートユーザー: セキュリティのベストプラクティス

# サービスを起動する
docker-compose up -d

# ログを表示する
docker-compose logs -f

# 状態を確認する
curl http://localhost:8000/health

# サービスを停止する
docker-compose down

---

🛠️ 構成

環境変数

サーバーは環境ベースの構成をサポートしています。.envファイルを作成します。

# サーバー構成
ENVIRONMENT=development           # developmentまたはproduction
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クライアントの設定 (例: Cursorの~/.cursor/mcp.json) でOpenAI APIキーを構成します。

{
  "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で試す:
# "Use phone_a_friend to ask: What is 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ユーザー - コンテナ内で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 key required"エラー

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. @mcp.tool()デコレータを使用してserver.pyにツールを実装する
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を含むエンタープライズグレードのレビュー

包括的なロギング

• デバッグのための完全なリクエスト/レスポンストレーシング
• 環境に応じたマスキング (デバッグ対本番)
• 構造化されたJSON出力を持つリクエストごとに5つ以上のログイベント
• すべてのステップでのAPIキー検証

プロフェッショナルなテスト

• 18のpytestテストによる92%のコードカバレッジ
• 実際のOpenAI API呼び出しを伴う10の統合テスト
• APIキーが利用できない場合の自動スキップ
• 完全なmypy準拠による型安全

開発ツール

• 自動的にコード品質を強制するプリコミットフック
• VS Code/Cursorワークスペースでの仮想環境の自動アクティブ化
• 簡単なデプロイのためのDockerサポート
• オプションのHTTPヘッダー構成サポート

---

🎯 なぜbrain-trustを選ぶべきか？

シンプル

• 学ぶ必要のあるツールは3つだけ
• 直接的で簡単な使用方法
• 複雑なコンテキスト管理が不要
• 明確で包括的なドキュメント

強力

• 好きなGPTモデルを使用できる
• コンテキストを考慮した回答
• 5段階のレビューレベル
• 10項目の分析を持つマスターレビューフレームワーク

実用的

• 実際の問題を解決する (質問、計画レビュー)
• Cursorと簡単に統合できる
• Dockerで本番環境に対応
• 92%のテストカバレッジで信頼性が保証される

拡張可能

• 新しいツールを簡単に追加できる
• クリーンで保守しやすいコードベース
• 貢献のために十分にドキュメント化されている
• プロフェッショナルなテストインフラストラクチャ

---

🤝 コントリビューション

コントリビューションを歓迎します！以下はコントリビュートする方法です。

新しいツールを追加する

1. 計画: plans/your-tool-name.mdに計画を作成する
2. 実装: @mcp.tool()デコレータを使用してserver.pyにツールを追加する
3. テスト: tests/test_tools.pyにテストを追加する
4. ドキュメント: READMEを更新し、必要に応じてdocs/に追加する
5. 品質: コミット時にプリコミットフックが自動的に実行されます
6. 提出: プルリクエストを作成する

例となる計画については、plans/compare-options-tool.mdを参照してください。

コード標準

• 型ヒントを持つPython 3.12以上
• 行長88のBlackフォーマット
• インポートの並べ替えのためのisort
• リンティングのためのflake8
• 型チェックのためのmypy
• テストのためのpytest (80%以上のカバレッジを目指す)
• コミットメッセージのためのConventional commits

テストの実行

# すべてのテストを実行する
pytest tests/

# カバレッジ付きで実行する
pytest --cov=server tests/

# プリコミットフックは自動的に実行されます
git commit -m "feat: add new tool"

ドキュメント標準

• すべての公開関数にdocstringを追加する
• ユーザー向けの変更についてREADME.mdを更新する
• 新機能について例を追加する
• docs/を最新の状態に保つ
• 既存のドキュメントスタイルに従う

---

📄 ライセンス

MITライセンス - 詳細はLICENSEファイルを参照してください。

---

🙏 謝辞

• FastMCPで構築 - 高速でPythonicなMCPフレームワーク
• Model Context Protocol仕様に触発されました
• インテリジェントな応答のために好きな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/

---

質問や問題、フィードバックはありますか？

イシューを作成するか、連絡してください！お手伝いします。🧠✨