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提供商
• 提高验证有效性
• 增强上下文感知
• 扩大验证覆盖范围
• 优化内存管理
• 添加新的验证策略