MCP コネクタを申請・無人運用に回す前に、各ツールを契約テストで確かめる

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 
// テスト対象のコネクタを子プロセスとして起動して接続します
export async function connect(): Promise<Client> {
  const transport = new StdioClientTransport({
    command: "node",
    args: ["dist/server.js"],
  });
  const client = new Client(
    { name: "contract-tester", version: "1.0.0" },
    { capabilities: {} },
  );
  await client.connect(transport);
  return client;
}
 
type Issue = { tool: string; rule: string; detail: string };
 
export async function checkSelfDescription(client: Client): Promise<Issue[]> {
  const { tools } = await client.listTools();
  const issues: Issue[] = [];
 
  for (const t of tools) {
    // 説明文が無い・短すぎるツールは、モデルが用途を判断できません
    if (!t.description || t.description.trim().length < 12) {
      issues.push({ tool: t.name, rule: "description", detail: "説明文が無いか短すぎます" });
    }
    // inputSchema はオブジェクト型で properties を持つのが最低条件です
    const schema = t.inputSchema as { type?: string; properties?: object } | undefined;
    if (!schema || schema.type !== "object") {
      issues.push({ tool: t.name, rule: "schema", detail: "inputSchema が object ではありません" });
    } else if (!schema.properties) {
      issues.push({ tool: t.name, rule: "schema", detail: "properties が定義されていません" });
    }
  }
  return issues;
}

export async function checkReadContract(
  client: Client,
  tool: string,
  args: Record<string, unknown>,
): Promise<Issue[]> {
  const issues: Issue[] = [];
  const res = await client.callTool({ name: tool, arguments: args });
 
  // 正常系のはずが isError で返るなら、引数かサーバ実装の契約違反です
  if (res.isError) {
    issues.push({ tool, rule: "read-error", detail: "正常系の引数で isError が返りました" });
    return issues;
  }
  // MCP のツール応答は content 配列を持つのが約束です
  if (!Array.isArray(res.content) || res.content.length === 0) {
    issues.push({ tool, rule: "read-shape", detail: "content が空、または配列ではありません" });
  }
  // 構造化出力を謳うツールは structuredContent の有無まで固定します
  if (res.structuredContent !== undefined && typeof res.structuredContent !== "object") {
    issues.push({ tool, rule: "read-structured", detail: "structuredContent がオブジェクトではありません" });
  }
  return issues;
}

import { randomUUID } from "node:crypto";
 
export async function checkIdempotency(
  client: Client,
  writeTool: string,
  countTool: string,
): Promise<Issue[]> {
  const issues: Issue[] = [];
  const key = `contract-${randomUUID()}`; // 一意なセンチネル
 
  const before = await readCount(client, countTool);
 
  // 同じ冪等キーで 2 回書き込みます
  const first = await client.callTool({ name: writeTool, arguments: { idempotencyKey: key, payload: { sentinel: key } } });
  const second = await client.callTool({ name: writeTool, arguments: { idempotencyKey: key, payload: { sentinel: key } } });
 
  const after = await readCount(client, countTool);
 
  if (first.isError) {
    issues.push({ tool: writeTool, rule: "write-first", detail: "初回の書き込みが失敗しました" });
  }
  // 2 回目は成功応答（すでに適用済みを含む）で返るのが冪等な設計です
  if (second.isError) {
    issues.push({ tool: writeTool, rule: "idempotent-retry", detail: "2回目の呼び出しが isError になりました" });
  }
  // 件数が 2 増えていたら、二重発火しています
  if (after - before > 1) {
    issues.push({ tool: writeTool, rule: "idempotent-effect", detail: `件数が ${after - before} 増えました（期待は 1）` });
  }
  return issues;
}
 
async function readCount(client: Client, countTool: string): Promise<number> {
  const res = await client.callTool({ name: countTool, arguments: {} });
  const text = (res.content?.[0] as { text?: string })?.text ?? "0";
  return Number.parseInt(text, 10) || 0;
}

export async function measureLatency(
  client: Client,
  tool: string,
  args: Record<string, unknown>,
  runs = 20,
): Promise<{ p50: number; p95: number }> {
  const samples: number[] = [];
  for (let i = 0; i < runs; i++) {
    const start = performance.now();
    await client.callTool({ name: tool, arguments: args });
    samples.push(performance.now() - start);
  }
  samples.sort((a, b) => a - b);
  const at = (q: number) => Math.round(samples[Math.floor(q * (samples.length - 1))]);
  return { p50: at(0.5), p95: at(0.95) };
}

async function main() {
  const client = await connect();
  const issues: Issue[] = [];
 
  issues.push(...(await checkSelfDescription(client)));
  issues.push(...(await checkReadContract(client, "list_articles", { limit: 1 })));
  issues.push(...(await checkIdempotency(client, "upsert_article", "count_articles")));
 
  const lat = await measureLatency(client, "list_articles", { limit: 1 });
  console.log(`list_articles p50=${lat.p50}ms p95=${lat.p95}ms`);
 
  await client.close();
 
  if (issues.length > 0) {
    for (const i of issues) console.error(`❌ [${i.tool}] ${i.rule}: ${i.detail}`);
    process.exit(1); // 申請・デプロイをここで止めます
  }
  console.log("✅ contract passed");
}
 
main().catch((e) => { console.error(e); process.exit(1); });