athena-protocol

Athena Protocol MCP Server：Context Orchestration Protocol の先駆け

コーディングエージェントのAIテックリードとして機能するインテリジェントなMCPサーバーです。コード変更を行う前に、専門的な検証、影響分析、戦略的なガイダンスを提供します。シニアエンジニアがアプローチをレビューするように、Athena ProtocolはAIエージェントが重大な問題を早期に発見し、実際のコードベースに照らして前提を検証し、問題解決の戦略を最適化できるよう支援します。その結果、コードの品質が向上し、リグレッションが減り、アーキテクチャ上の意思決定がより慎重になります。

主な機能： analysisTargets による高精度なファイル分析。対象を絞ったコード分析により、トークン消費を70～85％削減し、処理速度を3～4倍に向上できます。詳しくは強化されたファイル分析をご覧ください。

Context Orchestration Protocol：AI支援開発の未来

洗練され、対象を絞ったコンテキストを用いてLLMが作業することで、推測をなくし、エラーを80％削減し、熟練したアーキテクトのような精度でコードを提供する様子を想像してください。これにより、複雑なコードベースをAIエージェントが理解し、強化する方法が一変します。

目次

• セキュリティ
• 背景
• インストール
• 使い方
• API
• コントリビューション
• ライセンス

セキュリティ

このサーバーは複数のLLMプロバイダーのAPIキーを扱います。.env ファイルを適切に保護し、バージョン管理に絶対にコミットしないでください。サーバーは起動時にすべてのAPIキーを検証し、設定に問題がある場合は詳細なエラーメッセージを表示します。

背景

Athena Protocol MCP Serverは、AIコーディングエージェント向けに体系的な思考の検証を提供します。14種類のLLMプロバイダーに対応し、思考の検証、影響分析、前提の確認、依存関係のマッピング、思考の最適化など、さまざまな検証ツールを備えています。

主な機能：

• スマートクライアントモードによる、対象を絞った高精度なコード分析（トークン消費を70～85％削減）
• ハードコードされたデフォルト値を使わない、環境変数主導の設定
• 自動フォールバックに対応したマルチプロバイダーLLMサポート（14プロバイダー）
• 複数のモード（full、head、tail、range）に対応した強化版ファイル読み込み
• 3～4倍のパフォーマンス向上を実現する並行ファイル操作
• セッションベースの検証履歴とメモリ管理
• 包括的な設定検証とヘルスモニタリング
• 効率的な検証ワークフローを実現するデュアルエージェントアーキテクチャ

インストール

このモジュールを利用するには、Node.jsとnpmの知識が必要です。

npm install
npm run build

前提条件

• Node.js >= 18
• npm または yarn

設定

Athena Protocolでは、環境変数を100％使用して設定します。プロバイダーの値やデフォルト値はハードコードされていません。すべて .env ファイルで設定してください。

1. 設定例をコピーします：

   cp .env.example .env

2. .env を編集し、プロバイダーを設定します：

   • DEFAULT_LLM_PROVIDER を設定します（例：openai、anthropic、google）
   • 選択したプロバイダーのAPIキーを追加します
   • モデルとパラメーターを設定します（任意）

3. 検証してテストします：

   npm install
   npm run build
   npm run validate-config  # Validates your .env configuration
   npm test
   

設定可能な項目とサポート対象の14プロバイダーすべてについては、.env.example をご覧ください。

重要な設定要件

• PROVIDER_SELECTION_PRIORITY は必須です。優先順位に従ってプロバイダーを列挙してください
• ハードコードされたフォールバックはありません。すべての設定を .env で明示する必要があります
• フェイルファスト検証：設定が無効な場合、起動は直ちに失敗します
• プロバイダーごとに完全な設定が必要です。API キー、モデル、パラメーターを設定してください

対応プロバイダー

Athena Protocol は 14 の LLM プロバイダーに対応しています。OpenAI が一般的に使用されていますが、次のいずれも設定できます。

主要なクラウドプロバイダー：

• OpenAI - GPT-5（思考機能付き）、GPT-4o、GPT-4-turbo
• Anthropic - Claude Opus 4.1、Claude Sonnet 4.5、Claude Haiku 4.5
• Google - Gemini 2.5（Flash／Pro／Ultra）
• Azure OpenAI - エンタープライズグレードの GPT モデル
• AWS Bedrock - Claude、Llama など
• Google Vertex AI - エンタープライズ機能を備えた Gemini

特化型プロバイダー：

• OpenRouter - 400 以上のモデルにアクセス可能
• Groq - 超高速な推論
• Mistral AI - オープンソースモデル
• Perplexity - 検索拡張モデル
• XAI - Grok モデル
• Qwen - Alibaba の高性能 LLM
• ZAI - GLM モデル

ローカル／セルフホスト：

• Ollama - モデルをローカルで実行

簡単な切り替えの例：

# Edit .env file
ANTHROPIC_API_KEY=sk-ant-your-key-here
DEFAULT_LLM_PROVIDER=anthropic

# Restart server
npm run build && npm start

プロバイダーの切り替え

詳しい設定手順については、プロバイダーの詳細ガイドをご覧ください。

使用方法

MCP クライアントの設定

詳しく、動作確認済みの MCP クライアント設定については、CLIENT_MCP_CONFIGURATION_EXAMPLES.mdをご覧ください

ローカルインストールの場合（.env ファイルを使用）

.env ファイルを使ったローカルインストールは、引き続き完全に機能し、変更はありません。リポジトリをクローンして、次を実行するだけです。

npm install
npm run build

次に、ローカルインストールを参照するように MCP クライアントを設定します。

{
  "mcpServers": {
    "athena-protocol": {
      "command": "node",
      "args": ["/absolute/path/to/athena-protocol/dist/index.js"],
      "type": "stdio",
      "timeout": 300
    }
  }
}

NPM インストールの場合（MCP 環境変数を使用 - 推奨）

npm／npx を使用する場合は、環境変数を使って MCP クライアントを設定してください。CLIENT_MCP_CONFIGURATION_EXAMPLES.mdに記載されている設定のみ、動作確認済みで、動作が保証されています。

GPT-5 の例：

{
  "mcpServers": {
    "athena-protocol": {
      "command": "npx",
      "args": ["@n0zer0d4y/athena-protocol"],
      "env": {
        "DEFAULT_LLM_PROVIDER": "openai",
        "OPENAI_API_KEY": "your-openai-api-key-here",
        "OPENAI_MODEL_DEFAULT": "gpt-5",
        "OPENAI_MAX_COMPLETION_TOKENS_DEFAULT": "8192",
        "OPENAI_VERBOSITY_DEFAULT": "medium",
        "OPENAI_REASONING_EFFORT_DEFAULT": "high",
        "LLM_TEMPERATURE_DEFAULT": "0.7",
        "LLM_MAX_TOKENS_DEFAULT": "2000",
        "LLM_TIMEOUT_DEFAULT": "30000"
      },
      "type": "stdio",
      "timeout": 300
    }
  }
}

動作する設定の完全な例については、CLIENT_MCP_CONFIGURATION_EXAMPLES.mdをご覧ください。

設定に関する注意事項：

• NPM インストール：最も簡単に設定するには、env フィールドを使って npx @n0zer0d4y/athena-protocol を実行してください
• ローカルインストール：.env ファイルを使ったローカル実行は、引き続き完全に機能し、変更はありません
• 環境変数の優先順位：MCP の env 変数は .env ファイルの変数より優先されます
• GPT-5 のサポート：GPT-5 モデル専用のパラメーターが含まれています
• タイムアウトの設定：デフォルトのタイムアウトは、GPT-5 のような推論モデル向けに 300 秒（5 分）に設定されています。より高速な LLM（GPT-4、Claude、Gemini）では、60～120 秒に短縮できます
• GPT-5 のパラメーターに関する注意：LLM_TEMPERATURE_DEFAULT、LLM_MAX_TOKENS_DEFAULT、LLM_TIMEOUT_DEFAULT の各パラメーターは、現在 GPT-5 モデルで必須ですが、モデル自体では使用されません。これは一時的な制限であり、今後のリファクタリングで対応予定です
• セキュリティ：API キーをバージョン管理にコミットしないでください。代わりに MCP クライアントの環境変数を使用してください

今後のリファクタリング計画

GPT-5 パラメーターの最適化

現在の問題：GPT-5 モデルでは、モデルがこれらのパラメーターを使用しないにもかかわらず、標準の LLM パラメーター（LLM_TEMPERATURE_DEFAULT、LLM_MAX_TOKENS_DEFAULT、LLM_TIMEOUT_DEFAULT）が現在必要です。

予定している解決策：

1. getTemperature() 関数を変更し、ハードコードされたデフォルト値の代わりに、GPT-5 以降のモデルでは undefined を返すようにします
2. undefined の温度値を処理できるように、AI プロバイダーのインターフェースを更新します
3. GPT-5 以降のモデルでは標準パラメーターを省略する、条件付きのパラメーター検証を実装します
4. GPT-5 API との通信時に未使用のパラメーターを省略するように、OpenAI プロバイダーを更新します

メリット：

• GPT-5 ユーザー向けの設定がより簡潔になります
• モデルの機能をより正確に表現できます
• OpenAI の GPT-5 API 仕様への準拠が向上します

予定時期：v0.3.0 での実装を目標としています

サーバーモード

MCP サーバーモード（本番環境での使用向け）

npm start                    # Start MCP server for client integration (requires .env or MCP env)
npm run dev                  # Development mode with auto-restart
npx @n0zer0d4y/athena-protocol  # Run published version via npx (requires MCP env)

スタンドアロンモード（テスト向け）

npm run start:standalone     # Test server without MCP client
npm run dev:standalone       # Development standalone mode

設定ツール

# Validate your complete configuration
npm run validate-config

# Or use the comprehensive MCP validation tool
node dist/index.js
# Then call: validate_configuration_comprehensive

主な機能

マルチプロバイダー LLM サポート

Athena Protocol は、以下を含む 14 のプロバイダーに対応しています。

• クラウドプロバイダー：OpenAI、Anthropic、Google、Azure OpenAI、AWS Bedrock、Vertex AI
• 特化型：OpenRouter（400 以上のモデル）、Groq、Mistral、Perplexity、XAI、Qwen
• ローカル／セルフホスト型：Ollama、ZAI

ローカルモデル向けの Ollama を除き、すべてのプロバイダーで API キーが必要です。設定方法については、設定のセクションを参照してください。

インテリジェントな思考検証

• 焦点を絞った検証：コミュニケーションを簡潔に保ちながら、推論の重要な側面を検証します
• デュアルエージェントアーキテクチャ：プライマリエージェントと検証エージェントが連携して動作します
• 信頼度スコア：意思決定の指針となる、明示的な信頼度レベルを示します
• ループの防止：分析が行き詰まるのを防ぐため、タスクごとのやり取りを最大 3 回に制限します

体系的なアプローチ

• 必要な情報のみ：効果的な検証に必要な情報だけを共有します
• 実行可能な出力：すぐに適用できる、明確で具体的な推奨事項を提示します
• 段階的な詳細化：まずは広く検討し、必要な場合にのみ具体化します
• セッション管理：複数回の試行を通じて、永続的な検証セッションを維持します

デュアルモード動作

• MCP サーバーモード：MCP クライアント（Claude Desktop、Cline など）と完全に統合します
• スタンドアロンモード：MCP クライアントを使用せずに、独立してテストと検証を行います

API

Athena Protocol MCP サーバーは、思考の検証と分析のために以下のツールを提供します。

thinking_validation

主要エージェントの思考プロセスを、焦点を絞った必要な情報に基づいて検証します。

必須パラメーター：

• thinking (string)：アプローチと推論の簡潔な説明
• proposedChange (object)：提案された変更の詳細
  • description (string, required)：変更内容
  • code (string, optional)：実際のコード変更
  • files (array, optional)：影響を受けるファイル
• context (object)：検証のコンテキスト
  • problem (string, required)：問題の簡潔な説明
  • techStack (string, required)：技術スタック（react|node|python など）
  • constraints (array, optional)：主な制約
• urgency (string)：緊急度（low、medium、high）
• projectContext (object)：ファイル分析のプロジェクトコンテキスト
  • projectRoot (string, required)：プロジェクトルートの絶対パス
  • workingDirectory (string, optional)：現在の作業ディレクトリ
  • analysisTargets (array, REQUIRED)：対象を絞って読み取るコードセクション
    • file (string, required)：ファイルパス（相対パスまたは絶対パス）
    • mode (string, optional)：読み取りモード（full、head、tail、range）
    • lines (number, optional)：行数（head／tail モードの場合）
    • startLine (number, optional)：開始行番号（range モードの場合、1 始まり）
    • endLine (number, optional)：終了行番号（range モードの場合、1 始まり）
    • priority (string, optional)：分析の優先度（critical、important、supplementary）
• projectBackground (string)：誤った推測を防ぐための、プロジェクトの簡潔な説明

オプションのパラメーター：

• sessionId (string)：コンテキストを保持するためのセッション ID
• provider (string)：LLM プロバイダーの上書き（openai、anthropic、google など）

出力：

信頼度スコア、重大な問題、推奨事項、テストケースを含む検証結果を返します。

impact_analysis

提案された変更による主な影響をすばやく特定します。

必須パラメーター：

• change (object)：変更の詳細
  • description (string, required)：変更内容
  • code (string, optional)：コード変更
  • files (array, optional)：影響を受けるファイル
• projectContext (object)：プロジェクトコンテキスト（thinking_validation と同じ構造）
  • projectRoot (string, required)
  • analysisTargets (array, REQUIRED)：読み取りモードを指定して分析するファイル
  • workingDirectory (optional)
• projectBackground (string)：プロジェクトの簡潔な説明

オプションのパラメーター：

• systemContext (object)：システムアーキテクチャのコンテキスト
  • architecture (string)：アーキテクチャの簡潔な説明
  • keyDependencies (array)：主要なシステム依存関係
• sessionId (string)：コンテキストを保持するためのセッション ID
• provider (string)：LLM プロバイダーの上書き

出力：

全体的なリスク評価、影響を受ける領域、連鎖的なリスク、実施すべき簡単なテストを返します。

assumption_checker

過度な分析を避けながら、重要な前提をすばやく検証します。

必須パラメーター：

• assumptions (array)：検証する前提を表す文字列のリスト
• context (object)：検証のコンテキスト
  • component (string, required)：コンポーネント名
  • environment (string, required)：環境（production、development、staging、testing）
• projectContext (object)：プロジェクトコンテキスト（thinking_validation と同じ構造）
  • projectRoot (string, required)
  • analysisTargets (array, REQUIRED)：読み取りモードを指定して分析するファイル
• projectBackground (string)：プロジェクトの簡潔な説明

オプションのパラメーター：

• sessionId (string)：コンテキストを保持するためのセッション ID
• provider (string)：LLM プロバイダーの上書き

出力：

妥当な前提、緩和策を伴うリスクのある前提、簡単な検証手順を返します。

dependency_mapper

重要な依存関係を効率的に特定します。

必須パラメーター：

• change（オブジェクト）：変更の詳細
  • description（文字列、必須）：変更内容の簡単な説明
  • files（配列、任意）：変更対象のファイル
  • components（配列、任意）：変更対象のコンポーネント
• projectContext（オブジェクト）：プロジェクトのコンテキスト（thinking_validation と同じ構造）
  • projectRoot（文字列、必須）
  • analysisTargets（配列、必須）：読み取りモードを指定して分析するファイル
• projectBackground（文字列）：プロジェクトの簡単な説明

任意のパラメーター：

• sessionId（文字列）：コンテキストを保持するためのセッション ID
• provider（文字列）：LLM プロバイダーの上書き指定

出力：

影響分析とテストの重点領域を含む、重要および二次的な依存関係を返します。

thinking_optimizer

問題の種類に応じて、思考アプローチを最適化します。

必須パラメーター：

• problemType（文字列）：問題の種類（bug_fix、feature_impl、refactor のいずれか）
• complexity（文字列）：複雑さのレベル（simple、moderate、complex のいずれか）
• timeConstraint（文字列）：時間の制約（tight、moderate、flexible のいずれか）
• currentApproach（文字列）：現在の思考アプローチの簡単な説明
• projectContext（オブジェクト）：プロジェクトのコンテキスト（thinking_validation と同じ構造）
  • projectRoot（文字列、必須）
  • analysisTargets（配列、必須）：読み取りモードを指定して分析するファイル
• projectBackground（文字列）：プロジェクトの簡単な説明

任意のパラメーター：

• sessionId（文字列）：コンテキストを保持するためのセッション ID
• provider（文字列）：LLM プロバイダーの上書き指定

出力：

次の項目を含む、包括的な最適化戦略を返します。

• optimizedStrategy：推奨されるアプローチ、使用するツール、時間配分の内訳、成功確率、重要な重点領域
• tacticalPlan：問題の分類、grep 検索戦略、主な調査結果の仮説、判断ポイント、段階的な実装計画、テスト戦略、リスク軽減策、進捗チェックポイント、価値と労力の評価を含む、詳細な実装ガイダンス
• metadata：使用したプロバイダーとファイル分析の指標

athena_health_check

Athena Protocol サーバーの健全性と設定を確認します。

パラメーター： なし

出力：

デフォルトのプロバイダー、有効な API キーを持つアクティブなプロバイダーの一覧、設定状況、システムの健全性に関する情報を返します。

session_management

コンテキストの保持と進捗の追跡のために、思考検証セッションを管理します。

必須パラメーター：

• action（文字列）：セッションの操作 — create、get、update、list、delete のいずれか

任意のパラメーター：

• sessionId（文字列）：セッション ID（get、update、delete の各操作で必須）
• tags（配列）：セッションを分類するタグ
• title（文字列）：セッションのタイトル／説明（作成時・更新時）

出力：

操作に応じて、セッション情報またはセッションの一覧を返します。

---

強化されたファイル分析（新機能）

すべてのツールで、analysisTargets を使って対象を正確に指定する スマートクライアントモード が利用できます。

利点：

• 関連するコード部分のみを読み取ることで、トークンを 70～85％削減
• ファイルを並行して読み取ることで、3～4 倍高速化
• モードベースの読み取り：full、head（先頭から N 行）、tail（末尾から N 行）、range（X～Y 行）
• 優先度に基づく処理：critical → important → supplementary

例：

{
  "projectContext": {
    "projectRoot": "/path/to/project",
    "analysisTargets": [
      {
        "file": "src/auth.ts",
        "mode": "range",
        "startLine": 45,
        "endLine": 78,
        "priority": "critical"
      },
      {
        "file": "src/config.ts",
        "mode": "head",
        "lines": 20,
        "priority": "supplementary"
      }
    ]
  }
}

注： すべてのツールで、ファイル分析には analysisTargets が必要です。適切な読み取りモード（full、head、tail、range）を指定したファイルを少なくとも 1 つ提供してください。

重要なお知らせ

メモリシステムの状況

永続メモリシステム（thinking-memory.json）は現在、レビュー中で、リファクタリング待ちです。機能はしていますが、次の点があります。

• プロジェクトのルートディレクトリにメモリファイルを作成します
• セッションをまたいで検証履歴を保持します
• テストや開発中に手動でのクリーンアップが必要になる場合があります

今後の改善予定：

• ストレージを.gitignore対象のディレクトリ（例：athena-memory/）に移動します
• 自動クリーンアップの仕組みを追加します
• セッション管理を強化します
• ファイルパスの処理を改善します

リファクタリングが完了するまでは、本番環境でこの機能を実験的なものとして扱ってください。

設定方法

Athena Protocol では、優先順位が明確な2つの設定方法をサポートしています。

1. MCP クライアントの環境変数（最優先 — npm インストールで推奨）
2. ローカルの .env ファイル（フォールバック — ローカル開発向け）
3. システム環境変数（最も優先度が低い）

npm 公開版を使用する場合は、MCP クライアントのenvフィールドで設定をすべて直接指定してください。ローカル開発では、引き続き.envファイルを使用してください。

プロバイダーのテスト状況

Athena Protocol は14の LLM プロバイダーをサポートしていますが、十分にテストされているのは次のプロバイダーのみです。

• OpenAI
• Google
• ZAI
• Mistral
• OpenRouter
• Groq

その他のプロバイダー（Anthropic、Qwen、XAI、Perplexity、Ollama、Azure、Bedrock、Vertex）は設定済みで、動作するはずですが、広範なテストは行われていません。プロバイダーで問題が発生した場合は、次の情報を添えてイシューを作成してください。

• プロバイダー名とモデル
• エラーメッセージまたは予期しない動作
• MCP の設定または.envの設定（API キーは伏せてください）

貢献

このサーバーは、LLM コーディングエージェント向けに特化して設計されています。貢献では、次の点に注力してください。

• 新しい LLM プロバイダーの追加
• 検証の有効性の向上
• コンテキスト認識の強化
• 検証対象範囲の拡大
• メモリ管理の最適化
• 新しい検証戦略の追加

ライセンス

MIT License — 詳細は LICENSE ファイルを参照してください。