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" } } } }

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

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. / 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 -amd64 and -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.