EVOKORE-MCP：AI工作流中央路由器，统一管理MCP工具与权限

1. 项目概述：一个为AI工作流设计的中央路由器

如果你和我一样，在日常开发中深度依赖像Claude、Cursor这类AI助手，那你肯定对MCP（Model Context Protocol）不陌生。简单来说，MCP就是一套标准，让AI助手能安全、可控地调用你本地的工具，比如读取文件、查询GitHub、操作数据库。但用久了，痛点就来了：每个工具都得单独配置一个MCP服务器，管理起来像一盘散沙，工具列表长得让人眼花缭乱，权限控制更是麻烦。

EVOKORE-MCP就是为了解决这些“散、乱、难”的问题而生的。你可以把它理解为一个智能的MCP路由器或者中央网关。它本身是一个用TypeScript写的标准stdio MCP服务器，但它的核心能力是“聚合”。它能把你自己写的原生工具、以及一大堆第三方MCP服务器（比如官方的github、fs，或者社区的elevenlabs、supabase）全部整合起来，对外只暴露一个统一的MCP端点给你的AI客户端。

这样一来，你的Claude只需要连接EVOKORE这一个入口，就能获得一个经过整理、去重、并附加了权限控制和审批流程的超级工具集。我花了相当长时间去配置和磨合各种独立的MCP服务器，直到遇到EVOKORE，才真正把AI工作流的效率提升了一个维度。它特别适合那些希望将AI深度集成到复杂开发、运维或创作流程中的团队和个人，尤其是当你的工具链涉及代码库、文件系统、云服务等多个维度时。

2. 核心架构与设计哲学拆解

2.1 为什么是“路由器”而非“聚合器”

很多同类工具会自称“聚合器”，但EVOKORE的设计更贴近“路由器”。这不仅仅是语义上的区别，而是体现了其核心的命名空间隔离和请求路由机制。

当你通过mcp.config.json配置了多个子服务器（例如github和fs）后，EVOKORE在启动时会以子进程或HTTP客户端的形式将它们逐一启动。关键在于，它不会简单地把所有工具平铺在一个列表里。相反，它会为每个来自子服务器的工具名称加上一个前缀，格式是${serverId}_${tool.name}。例如，github服务器的search_repositories工具，在EVOKORE中会变成github_search_repositories。

这个设计解决了MCP生态中一个非常实际的问题：工具名冲突。不同服务器的工具完全可能重名，平铺列表会导致后加载的工具覆盖先加载的，造成功能丢失。前缀化确保了每个工具的全局唯一性，这是实现稳定聚合的基础。

2.2 动态工具发现：从“信息过载”到“按需加载”

工具列表过长是另一个用户体验的灾难。想象一下，你的AI助手一连接，就收到了上百个工具的描述，不仅拖慢了初始化速度，也让AI在理解当前上下文时产生了大量无关的“噪音”。

EVOKORE v3.0引入的动态工具发现模式就是为了根治这个问题。它提供了两种模式：

• legacy模式（默认）：传统方式，一次性列出所有原生和代理工具。适合工具总数不多，或者你需要AI随时知晓所有可能性的场景。
• dynamic模式：革命性的改进。在此模式下，EVOKORE初始化时只向AI客户端公开其原生工具（如discover_tools,search_skills）和少数核心代理工具。其他的代理工具处于“隐藏”状态。当AI需要完成特定任务时，你可以通过调用discover_tools这个原生工具，并传入相关关键词（如“git”、“database”），EVOKORE会在后台进行匹配，将相关的代理工具“激活”并加入到当前会话的工具列表中。

这个机制的巧妙之处在于“会话隔离”。工具激活只对当前AI会话有效，不会影响其他连接。同时，它保留了“精确名称调用”的兼容性。即使一个代理工具在动态模式下被隐藏，AI仍然可以通过其完整的带前缀名称（如github_search_repositories）直接调用它。这为工作流提供了极大的灵活性：你可以让AI自主发现常用工具，同时在编写固定脚本时使用确定的工具名。

2.3 安全与管控的三层防线

让AI自由调用工具的同时，必须筑起牢靠的安全围墙。EVOKORE在这方面考虑得非常周全，构建了从应用到操作的三层防线。

第一层：基于角色的访问控制这是最基础的权限模型。通过环境变量EVOKORE_ROLE，你可以为EVOKORE实例设置角色：admin（管理员）、developer（开发者）、readonly（只读）。不同的角色在permissions.yml配置文件中被赋予了不同的能力。例如，readonly角色可能只能调用查询类工具，而admin角色可以执行所有操作，包括技能管理。如果未设置角色，则回退到扁平的、基于工具名的允许/拒绝策略。

第二层：人机交互审批这是EVOKORE的杀手级特性。对于在permissions.yml中被标记为require_approval的工具（通常是高风险操作，如文件删除、数据库写入），当AI尝试调用时，EVOKORE不会直接执行。它会返回一个特殊的_evokore_approval_token（审批令牌）和一个说明。此时，需要真人介入。

你需要打开EVOKORE的会话仪表盘（通常运行在127.0.0.1:8899），在/approvals页面会看到待处理的请求。审查具体的参数后，你可以选择批准或拒绝。批准后，AI可以使用返回的令牌在短时间内重试原请求，这次才会真正执行。这个“人在回路”机制，为自动化流程嵌入了关键的人工决策点，极大地提升了操作的安全性。

第三层：速率限制为了防止AI客户端过度频繁的调用导致子服务器或自身资源耗尽，EVOKORE实现了可配置的令牌桶速率限制。你可以在mcp.config.json中为每个子服务器或单个工具设置rateLimit。例如，你可以限制GitHub API的调用为每分钟60次，或者限制文件写入工具每秒最多调用1次。这层防护对于使用按量付费的API服务尤为重要。

3. 核心模块深度解析与实操要点

3.1 技能生态系统：让AI学会“技能复用”

EVOKORE的“技能”概念，是我认为它超越普通MCP工具聚合器的关键。你可以把“技能”理解为可版本化、可远程存储、可安全执行的AI工作流脚本。

• SkillManager模块：这是原生工具的核心。它负责技能的整个生命周期管理。fetch_skill可以从配置的远程注册表（比如一个Git仓库）拉取技能。list_registry可以查看可用的技能。execute_skill则是在一个受控的沙箱环境中运行技能。
• 技能是什么？一个技能本质上是一个包含元数据（名称、版本、描述、输入输出模式）和可执行逻辑（通常是JavaScript/TypeScript）的包。例如，你可以创建一个“代码审查”技能，它接受一个文件路径，调用本地的linter和静态分析工具，然后生成一份报告。一旦创建并发布，任何连接了EVOKORE的AI都可以通过execute_skill来复用这个完整的审查流程。
• 沙箱执行：这是安全性的基石。技能不是在EVOKORE的主进程中运行，而是在一个隔离的Node.js子进程或类似的安全环境中运行，限制了其对主机系统的访问权限，防止恶意技能造成损害。
• 实操心得：在定义技能时，元数据的质量至关重要。清晰的description和结构化的inputSchema能极大帮助AI理解何时以及如何使用这个技能。我建议为技能设置语义化版本（如1.0.0），并在注册表中维护更新日志，这样AI可以通过refresh_skills获取最新能力，实现工作流的平滑演进。

3.2 代理管理器：异构服务器的统一桥梁

ProxyManager是EVOKORE与外部世界连接的枢纽。它的设计需要处理多种复杂性：

1. 传输协议适配：子服务器可能使用标准的stdio协议，也可能提供HTTP端点。EVOKORE的StreamableHTTPClientTransport支持后者，你只需在mcp.config.json中配置"transport": "http"和对应的"url"即可。
2. 异步启动：如果同时配置了多个子服务器，串行启动会显著增加MCP握手时间。EVOKORE实现了异步代理启动。它在主握手完成后立即响应客户端，同时在后端并行启动所有子服务器。这意味着你的AI助手几乎可以瞬间连接成功，工具列表会在后台逐渐填充，体验非常流畅。
3. 环境变量插值：在mcp.config.json中，你可以使用${ENV_VAR_NAME}的语法来引用环境变量。这避免了将敏感令牌硬编码在配置文件中。ProxyManager会在启动子进程前完成这些变量的替换。
4. 配置要点：一个典型的mcp.config.json条目如下所示。注意rateLimit和args的配置方式，它们提供了细粒度的控制。

{ "servers": { "github": { "command": "npx", "args": ["@modelcontextprotocol/server-github"], "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}" }, "rateLimit": { "tokensPerInterval": 60, "interval": 60000 } }, "my_custom_server": { "command": "node", "args": ["/path/to/my-server.js"], "transport": "stdio" // 默认，可省略 } } }

3.3 会话连续性与操作员仪表盘

长期项目开发中，我们经常需要与AI进行多次、断续的会话。如何保持上下文连贯是个大问题。EVOKORE的会话连续性工具就是为了解决这个痛点。

• 会话清单：EVOKORE会为每次重要的交互会话生成一个清单文件，记录使用了哪些工具、产生了什么结果、当前的代码库状态等。这个清单文件存储在~/.evokore/目录下。
• Claude记忆同步：对于Claude Desktop这类支持记忆功能的客户端，EVOKORE提供了钩子，将会话的关键信息同步到Claude的记忆中。这样，即使你隔了一天再打开Claude继续工作，它也能回忆起上次会话的进度和决策。
• 操作员仪表盘：运行npm run dashboard会启动一个本地Web服务。这不仅仅是一个审批界面。它是一个综合性的操作中心。在这里，你可以：
  • 实时查看所有活跃的MCP会话。
  • 审批待处理的工具调用请求。
  • 查看EVOKORE和各个子服务器的运行状态。
  • 浏览历史会话的清单和日志。
  • 执行repo:audit等运维命令。
• 仓库状态审计：npm run repo:audit是我在开始新一轮工作前必用的命令。它会检查Git仓库的状态：是否有分支偏离、工作区是否有未提交的更改、是否存在陈旧的临时分支、是否有已打开的Pull Request等。这能有效避免在多轮AI协作中产生的上下文混乱和状态冲突。

4. 从零开始的完整配置与集成指南

4.1 环境准备与项目初始化

首先，你需要一个Node.js环境（建议v18+）。然后克隆项目并安装依赖：

git clone <EVOKORE-MCP仓库地址> cd EVOKORE-MCP npm ci # 使用ci确保依赖版本锁一致，避免构建问题 npm run build # 编译TypeScript到dist目录

接下来是关键的配置环节。复制环境变量模板并填写你的密钥：

cp .env.example .env

用你喜欢的编辑器打开.env文件。以下是一些关键配置的说明：

# 必须：GitHub个人访问令牌，用于github服务器 GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxxxxxxxxxxx # 可选：ElevenLabs API密钥，用于语音合成 ELEVENLABS_API_KEY=sk_xxxxxxxx # 可选：Supabase访问令牌 SUPABASE_ACCESS_TOKEN=sbp.xxxxxxxx # --- 核心行为配置 --- # 工具发现模式：`legacy` 或 `dynamic` EVOKORE_TOOL_DISCOVERY_MODE=dynamic # RBAC角色：`admin`, `developer`, `readonly` EVOKORE_ROLE=developer # 是否启用技能文件监视器（开发时热重载有用） EVOKORE_SKILL_WATCHER=false # 子服务器启动超时时间（毫秒） EVOKORE_CHILD_SERVER_BOOT_TIMEOUT_MS=30000

注意：.env文件包含敏感信息，务必将其添加到你的.gitignore中，切勿提交到版本库。

4.2 配置子服务器与权限规则

EVOKORE的强大源于其聚合能力，这主要通过mcp.config.json和permissions.yml两个文件定义。

1. 配置mcp.config.json这个文件定义了你要聚合哪些子服务器。项目已经提供了一些示例。你需要根据实际情况调整。例如，一个基础的配置可能包含GitHub和文件系统：

{ "servers": { "github": { "command": "npx", "args": ["@modelcontextprotocol/server-github"], "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PERSONAL_ACCESS_TOKEN}" } }, "fs": { "command": "npx", "args": ["@modelcontextprotocol/server-filesystem"], "env": { // 可以指定允许访问的目录，增强安全性 "MCP_SERVER_FILESYSTEM_DIRECTORY": "/Users/yourname/Projects" } } } }

2. 配置permissions.yml这个文件定义了安全策略。它支持扁平化和基于角色的两种配置。一个基于角色的配置示例：

# 全局默认策略（当工具未在角色中明确列出时） default: deny # 角色定义 roles: admin: - allow: "*" # 管理员允许所有操作 developer: - allow: - "github_*" # 允许所有GitHub工具 - "fs_read*" # 允许所有fs读取工具 - require_approval: - "fs_write*" # 写入文件需要审批 - "fs_delete*" # 删除文件需要审批 - deny: - "fs_*" # 显式拒绝其他所有fs工具（兜底） readonly: - allow: - "github_search*" - "fs_list*" - "fs_read*" - deny: "*"

4.3 注册到你的AI客户端

这是最后一步，也是让一切生效的关键。你需要告诉你的AI客户端（如Claude Desktop、Cursor）去哪里找EVOKORE服务器。

通用方法（手动配置）： 找到你AI客户端的MCP服务器配置文件。例如，Claude Desktop的配置文件通常在~/Library/Application Support/Claude/claude_desktop_config.json（Mac）或%APPDATA%\Claude\claude_desktop_config.json（Windows）。在其中添加：

{ "mcpServers": { "evokore": { "command": "node", "args": ["/ABSOLUTE/PATH/TO/EVOKORE-MCP/dist/index.js"], "env": { // 可以在这里覆盖或补充环境变量 } } } }

便捷方法（使用同步助手）： EVOKORE提供了自动化脚本，可以帮你检测系统并尝试自动配置到支持的客户端：

# 先干跑，看看它会做什么 npm run sync:dry # 确认无误后执行 npm run sync

这个脚本目前支持自动配置 Claude Desktop、Cursor、Copilot CLI 等。对于其他客户端，如 Gemini CLI，脚本会输出需要手动执行的命令。

配置完成后，重启你的AI客户端。如果一切正常，你应该能在客户端的设置或连接信息中看到EVOKORE-MCP已成功连接。

5. 高级工作流与实战技巧

5.1 利用动态发现模式构建上下文感知的AI会话

动态模式是EVOKORE的精髓。以下是一个典型的使用场景：

1. 会话开始：你启动Claude，并连接上运行在dynamic模式的EVOKORE。初始工具列表很短，只有discover_tools、search_skills等原生工具。
2. 任务启动：你对Claude说：“帮我分析一下当前项目src/utils目录下的代码结构，看看有没有重复的函数。”
3. 工具发现：Claude意识到它需要文件系统遍历和代码分析工具。它调用discover_tools，并传入关键词：“filesystem, list, read, code, analysis”。
4. 动态激活：EVOKORE收到请求，在已注册的代理工具中搜索匹配项。它找到了fs_listDirectory、fs_readFile等工具，并将它们“激活”加入到当前Claude会话的工具列表中。
5. 任务执行：Claude现在拥有了所需的工具，开始递归列出目录、读取文件内容，并进行模式分析。
6. 会话隔离：与此同时，你可能在另一个ChatGPT会话中也连接着同一个EVOKORE实例。那个会话的工具列表仍然是初始状态，除非它也触发了自己的discover_tools调用。这实现了完美的资源与上下文隔离。

实操心得：为了让动态发现更精准，在创建自定义MCP服务器或技能时，务必在工具的description和name中使用清晰、相关的关键词。EVOKORE的搜索是基于这些元数据的。

5.2 技能创作与远程注册表管理

EVOKORE的技能系统让你可以封装复杂的多步骤操作为可复用的单元。

创建一个简单的技能： 技能通常放在项目的skills/目录下。一个最简单的技能结构如下：

# skills/my-first-skill/skill.yaml name: list_todo_files version: 1.0.0 description: 扫描指定目录，找出所有包含“TODO”或“FIXME”注释的文件。 author: Your Name runtime: nodejs@18 entrypoint: ./index.js inputSchema: type: object properties: directory: type: string description: 要扫描的目录路径 required: [directory]

// skills/my-first-skill/index.js export default async function ({ directory }, context) { const fs = context.fs; // 通过context获取注入的能力（如fs工具） const files = await fs.listDirectory(directory); const todoFiles = []; for (const file of files) { if (file.type === 'file' && (file.name.endsWith('.js') || file.name.endsWith('.ts'))) { const content = await fs.readFile(`${directory}/${file.name}`); if (content.includes('TODO') || content.includes('FIXME')) { todoFiles.push(file.name); } } } return { found: todoFiles.length, files: todoFiles }; }

发布到注册表： 你可以搭建一个简单的HTTP服务（甚至是一个Git仓库）作为技能注册表。在EVOKORE的配置中指向它。然后，AI就可以通过list_registry查看、通过fetch_skill拉取、并通过execute_skill运行这个技能了。

注意事项：技能在沙箱中运行，其能访问的资源受context对象限制。EVOKORE会向沙箱注入一些安全的工具句柄（如fs），但技能无法直接访问主进程的环境变量或文件系统，这保证了安全性。

5.3 语音集成与钩子系统

EVOKORE的语音侧车（VoiceSidecar）是一个独立运行的WebSocket服务，为AI交互增加了语音维度。

1. 启动侧车：npm run voice:sidecar。它会启动在ws://localhost:8888。
2. 配置语音工具：在mcp.config.json中配置elevenlabs服务器（需要API密钥）。EVOKORE会将它的工具（如text_to_speech）代理过来。
3. 钩子驱动：EVOKORE的核心原生工具在执行时，可以触发预定义的钩子（hooks）。这些钩子脚本位于scripts/目录下，可以执行任何操作，包括向VoiceSidecar发送消息，让其播放一段语音。
4. 应用场景：例如，你可以设置一个钩子，当execute_skill完成一个耗时很长的部署任务后，触发VoiceSidecar说一句“部署已完成”。或者，当有工具调用进入审批队列时，让语音提示你“有新的操作等待审批”。

配置示例（钩子）： 在scripts/目录下创建一个on_skill_executed.js文件：

// scripts/on_skill_executed.js export default async function (event) { if (event.skillName === 'deploy_production' && event.result.success) { // 调用VoiceSidecar播放语音 await fetch('http://localhost:8888/speak', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ text: '生产环境部署已成功完成。', voice: 'echo' }) }); } }

这个系统将视觉（仪表盘）、交互（AI聊天）、听觉（语音）打通，构建了一个多维度的AI操作环境。

6. 故障排查与效能优化指南

6.1 常见问题与解决方案

在实际部署和使用EVOKORE的过程中，你可能会遇到以下典型问题。这里我整理了排查思路和解决方法。

6.2 性能调优与最佳实践

要让EVOKORE在生产环境中稳定高效运行，以下几点经验值得参考：

1. 精简mcp.config.json只配置你真正需要的子服务器。每个额外的服务器都会增加内存占用和启动开销。特别是那些通过HTTP连接的外部服务，网络延迟会成为性能瓶颈。定期审查你的配置，移除不用的服务器。

2. 合理使用发现模式对于工具集固定且数量不多的场景，使用legacy模式即可，简单直接。对于工具数量庞大（超过20个）或希望AI会话保持高度上下文聚焦的场景，务必启用dynamic模式。这能显著提升AI的初始响应速度和工具调用的准确性。

3. 优化权限配置permissions.yml的匹配顺序是从上到下。将最具体、最常用的allow规则放在前面，将广泛的deny规则放在最后作为兜底。避免使用过多的通配符*，这可能会增加匹配开销并导致意外的权限覆盖。

4. 技能设计的优化

• 保持技能轻量：技能应专注于单一职责。复杂的流程可以拆分成多个技能链式调用。
• 善用缓存：如果技能需要频繁读取相同数据，可以考虑在技能内部实现简单的缓存逻辑，或者通过EVOKORE的会话状态来暂存数据。
• 清晰的错误处理：在技能代码中提供有意义的错误信息，这能帮助AI理解失败原因并采取纠正措施。

5. 监控与日志EVOKORE的运行日志是排查问题的金矿。建议在启动时重定向日志到文件，便于后续分析：

node dist/index.js > evokore.log 2>&1 &

定期检查日志文件，关注警告和错误信息。会话仪表盘也提供了运行时状态的可视化，养成定期查看的习惯。

6. 版本控制与回滚将你的EVOKORE配置（mcp.config.json,permissions.yml,.env.example）以及自定义技能纳入Git版本控制。在升级EVOKORE本体或任何子服务器版本前，创建一个标签或分支。如果新版本出现问题，可以快速回滚到已知稳定的状态。

经过数月的深度使用，EVOKORE-MCP已经从一个实验性项目演变为我AI增强工作流中不可或缺的基础设施。它的设计哲学——聚合、管控、扩展——精准地命中了当前MCP生态发展的关键节点。最大的体会是，它将我从繁琐的MCP服务器管理中解放出来，让我能更专注于定义AI能做什么，而不是折腾AI怎么连接。如果你正在构建严肃的、基于AI代理的自动化流程，投入时间学习和配置EVOKORE，其回报将是长期且显著的。