Claude MCP ハイブリッドアーキテクチャ入門 — 決定論的ツールとAI推論を組み合わせる設計パターン

// mcp-server/tools/database-query.ts
// データベースクエリツール — 決定論的処理の例
import { z } from "zod";
 
const QueryParamsSchema = z.object({
  table: z.string().describe("クエリ対象のテーブル名"),
  filters: z.record(z.string()).describe("フィルター条件（キー=カラム名、値=条件値）"),
  limit: z.number().default(10).describe("取得件数の上限"),
});
 
export const databaseQueryTool = {
  name: "query_database",
  description: "指定されたテーブルからフィルター条件に合うレコードを取得する",
  inputSchema: QueryParamsSchema,
 
  async execute(params: z.infer<typeof QueryParamsSchema>) {
    // バリデーション済みのパラメータで確定的にクエリを実行
    const { table, filters, limit } = params;
 
    const whereClause = Object.entries(filters)
      .map(([key, value]) => `${key} = '${value}'`)
      .join(" AND ");
 
    const query = `SELECT * FROM ${table} WHERE ${whereClause} LIMIT ${limit}`;
 
    // 実行結果は入力が同じなら（データが同じ前提で）常に同じ
    const results = await db.execute(query);
    return { success: true, data: results, query };
  },
};

// orchestrator/hybrid-agent.ts
// Claude をオーケストレーターとして使うハイブリッドエージェント
import Anthropic from "@anthropic-ai/sdk";
 
const client = new Anthropic();
 
async function runHybridAgent(userMessage: string) {
  const response = await client.messages.create({
    model: "claude-sonnet-4-6",
    max_tokens: 4096,
    system: `あなたはデータ分析アシスタントです。
ユーザーのリクエストを分析し、適切なツールを呼び出してください。
 
重要な設計原則:
1. 数値計算やデータ取得は必ずツールを使う（自分で計算しない）
2. ツールの実行結果をそのまま信頼する（結果を「想像」しない）
3. 複数のツールが必要な場合は、依存関係を考慮して順序を決定する
4. エラーが発生した場合は、代替手段を検討してからユーザーに報告する`,
    tools: mcpTools, // MCP サーバーから取得したツール定義
    messages: [{ role: "user", content: userMessage }],
  });
 
  return response;
}

// orchestrator/result-synthesizer.ts
// ツール実行結果の統合ロジック
async function synthesizeResults(
  toolResults: ToolResult[],
  originalQuery: string
) {
  const response = await client.messages.create({
    model: "claude-sonnet-4-6",
    max_tokens: 2048,
    messages: [
      {
        role: "user",
        content: `以下のツール実行結果を統合して、ユーザーの質問に回答してください。
 
ユーザーの質問: ${originalQuery}
 
ツール実行結果:
${toolResults
  .map(
    (r, i) =>
      `[ツール${i + 1}: ${r.toolName}]\n${JSON.stringify(r.output, null, 2)}`
  )
  .join("\n\n")}
 
回答のルール:
- 数値データはツール結果の値をそのまま使うこと
- 推測や補完を行う場合は明示すること
- 結果が矛盾する場合はその旨を報告すること`,
      },
    ],
  });
 
  return response;
}

// patterns/plan-execute-verify.ts
// 計画→実行→検証のループパターン
 
const systemPrompt = `あなたはタスク実行エージェントです。
以下の3ステップで作業を進めてください。
 
Step 1 - 計画: ユーザーのリクエストを分析し、必要なツール呼び出しの
  実行計画を JSON 形式で出力してください。
Step 2 - 実行: 計画に基づいてツールを順番に呼び出します。
Step 3 - 検証: 全ツールの実行結果を確認し、期待通りの結果が
  得られたかを判定します。問題があれば計画を修正して再実行します。`;
 
async function planExecuteVerify(userRequest: string) {
  let attempts = 0;
  const maxAttempts = 3;
 
  while (attempts < maxAttempts) {
    // Step 1: Claude が計画を立てる（確率的）
    const plan = await generatePlan(userRequest);
 
    // Step 2: 計画に基づきツールを実行（決定論的）
    const results = await executePlan(plan);
 
    // Step 3: Claude が結果を検証（確率的）
    const verification = await verifyResults(results, userRequest);
 
    if (verification.isSuccess) {
      return verification.finalResponse;
    }
 
    // 検証失敗 → 計画を修正して再試行
    userRequest = `前回の実行結果: ${JSON.stringify(results)}
修正点: ${verification.feedback}
元のリクエスト: ${userRequest}`;
    attempts++;
  }
 
  return "最大試行回数に達しました。手動での確認をお願いします。";
}

// patterns/tool-narrowing.ts
// ツールの段階的絞り込みパターン
 
const toolCategories = {
  database: ["query_database", "insert_record", "update_record"],
  file: ["read_file", "write_file", "list_directory"],
  api: ["http_get", "http_post", "graphql_query"],
  calculation: ["statistics", "aggregate", "transform"],
};
 
async function narrowAndExecute(userMessage: string) {
  // Phase 1: カテゴリ判別（少ないトークンで実行）
  const categoryResponse = await client.messages.create({
    model: "claude-haiku-4-5", // 軽量モデルで分類
    max_tokens: 100,
    messages: [
      {
        role: "user",
        content: `次のリクエストに必要なツールカテゴリを選んでください。
カテゴリ: database, file, api, calculation
リクエスト: ${userMessage}
カテゴリ名のみ回答:`,
      },
    ],
  });
 
  const category = categoryResponse.content[0].text.trim();
 
  // Phase 2: 絞り込んだツールだけで実行（トークン節約）
  const relevantTools = toolCategories[category] || [];
  const fullTools = await getMCPTools(relevantTools);
 
  return client.messages.create({
    model: "claude-sonnet-4-6", // 本実行は高性能モデル
    max_tokens: 4096,
    tools: fullTools,
    messages: [{ role: "user", content: userMessage }],
  });
}

// patterns/deterministic-guardrails.ts
// 決定論的ガードレールパターン
 
interface GuardrailCheck {
  name: string;
  check: (toolCall: ToolCall) => { allowed: boolean; reason?: string };
}
 
const guardrails: GuardrailCheck[] = [
  {
    name: "SQL_INJECTION_CHECK",
    check: (call) => {
      if (call.name === "query_database") {
        const hasInjection = /;\s*(DROP|DELETE|UPDATE)\s/i.test(
          JSON.stringify(call.input)
        );
        return hasInjection
          ? { allowed: false, reason: "SQLインジェクションの疑い" }
          : { allowed: true };
      }
      return { allowed: true };
    },
  },
  {
    name: "RATE_LIMIT_CHECK",
    check: (call) => {
      const count = getRecentCallCount(call.name, 60); // 直近60秒
      return count > 10
        ? { allowed: false, reason: `レート制限超過: ${count}/10 per min` }
        : { allowed: true };
    },
  },
];
 
// ツール実行前に必ずガードレールを通す
async function executeWithGuardrails(toolCall: ToolCall) {
  for (const guardrail of guardrails) {
    const result = guardrail.check(toolCall);
    if (!result.allowed) {
      return {
        success: false,
        error: `ガードレール [${guardrail.name}]: ${result.reason}`,
      };
    }
  }
  // 全チェック通過 → ツール実行
  return await executeTool(toolCall);
}

// example/sales-analysis-agent.ts
// 売上分析ハイブリッドエージェントの実装例
import Anthropic from "@anthropic-ai/sdk";
 
const client = new Anthropic();
 
// 決定論的ツール定義
const salesTools = [
  {
    name: "get_sales_data",
    description: "指定期間の売上データを取得する",
    input_schema: {
      type: "object",
      properties: {
        start_date: { type: "string", description: "開始日 (YYYY-MM-DD)" },
        end_date: { type: "string", description: "終了日 (YYYY-MM-DD)" },
        product_category: {
          type: "string",
          description: "商品カテゴリ（省略時は全カテゴリ）",
        },
      },
      required: ["start_date", "end_date"],
    },
  },
  {
    name: "calculate_statistics",
    description: "数値配列の統計値（平均、中央値、標準偏差）を計算する",
    input_schema: {
      type: "object",
      properties: {
        values: {
          type: "array",
          items: { type: "number" },
          description: "計算対象の数値配列",
        },
      },
      required: ["values"],
    },
  },
];
 
async function analyzeSales(question: string) {
  const messages: Anthropic.MessageParam[] = [
    { role: "user", content: question },
  ];
 
  // エージェントループ: ツール呼び出しが完了するまで繰り返す
  let continueLoop = true;
  while (continueLoop) {
    const response = await client.messages.create({
      model: "claude-sonnet-4-6",
      max_tokens: 4096,
      system: `あなたは売上分析の専門家です。
ユーザーの質問に答えるために、必ずツールを使ってデータを取得・計算してください。
自分で数値を推測せず、ツールの結果だけを根拠にしてください。`,
      tools: salesTools,
      messages,
    });
 
    // レスポンスを処理
    if (response.stop_reason === "tool_use") {
      // ツール呼び出しを実行（決定論的処理）
      const toolResults = [];
      for (const block of response.content) {
        if (block.type === "tool_use") {
          const result = await executeWithGuardrails(block);
          toolResults.push({
            type: "tool_result",
            tool_use_id: block.id,
            content: JSON.stringify(result),
          });
        }
      }
      // 会話履歴に追加して次のループへ
      messages.push({ role: "assistant", content: response.content });
      messages.push({ role: "user", content: toolResults });
    } else {
      // 最終回答が得られた
      continueLoop = false;
      return response.content;
    }
  }
}
 
// 実行例
// 期待される動作:
// 1. Claude が get_sales_data を呼び出す（決定論的）
// 2. 取得データから calculate_statistics を呼び出す（決定論的）
// 3. Claude が統計結果を解釈してレポートを生成する（確率的）
const report = await analyzeSales(
  "先月と今月の売上を比較して、トレンドを分析してください"
);
console.log(report);