mcp-server-architect

mcp-server-architect

AI ソフトウェアアーキテクトとして機能する Model Context Protocol サーバーです。コードベースを分析して製品要件定義書（PRD）を生成し、強力なエージェントベースのアーキテクチャを用いて、複雑なコーディングタスクの推論を支援します。

機能

• マルチモデルアーキテクチャ：専門的なツールを利用できる OpenAI の GPT-4o を主要なエージェントタスクに使用します
• インテリジェントなコードベース分析：プロジェクトファイルから包括的なコードコンテキストを構築し、アーキテクチャを理解します
• エージェントベースの設計：各タスクで使用するツールを自律的に判断する、スマートなエージェントを使用します
• ツールベースの処理：コードの読み取り、ウェブ検索、対象を絞った LLM クエリ用の専門ツールを備えています
• 包括的な PRD 生成：アーキテクチャに関する知見を盛り込んだ、詳細な製品要件定義書を作成します
• 高度な推論：開発者が複雑なコーディング課題を段階的な推論で解決できるよう支援します
• Logfire による計測：詳細なテレメトリーを用いた、エージェントのアクティビティの監視とデバッグ機能を内蔵しています
• MCP 統合：Model Context Protocol を介して Claude Code にシームレスに接続します
• シンプルなデプロイ：uvx mcp-server-architect を使ってすばやくインストールして実行できます

仕組み

Architect MCP Server は、人間のソフトウェアアーキテクトが複雑な設計タスクに取り組む方法を模した、高度なエージェントベースのアーキテクチャを実装しています。

1. エージェントループ：リクエスト（PRD の生成または推論支援）を受け取ると、GPT-4o ベースのプライマリエージェントがタスクを評価し、解決プロセスを統括します。

2. ツールベースのアーキテクチャ：エージェントは、次の専門ツールを利用できます。

   • コードリーダー：ソースコードファイルを分析し、まとまりのあるコンテキスト表現に統合します
   • ウェブ検索：Exa AI を使用して、関連する技術情報をウェブ上から検索します
   • LLM ツール：特定のサブタスク向けに、専門的な言語モデルを対象を絞って呼び出します

3. 自律的な意思決定：エージェントが、どのツールをいつ使用するか、また最終結果を生成するために各出力をどのように統合するかを判断します。

4. コンテキストの把握：PRD の生成では、推奨事項を提示する前に、コードベースの構造、依存関係、設計パターンを深く理解します。

5. 柔軟な応答生成：すべての出力は、ワークフローに簡単に組み込めるよう、明確で構造化された Markdown 形式で生成されます。

コンポーネントアーキテクチャ

システムは、次の主要コンポーネントで構成されるモジュール設計に従っています。

┌─────────────────────────────────────────────────────────────────┐
│                       MCP Server Interface                      │
│                    (mcp_server_architect/__main__.py)           │
└───────────────────────────────┬─────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                       Architect Core                            │
│                    (mcp_server_architect/core.py)               │
└───────────────────────────────┬─────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                       Agent Executor                            │
│                (mcp_server_architect/agents/executor.py)        │
└───┬─────────────────────┬────────────────────────┬──────────────┘
    │                     │                        │
    ▼                     ▼                        ▼
┌───────────────┐    ┌─────────────┐         ┌─────────────┐
│ LLM Models    │    │    Tools    │         │ Dependencies│
│ OpenAI GPT-4o │    │ code_reader │         │ArchitectDeps│
│ Gemini 2.5    │    │ web_search  │         └─────────────┘
└───────────────┘    │ llm         │
                     └─────────────┘

コンポーネントのフロー：

1. MCP サーバーインターフェース：Model Context Protocol を介してサービスを公開するエントリーポイント

   • ツール（generate_prd と think）を登録します
   • 受信したリクエストを処理し、コアに振り分けます

2. Architect Core：処理を調整する中心的なコンポーネント

   • エージェントの作成と実行を管理します
   • 公開 API（generate_prd、think）を実装します
   • エラー処理とロギングを行います

3. Agent Executor：適切なモデルとツールを設定して、エージェントを作成します

   • タスクに応じてモデル（OpenAI または Gemini）を選択します
   • OpenAI モデルには直接モデル初期化を使用します
   • エージェントにツールを登録します
   • タスクごとにエージェントを実行するメソッドを提供します

4. LLM モデル：

   • メインのエージェントループには OpenAI GPT-4o を使用します（一般的なタスクのデフォルト）
   • 特定のタスク（PRD 生成と思考）には Gemini 2.5 を使用します

5. ツール：

   • code_reader：コードベースのソースコードファイルを分析します
   • web_search：関連情報をウェブ上から検索します
   • llm：特定のサブタスク向けに、対象を絞って LLM を呼び出します

6. 依存関係：

   • ArchitectDependencies：ツールにコードベースのパスと API キーを提供します

データフロー：

1. ユーザーリクエスト → MCP サーバーインターフェース
2. インターフェースがリクエストをルーティング → Architect Core
3. Core が Agent Executor の適切なメソッドを呼び出す
4. Agent Executor がエージェントを作成して設定する
5. エージェントがツールを使って実行し、必要に応じてモデルにアクセスする
6. 結果が同じ経路を通って戻る
7. 整形された応答がユーザーに返される

最新の改善については、CHANGELOGを参照してください。

前提条件

• Python 3.10 以降
• GPT-4o 用の OpenAI API キー（OpenAI Platformから取得してください）
• Gemini Pro 用の Google API キー（Google AI Studioから取得してください）
• ウェブ検索機能用の Exa API キー（Exa AIから取得してください）
• モニタリング用の Logfire API キー（任意。Logfireから取得してください）

このシステムは、メインエージェントのタスクには OpenAI のモデルを優先して使用し、特定のツール操作には Google Gemini を使用します。最適なパフォーマンスを得るには、両方の AI モデルの API キーを用意することを推奨します。Logfire API キーは任意ですが、エージェントのアクティビティのモニタリングとデバッグに役立つテレメトリーを提供します。

インストール

uv を使ったクイックインストール（推奨）

サーバーをインストールして使用する最も簡単な方法は、パッケージマネージャーの uv を使用することです。

# Install uv if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# No installation needed - run directly with uvx (one-liner)
env GEMINI_API_KEY=your_api_key_here uvx mcp-server-architect

pip を使ったインストール

PyPI からパッケージをインストールすることもできます。

pip install mcp-server-architect

インストール後、コマンドとして実行できます。

env GEMINI_API_KEY=your_api_key_here mcp-server-architect

API キーの要件

このサーバーで Google Gemini モデルにアクセスするには、Gemini API キーが必要です。Google AI Studioから取得できます。API キーは複数の方法で指定できます。

1. env プレフィックスを付けた環境変数として指定する：env GEMINI_API_KEY=your_key mcp-server-architect
2. カレントディレクトリに .env ファイルを作成し、GEMINI_API_KEY=your_key を記述する

注： 実行前に export で環境変数を設定する方法は、安定して動作しない場合があります。env コマンドのプレフィックスを付ける方法を推奨します。

開発環境へのインストール

コードを開発または変更する場合：

1. リポジトリをクローンする：

   git clone <your-repo-url>
   cd <your-repo-directory>
   

2. 開発環境をセットアップする：

   uv venv
   source .venv/bin/activate
   uv pip install -e ".[dev]"
   

3. 開発モードで実行する：

   env GEMINI_API_KEY=your_api_key_here python -m mcp_server_architect
   

4. 開発用に MCP Inspector で実行する：

   env GEMINI_API_KEY=your_api_key_here npx @modelcontextprotocol/inspector python -m mcp dev --with-editable . mcp_server_architect/__main__.py
   

サーバーの実行と使用

uvx で直接実行する

サーバーを実行する最も簡単な方法は、Gemini API キーを渡して uvx を使用することです。

# As a one-liner (recommended)
env GEMINI_API_KEY=your_api_key_here EXA_API_KEY=your_exa_key_here uvx mcp-server-architect

# Alternatively, use a .env file in the current directory
# with GEMINI_API_KEY and EXA_API_KEY environment variables

MCP Inspector で使用する

MCP Inspector でサーバーをデバッグまたはテストするには：

env GEMINI_API_KEY=your_api_key_here EXA_API_KEY=your_exa_key_here npx @modelcontextprotocol/inspector uvx mcp-server-architect

インスペクターのインターフェース（通常は http://localhost:8787）が開き、サーバーのツールを対話形式でテストできます。

Claude Code に追加する

Claude Code は、さまざまなスコープで MCP サーバーをサポートしています。Gemini API キーを使って Architect サーバーを追加する方法は次のとおりです。

# Local scope (only available to you in the current project)
claude mcp add architect -- env GEMINI_API_KEY=your_api_key_here EXA_API_KEY=your_exa_key_here uvx mcp-server-architect

# Project scope (shared with everyone via .mcp.json)
claude mcp add architect -s project -- env GEMINI_API_KEY=your_api_key_here EXA_API_KEY=your_exa_key_here uvx mcp-server-architect

# User scope (available to you across all projects)
claude mcp add architect -s user -- env GEMINI_API_KEY=your_api_key_here EXA_API_KEY=your_exa_key_here uvx mcp-server-architect

重要： your_api_key_here を Gemini 用の実際の Google API キーに、your_exa_key_here をウェブ検索用の Exa API キーに置き換えてください。

MCP サーバーのスコープについて

Claude Code では、MCP サーバーに次の 3 種類のスコープを指定できます。

• Local（デフォルト）：現在のプロジェクトで、あなたのみが利用できます
• Project：.mcp.json ファイルに保存され、バージョン管理にコミットしてチームと共有できます
• User：すべてのプロジェクトで利用できます

チームでの共同作業には、チームの全員が個別に設定することなく同じ MCP サーバーにアクセスできる Project スコープを推奨します。

API キーを安全に保存する

セキュリティのため、API キーをより安全な方法で保存できます。次の方法があります。

1. .env ファイルを使用する（Project スコープの場合）：

   # Create a .env file (don't commit this!)
   echo "GEMINI_API_KEY=your_api_key_here" > .env
   echo "EXA_API_KEY=your_exa_key_here" >> .env
   
   # Add to Claude Code with the env prefix
   claude mcp add architect -- env GEMINI_API_KEY=your_api_key_here EXA_API_KEY=your_exa_key_here uvx mcp-server-architect
   

2. OS の安全な認証情報ストレージを使用する：

   • macOS では、Keychain に保存し、スクリプトで取得できます
   • コマンドにスクリプトへの参照を追加します

インストールを確認する

インストール後、Claude にサーバーが登録されていることを確認できます。

# List all configured servers
claude mcp list

# Get details for the architect server
claude mcp get architect

テストの実行

テストスイートを実行するには、次のコマンドを実行します。

# Using uv
uv run pytest

# Using pip
python -m pytest

テストでは pytest-recording を使用して、API との HTTP 通信を記録します。デフォルトでは、以前に記録されたレスポンスを使用します。記録を更新するには、次のコマンドを実行します。

# Force rewrite of API recordings
pytest tests/ --record-mode=all

テストの詳細については、tests/README.md を参照してください。

MCP リソースとツール

この MCP サーバーでは、次のリソースとツールを公開しています。

ツール

• Architect::generate_prd：コードベースの分析に基づいて、製品要件定義書を生成します

  • パラメーター：
    • task_description（必須）：実装するプログラミングタスクまたは機能の詳細な説明
    • codebase_path（必須）：分析対象のコードベースディレクトリのローカルファイルパス

• Architect::think：コーディングタスクで行き詰まった LLM に推論のサポートを提供します

  • パラメーター：
    • request（必須）：コーディングタスクや問題、および関連するコードスニペットの詳細な説明

使用例

PRD の生成例

インストール後、次のようにプロンプトを入力すると、Claude Code で PRD ツールを使用できます。

@Architect please generate a PRD for creating a new feature.
Task Description: "Create a user profile page that displays user information and activity history, with edit functionality."
Codebase Path: "/path/to/your/local/project"

より具体的な技術的詳細を含む例：

@Architect generate a PRD for a new feature.
Task Description: "Implement JWT authentication in a Flask application, with login, registration, and token refresh endpoints. Add middleware for protected routes and handle token expiration gracefully."
Codebase Path: "/Users/username/projects/my-flask-app"

推論サポートの例

コーディングタスクで行き詰まったときは、推論ツールを使用して詳細な推論を得られます。

@Architect I need help thinking through a coding problem.
I'm trying to implement a function that reverses a linked list but I'm stuck on handling the edge cases.
Here's my code:
```python
def reverse_linked_list(head):
    if not head or not head.next:
        return head
    prev = None
    current = head
    while current:
        next_node = current.next
        current.next = prev
        prev = current
        current = next_node
    return prev

見落としているエッジケースはありますか？実装は正しいですか？

You can also create custom slash commands for easier access:

1. Create a commands directory in your project:
   ```bash
   mkdir -p .claude/commands

2. Architect ツールのコマンドファイルを作成します。

   # PRD generation command
   echo "Generate a PRD for the following task:\n\nTask Description: \"$ARGUMENTS\"\nCodebase Path: \"`pwd`\"" > .claude/commands/prd.md
   
   # Thinking assistance command
   echo "I need help thinking through this coding problem:\n\n$ARGUMENTS" > .claude/commands/think.md
   

3. Claude Code で使用します。

   # For PRD generation
   /project:prd Implement a new user authentication system
   
   # For reasoning assistance
   /project:think I'm trying to optimize this recursive function but hitting a stack overflow...
   

ビルドと公開

uv を使用してパッケージをビルドし、PyPI に公開するには、次の手順を実行します。

1. パッケージをビルドします。

   uv build --no-sources
   

   これにより、dist/ ディレクトリに配布パッケージが作成されます。

2. TestPyPI に公開します（任意ですが、推奨します）。

   # Set your TestPyPI token
   export UV_PUBLISH_TOKEN=your_testpypi_token
   
   # Publish to TestPyPI
   uv publish --publish-url https://test.pypi.org/legacy/
   

3. PyPI に公開します。

   # Set your PyPI token
   export UV_PUBLISH_TOKEN=your_pypi_token
   
   # Publish to PyPI
   uv publish
   

リリース手順の概要

新しいバージョンを準備してリリースする手順の概要は次のとおりです。

1. 次のファイルで、セマンティックバージョニング（major.minor.patch）に従ってバージョンを更新します。

   • pyproject.toml
   • mcp_server_architect/version.py
   • mcp_server_architect/__init__.py

2. テストが成功することを確認します。

   uv run pytest
   

3. パッケージをビルドします。

   uv build --no-sources
   

4. パッケージをローカルでテストします。

   # Create a temporary directory
   mkdir -p /tmp/test-architect
   cd /tmp/test-architect
   
   # Test installing from the built package
   uv run --with-pin /path/to/your/dist/mcp_server_architect-*.whl --no-project -- python -c "from mcp_server_architect import __version__; print(__version__)"
   

5. PyPI に公開します。

   uv publish
   

6. インストールを確認します。

   # In a fresh environment
   uvx mcp-server-architect --version
   

ライセンス

MIT