ultra-e2e-test tasks

mcp-server

An MCP server that gives an AI assistant three tools over the task API: list_tasks, create_task and move_task. It speaks the protocol over stdio, so a client starts it as a subprocess.

It is the same architecture as the services beside it, with the transport changed (ADR-0007): src/domain holds the rules, src/application the use cases behind an outbound port, src/adapters the two things that touch the outside world — the HTTP client that calls the task API, and the MCP layer that publishes the use cases as tools — and src/main.ts wires them. npm run check:boundaries fails the build when a layer reaches past its allowlist.

The rules are repeated here rather than imported from another module (ADR-0004), and they earn their place: an illegal status move is refused here, with the legal moves named, instead of reaching the model as a 409 it usually retries.

Run it

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

Register it with a client — for Claude Code, claude mcp add tasks -- node /absolute/path/to/services/mcp-server/src/main.ts, or the equivalent entry in another client's configuration:

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

Variable	Default	Meaning
TASK_API_URL	http://localhost:8080	Where the task API is. Must be an absolute http or https URL
TASK_API_TIMEOUT_MS	10000	How long one API call may take before it is abandoned

A value it cannot use stops the process at startup. A server that starts and then fails every tool call is worse than one that never started: the model keeps trying.

Nothing is ever written to stdout. On a stdio server stdout is the protocol channel, and one stray console.log corrupts the stream. Diagnostics go to stderr.

Tools

Tool	Input	Answers with
list_tasks	—	Every task, its status, and the moves that status allows
create_task	title	The created task, in todo
move_task	id, status	The moved task, or which moves are legal from where it is

A failure the caller can act on — a broken rule, an unreachable API — comes back as a tool result with isError: true and the reason. Only a bug here throws, because a thrown error reaches the model as a protocol error it cannot inspect.

Check

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

The tests drive the server through a real MCP client over an in-memory transport pair, so a tool that is registered but unreachable — a bad schema, a handler that throws — fails here rather than in someone's editor.

Publish

.github/workflows/mcp-publish.yml publishes the image to GitHub Container Registry and server.json to the MCP Registry, where clients discover servers. It uses no stored token: the image is pushed with the run's GITHUB_TOKEN, and the registry trusts GitHub's OIDC identity for the io.github.<owner>/ namespace. The image is built for linux/amd64 and linux/arm64, each on a native runner, and published as one tag, so it runs natively on an Apple Silicon Mac. The two builds also stay in the registry as <version>-amd64 and <version>-arm64. In a private repository the arm64 runner uses paid Actions minutes once the free allowance is spent.

It runs after each release that creates a version tag, and on demand with a version. Its first job runs in the GitHub environment mcp-registry, which GitHub creates on first use; a required reviewer or a limit on which refs may publish, set there, holds the whole publish. One-time setup:

1. Release at least once, so a v* tag exists (the release feature does this; gh release create works too).
2. Set the repository variable MCP_PUBLISH_ENABLED=true, then run the workflow once by hand with that version. This first run is expected to fail at its last step, Publish server.json to the MCP Registry, with "is private or requires authentication". The images are pushed by then, but GitHub creates a new container package as private, and the registry only accepts an image anyone can pull.
3. Make the package public: on its page, Package settings → Danger Zone → Change visibility → Public. It is OWNER/ultra-e2e-test-mcp-server, listed under the repository's Packages. The registry reads the image's io.modelcontextprotocol.server.name label to confirm you own it, which it cannot do for a private image. Check before going on: curl -s -o /dev/null -w '%{http_code}\n' "https://ghcr.io/token?scope=repository:OWNER/ultra-e2e-test-mcp-server:pull" prints 200 once the package is public, and 401 while it is still private.
4. Re-run the failed job of that run (Re-run failed jobs). It publishes server.json, and every later release publishes on its own.

test/server-json.test.ts keeps the manifest honest in the meantime: the image label must equal the server's name, and every advertised variable must be one src/config.ts reads, with the default it really uses.

Container

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

-i matters: the protocol is stdin and stdout.