はじめに
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 開発者ガイド