はじめに

Model Context Protocol (MCP) を使って Redmine 連携ツールを開発していたところ、予期せぬクライアントのクラッシュに遭遇しました。この記事では、遭遇した問題と具体的な解決方法を共有します。

この記事は MCPツールのdescription制約：Claudeクライアントのクラッシュを防ぐ実装戦略をベースに、実装者向けにより実践的な内容として再構成したものです。

TL;DR

MCPツールの description に特定のパターンを含むとクラッシュする
括弧やアンダースコアの使用を避ける
説明は4行以内に収める
ユニオン型の代わりにハンドラーで型変換を行う

発生した問題

開発中のRedmine MCPサーバーで、以下のようなツール定義を行った際にクラッシュが発生しました：

{
  name: "list_time_entries",
  description: "List time tracking records (time_entries) from the database. Returns data in JSON format.",
  parameters: {
    type: ["number", "string"],
    // ... 他のパラメータ定義
  }
}

クラッシュの原因

クラッシュの原因特定には大変苦労しました。当初はツールの実装に問題があるのではないかと考え、コードの見直しを行いましたが原因は特定できませんでした。その後、説明文のパターンを変更しながらテストを繰り返すことで、以下の3点が原因であることが判明しました：

説明文での括弧の使用：説明文中に括弧を含めるとクラッシュが発生
アンダースコアを含む技術用語：time_entries などの一般的な技術用語でもクラッシュの原因に
パラメータでのユニオン型の使用：配列による型定義がクラッシュを引き起こす

この発見により、MCPの公式仕様には記載されていない、クライアント固有の制約が存在することが分かりました。これらの制約は文書化されていないため、実装時に注意が必要です。

解決方法

1. 説明文の改善

説明文は以下のようなパターンで記述します：

{
  name: "list_time_entries",
  description: "List time tracking records. JSON response format. Optional filtering by date range. Available since version 1.1",
  // ...
}

このように情報を分割して記述することで、括弧を使わずに必要な情報を伝えられます。

2. 技術用語の言い換え

一般的な技術用語でも、パラメータ名であっても、アンダースコアを含むものは別の表現に置き換える必要があります：

time_entries → time records // パラメータ名も変更が必要
custom_fields → custom fields // よく使われる用語でも注意
issue_tracking → issue management // 機能説明でも置き換えを忘れずに

予想以上に制約は厳密で、description内のあらゆる場所でアンダースコアの使用を避ける必要があります。パラメータ名を参照する場合も例外ではありません。

3. 型の処理

ユニオン型の代わりに、文字列として受け取ってハンドラーで変換する方法を採用します：

// Before
parameters: {
  type: ["number", "string"]
}

// After
parameters: {
  type: "string"
}

// ハンドラーでの処理
function handleParameter(value) {
  if (!isNaN(value)) {
    return Number(value);
  }
  return value;
}

実装のポイント

説明文は4行以内を目安に
括弧は使用しない
アンダースコアを含む用語は言い換える
型の柔軟性はハンドラーで確保

今後の展望

MCPは2024年11月に公開された新しいプロトコルで、今後も実装パターンや制約に関する知見が蓄積されていくと考えられます。現在は以下の分野で特に発展が見られます：

各言語のSDK整備
エンタープライズツールとの統合
プロトコルの拡張に関する議論

おわりに

MCPを使った開発では、公式の仕様だけでなく、実装時の制約にも注意が必要です。この記事で紹介した対応方法が、皆さんの開発の参考になれば幸いです。

参考資料

MCPの公式ドキュメント
Claude Desktop 開発者ガイド