mcp-ts-template

---

説明できるものなら何でも AI ツールに

API、データセット、ワークフローを Model Context Protocol（MCP）経由で AI エージェントに接続できます。プロジェクトにはドメインコードを配置し、@cyanheads/mcp-ts-core が認証、ストレージ、ロギング、トランスポートを支えます。

エージェントネイティブ。 すべてのスキャフォールドには、フレームワークのリファレンスと一連のエージェントスキルが含まれます。これらは、ツールの設計、テストの作成、セキュリティのレビュー、リリースの実施に役立つワークフローです。サーバーの動作はあなたが決め、エージェントはスキルに従って構築します。

フレームワークは依存関係のままです。 インフラストラクチャの修正は、パッケージのアップグレードで取り込めます。maintenance スキルを実行すると、エージェントがコアを更新し、最新のスキルを同期して、変更内容を反映します。

クイックスタート

サーバーは Bun、Node.js 24+、または Cloudflare Workers で実行できます。

bunx @cyanheads/mcp-ts-core init my-mcp-server
cd my-mcp-server
bun install

スキャフォールドには、ソースツリー、ビルドとテストの設定、CLAUDE.md/AGENTS.md、エージェントスキル、Claude Code と Codex 用のプラグインメタデータが含まれています。Claude Code、Codex、または別のエージェントで開き、作りたいものを説明してください。

チームの在庫 API 用の MCP サーバーを構築してください。商品の検索、倉庫ごとの在庫確認、在庫移動の調査、調整と移動の記録が必要です。始めましょう。

すでに TypeScript プロジェクトがある場合は、bun add @cyanheads/mcp-ts-core を実行し、createApp() で定義を登録してください。

ツールはスキーマと関数で構成されます

これは、3 項目のカタログを検索する完全なサーバーです。試すには、スキャフォールドの src/index.ts を次の内容に置き換えてください。

import { createApp, tool, z } from '@cyanheads/mcp-ts-core';

const catalog = ['Notebook', 'Mechanical pencil', 'Desk lamp'];

const search = tool('catalog_search', {
  description: 'Search catalog item names. An empty query lists all items.',
  annotations: { readOnlyHint: true },
  input: z.object({
    query: z.string().describe('Text to find in an item name'),
  }),
  output: z.object({
    items: z.array(z.string()).describe('Matching item names'),
  }),
  async handler({ query }) {
    return {
      items: catalog.filter((name) =>
        name.toLowerCase().includes(query.toLowerCase()),
      ),
    };
  },
});

await createApp({ name: 'catalog-mcp-server', title: 'catalog-mcp-server', tools: [search] });

ビルドして HTTP 経由で実行します。

bun run rebuild
bun run start:http

MCP クライアントを http://127.0.0.1:3010/mcp（Streamable HTTP）に接続するか、クライアントから bun /absolute/path/to/dist/index.js を使って stdio 経由で起動してください。

含まれる機能

必要なこと	フレームワークが提供するもの
アシスタントに役立つ機能を提供する	ツール、リソース、プロンプト、インタラクティブな MCP Apps 用の型付きビルダー
エージェントが機能を正しく使えるようにする	サーバーの指示、結果の拡充、復旧ガイダンス付きの宣言型エラー
アクセスを制御し、状態を保持する	JWT/OAuth、定義ごとのスコープ、バックエンドを切り替え可能なテナントスコープのストレージ
ローカルで実行するか、サービスをホストする	Bun/Node.js 上の stdio と HTTP、Cloudflare Workers 用の独立したエントリーポイント
失敗を把握し、ミスを検出する	構造化ログ、オプションの OpenTelemetry、定義のリント、コントラクトテスト、ファズテスト

オプションのインテグレーション（DuckDB、Supabase、OpenTelemetry SDK）はピア依存関係です。必要に応じてインストールしてください。

エージェントに役立つ結果を返す

エージェントが受け取る内容は、2 つの宣言済みコントラクトによって決まります。enrichment には成功時のコンテキスト（合計数、解析済みのクエリ、結果が空の場合の通知）が含まれ、ctx.enrich() で設定します。errors には想定される各エラーとその復旧ガイダンスが記載され、ハンドラーは型付きの ctx.fail() でエラーをスローします。

runSearch(query, limit) は検索バックエンドの代わりとなるものです。{ items, total, parsed } を返すか、インデックスが停止している場合は null を返します。

import { createApp, tool, z } from '@cyanheads/mcp-ts-core';
import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';

const search = tool('search', {
  description: 'Search the catalog and return ranked matches.',
  annotations: { readOnlyHint: true },
  input: z.object({
    query: z.string().describe('Search terms'),
    limit: z.number().int().min(1).default(10).describe('Max results'),
  }),
  output: z.object({
    items: z.array(z.string()).describe('Matching item names, best first'),
  }),
  enrichment: {
    effectiveQuery: z.string().describe('Query as the server parsed it'),
    totalCount: z.number().describe('Total matches before the limit'),
    notice: z.string().optional().describe('Guidance when nothing matched'),
  },
  errors: [
    {
      reason: 'index_unavailable',
      code: JsonRpcErrorCode.ServiceUnavailable,
      when: 'The upstream search index is unreachable.',
      retryable: true,
      recovery: 'Retry in a few seconds — the index may be briefly unavailable.',
    },
  ],
  handler: async (input, ctx) => {
    const res = await runSearch(input.query, input.limit);
    if (!res) throw ctx.fail('index_unavailable');
    ctx.enrich({ effectiveQuery: res.parsed, totalCount: res.total });
    if (res.items.length === 0) {
      ctx.enrich({ notice: `No matches for "${input.query}". Try broader terms.` });
    }
    return { items: res.items }; // enrichment never rides in the domain return
  },
});

await createApp({ tools: [search] });

どちらのコントラクトも tools/list で公開されるため、クライアントは呼び出す前に内容を確認できます。また、定義リンターはハンドラーがコントラクトに準拠しているかをチェックします。宣言済みの理由を伴うエラーは、その項目の復旧ヒントとともにクライアントに届きます。また、すべてのツールエラーには、サーバーログの記録と共通するリクエスト ID が付与されます。

クライアントの各サーフェスで同じデータを表示する

MCP ホストによって、ツールの結果のうちエージェントに渡す部分は異なります。structuredContent（JSON）、content[]（テキスト）、またはその両方です。フレームワークは両方に同じデータを設定するため、どのホストでもエージェントには同じ結果が表示されます。

format() はテキスト側をレンダリングします。指定しない場合、content[] には JSON が設定されます。フォーマットの整合性をチェックするリンタールールは、レンダリングされたテキストに出力フィールドが 1 つでも欠けていると lint:mcp を失敗させます。フレームワークがエンリッチメントを両方のサーフェスに追加するため、エンリッチメントに format() のエントリーは不要です。このフォーマッターは、項目を Markdown リストとしてレンダリングします。

format: (result) => [{
  type: 'text',
  text: result.items.length > 0
    ? result.items.map((name) => `- ${name}`).join('\n')
    : 'No matching items.',
}],

リソース

リソースは URI でデータを公開します。このリソースは、独自の getItem() サービスからデータを読み取ります。

import { resource, z } from '@cyanheads/mcp-ts-core';

export const itemData = resource('items://{itemId}', {
  description: 'Retrieve item data by ID.',
  params: z.object({
    itemId: z.string().describe('Item ID'),
  }),
  async handler(params) {
    return await getItem(params.itemId);
  },
});

エントリーポイントでは、すべてを createApp() で登録します。

await createApp({
  name: 'my-mcp-server',
  title: 'my-mcp-server', // display name in client UIs
  tools: allToolDefinitions,
  resources: allResourceDefinitions,
  prompts: allPromptDefinitions,
  instructions: 'Brief composition hints for the model.', // optional, sent on every `initialize`
  skills: 'skills', // optional, serves root skills/ over the SEP-2640 Skills extension
});

Cloudflare Workers では、別のエントリーポイントから同じ定義を createWorkerHandler() に渡します。

ランタイムと統合の詳細

• 認証とストレージ： 定義に auth: ['scope'] を指定すると、ハンドラーの実行前に JWT または OAuth のもとでスコープが確認されます。ctx.state はテナントごとに分離されたストレージで、設定に応じてメモリ内、ファイルシステム、Supabase、Cloudflare D1/KV/R2 を使用します。
• クライアントとのやり取り： ctx.requestInput(...) を返すと、ユーザーからの入力、サンプル用のクライアントのモデル、またはクライアントのルートを要求できます。回答は ctx.inputs に設定され、ハンドラーが再度実行されます。
• プロトコルの互換性： HTTP は、2026-07-28 のクライアント（リクエストごとの _meta エンベロープ）と、セッションベースの2025年頃のクライアントに対応します。SDK の互換性レイヤーが、旧バージョンのクライアント向けの入力要求を処理します。
• サーバーの表示情報： instructions を指定すると、すべてのツールの説明に記載する代わりに、initialize 時にモデルへサーバー全体のガイダンスを一度だけ提供できます。識別情報フィールド（title、websiteUrl、description、icons）は、クライアントのサーバー情報、/.well-known/mcp.json のサーバーカード、HTTP ランディングページに反映されます。skills: 'skills' を指定すると、SEP-2640 Skills 拡張（skills/list、skills/get）を通じて、サーバーがルートの skills/ で公開する Agent Skills を提供します。これらはビルド時に lint:packaging で検証されます。
• 定義のチェック： lint:mcp は、名前、スキーマ、スコープ、アノテーション、フォーマットの整合性、JSON Schema の移植性をチェックします。実行されるのはビルド時であり、起動時ではないため、新しいルールによってデプロイ済みのサーバーが壊れることはありません。
• DataCanvas： エージェントがステージング済みの API 結果に対して SQL を実行し、CSV、Parquet、JSON をエクスポートできる、オプションの DuckDB ワークスペースです。エージェント間でキャンバストークンを渡すことで、ワークスペースを共有できます。CANVAS_PROVIDER_TYPE=duckdb と @duckdb/node-api で有効にします（Bun または Node.js のみ）。brapi-mcp-server では、API 結果をデータフレームに読み込んでクエリを実行する手順を紹介しています。
• ミラー： /mirror モジュールは、大規模な上流データセットの永続的なローカルコピーを、オプションの FTS5 インデックス付きで組み込み SQLite に保持します。これにより、ツールは呼び出しのたびにライブ API をページングする代わりに、ローカルでクエリを実行できます。sync インジェスターとスキーマを記述すると、ストレージ、再開可能な初回ロード、増分更新はフレームワークが処理します。Bun または Node.js のみ（Node では better-sqlite3 はオプションのピア依存関係です）。faa-aircraft-registry-mcp-server は、この方式で FAA の登録情報全体を提供します。

設定とハンドラーパターンについてはフレームワークリファレンスを、Pino ロギングと OpenTelemetry のトレースおよびメトリクスについては可観測性ガイドを参照してください。

サーバーの構成

my-mcp-server/
  src/
    index.ts                              # createApp() entry point
    worker.ts                             # createWorkerHandler() (optional)
    config/
      server-config.ts                    # Server-specific env vars
    services/
      [domain]/                           # Domain services (init/accessor pattern)
    mcp-server/
      tools/definitions/                  # Tool definitions (.tool.ts)
      resources/definitions/              # Resource definitions (.resource.ts)
      prompts/definitions/                # Prompt definitions (.prompt.ts)
  package.json
  tsconfig.json                           # extends @cyanheads/mcp-ts-core/tsconfig.base.json
  CLAUDE.md / AGENTS.md                   # Server conventions; points to core's framework reference

フレームワークのインフラストラクチャは node_modules に置かれ、ソースツリーにはサーバーの定義、設定、ドメインサービスが含まれます。

設定

基本設定は環境変数から取得し、Zod で検証します。サーバー固有の変数には専用のスキーマを用意し、リクエスト時に Workers が環境変数を注入できるよう、遅延して解析します。

変数	説明	デフォルト
MCP_TRANSPORT_TYPE	stdio または http	stdio
MCP_HTTP_PORT	HTTP サーバーのポート	3010
MCP_HTTP_HOST	HTTP サーバーのホスト名	127.0.0.1
MCP_AUTH_MODE	none、jwt、または oauth	none
MCP_AUTH_SECRET_KEY	JWT 署名シークレット（jwt モードでは必須）	—
MCP_REQUEST_STATE_KEY	オプトイン用のキー（32 バイト以上で、すべてのインスタンスで同一）。このキーを使ってハンドラーが返す requestState を封印し、このサーバーから取得していないものをクライアントが送信した場合は拒否します	—
STORAGE_PROVIDER_TYPE	in-memory、filesystem、supabase、cloudflare-d1/kv/r2	in-memory
CANVAS_PROVIDER_TYPE	none または duckdb（オプションのピア依存関係 @duckdb/node-api）	none
OTEL_ENABLED	OpenTelemetry を有効にします	false
LOG_TOOL_FAILURE_PAYLOADS	失敗したツール呼び出しの引数と結果を、キー名に基づいて機密情報を伏せてログに記録します（自由形式の値に含まれるシークレットは検出できません）	false
LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES	ログに記録するペイロードごとの上限（UTF-8 バイト数）	16384
OPENROUTER_API_KEY	オプションの OpenRouter LLM プロバイダー（/services）の API キー	—

設定の全リファレンスについては、CLAUDE.md/AGENTS.md を参照してください。

API の概要

エントリーポイント

関数	目的
createApp(options)	Bun または Node.js のサーバー。起動とシャットダウンを管理します
createWorkerHandler(options)	Cloudflare Workers 用。ExportedHandler を返します

ビルダー

ビルダー	用途
tool(name, options)	handler(input, ctx) を持つツールを定義します
resource(uriTemplate, options)	handler(params, ctx) を持つリソースを定義します
prompt(name, options)	generate(args) を持つプロンプトを定義します
appTool(name, options)	_meta.ui を自動設定する MCP Apps ツールを定義します
appResource(uriTemplate, options)	読み取りコンテンツに適切な MIME タイプと _meta.ui のミラーリングを設定する MCP Apps HTML リソースを定義します

コンテキスト

ツールとリソースのハンドラーは Context を受け取ります。ctx.enrich と ctx.fail は、定義で宣言されたコントラクトに対して型付けされています。

プロパティ	型	説明
ctx.log	ContextLogger	リクエスト単位のロガー（requestId、traceId、tenantId を自動的に関連付けます）。クライアントにも notifications/message としてミラーされます
ctx.state	ContextState	テナント単位のキーと値のストレージ
ctx.requestInput	(spec) => never	一時停止して呼び出し元に追加の入力を求めます。回答を受け取るとハンドラーが再実行されます
ctx.inputs	ContextInputs	リクエストへの応答。クライアントが宣言した種類に限定されます — .accepted()、.view()、.state()、.dropped
ctx.clientCapabilities	ClientCapabilities | undefined	このリクエストについてクライアントが宣言した内容です。省略可能なコンテキストを求めるかどうかを決めますが、同意を求めるプロンプトを省略するかどうかは決めません
ctx.enrich	Enrich / TypedEnrich<E>	宣言された結果コンテキストを構造化出力とテキストコンテンツに追加します
ctx.content	ContentCollect	画像／音声ブロックを content[] に追加します — content.image(data, mimeType)、content.audio(...)、または生のブロック
ctx.fail	(reason, msg?, data?) => McpError	throw ctx.fail(...) 用のエラーを作成します。errors コントラクトが宣言されている場合に使用できます
ctx.recoveryFor	(reason) => object	宣言された復旧ヒントを { recovery: { hint } } に解決します。フレームワークは、その理由を持ち、独自のヒントを含まないエラーが発生した場合、すでにこのヒントを送信します
ctx.signal	AbortSignal	キャンセルシグナル
ctx.notifyResourceUpdated	Function?	リソースが変更されたことを、購読中のクライアントに通知します
ctx.notifyResourceListChanged	Function?	リソース一覧が変更されたことをクライアントに通知します
ctx.notifyPromptListChanged	Function?	プロンプト一覧が変更されたことをクライアントに通知します
ctx.notifyToolListChanged	Function?	ツール一覧が変更されたことをクライアントに通知します
ctx.requestId	string	リクエスト ID — 呼び出しのログレコードと共有され、エラーでは data.requestId として返されます
ctx.tenantId	string?	テナント ID（JWT の tid クレーム。または stdio および HTTP+MCP_AUTH_MODE=none の場合は 'default'）
ctx.auth	AuthContext?	リクエストが認証されている場合のトークンクレームとスコープ
ctx.sessionId	string?	ステートフル／auto セッションモードでの HTTP セッション ID — 認可主体ではなく、スコープ設定用のキーです
ctx.uri	URL?	パース済みのリソース URI。リソースハンドラーでのみ設定されます

サブパスのエクスポート

import { createApp, tool, resource, prompt } from '@cyanheads/mcp-ts-core';
import { createWorkerHandler } from '@cyanheads/mcp-ts-core/worker';
import { McpError, JsonRpcErrorCode, notFound, serviceUnavailable } from '@cyanheads/mcp-ts-core/errors';
import { checkScopes } from '@cyanheads/mcp-ts-core/auth';
import { markdown, fetchWithTimeout } from '@cyanheads/mcp-ts-core/utils';
import { OpenRouterProvider, GraphService } from '@cyanheads/mcp-ts-core/services';
import type { DataCanvas, CanvasInstance } from '@cyanheads/mcp-ts-core/canvas';
import { defineMirror, sqliteMirrorStore } from '@cyanheads/mcp-ts-core/mirror';
import { validateDefinitions } from '@cyanheads/mcp-ts-core/linter';
import { createMockContext } from '@cyanheads/mcp-ts-core/testing';
import { mcpTest, toolContractSuite } from '@cyanheads/mcp-ts-core/testing/vitest';
import { fuzzTool, fuzzResource, fuzzPrompt } from '@cyanheads/mcp-ts-core/testing/fuzz';
import { renderAppTool } from '@cyanheads/mcp-ts-core/testing/apps';

エクスポートの全一覧については、CLAUDE.md/AGENTS.md を参照してください。

例

examples/ には、パブリックエクスポートのみを使用して構築されたリファレンスサーバーが含まれています。examples/index.ts（Node/Bun）と examples/worker.ts（Cloudflare Workers）は、同じ definitions/index.ts バレルを登録します。

種類	名前	パターン
ツール	template_echo_message	ctx.fail を使った errors[] コントラクト、inputAliases、忠実度の高い format()
ツール	template_cat_fact	fetchWithTimeout、型付けされた not-found コントラクト、エンリッチメントのエコー
ツール	template_image_test	ctx.content.image
ツール	template_madlibs_elicitation	return ctx.requestInput、severity を含む入力拒否コントラクト
ツール	template_data_explorer	appTool／appResource、ホストのテーマ設定、cacheHint
リソース	echo://{message}	テンプレート化されたリソース
リソース	ui://template-data-explorer/app.html	template_data_explorer と組み合わせた UI リソース
プロンプト	code_review	completable() 引数、code 引数

テスト

import { createMockContext } from '@cyanheads/mcp-ts-core/testing';
import { myTool } from '@/mcp-server/tools/definitions/my-tool.tool.js';

const ctx = createMockContext();
const input = myTool.input.parse({ query: 'test' });
const result = await myTool.handler(input, ctx);

createMockContext() は、記録用の log、signal、およびメモリ内プロバイダー上の実際の StorageService によってバックアップされた state を提供します。そのため、キーの検証、TTL の期限切れ、保存値の JSON 変換は本番環境と同じように動作します。たとえば、Date は ISO 文字列として読み戻され、JSON でエンコードできない値は拒否されます。{ tenantId } を渡さない場合、テナントには 'default' が使われます。型付きの ctx.fail を使うには { errors: myTool.errors } を渡します。複数回のラウンドトリップを行うハンドラーを 2 回目から開始するには { inputResponses, requestState } を渡し、クライアントが宣言した機能を設定するには { clientCapabilities } を渡します（シードされたレスポンスは本番環境と同様、宣言された種類に絞り込まれます）。

/testing では、セッションに紐づくコンテキスト用の createMockSession()、上流 HTTP 用の厳格なフェイクである createFetchMock()、および定義をスキーマ、ハンドラー、フォーマット、エラーエンベロープの各チェックにかける runToolContract() もエクスポートされています。/testing/vitest では、mcpTest フィクスチャ（ctx、session、fetchMock、storage）と toolContractSuite() が追加されます。

/testing/fuzz は fast-check を使って、Zod スキーマから有効な入力と敵対的なペイロードを生成し、クラッシュ、スタックトレースの漏えい、プロトタイプ汚染がないかをチェックします。

import { fuzzTool } from '@cyanheads/mcp-ts-core/testing/fuzz';

const report = await fuzzTool(myTool, { numRuns: 100 });
expect(report.crashes).toHaveLength(0);
expect(report.leaks).toHaveLength(0);
expect(report.prototypePollution).toBe(false);

カスタムのプロパティベーステスト用に、fuzzResource、fuzzPrompt、zodToArbitrary、ADVERSARIAL_STRINGS もエクスポートされています。

/testing/apps はヘッドレスの MCP Apps ホストです。renderAppTool は MCP Apps クライアントとしてサーバーに接続し、アプリツールを呼び出し、MCP Apps 仕様で規定されたサンドボックスと CSP のもとで ui:// ビューを chrome-headless-shell に読み込み、ビューに対してスクリプト化された手順を実行し、レポートを返します。

import { renderAppTool } from '@cyanheads/mcp-ts-core/testing/apps';

const run = await renderAppTool({
  server: { command: 'bun', args: ['run', 'dist/index.js'] }, // or { url }
  tool: 'my_app_tool',
  arguments: { query: 'probe' },
  steps: [{ click: '#action-btn' }, { screenshot: 'after-click' }],
});
expect(run.initialized).toBe(true);
expect(run.errors).toHaveLength(0);
expect(run.cspViolations).toHaveLength(0);

レポートには、ビューとホスト間のすべてのメッセージ、ビューに描画されたテキスト、スクリーンショットのパスも含まれます。コマンドラインから同じ実行を行い、report.json とスクリーンショットを --out の下に書き出す方法は次のとおりです。

bunx @cyanheads/mcp-ts-core app-render --tool my_app_tool --args '{"query":"probe"}' \
  --click '#action-btn' --out ./app-run -- bun run dist/index.js

オプションのピア依存関係である @modelcontextprotocol/client と @modelcontextprotocol/ext-apps、および chrome-headless-shell のビルドが必要です。Puppeteer のキャッシュにある最新のビルド（npx @puppeteer/browsers install chrome-headless-shell@stable --path ~/.cache/puppeteer）を使うか、browserPath、--browser、または MCP_APPS_BROWSER_PATH で実行可能ファイルのパスを明示してください。インストール済みの Chrome、Edge、Brave、Chromium は検索されません。

ドキュメント

• CLAUDE.md/AGENTS.md：エクスポート、パターン、Context、エラーコード、認証、設定、テストを網羅したフレームワークリファレンスです。npm パッケージに同梱されているため、エージェントは init の後に node_modules からこれを読み込みます。
• docs/telemetry/：フレームワークが出力するすべてのスパン、メトリクス、属性（observability.md）に加え、Grafana ダッシュボードの例と、Datadog、New Relic、Honeycomb 向けのクエリレシピを掲載しています（dashboards.md）。
• CHANGELOG.md：バージョン履歴です。changelog/ 内にリリースごとに 1 つのファイルを置いています。各ファイルには概要、移行に関する注意事項、コミットと Issue へのリンクが含まれます。後続の変更が必要なリリースには、maintenance スキルが対応するための agent-notes が付いています。

開発

bun run rebuild        # clean + build (scripts/clean.ts + scripts/build.ts)
bun run devcheck       # full gate: lint/format, typecheck, MCP defs, packaging, framework antipatterns, docs/skills/changelog sync, audit, outdated, tracked-secrets and to-do marker scans
bun run lint:mcp       # validate MCP definitions against spec
bun run test:all       # rebuild + coverage + Node.js + Workers + integration
bun run test:package   # pack the tarball and consume it as an external project would
bun run test:soak      # sustained HTTP load; fails when the server heap grows per request

ライセンス

Apache 2.0 — LICENSE を参照してください。

---