mcp-ticket-demo

MCP Ticket Demo — フルスタック MCP リファレンスサーバー

5 分以内に実行できる、本番環境を想定した MCP サーバーです。19 個のツール、3 個のリソース、5 個のプロンプト、3 種類の認証モード、API キー管理、ツールごとのアクセス制御、レート制限、リアルタイムのオブザーバビリティダッシュボード、そして VS Code／Bob／Cursor／Windsurf 向けのコントロールプレーン拡張機能が付属します。

MCP の学習、IDE 統合のテスト、ライブデモの実施に使ったり、独自サーバーを構築する際のリファレンス実装として活用したりできます。

プラットフォームとしての MCP：MCP サーバーのポートフォリオ構築から学んだこと に付随する講演です · MCP Dev Summit Toronto · 2026 年 10 月 5 日 · 講演スライド →

MCP サーバー (3.0.1)	npm install mcp-ticket-demo
VS Code 拡張機能 (1.16.0)	VS Code Marketplace · Open VSX
講演スライド	markusvankempen.github.io/linuxfoundation-mcp-dev-summit

個人のオープンソースプロジェクトです。

---

hello-world を超えて役立つ理由

ほとんどの MCP の例は、「文字列を返すツールはこちらです」で終わります。この例はさらに踏み込んでいます。

機能	学べること
意図が伝わる説明を持つ19個のツール	名詞はスキーマに、動詞はツールに置きます。request(path, method) ではありません
3つのリソース（ticket://、tickets://open、schema://）	resources/list でインスタンスを列挙し、読み取りには対応するツールと同じ gate() を使います
5つの MCP プロンプト	ユーザー向けプロンプトとエージェント向けツールの違い
ツールのアノテーション（readOnlyHint、destructiveHint、idempotentHint、openWorldHint: false）	クライアントでの確認・再試行の UX
サーバーの指示	モデルが実際に読む README
すべての失敗で isError: true	クライアントで ok: false を解析する必要がありません
帰属情報の欠落 — requester_email を指定しない create_ticket	201 では完了ではありません。チケットの所有者はボットです。
スキーマの検出 — get_schema → run_query	query_* という名前を並べるより、1つのクエリツールが優れています
検出されたツールが0個 — ノート PC のパスをクラウドランナーに渡す	エラーも警告もなく発生する、静かな失敗です
1つのコードベースから stdio、SSE、Streamable HTTP を提供	3つのトランスポートで同じ19個のツールを使えます
認証モード（off / write / all）＋ツールごとのゲート＋ツールごとの認証ロック	セキュリティは運用者が担うものです
管理者がゲートを切り替えたときの tools/list_changed ブロードキャスト	SSE と Streamable HTTP のセッションは更新されますが、1回限りの curl は更新されません
エラー内の retry_after_seconds によるレート制限	モデルがループ内で再試行し続けるのを防ぎます
run_query の schema=customers に対するPII のマスキング	同じツール、同じエンドポイントでも、pii スコープがなければ phone フィールドは REDACTED になります
/health と /test の違い	稼働中 ≠ 動作する。公開 /test は読み取り専用で、cwd は公開 /health に表示されません
ライブでの可観測性 — カウンター、エラーログ、呼び出しトレースを備えた /log ページ	モデルが実際に何をしているかを確認できます
MCP 経由での運用 — 設定（1つの update_settings パッチ）、ユーザー、API キー、設定のインポートはツールで操作し、設定のエクスポートには run_query schema=settings を使います。また、認証が off でも、その大半には admin スコープが必要です	コントロールプレーンはサーバーの一部であり、裏口ではありません
1つのサーバーを運用する3つの方法 — /admin の Remote config、拡張機能の Remote config タブ、mcp-ticket-demo コマンドライン	同じ手順、同じ Demo 設定を相互に照合します

---

クイックスタート — 5分

# Run directly from npm — no clone needed
npx mcp-ticket-demo           # stdio (IDE spawns this)
MCP_MODE=http npx mcp-ticket-demo  # HTTP — opens /health /test /admin /mcp

# Or clone and run
git clone https://github.com/markusvankempen/mcp-ticket-demo
cd mcp-ticket-demo/server && npm install && npm run http

次に、ブラウザーで以下を開きます。

URL	表示内容
http://127.0.0.1:8787/health	プロセスは稼働していますか？（cwd は localhost の場合のみ）
http://127.0.0.1:8787/test	読み取り専用のスモークテスト：チケット、スキーマ、run_query のシードデータ
http://127.0.0.1:8787/admin	認証モード、API キー、ツールゲート、可観測性
http://127.0.0.1:8787/log	呼び出しカウンター、エラーログ、完全な呼び出しトレース
http://127.0.0.1:8787/tools	スコープと認証状態を含むツール一覧

ターミナルから

同じ mcp-ticket-demo コマンドは、ローカルまたはデプロイ済みの実行中サーバー向けのクライアントとしても使えます。引数を指定しない場合は引き続き MCP サーバーとして動作するため、以下の IDE 設定もそのまま使えます。

npx mcp-ticket-demo status                                    # http://127.0.0.1:8787/mcp by default
npx mcp-ticket-demo call run_query schema=tickets 'filter={"status":"open"}' limit=5   # any tool, values typed from its schema
npx mcp-ticket-demo demo apply --user demo --password demo    # users, keys, auth write, 30 calls / 60 s
npx mcp-ticket-demo demo check --user demo --password demo    # acts as each role and as nobody
npx mcp-ticket-demo status --url https://my-host.example.com  # a deployed server

--json はスクリプト向けに1つのドキュメントを出力します。終了コードは 0 が完了、1 が拒否、2 が使用方法の誤り、3 が接続不能です。削除や再設定を行うコマンドは、最初に確認を求めます。すべてのコマンド、オプション、使用例は server/README.md に記載されています。稼働中のサーバーでは /clients/cli.html にコピー＆ペースト用のページがあります。demo apply は実際の設定を変更するため、自分が所有するサーバーで使用してください。

ノート PC でのログイン情報は demo / demo です。公開バインド（HOST=0.0.0.0、コンテナー、Code Engine）では ADMIN_PASSWORD を設定してください。デフォルトでは無効になっています。書き込みスモークテストは、管理者としてサインインした後に /test?write=1 で実行できます。

---

IDE に追加する（1 行）

VS Code / GitHub Copilot — .vscode/mcp.json：

{
  "servers": {
    "mcp-ticket-demo": {
      "type": "stdio",
      "command": "npx",
      "args": ["mcp-ticket-demo"],
      "env": { "MCP_MODE": "stdio" }
    }
  }
}

Bob / Cursor / Windsurf — .bob/mcp.json / .cursor/mcp.json / .windsurf/mcp.json：

{
  "mcpServers": {
    "mcp-ticket-demo": {
      "command": "npx",
      "args": ["mcp-ticket-demo"],
      "env": { "MCP_MODE": "stdio" }
    }
  }
}

または、拡張機能をインストールして すべての IDE にサーバーを登録 をクリックすると、4 つの設定を一度に書き込みます： VS Code Marketplace · Open VSX

---

ツール

サーバーには 19 個のツールがあります。そのうち 6 個は以下のチケットデスク用です。8 個はサーバー自体を操作します：update_settings（認証モード、レート制限、呼び出しトレース、デスクのサインイン、トランスポート、イベント、ゲート、ロック、スコープなど、すべての設定を 1 つのパッチで更新）、set_mqtt、ユーザー、API キー、import_settings、サンプルトラフィックです。これらの大半は、認証が off の場合でも admin スコープが必要です。各ツールのスコープについては server/README.md をご覧ください。タイマー用のツールは 3 個あり、start_timer、stop_timer、push_timer です。get_timer はありません（push_timer はタイマーをイベントとしてストリーミングすることもできます。イベントを参照）。タイマーはスキーマを介して、schema=timers を指定した run_query で読み取ります（server/README.md）。push_log はログ行をイベントとして送信し、watch_system はコンテナーの cgroup 制限を含むマシン情報を system.info として公開します。単なるリストはそれ自体がツールではありません。run_query で settings（保存済み設定。そのままインポート可能）、system（マシン）、events（送信済みのイベント）を読み取れます。また、管理者の認証情報があれば、users、api_keys、trace、errors、counters も読み取れます。/clients/dashboard.html のページにこれらが表示されます。これらのツールはそれぞれ一度だけ定義され、その他すべてはその定義から生成されます。

チケットデスク（6 個）

ツール	スコープ	使用する場面	教訓
describe_server	read	最初の呼び出し時、および拒否された後	推測するより確認する
create_ticket	write	チケットを作成する — 必ず requester_email を渡してください	省略すると → 201 + ボットがチケットを所有
add_comment	write	既知のチケットにコメントする	書き込みツール。ゲートあり
close_ticket	write	チケットを解決する。必要に応じて解決メモを追加	destructiveHint: true, idempotentHint: true
get_schema	read	クエリの前に呼び出す	name を指定しないと、すべての名前と種類（data、query、tool）を一覧表示します。name を指定すると、その形状または引数を返します
run_query	read	唯一のクエリツール：schema=tickets（status / requester_email / query で検索、または本文とコメントを含むチケット 1 件を id で取得）、schema=customers（pii スコープがない場合、電話番号は REDACTED）、さらに assets、timers、system、settings、events（管理者の場合は users、api_keys、trace、errors、counters も）	スキーマには名詞、ツールには動詞を使います。query_tickets / query_assets / … を置き換えます

---

リソース（3 個）

リソースはアドレス指定可能で、ピン留めできます。クライアントは購読して更新できます。ツールはエージェントのループで使用します。

URI	返される内容	同じゲート
ticket://TCK-1001	ID で指定した 1 件のチケット	run_query
tickets://open	リアルタイムのオープンチケット一覧（上位 25 件）	run_query
schema://tickets	クエリスキーマの形状（customers、assets も同様）	get_schema

resources/list を呼び出すと一覧を参照できます。URI を事前に知っておく必要はありません。読み取りを拒否された場合は JSON-RPC エラーが返されます（ピン留め可能な偽のチケットドキュメントではありません）。

---

5 プロンプト

ユーザー向けプロンプト — ユーザーが選び、モデルが実行します。

プロンプト	学べること
search-open-tickets	ライブデータからサービスアカウントの痕跡を見つける
attribution-scar	requester_email を指定せずに作成し、何が壊れたかを説明する
schema-discovery	get_schema（名前なし）→ get_schema（名前あり）→ run_query の手順
close-ticket-flow	add_comment の後に close_ticket を順番に実行する
diagnose-server	describe_server — 認証モード、スコープ、利用可能なツール

---

認証モデル

off    All tools open. No credential needed. Default for local dev.
write  Read tools open. Write tools need a credential. The customer phone shows only with a `pii` credential.
all    Every tool call requires a credential.

認証情報：HTTP では Authorization: Bearer <api key>、stdio では環境変数 MCP_API_KEY を使用します。

/admin でキーを発行し、モードを設定し、ツールごとのゲートを切り替え、個々のツールをロックできます。 変更は、接続中の SSE および Streamable HTTP セッション（initialize の後の Cursor/Bob）に notifications/tools/list_changed をブロードキャストします。単発の POST /mcp（curl）にはセッションがないため、次の呼び出しで新しいリストが反映されます。

---

リポジトリの構成

mcp-ticket-demo/
  server/       MCP server — tools, resources, prompts, auth, HTTP pages
    src/cli/    The command line client (mcp-ticket-demo <command>)
    clients/    Copy-paste setup pages served at /clients/ (editors, browser, CLI, settings)
  extension/    VS Code / Bob / Cursor / Windsurf control-plane extension (packs a copy of server/)
  docs/         Walkthroughs, lessons learned, publishing guide
  Dockerfile    node:20-bookworm-slim, non-root USER node, WORKDIR /app

---

ドキュメント

ドキュメント	内容
docs/README.md	サーバー 3.0.1 と拡張機能 1.16.0 向けの各ガイドのインデックス
docs/DEMO.md	エンドツーエンドのデモガイド — 実際の出力を記録した、全レッスンを網羅する16個のライブ curl デモ
docs/LESSONS-LEARNED.md	実際の MCP サーバーを構築して学んだ15の教訓 — 実体験と公開前チェックリスト
docs/LOCAL.md	ローカルの stdio と HTTP の手順
docs/REMOTE.md	Code Engine へのデプロイと、ツールが1つも検出されない問題の再現
docs/ADMIN-AND-SECURITY.md	認証モード、API キー、ツールゲート
docs/BOB.md	IBM Bob 固有の設定
docs/PUBLISHING.md	npm、MCP Registry、VS Code Marketplace への公開手順
docs/EXTENSION.md	VS Code / Cursor / Bob 拡張機能 — タブ、リモート設定、コマンド
server/README.md	各エンドポイントとコマンドラインクライアントの curl リファレンス

---

環境変数

変数	デフォルト	説明
MCP_MODE	stdio	stdio または http
PORT	8080	HTTP 専用です。npm run http では 8787 を使用します
HOST	127.0.0.1	コンテナ内では 0.0.0.0（自動設定）
AUTH_MODE	off	off · write · all
ADMIN_USER / ADMIN_PASSWORD	demo / demo	/admin へのログイン。公開アドレスへのバインド時は、ADMIN_PASSWORD が設定されるまでデフォルトで無効です
CORS_ORIGINS	未設定	/mcp で許可する追加の Origin 値。localhost と同一ホストは常に許可されます
API_KEY / API_KEY_SCOPES	未設定	起動時に1つのキーを登録します
MCP_API_KEY	未設定	stdio の認証情報。コマンドラインクライアントはベアラーキーとして送信します
MCP_USERNAME / MCP_PASSWORD	未設定	stdio の基本認証。コマンドラインクライアントは HTTP Basic として送信します
MCP_URL	http://127.0.0.1:8787/mcp	コマンドラインクライアント専用：接続先サーバー
MCP_USERS	未設定	追加ログイン "alice:secret:read,write"
RATE_LIMIT / RATE_LIMIT_WINDOW_MS	60 / 60000	呼び出し元ごとのウィンドウあたりの呼び出し回数
TENANT_ID	未設定	設定されている場合、書き込みには x-tenant-id ヘッダーが必要です

---

正直な制約事項

• チケットはメモリ上に保存されます。新しいコンテナーはシードデータから開始します。
• 管理者認証はセッション Cookie を使用し、SSO ではありません。Cookie は HttpOnly で、HTTPS では Secure になります。
• /health が正常でも、チケットが適切な担当者に届いたとは限りません。
• 公開されている /test はチケットを作成もクローズもしません。管理者としてサインインした後に /test?write=1 を使用してください。
• リモート設定、拡張機能の「リモート設定」タブ、コマンドラインからは、接続先のサーバー上の実際の設定（認証モード、ユーザー、キー、レート制限）を変更できます。デモのセットアップは、ご自身が所有するサーバーで使用してください。

---

作者： Markus van Kempen · [email protected] · markusvankempen.github.io · MCP Dev Summit Toronto 講演 · 講演スライド · npm · VS Code Marketplace · Open VSX