ultra-e2e-test tasks

mcp-server

一个 MCP 服务，通过任务 API 为 AI 助手提供三个工具：list_tasks、create_task 和 move_task。它通过 stdio 使用该协议，因此客户端会将其作为子进程启动。

它采用与旁边的服务相同的架构，只更换了传输方式（ADR-0007）：src/domain 存放规则，src/application 存放通过出站端口实现的用例，src/adapters 存放与外部世界交互的两个部分——调用任务 API 的 HTTP 客户端，以及将用例发布为工具的 MCP 层——src/main.ts 负责将它们连接起来。当某一层越过其允许列表时，npm run check:boundaries 会使构建失败。

这里会重复这些规则，而不是从另一个模块导入（ADR-0004），这也有其必要：非法的状态变更会在此处被拒绝，并指出合法的变更，而不会以模型通常会重试的 409 错误返回给模型。

运行

npm install
npm start          # serves over stdio; the task API must be running

将其注册到客户端——对于 Claude Code，运行 claude mcp add tasks -- node /absolute/path/to/services/mcp-server/src/main.ts；对于其他客户端，则在其配置中添加等效条目：

{
  "mcpServers": {
    "tasks": {
      "command": "node",
      "args": ["/absolute/path/to/services/mcp-server/src/main.ts"],
      "env": { "TASK_API_URL": "http://localhost:8080" }
    }
  }
}

变量	默认值	含义
TASK_API_URL	http://localhost:8080	任务 API 的地址。必须是绝对 http 或 https URL
TASK_API_TIMEOUT_MS	10000	单次 API 调用在放弃前最多等待的时间

如果某个值无法使用，进程会在启动时停止。启动后每次工具调用都失败的服务，不如根本无法启动的服务：模型会不断重试。

绝不会向 stdout 写入任何内容。 对于 stdio 服务，stdout 是协议通道，一条意外的 console.log 就会破坏数据流。诊断信息会写入 stderr。

工具

工具	输入	返回内容
list_tasks	—	每个任务、其状态，以及该状态允许的变更
create_task	title	创建的任务，状态为 todo
move_task	id、status	已变更的任务，或说明当前状态允许哪些变更

调用方可以处理的失败情况——例如违反规则或 API 无法访问——会作为工具结果返回，并带有 isError: true 和失败原因。只有此处的程序错误才会抛出异常，因为抛出的错误会作为模型无法检查的协议错误传给模型。

检查

npm run verify    # import boundaries, type-check, tests

测试会通过一对内存传输通道，让真实 MCP 客户端驱动服务，因此已注册却无法调用的工具——例如模式错误或处理程序抛出异常——会在此处失败，而不是等到有人在编辑器中使用时才发现。

发布

.github/workflows/mcp-publish.yml 会将镜像发布到 GitHub Container Registry，并将 server.json 发布到 MCP Registry，客户端可在其中发现服务。它不会使用存储的令牌：镜像使用本次运行的 GITHUB_TOKEN 推送，注册表则信任 GitHub 的 OIDC 身份，用于 io.github.<owner>/ 命名空间。镜像针对 linux/amd64 和 linux/arm64 构建，每种架构都使用原生运行器，并发布为一个标签，因此可在 Apple Silicon Mac 上原生运行。两个构建也会以 <version>-amd64 和 <version>-arm64 的形式保留在注册表中。在私有仓库中，免费额度用完后，arm64 运行器会消耗付费 Actions 分钟数。

每次创建版本标签的发布完成后，工作流都会运行；也可以按需指定版本运行。第一个作业在 GitHub 环境 mcp-registry 中运行，该环境会由 GitHub 在首次使用时创建；在该环境中设置必需的审核者或允许发布的 refs 范围后，整个发布流程都会受到限制。一次性设置步骤：

1. 至少发布一次，以便创建 v* 标签（release 功能会创建该标签；也可以使用 gh release create）。
2. 将仓库变量 MCP_PUBLISH_ENABLED=true，然后手动使用该版本运行一次工作流。首次运行预计会在最后一步失败，即 将 server.json 发布到 MCP Registry，并显示 “is private or requires authentication”。此时镜像已推送，但 GitHub 会将新建的容器包设为私有，而注册表只接受任何人都能拉取的镜像。
3. 将软件包设为公开：在其页面中，选择 Package settings → Danger Zone → Change visibility → Public。该软件包为 OWNER/ultra-e2e-test-mcp-server，列在仓库的 Packages 下。注册表会读取镜像的 io.modelcontextprotocol.server.name 标签，以确认你拥有该镜像；私有镜像无法通过此验证。继续之前请检查：执行 curl -s -o /dev/null -w '%{http_code}\n' "https://ghcr.io/token?scope=repository:OWNER/ultra-e2e-test-mcp-server:pull"；软件包公开后会输出 200，仍为私有时则会输出 401。
4. 重新运行该次运行中失败的作业（Re-run failed jobs）。它会发布 server.json，之后的每次发布都会自动完成发布。

test/server-json.test.ts 会确保清单内容准确：镜像标签必须与服务的 name 相同，且每个声明的变量都必须是 src/config.ts 会读取的变量，并且使用其实际采用的默认值。

容器

docker build --tag mcp-server .
docker run --rm -i --env TASK_API_URL=http://host.docker.internal:8080 mcp-server

-i 很重要：协议通过 stdin 和 stdout 传输。