MCPツールのdescription制約：Claudeクライアントのクラッシュを防ぐ実装戦略

Model Context Protocol (MCP)のツール説明文に関するClaude Desktop固有の制約と、その対応方法について解説します。RedmineMCPサーバーでの実装経験から、クラッシュを防ぐための具体的な実装パターンと改善方法を紹介します。

公開: 2025/1/9

MCPサーバーの開発において、予期せぬクライアント固有の制約に遭遇することがあります。最近のRedmine MCPサーバーの開発で、Claude Desktopクライアントがツール説明文の特定のパターンでクラッシュする問題を発見しました。本記事では、この制約の詳細と具体的な対応方法について、実装例とともに解説します。

この記事で伝えたいこと

MCP (Model Context Protocol)のツール説明文に関するClaude Desktop固有の制約を説明します。
RedmineMCPサーバーでの実装経験から、クラッシュを回避するための具体的なパターンを紹介します。
他のMCPサーバー開発者が同様の問題を回避するための実践的なノウハウを共有します。

MCP仕様外の制約について

本記事で紹介する制約は、MCPの公式仕様やドキュメントには記載されていないものです。開発中の発見を共有することで、コミュニティの知見として活用していただければと思います。

課題：仕様外の制約への対応

MCPの公式仕様では、ツールの説明文（description）に関して特別な制約は設けられていません。しかし、Redmine MCP Serverの開発中に、Claude Desktopクライアントで以下の制約によりクラッシュが発生することが判明しました。

src/tools/projects.ts

1// 問題のある実装例
2export const PROJECT_SHOW_TOOL: Tool = {
3  name: "show_project",
4  description:
5    "Get project details by ID (numeric) or identifier (string). " +
6    "Includes time_entries and custom_fields in response. " +
7    "Admin permissions required for some operations.",
8  inputSchema: {
9    type: "object",
10    properties: {
11      id: {
12        type: ["number", "string"],  // ユニオン型の使用
13        description: "Project ID (numeric) or identifier (string)"
14      }
15    }
16  }
17};

このコードには以下の問題が含まれています：

文字の制限
- 括弧「(」「)」の使用
- アンダースコア「_」の使用（time_entries）
長さの制限
- 説明文が4行を超過する可能性
タイプ定義の制限
- ユニオン型（type: ["number", "string"]）の使用

実装上の注意

これらの制約は、MCPの公式仕様やドキュメントには記載されていないClaude Desktop固有のものです。制約に違反する実装を行うと、クライアントがクラッシュする可能性があります。

解決策：安全な実装パターン

上記の問題に対して、以下のような改善パターンを適用することで、クラッシュを回避しながら必要な情報を伝えることができます。

改善後のコード

1// 安全な実装パターン
2export const PROJECT_SHOW_TOOL: Tool = {
3  name: "show_project",
4  description:
5    "Get detailed project information. " +
6    "Specify using project ID or key. " +
7    "Supports retrieving additional data. " +
8    "Available since Redmine 1.0",
9  inputSchema: {
10    type: "object",
11    properties: {
12      id: {
13        type: "string",  // 文字列型として受け取る
14        description: "Project ID as number or project key as text"
15      }
16    }
17  }
18};

1. 説明文の改善

説明文は4行以内に収め、括弧を使用せずに情報を伝えます：

1行目：主要な機能の説明
2行目：入力形式や制約
3行目：オプション機能
4行目：バージョン情報など

2. テクニカルタームの書き換え

アンダースコアを含む技術用語は、自然な表現に置き換えます：

time_entries → time tracking records
custom_fields → custom fields
issue_tracking → issue management

3. 型の処理をハンドラーで対応

handlers/projects.ts

1// ハンドラーでの型変換処理
2const handleProjectId = (id: string): number | string => {
3  const numId = parseInt(id, 10);
4  return isNaN(numId) ? id : numId;
5};

ユニオン型は使用せず、文字列として受け取ってハンドラーで適切に変換します。これにより：

スキーマ定義をシンプルに保てる
型の柔軟性を維持できる
バリデーションをより詳細に制御できる

ハンドラーでの処理のメリット

ハンドラーでの変換処理は、エラーハンドリングやログ出力など、より詳細な制御が可能です。入力値の検証やサニタイズもこのレイヤーで実装することをお勧めします。

実装のヒントとコツ

実装時の具体的なヒントとコツをパターン別に紹介します。以下の実装パターンを組み合わせることで、制約に対応しつつ必要な情報を伝えることができます。

説明文のフォーマット

description-template.ts

1description:
2  "Get detailed project information. " +           // 主要機能
3  "Specify using project ID or key. " +          // 入力形式
4  "Supports retrieving additional data. " +      // オプション
5  "Available since Redmine 1.0"                 // バージョン

括弧を避ける工夫

brackets-alternatives.ts

1// 括弧を使用（避けるべき）
2description: "Project ID (numeric) or identifier (string)"
3
4// 代替表現（推奨）
5description: "Project ID as number or project key as text"
6
7// コロン表現（代替案）
8description: "Input: numeric ID or text identifier"

技術用語の言い換え

terms-mapping.ts

1// 技術用語のマッピング定義
2const termMappings = {
3  // API関連
4  time_entries: "time tracking records",
5  custom_fields: "custom fields",
6  issue_tracking: "issue management",
7
8  // 一般用語
9  source_code: "source files",
10  pull_request: "pull request",
11  web_hook: "webhook"
12} as const;

特に注意が必要なのは、一般的な技術用語でもアンダースコアを含むものは書き換える必要がある点です。普及した用語であってもクライアントの制約を優先します。

おわりに

Model Context Protocol（MCP）は、LLMアプリケーションと外部データソース・ツールを統合する新しい可能性を切り開くプロトコルです。今回発見された制約は、この発展途上のプロトコルならではの課題の一つと捉えることができます。

MCPは、LLMに外部のデータやツールへのアクセスを提供し、より強力なAIアプリケーションの開発を可能にします。例えば、RedmineサーバーとLLMの統合により、プロジェクト管理や課題追跡の新しいインターフェースが実現できます。まだ対応が必要な制約はありますが、それ以上にMCPがもたらす価値は大きいと考えています。

今後、他のMCPサーバー実装やクライアントの知見が共有され、より良い実装パターンが見つかるかもしれません。MCPを通じて、AIとツールの新しい対話の形が生まれることを期待しています。

MCPコミュニティの広がり

Model Context Protocol（MCP）は2024年11月にAnthropicによって公開されて以来、急速にコミュニティの注目を集めています。特に、以下の分野での発展が見られます：

各言語のSDKが整備され（Python, TypeScript, Kotlin）、開発のエントリーポイントが増えています
エンタープライズツールとの統合事例も増加し、実用的なユースケースが蓄積されています
HTTPトランスポートのサポートなど、プロトコルの拡張に向けた議論も活発です

また、MCPサーバーのマーケットプレイス的な発展も期待されています。Claude Desktopのような汎用LLMクライアントに、ユーザーが必要なサーバーを自由に組み合わせて利用できる未来像も描かれています。今回のような実装上の発見を共有し、議論することで、プロトコルとコミュニティがより良い形で発展していくことを願っています。

開発者の方々は、公式のドキュメントやSDKを参照しつつ、このような実装の知見も活用していただければと思います。MCPのエコシステムは、私たち開発者一人一人の貢献によって育っていくのではないでしょうか。