ultra-e2e-test tasks

mcp-server

タスク API を介して AI アシスタントに list_tasks、create_task、move_task の 3 つのツールを提供するMCPサーバーです。stdio 経由でプロトコルをやり取りするため、クライアントはサブプロセスとして起動します。

隣接するサービスと同じアーキテクチャを採用し、トランスポートを変更しています（ADR-0007）。src/domain にはルール、src/application にはアウトバウンドポートの背後にあるユースケース、src/adapters には外部と接する 2 つの要素、つまりタスク 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 がプロトコルのチャネルであり、たった 1 つの余計な 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 でプッシュされ、レジストリは io.github.<owner>/ 名前空間に対する GitHub の OIDC ID を信頼します。イメージは linux/amd64 と linux/arm64 向けに、それぞれネイティブランナーでビルドされ、1つのタグとして公開されるため、Apple Silicon 搭載 Mac でネイティブに動作します。2つのビルドは、<version>-amd64 と <version>-arm64 としてレジストリにも保持されます。プライベートリポジトリでは、無料枠を使い切ると arm64 ランナーで有料の Actions 分数が消費されます。

バージョンタグを作成する各リリースの後に実行され、バージョンを指定して手動で実行することもできます。最初のジョブは GitHub 環境 mcp-registry で実行されます。この環境は初回使用時に GitHub が作成します。ここで設定した必須レビュアー、または公開可能な refs の制限によって、公開処理全体が保留されます。初回のみ必要な設定は次のとおりです。

1. v* タグが存在するように、少なくとも1回リリースします（release 機能を使うか、gh release create でも実行できます）。
2. リポジトリ変数 MCP_PUBLISH_ENABLED=true を設定し、そのバージョンを指定してワークフローを1回手動で実行します。この初回実行は、最後のステップ Publish server.json to the 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

プロトコルは stdin と stdout を使うため、-i が重要です。