Posted inAI

Claude Codeを強力にする：カスタムMCPスキルの構築ガイド

AI tutorial - IT technology blog
AI tutorial - IT technology blog

AIのコンテキストの壁を打ち破る

私はこの6ヶ月間、Claude Codeを本番環境で限界まで使い込んできました。ボイラープレートの作成には優れていますが、社内APIやプライベートなJiraボード、チーム固有 deデプロイ手順などは把握できないという壁にいつか突き当たります。Claude CodeはAnthropicのCLIエージェントで、コードやGitワークフローを処理しますが、その賢さはアクセスできるデータ量に依存します。

真のチームメイトにするには、カスタムの「スキル」を構築する必要があります。これらはModel Context Protocol (MCP)によって動きます。MCPサーバーは、Claudeがサンドボックスの外に出て、安全に社内インフラと通信するための架け橋だと考えてください。私の経験では、2〜3個のカスタムツールを追加するだけで、日々の手動調査時間を20%削減できます。

5分でできるセットアップ：最初のカスタムスキル

最も早く始める方法は、TypeScript MCPスターターを使用することです。これにより、自分で書いたローカルロジックをClaudeに実行させることができます。

1. プロジェクトの初期化

# カスタムのJiraまたはWikiフェッチャー用プロジェクトを作成
mkdir claude-internal-tools && cd claude-internal-tools

# 新しいMCPサーバーの雛形を作成
npx @modelcontextprotocol/create-server internal-docs-server

2. 実用的なツールの定義

src/index.tsを開きます。一般的な例ではなく、社内開発環境のスペックを取得するツールを作ってみましょう。これにより、Claudeが使用するポートやURLを推測（ハルシネーション）するのを防げます。

server.tool(
  "get_service_config",
  "社内レジストリから開発環境のポートとURLを取得します",
  { serviceName: z.string().description("マイクロサービスの名前（例：'auth-api'）") },
  async ({ serviceName }) => {
    // 本番環境では、これは社内レジストリへのAxiosコールになります
    const mockData = { "auth-api": "Port: 8081, DB: pg-dev-01", "gateway": "Port: 3000" };
    return { 
      content: [{ type: "text", text: mockData[serviceName] || "サービスが見つかりません" }]
    };
  }
);

3. スキルをClaude Codeにリンクする

Claude Codeにサーバーの場所を教える必要があります。claude_desktop_config.jsonを編集します。macOSでは ~/Library/Application Support/Claude/ に、Windowsでは %APPDATA%\Claude\ にあります。

{
  "mcpServers": {
    "internal-docs": {
      "command": "node",
      "args": ["/Users/yourname/dev/claude-internal-tools/build/index.js"]
    }
  }
}

Claude Codeのセッションを再起動します。これで、「auth-apiはどのポートを使っている？」と聞くだけで、Claudeはコードを呼び出して回答してくれるようになります。

セマンティック・インターフェースの極意

スキルを構築するとき、単にコードを書いているのではありません。モデルへの指示を書いているのです。Claudeは description フィールドを見て、いつツールを起動するかを判断します. 説明が不十分だと、Claudeはそのツールを無視したり、パラメータを捏造したりします。

以前、作成したデータベースツールをClaudeが使ってくれず、2時間デバッグしたことがあります。原因は曖昧な説明でした。「データベースをクエリする」から、「標準的なメールアドレス形式を使用して、ユーザーレコードをPostgreSQLの本番データベースから照会する」に変更したところ、成功率は40%から一気に100%近くまで上がりました。

スキルの主要コンポーネント：

  • 名前（Name）: fetch_sentry_errors のように、明確なsnake_caseを使用します。
  • 説明（Description）: 非常に具体的に記述してください。データ形式や正確なユースケースに言及します。
  • 入力スキーマ（Input Schema）: Zodを使用して、Claudeが送信できる内容を厳格に定義します。これにより、APIがISOタイムスタンプを期待しているのに、モデルが「昨日」といった文字列を送信するのを防げます。

複雑さへの対応：状態と非同期ワークフロー

基本的なツールも便利ですが、真の力は長時間かかるタスクの処理にあります。Claude Codeにはツールのレスポンスにタイムアウトがあります。CIスイートのフル実行など、タスクに30秒以上かかる場合は、Claudeを待たせないようにしましょう。「ジョブID」パターンを使用します。

// ツール1：時間のかかるプロセスを開始
server.tool("trigger_deploy", { cluster: z.string() }, async ({ cluster }) => {
  const jobId = "job_" + Math.random().toString(36).substring(7);
  return { content: [{ type: "text", text: `${cluster} でデプロイを開始しました。ID: ${jobId}。60秒後にステータスを確認してください。` }] };
});

// ツール2：結果をポーリング
server.tool("get_deploy_status", { jobId: z.string() }, async ({ jobId }) => {
  return { content: [{ type: "text", text: "ステータス：成功" }] };
});

本番環境での信頼性を高めるヒント

これまでに数十個のスキルを構築してきた中で、信頼性を確保するための譲れないルールをいくつか見つけました。

1. スタックトレースをClaudeに渡す。 ツールでエラーが発生した際、単に「エラーが発生しました」とだけ返さないでください。具体的なエラーメッセージを返します。Claudeはエラーを読み取り、入力のタイプミスに気づいて、ユーザーが何も言わなくても自動的に再試行することがよくあります。

2. Stderr経由でデバッグする。 MCPは通信に stdin と stdout を使用します。デバッグに console.log() を使用すると、JSONストリームが壊れて接続がクラッシュします。代わりに console.error() を使用してください。Claude Codeはこれを無視しますが、デバッグ用にターミナルには表示されます。

3. ツールの役割を絞る。 何でもこなそうとする「万能ツール」は避けてください。1つの巨大で複雑なサーバーよりも、5つの特化したMCPサーバーを持つ方が賢明です。これにより、プロンプトのコンテキストがクリーンに保たれ、モデルが目の前のタスクに集中しやすくなります。

カスタムスキルは、Claude Codeを汎用的なチャットボットから、専門的なエンジニアリングパートナーへと変貌させます。特定のスタックに接続することで、AIとデータの間の仲介役を務める必要がなくなります。これにより、AIが繰り返しのAPI調査やステータスチェックを処理している間、あなたはアーキテクチャの設計に集中できるようになります。

Share:
Tags: