evc-mesh-mcp

EVC Mesh MCP Server

通过 MCP 为由人类和 AI Agent 组成的团队提供任务、评论、共享记忆和交接功能。

EVC Mesh 是一款开源任务管理器，专为人类和 AI Agent 并肩协作的团队打造。这个 Model Context Protocol 服务可将你的 Agent 连接到 Mesh 工作区：它可以领取分配的任务、开始处理工作、发表评论、推动任务在工作流中流转、将工作交接给队友，并将决策保存在共享项目记忆中。

提供两种工具配置：core（26 个工具，适用于日常任务）和 full（69 个工具，包含周期性任务、文档和工作区管理）。每个工具都标记为只读或写入，因此客户端可以在进行更改前征求确认。

你需要一个 Mesh 工作区和从中获取的 Agent 密钥。Mesh 可自托管（采用 Apache-2.0 许可证，可在 evc-mesh 仓库中通过 docker compose 配置）。将 MESH_API_URL 设置为你的实例地址，并将 MESH_AGENT_KEY 设置为 Agent 的密钥。托管实例上的工作区仅限受邀者使用。

支持 Cursor、Cline、OpenClaw 和其他 MCP 客户端。

这是目前积极开发的版本。 evc-mesh 也随附一个 MCP 服务（./cmd/mcp，使用相同的 internal/mcp 工具集），并自行构建和部署它——这两个版本之所以同时存在，是因为 Go 的 internal/ 可见性规则使一个仓库无法导入另一个仓库的包，而不是因为它们计划各自发展。新工具和修复会优先在此处发布。

前提条件

• Go 1.22+
• 正在运行的 EVC Mesh 实例
• 在 Mesh 中注册且拥有 API 密钥（agk_...）的 Agent

安装

go install github.com/entire-vc/evc-mesh-mcp@latest

或者从源代码构建：

git clone https://github.com/entire-vc/evc-mesh-mcp.git
cd evc-mesh-mcp
go build -o evc-mesh-mcp .

Docker

docker run -i --rm \
  -e MESH_API_URL \
  -e MESH_AGENT_KEY \
  ghcr.io/entire-vc/evc-mesh-mcp

必须使用 -i——服务通过标准输入输出（stdio）使用 MCP 通信，而 Docker 只有在容器以交互模式运行时才会连接标准输入。镜像默认使用 core 配置；添加 -e MESH_MCP_PROFILE=full 可启用所有工具（见下方的工具配置）。每次发布带标签的版本时，都会从本仓库中的 Dockerfile 构建并发布适用于 linux/amd64 和 linux/arm64 的镜像（docs/RELEASING.md）。

工具配置

MCP 服务支持两种配置，以优化上下文窗口使用：

配置	工具数	上下文开销	适用场景
core	26	~8K tokens（占 200K 的 4%）	Claude Code、Cursor、小上下文模型
full	69	~18K tokens（占 200K 的 9%）	高级用户、自动化 Agent、管理操作

通过 MESH_MCP_PROFILE 环境变量设置。默认值：二进制文件为 full，Docker 镜像为 core（设置 -e MESH_MCP_PROFILE=full 可切换）。

配置

变量	必填	默认值	说明
MESH_API_URL	是	http://localhost:8005	Mesh API 的基础 URL
MESH_AGENT_KEY	是（stdio）	—	Agent API 密钥（agk_...）
MESH_MCP_PROFILE	否	full（Docker 镜像：core）	stdio 的工具配置：core 或 full（SSE 同时提供两者）
MESH_MCP_TRANSPORT	否	stdio	传输模式：stdio 或 sse
MESH_MCP_HOST	否	0.0.0.0	SSE 服务绑定的主机
MESH_MCP_PORT	否	8081	SSE 服务绑定的端口
MESH_MCP_AUTH_FAIL_RPM	否	20	SSE 模式：针对尚未缓存的 Agent 密钥，在 /sse、/core/sse、/mcp、/mcp/core 上进行身份验证尝试时，每个 IP 的额度。超出额度 → 429，且不会调用 Mesh API。0 表示禁用。
MESH_MCP_SESSION_CACHE_TTL_MIN	否	15	SSE 模式：成功通过身份验证后，在重新检查密钥前信任该身份的时长——这限制了密钥被撤销后，在无需重启的情况下仍可使用的时间。
MESH_MCP_AUTH_FAIL_CACHE_SEC	否	30	SSE 模式：记住身份验证失败（密钥错误或未知）的时长，避免每次请求都因重复使用同一个错误密钥而调用 Mesh API。
MESH_MCP_PUBLIC_URL	否	MESH_MCP_PUBLIC_URL 的源站	SSE 模式：从外部访问 MCP 根路径所用的 URL，例如 https://mesh.example.com/mcp。用于生成绝对 SSE 端点和 OAuth 资源 URL（参见 OAuth）。未设置时：根据每个请求的主机推导，只有客户端直接访问此服务时才正确——如果服务位于代理之后，请设置此变量，否则推导出的 core URL（/core）将与公开 URL（/mcp/core）不一致。
MESH_MCP_OAUTH_ISSUER	否	MESH_MCP_PUBLIC_URL 的源站	SSE 模式：受保护资源元数据中指定的 OAuth 授权服务器——即 Mesh 实例的公开源站。仅当 MCP 服务与 Mesh API 的源站不同时才设置。
MESH_MCP_OAUTH_CACHE_TTL_SEC	否	60	SSE 模式：在再次向 Mesh API 验证之前，信任已验证 OAuth 访问令牌的时长。该时长刻意远短于 Agent 密钥的 TTL，因此授权被撤销后，大约一分钟内就会停止生效。
MESH_MCP_DECIDER_USERNAME	否	—	record_owner_decision 为受门控任务作答时，记录为 decided_by 的用户名。未设置时：使用工作区所有者。
MESH_MCP_LEGACY_TOOL_ALIASES	否	关闭	设置为 1 时，也会注册工具的旧名称，供仍在使用旧名称的部署调用方使用。新安装请保持关闭。

无凭据运行

在 stdio 模式下，即使未设置 MESH_AGENT_KEY，服务也会启动。此时它会照常响应 initialize 和 tools/list，并在每次工具调用时返回设置 MESH_API_URL 和 MESH_AGENT_KEY 的说明。这样，MCP 客户端和目录就可以在你获得密钥之前查看工具列表。如果已设置密钥，但启动时身份验证失败（API 无法访问或密钥被拒绝），服务仍会继续运行：工具会列出，每次调用都会重试身份验证，并在成功前返回失败原因。

工具注解

每个工具都会声明 MCP 提示 readOnlyHint、destructiveHint、 idempotentHint 和 openWorldHint，因此客户端可以区分只读工具 （get_*、list_*、recall、search_docs……）与会更改或 删除数据的工具（update_*、move_task、forget……）。

客户端指标

每次 initialize 都会记录客户端的 clientInfo.name 和版本， 并计入 Prometheus 指标 mesh_mcp_initialize_total{client,profile} （SSE 模式下通过 /metrics 暴露；客户端名称会经过规范化并设有长度上限）。

Claude Code（stdio 模式）

将以下内容添加到项目的 .mcp.json：

{
  "mcpServers": {
    "evc-mesh": {
      "command": "evc-mesh-mcp",
      "env": {
        "MESH_API_URL": "https://your-mesh-instance.example.com",
        "MESH_AGENT_KEY": "agk_your-workspace_your-key",
        "MESH_MCP_PROFILE": "core"
      }
    }
  }
}

Cursor

添加到 Cursor MCP 设置中（设置 → MCP 服务器）：

{
  "evc-mesh": {
    "command": "evc-mesh-mcp",
    "env": {
      "MESH_API_URL": "https://your-mesh-instance.example.com",
      "MESH_AGENT_KEY": "agk_your-workspace_your-key",
      "MESH_MCP_PROFILE": "core"
    }
  }
}

SSE 模式（多 Agent，共享服务）

用于通过共享 MCP 端点连接多个 Agent：

MESH_API_URL=https://your-mesh-instance.example.com \
MESH_MCP_PORT=8081 \
evc-mesh-mcp --transport sse

SSE 模式会在不同路径上同时提供 两种配置：

路径	配置	描述
/sse + /message	full	全部 69 个工具（向后兼容）
/core/sse + /core/message	core	26 个基本工具

同一进程也会提供 Streamable HTTP 传输（无状态，每个请求使用一个 Agent 密钥，通过 Authorization: Bearer 或 X-Agent-Key 标头发送——此处不接受查询参数）：

路径	配置
/mcp	full
/core	core

每个连接通过以下方式进行身份验证：

• Authorization: Bearer agk_... 标头
• X-Agent-Key: agk_... 标头
• ?agent_key=agk_... 查询参数（仅用于 SSE 连接）
• Authorization: Bearer mot_...——由你的 Mesh 实例签发的 OAuth 访问令牌（见下文）；仅限标头，绝不能放在查询字符串中，且仅用于 Streamable HTTP 端点（SSE 连接需要 Agent 密钥）

OAuth（远程连接器）

使用 OAuth 登录用户的客户端——远程连接器目录、MCP Inspector，以及遵循 MCP 授权规范的编辑器——无需预共享密钥即可连接到 Streamable HTTP 端点。你的 Mesh 实例是 授权服务器（动态客户端注册、PKCE、用户同意）；此服务是资源服务器，并负责两项工作：

• 发起质询。 对于未提供凭据的请求，或使用 Mesh API 拒绝的 OAuth 访问令牌（已过期、已撤销、从未签发）发出的请求，会返回 401 和

  WWW-Authenticate: Bearer resource_metadata="https://mesh.example.com/.well-known/oauth-protected-resource/mcp", scope="mesh"
  

  客户端会据此开始授权流程。被拒绝的 Agent 密钥仍返回 403。只有 Mesh API 返回的判定（除 408/429 外的 4xx）才会使令牌失效：如果无法访问 Mesh API，或其返回的错误与令牌无关（5xx、429），则会返回带有 Retry-After 的 503，避免因服务中断而丢弃有效令牌。

• 提供元数据（RFC 9728），路径根据各端点的 URL 推导，位于众所周知的路径：

  端点	元数据
  https://mesh.example.com/mcp（full）	/.well-known/oauth-protected-resource/mcp
  https://mesh.example.com/mcp/core（core）	/.well-known/oauth-protected-resource/mcp/core

  {
    "resource": "https://mesh.example.com/mcp",
    "authorization_servers": ["https://mesh.example.com"],
    "scopes_supported": ["mesh"],
    "bearer_methods_supported": ["header"]
  }
  

  resource 为 MESH_MCP_PUBLIC_URL（去除末尾斜杠、查询参数和片段；core 配置会追加 /core），因此请将其设为用户粘贴到客户端中的 URL。 授权服务器默认使用该 URL 的源；可通过 MESH_MCP_OAUTH_ISSUER 覆盖。

OAuth 令牌会作为连接器 Agent，在用户授予访问权限时选择的工作区中运行，并拥有该 Agent 的权限——与 Agent 密钥使用相同的工具和权限模型。已验证的令牌会缓存一分钟（MESH_MCP_OAUTH_CACHE_TTL_SEC）。每 IP 预算（MESH_MCP_AUTH_FAIL_RPM）仅在令牌被拒绝时扣减，而非在验证时扣减，因此，共用一个地址的许多用户不会因各自刷新令牌而受到限流。令牌不绑定受众：你的 Mesh 实例签发的任何有效访问令牌都会被接受，这是授权服务器和此服务属于同一部署时的预期行为。Authorization 或 X-Agent-Key 中的 Agent 密钥（agk_...）仍按原样工作，stdio 模式不受影响。

你的反向代理必须将 /.well-known/oauth-protected-resource* 转发到此服务，而非 Web 应用的兜底路由：单页应用会对每个未知路径返回 200 text/html，客户端无法将其与缺失的元数据区分开来。

Agent Context Protocol（ACP）

会话开始时，按顺序执行以下 5 个步骤：

1. heartbeat(status="online")              → register as alive
2. get_project_knowledge(project_id)       → load accumulated decisions & conventions
3. get_my_rules(project_id)                → understand constraints
4. get_context(project_id)                 → see recent activity + project knowledge
5. get_my_tasks()                          → check assigned work

会话结束时：

publish_event(type="summary", memory={persist: true})  → broadcast + persist
session_report(model, tokens_in, tokens_out)           → report metrics

MCP 工具 — Core 配置（26）

ACP 与身份

工具	描述
heartbeat	发送心跳。在会话开始时使用 status=online 调用。响应包含 mesh_version（运行中二进制文件的构建 git-SHA；如果是未固定的本地构建，则为 "dev"）——无需通过 Shell 调用主机，即可快速检查修复是否已进入已安装的二进制文件。
get_project_knowledge	获取所有永久知识（决策、约定）。ACP 第 2 步
get_my_rules	获取所有治理规则（工作流 + 分配）。ACP 第 3 步
get_context	获取近期活动 + 项目知识。ACP 第 4 步
get_my_tasks	获取分配给自己的任务，包含完整描述和可选的无损条件响应。ACP 第 5 步

任务管理

工具	描述
list_projects	列出工作区项目
list_tasks	按筛选条件列出任务（状态、优先级、受派人、搜索）
get_task	获取任务详情，可选择包含评论、制品和依赖项
create_task	创建新任务
update_task	更新任务字段
move_task	使用 slug 更改任务状态
assign_task	分配或取消分配任务
get_task_context	一次调用即可获取任务的所有信息
add_vcs_link	将任务关联到拉取请求、提交或分支

通信

工具	描述
add_comment	向任务添加评论（Markdown）。响应包含一个 delivery 数组，逐条报告 @ 提及是否确实送达接收者（任务队列/通知），或是否被跳过/发送失败及原因
publish_event	发布事件 + 可选的记忆提示，以便持久化

记忆

工具	描述
recall	按关键词搜索记忆（默认精简：每项约 300 个字符；full=true 可获取未截断的全部内容）
get_memory	根据确切键获取一条记忆的全文
remember	保存知识（按键执行 UPSERT）
forget	删除记忆条目
recall_with_graph	搜索记忆，并通过知识图谱扩展结果
set_project_knowledge	写入结构化项目事实（按键执行 upsert）
get_canonical_updates	获取指定时间之后记录的规范决策
record_owner_decision	将工作区所有者的决策记录为规范项目知识

recall 对其结果的保证

limit 是硬性上限。 响应中的条目不会超过 limit，且 total 始终等于实际返回的条目数。页面确定大小后，不会再添加任何内容——既不会添加置顶行，也不会添加图谱扩展的邻居。

不符合 scope/tags/tags_any 条件的行会被剔除，绝不会在未标记的情况下返回。 无论某行是通过何种方式进入结果，普通检索、置顶还是图谱扩展，都遵循这一规则。置顶行豁免于排序，而不是豁免于符合条件——“置顶”的意思是“不要让排序把它埋没”，而不是“向要求其他 scope 的调用者展示它”。

图谱邻居会被标记并受到数量限制。 当 RECALL_GRAPH_ENABLED=true 时，recall 还会执行知识图谱扩展，并纳入 hop > 0 的邻居；每个邻居都会带有 graph_boost: true 和 provenance: via:graph。它们最多占据页面的 limit/4（当 limit >= 2 时至少为 1 个；当 limit < 2 时为 0 个），并占用页面末尾的槽位，替换掉较弱的检索结果，而不是在其上追加。当扩展没有返回可用内容时，页面与基础结果完全一致——预留量是上限，不是配额。graph_boost_count 会报告实际占用的槽位数。

设置预留量是因为基础结果带有 score（各检索分支上的 RRF 分数），而邻居带有来自单独遍历过程的 composite_score——字段不同，量级也不同。用共同的键对两者合并排序，并不能平衡它们；实际上，所有观察到的邻居排名都低于所有基础结果，因此简单的归并排序会在不知不觉中禁用图谱加权。预留量明确体现了这一权衡，也使其可调。

预设不会凌驾于你的设置之上。 recall 会对查询分类，并可能应用配置档案（例如，多会话场景会扩大页面）。配置档案只会补充你未提供的参数；显式指定的 limit 始终优先。

实用工具

工具	描述
report_error	报告任务中的错误
session_report	报告会话指标（模型、令牌、成本）

MCP 工具 — 完整配置档案（新增 43 个，共 69 个）

其他任务工具

工具	描述
get_project	获取包含状态和自定义字段的项目详情
create_subtask	在父任务下创建子任务（status_slug 可选；默认使用项目的默认状态，而不是父任务的状态）
add_dependency	在任务之间添加依赖；可选的 condition（task_done、access_ready、contract_ready、artifact_published、shipped、deployed、accepted）用于指定 blocks 边等待的条件
update_dependency	设置现有依赖边的 condition / evidence_url；对于非 task_done 边，提供证据后，即使阻塞任务尚未完成，也会解除对依赖任务的阻塞
mark_vcs_deployed	在 PR 链接上记录一次部署（sha、env）：设置 deployed_sha / deployed_env / deployed_at，并解除等待 deployed 边的依赖任务
remove_dependency	移除依赖边（task_id 为被阻塞的任务，depends_on_task_id 为阻塞任务；必须填写 reason，且会记录该原因）
checkout_task	用于多 Agent 协作的原子任务锁
release_task	释放原子任务锁
extend_checkout	延长现有任务锁的时限，以支持耗时更长的工作
set_human_gate	暂停任务，直到指定人员回答已记录的问题（addressee 必须是人员；supersedes 和 canonical_key 用于处理已回答问题的重复提问）
clear_human_gate	解除人工关卡

评论和制品

工具	描述
list_comments	列出任务评论（默认按时间倒序）
upload_artifact	将文件/代码/日志上传到任务
list_artifacts	列出任务制品
get_artifact	获取制品详情（download_path；通过下方的两步下载获取字节）

下载制品

下载制品需要执行两次 GET。步骤 1：使用标头 X-Agent-Key: 向 /api/v1/artifacts//download 发送 GET 请求 -> 返回 200 和 JSON {"url": ""}。步骤 2：不带任何标头向该 url 发送 GET 请求 -> 返回 200 和文件字节。注意事项：步骤 1 仅接受 X-Agent-Key（X-API-Key 和 Authorization: Bearer 会返回 401）；步骤 2 中任何额外标头，尤其是 Authorization，都会导致预签名失效（400）。制品的 download_path 就是步骤 1 的路径。browser_only_url 是面向用户的页面，按设计会对 Agent 密钥返回 401。

事件总线

工具	描述
publish_summary	发布工作摘要（便捷封装）
subscribe_events	配置事件的 webhook 投递
poll_tasks	长轮询以获取新的任务分配

Agent 与团队

工具	描述
register_sub_agent	注册子 Agent
list_sub_agents	列出子 Agent（可递归）
get_team_directory	获取工作区团队目录
update_agent_profile	更新 Agent 角色、能力和个人资料

治理与配置

工具	描述
get_project_rules	获取所有项目规则
get_assignment_rules	获取任务分配规则
get_workflow_rules	获取调用方权限对应的工作流规则
import_workspace_config	从 YAML 导入工作区配置
export_workspace_config	将工作区配置导出为 YAML

周期性任务

工具	描述
create_recurring_task	创建周期性任务计划
list_recurring_schedules	列出周期性计划
get_recurring_history	获取某个计划的实例历史记录
trigger_recurring_now	立即触发下一个实例
update_recurring_schedule	更改或停用周期性计划
delete_recurring_schedule	删除周期性计划（现有实例会保留）

文档与知识

工具	描述
list_docs	列出项目文档（仅元数据）
get_doc	阅读文档（默认显示大纲，也可按需显示正文）
search_docs	在项目文档中进行全文搜索
create_doc	创建文档
update_doc	编辑文档（通过 base_version 实现乐观并发控制）
comment_doc	对文档或引用段落发表评论
list_doc_comments	阅读文档的评论串
post_project_update	将项目的每日状态报告发布到其 Updates 部分
get_project_updates	阅读项目的 Updates 动态，按时间从新到旧排列
get_canonical	查询主题相关的精选事实和决策

架构

AI Agent (Claude Code / Cursor / Cline / OpenClaw)
    ↕ MCP (stdio or SSE)
EVC Mesh MCP Server (core or full profile)
    ↕ REST API (HTTP)
EVC Mesh API Server
    ↕
PostgreSQL / Redis / NATS / S3

MCP 服务是一个轻量级代理，可将 MCP 工具调用转换为 REST API 请求。无需直接访问数据库。

运行共享 HTTP 服务

若要在一个进程中为多个 Agent 提供服务，请在 Mesh API 旁以 SSE 模式运行该服务 （可使用相同镜像：docker run -e MESH_MCP_TRANSPORT=sse -e MESH_API_URL=... -p 8081:8081 ghcr.io/entire-vc/evc-mesh-mcp），并将其置于 反向代理之后。它同时提供 SSE（/sse、/core/sse）和 Streamable HTTP（/mcp、/core）；每个连接或请求都使用各自的 Agent 密钥进行身份验证。 该服务自身不使用数据库：它会调用 Mesh REST API，因此 Mesh API 升级后也应升级该服务。

heartbeat 工具会返回 mesh_version，即运行中的二进制文件所基于的提交版本；--version 也会打印该版本。

技能和插件布局

此仓库遵循 Open Plugins 布局：plugin.json（清单）、mcp.json / .mcp.json（stdio 服务配置，值来自你的环境）以及 skills/：

技能	用途
mesh-tasks	会话启动协议、领取、更新和关闭任务
mesh-memory	remember / recall / forget 约定
mesh-coordination	团队目录、锁、事件、交接（完整配置）

此服务仅提供工具，不定义 MCP 提示词或资源。

相关项目

• evc-mesh — 核心平台（API + Web UI）
• evc-mesh-openclaw-skill — OpenClaw 技能（bash 脚本）

在其他目录中找到我们

许可证

MIT