Athena Protocol

🚀 Athena協議MCP服務器：上下文編排協議的先驅

Athena協議MCP服務器是一個智能的MCP服務器，它就像編碼代理的AI技術負責人。在代碼更改之前，它能提供專業驗證、影響分析和戰略指導。就像一位資深工程師審查你的方案一樣，Athena協議幫助AI代理儘早發現關鍵問題，根據實際代碼庫驗證假設，並優化其解決問題的策略。最終實現更高質量的代碼、更少的迴歸問題以及更周全的架構決策。

關鍵特性：使用analysisTargets進行精確文件分析，通過精確目標代碼分析，可減少 70 - 85% 的令牌使用量，並使性能提升 3 - 4 倍。詳情見增強型文件分析。

上下文編排協議：AI輔助開發的未來

想象一下，大語言模型（LLMs）在如此精煉和有針對性的上下文中工作，它們能消除猜測，將錯誤率降低 80%，並像經驗豐富的架構師一樣精確地交付代碼，從而改變AI代理理解和改進複雜代碼庫的方式。

🚀 快速開始

在使用Athena協議MCP服務器之前，需要了解Node.js和npm的相關知識。以下是基本的安裝和配置步驟：

npm install
npm run build

✨ 主要特性

• 智能客戶端模式：通過精準目標代碼分析，減少 70 - 85% 的令牌使用量。
• 環境驅動配置：無硬編碼默認值，所有配置都通過 .env 文件完成。
• 多提供商LLM支持：支持 14 個LLM提供商，並具有自動回退功能。
• 增強型文件讀取：支持多種讀取模式（全量、頭部、尾部、範圍）。
• 併發文件操作：性能提升 3 - 4 倍。
• 基於會話的驗證歷史和內存管理：記錄驗證歷史，便於後續查看和分析。
• 全面的配置驗證和健康監控：確保配置的正確性和服務器的健康狀態。
• 雙代理架構：實現高效的驗證工作流程。

📦 安裝指南

前提條件

• Node.js >= 18
• npm 或 yarn

配置步驟

Athena協議使用 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  # 驗證 .env 配置
npm test

關鍵配置要求

• PROVIDER_SELECTION_PRIORITY 是必需的，需要按優先級列出你的提供商。
• 沒有硬編碼的回退機制，所有配置必須在 .env 文件中明確指定。
• 快速失敗驗證，無效配置會導致立即啟動失敗。
• 每個提供商都需要完整的配置，包括API密鑰、模型和參數。

支持的提供商

Athena協議支持 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 - 阿里巴巴的高性能LLMs
• ZAI - GLM模型

本地/自託管

• Ollama - 本地運行模型

快速切換示例

# 編輯 .env 文件
ANTHROPIC_API_KEY=sk-ant-your-key-here
DEFAULT_LLM_PROVIDER=anthropic

# 重啟服務器
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
    }
  }
}

配置說明

• NPM安裝：使用 npx @n0zer0d4y/athena-protocol 並通過 env 字段進行最簡單的設置。
• 本地安裝：本地 .env 文件的執行仍然完全可用且無需更改。
• 環境優先級：MCP env 變量優先於 .env 文件變量。
• GPT - 5支持：包含針對GPT - 5模型的特定參數。
• 超時配置：默認超時時間為300秒（5分鐘），適用於像GPT - 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. 更新AI提供商接口，以處理 undefined 溫度值。
3. 實現條件參數驗證，跳過GPT - 5+ 模型的標準參數。
4. 更新OpenAI提供商，在與GPT - 5 API通信時省略未使用的參數。

好處：

• 為GPT - 5用戶提供更簡潔的配置。
• 更準確地反映模型能力。
• 更好地遵循OpenAI的GPT - 5 API規範。

時間線：目標在v0.3.0版本中實現。

服務器模式

MCP服務器模式（用於生產環境）

npm start                    # 啟動MCP服務器以進行客戶端集成（需要 .env 或 MCP 環境變量）
npm run dev                  # 開發模式，自動重啟
npx @n0zer0d4y/athena-protocol  # 通過npx運行已發佈版本（需要MCP環境變量）

獨立模式（用於測試）

npm run start:standalone     # 無需MCP客戶端測試服務器
npm run dev:standalone       # 獨立開發模式

配置工具

# 驗證完整配置
npm run validate-config

# 或使用全面的MCP驗證工具
node dist/index.js
# 然後調用：validate_configuration_comprehensive

📚 詳細文檔

增強型文件分析（新）

所有工具現在都支持帶有 analysisTargets 的智能客戶端模式，以實現精確目標定位：

優點

• 減少 70 - 85% 的令牌使用量：僅讀取相關代碼部分。
• 速度提升 3 - 4 倍：通過併發文件讀取實現。
• 基於模式的讀取：全量、頭部（前N行）、尾部（後N行）、範圍（第X - Y行）。
• 優先處理：關鍵 → 重要 → 補充。

示例

{
  "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）。

🔧 技術細節

API接口

Athena協議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)：行數（用於頭部/尾部模式）
    • startLine (number, optional)：起始行號（用於範圍模式，從1開始索引）
    • endLine (number, optional)：結束行號（用於範圍模式，從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)：環境（生產、開發、預發佈、測試）
• projectContext (object)：項目上下文（與 thinking_validation 結構相同）
  • projectRoot (string, required)
  • analysisTargets (array, REQUIRED)：要分析的文件及其讀取模式
• projectBackground (string)：簡要項目描述

可選參數：

• sessionId (string)：用於上下文持久化的會話ID
• provider (string)：LLM提供商覆蓋

輸出：返回有效假設、帶有緩解措施的風險假設以及快速驗證步驟。

dependency_mapper

高效識別關鍵依賴項。 必需參數：

• change (object)：更改的詳細信息
  • description (string, required)：簡要更改描述
  • files (array, optional)：正在修改的文件
  • components (array, optional)：正在更改的組件
• projectContext (object)：項目上下文（與 thinking_validation 結構相同）
  • projectRoot (string, required)
  • analysisTargets (array, REQUIRED)：要分析的文件及其讀取模式
• projectBackground (string)：簡要項目描述

可選參數：

• sessionId (string)：用於上下文持久化的會話ID
• provider (string)：LLM提供商覆蓋

輸出：返回關鍵和次要依賴項，以及影響分析和測試重點區域。

thinking_optimizer

根據問題類型優化思維方法。 必需參數：

• problemType (string)：問題類型（bug_fix、feature_impl 或 refactor）
• complexity (string)：複雜度級別（simple、moderate 或 complex）
• timeConstraint (string)：時間約束（tight、moderate 或 flexible）
• currentApproach (string)：當前思維的簡要描述
• projectContext (object)：項目上下文（與 thinking_validation 結構相同）
  • projectRoot (string, required)
  • analysisTargets (array, REQUIRED)：要分析的文件及其讀取模式
• projectBackground (string)：簡要項目描述

可選參數：

• sessionId (string)：用於上下文持久化的會話ID
• provider (string)：LLM提供商覆蓋

輸出：返回全面的優化策略，包括：

• optimizedStrategy：推薦的方法、要使用的工具、時間分配細分、成功概率和關鍵重點區域
• tacticalPlan：詳細的實施指導，包括問題分類、grep搜索策略、關鍵發現假設、決策點、分步實施計劃、測試策略、風險緩解、進度檢查點和價值/努力評估
• metadata：使用的提供商和文件分析指標

athena_health_check

檢查Athena協議服務器的健康狀態和配置。 參數：無 輸出：返回默認提供商、具有有效API密鑰的活動提供商列表、配置狀態和系統健康信息。

session_management

管理思維驗證會話，以實現上下文持久化和進度跟蹤。 必需參數：

• action (string)：會話操作 - create、get、update、list 或 delete

可選參數：

• sessionId (string)：會話ID（對於 get、update、delete 操作是必需的）
• tags (array)：用於對會話進行分類的標籤
• title (string)：會話標題/描述（用於 create/update）

輸出：根據操作返回會話信息或會話列表。

📄 許可證

本項目採用MIT許可證，詳情請參閱 LICENSE 文件。

重要提示

內存系統狀態

持久內存系統 (thinking-memory.json) 目前正在審查中，待重構。雖然它仍可正常工作，但存在以下情況：

• 在項目根目錄下創建一個內存文件。
• 在會話之間持久保存驗證歷史記錄。
• 在測試/開發期間可能需要手動清理。

計劃改進：

• 將存儲移動到 .gitignore 目錄（例如 athena-memory/）。
• 添加自動清理機制。
• 增強會話管理。
• 改進文件路徑處理。

在重構完成之前，對於生產環境使用，此功能應視為實驗性。

配置方法

Athena協議支持兩種配置方法，優先級明確：

1. MCP客戶端環境變量（最高優先級 - 推薦用於npm安裝）
2. 本地 .env 文件（備用 - 用於本地開發）
3. 系統環境變量（最低優先級）

對於npm發佈的使用方式，直接在MCP客戶端的 env 字段中配置所有設置。對於本地開發，繼續使用 .env 文件。

提供商測試狀態

雖然Athena協議支持14個LLM提供商，但只有以下提供商經過了全面測試：

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

其他提供商（Anthropic、Qwen、XAI、Perplexity、Ollama、Azure、Bedrock、Vertex）已配置，應該可以正常工作，但尚未進行廣泛測試。如果在使用任何提供商時遇到問題，請提交問題，並提供以下信息：

• 提供商名稱和模型
• 錯誤消息或意外行為
• 你的MCP配置或 .env 配置（請屏蔽API密鑰）

貢獻說明

本服務器專為LLM編碼代理設計。貢獻應集中在以下方面：

• 添加新的LLM提供商
• 提高驗證有效性
• 增強上下文感知
• 擴大驗證覆蓋範圍
• 優化內存管理
• 添加新的驗證策略