MCP サーバー開発 Tips — エージェントを本番戦力に

# 初期実装 - 素朴なツール定義
@mcp.tool()
def list_all_books():
    """全ての書籍を取得する"""
    response = requests.get("https://library-example.com/api/v1/books/")
    return response.json()
    

ユーザー: 「機械学習に関する本を探して」

エージェント: list_all_books()を呼び出し
→ 300冊全ての書籍データを受信 (約50,000トークン)
→ 全てのデータを読み込んで関連書籍を探そうとする
→ タイムアウトまたはコンテキスト超過
    

# 改善版 - 検索ベースのツール
@mcp.tool()
def search_books(
    query: str,
    category: Optional[str] = None,
    availability: str = "all",  # "all" | "available" | "borrowed"
    max_results: int = 10
) -> dict:
    """
    書籍を検索します。タイトル、著者名、説明文から関連する書籍を検索します。
    
    Args:
        query: 検索キーワード（例：「機械学習」「データ分析」「Python」）
        category: カテゴリでフィルタ（例：「プログラミング」「マーケティング」）
        availability: 貸出状況でフィルタ
            - "all": 全ての本
            - "available": 貸出可能な本のみ
            - "borrowed": 貸出中の本のみ
        max_results: 返却する最大件数（デフォルト: 10）
    
    Returns:
        検索結果のリスト。各書籍には以下の情報が含まれます：
        - title: 書籍タイトル
        - author: 著者名
        - category: カテゴリ
        - published_year: 出版年
        - available_copies: 貸出可能冊数
        - total_copies: 総蔵書数
        - brief_description: 簡潔な説明（最大200文字）
    """
    # 検索ロジック実装
    params = {
        "search": query,
        "category": category,
        "availability": availability,
        "limit": max_results
    }
    response = requests.get(
        "https://library-example.com/api/v1/books/search/",
        params=params
    )
    return response.json()
    

ユーザー: 「機械学習に関する本で、今借りられるものを探して」

エージェント: search_books(
    query="機械学習",
    availability="available",
    max_results=20
)

結果: 
- データ駆動型回帰分析 : 計量経済学と機械学習の融合- 貸出可能: 1冊
- 機械学習&ディープラーニングのしくみと技術がこれ1冊でしっかりわかる教科書 - 貸出可能: 1冊
- 機械学習デザインパターン : データ準備、モデル構築、MLOpsの実践上の問題と解決 - 貸出可能: 1冊
...（計18冊）

エージェント: 「機械学習に関する貸出可能な本が18冊見つかりました。
『機械学習&ディープラーニングのしくみと技術がこれ1冊でしっかりわかる教科書』（2019年）
から始めることをお勧めします...」
    

def get_book(book_id: str):
    """書籍の詳細を取得する"""
    # ...
    

ユーザー: 「『イシューからはじめよ』の詳細を教えて」

エージェント（内部思考）:
「book_idが必要だが、タイトルしか与えられていない...
まずsearch_booksで検索してIDを取得すべきか？
それとも、タイトルをIDとして使えるのか？
説明文には何も書かれていない...」

結果: エージェントが混乱し、誤ったパラメータで呼び出す
    

@mcp.tool()
def get_book_details(
    book_identifier: str,
    identifier_type: str = "title"
) -> dict:
    """
    書籍の詳細情報を取得します。
    
    このツールを使用する前に、通常はsearch_books()で書籍を検索し、
    その結果から正確なタイトルまたはISBNを取得することを推奨します。
    
    Args:
        book_identifier: 書籍を特定する情報
            - identifier_type="title"の場合：完全一致する書籍タイトル
              例：「機械学習を解釈する技術」
              注意：タイトルは正確に一致する必要があります。
              部分一致や曖昧な表現では見つかりません。
              
            - identifier_type="isbn"の場合：13桁のISBNコード
              例：「9784297119485」
              注意：ハイフンなしの数字のみです。
              
        identifier_type: 識別子のタイプ
            - "title": 書籍タイトルで検索（デフォルト）
            - "isbn": ISBNコードで検索
            
    Returns:
        書籍の詳細情報を含む辞書：
        {
            "title": "機械学習を解釈する技術",
            "author": "森下光之助",
            "publisher": "技術評論社",
            "published_date": "2021-08",
            "isbn": "9784297119485",
            "category": "機械学習",
            "pages": 272,
            "description": "あらゆる予測モデルを解釈する4つの手法...",
            "total_copies": 2,
            "available_copies": 2,
            "borrowed_by": [],  # 貸出中の場合、借りている人のリスト
            "related_books": [  # 関連書籍の提案（最大3件）
                {
                    "title": "機械学習デザインパターン",
                    "author": "...",
                    "available": true
                }
            ]
        }
        
    Raises:
        BookNotFoundError: 指定された書籍が見つからない場合
            - よくある原因：タイトルの誤字、部分一致での検索
            - 解決方法：まずsearch_books()で正確なタイトルを確認してください
            
    Examples:
        # タイトルで検索（推奨）
        get_book_details("機械学習を解釈する技術", identifier_type="title")
        
        # ISBNで検索
        get_book_details("9784297119485", identifier_type="isbn")
        
    Note:
        - 大量の書籍の詳細を一度に取得したい場合は、
          代わりにsearch_books()を使用してください。
        - このツールは1冊の詳細情報を取得するためのものです。
    """
    # 実装...
    

# エージェントが実際に行っていた検索例
user_query: "最新のAI技術トレンド"
actual_search_query: "最新のAI技術トレンド 2025"  # 不要な年号を追加
    

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "title": "機械学習を解釈する技術",
  "title_kana": "キカイガクシュウヲカイシャクスルギジュツ",
  "author": "森下光之助",
  "author_kana": "モリシタミツノスケ",
  "publisher": "技術評論社",
  "publisher_kana": "ギジュツヒョウロンシャ",
  "published_date": "2021-08-25T00:00:00Z",
  "isbn": "9784297119485",
  "isbn10": "4297119485",
  "category_id": "cat_ml_001",
  "category_name": "機械学習",
  "pages": 272,
  "width": 182,
  "height": 235,
  "depth": 18,
  "weight": 480,
  "description": "あらゆる予測モデルを解釈する4つの手法PFI、PD、ICE、SHAP/特徴量の重要度/特徴量と予測値の関係性/インスタンスごとの異質性/予測の理由―そのモデルの振る舞いを説明できますか?",
  "cover_image_url": "https://ndlsearch.ndl.go.jp/thumbnail/9784297119485.jpg",
  "cover_image_url_large": "https://books.google.com/books/content?id=...",
  "total_copies": 2,
  "available_copies": 2,
  "borrowed_copies": 0,
  "reserved_copies": 0,
  "damaged_copies": 0,
  "lost_copies": 0,
  "purchase_date": "2021-09-15T00:00:00Z",
  "purchase_price": 2980,
  "location_shelf": "3F-ML-05-A",
  "location_row": 5,
  "location_column": "A",
  "barcode": "1234567890123",
  "created_at": "2021-09-20T10:30:00Z",
  "updated_at": "2024-10-01T15:45:22Z",
  "created_by": "admin",
  "updated_by": "system",
  ...さらに30個のフィールド
}
    

@mcp.tool()
def library_search_books(
    query: str,
    category: Optional[str] = None,
    availability: str = "all",
    response_format: str = "concise",
    max_results: int = 10
) -> dict:
    """
    書籍を検索します。response_formatで情報の粒度を制御できます。
    
    Args:
        response_format: レスポンスの詳細度（重要なパラメータです）
            
            "concise" - 必要最小限モード（デフォルト、推奨）:
              ├─ フィールド数: 6個
              ├─ トークン消費: 50-100トークン/冊
              ├─ 用途: 一覧表示、簡易検索、在庫確認
              └─ 含まれる情報: タイトル、著者、年、カテゴリ、在庫数
              
            "detailed" - 詳細情報モード:
              ├─ フィールド数: 12個
              ├─ トークン消費: 200-300トークン/冊  
              ├─ 用途: 詳細確認、貸出判断、レポート作成
              └─ 含まれる情報: 上記6個 + 出版社、ISBN、説明文、
                              ページ数、借りている人、関連書籍
                              
    使い分けのガイドライン:
        ✓ ユーザーが「ある？」「何冊？」と聞く → concise
        ✓ ユーザーが「詳しく」「説明して」と聞く → detailed
        ✓ ユーザーが「関連する本も」と聞く → detailed
        ✓ 迷ったら → concise（必要なら後でdetailedで再取得）
        
    Returns (concise):
        {
            "books": [
                {
                    "title": "機械学習を解釈する技術",
                    "author": "森下光之助",
                    "published_year": "2021",
                    "category": "機械学習",
                    "available_copies": 2,
                    "total_copies": 2
                }
            ],
            "total_found": 23,
            "showing": 10
        }
        
    Returns (detailed):
        {
            "books": [
                {
                    "title": "機械学習を解釈する技術",
                    "author": "森下光之助",
                    "publisher": "技術評論社",
                    "published_date": "2021-08",
                    "isbn": "9784297119485",
                    "category": "機械学習",
                    "pages": 272,
                    "description": "あらゆる予測モデルを解釈する...",
                    "total_copies": 2,
                    "available_copies": 2,
                    "borrowed_by": [],
                    "related_books": [...]
                }
            ],
            "total_found": 23,
            "showing": 10
        }
        
    Token Usage Comparison:
        10冊の検索結果:
        - 改善前（全フィールド）: 8,000トークン
        - concise: 720トークン（91%削減）
        - detailed: 2,400トークン（70%削減）
        
    Performance Impact:
        - concise使用時の応答時間: 1-2秒
        - detailed使用時の応答時間: 2-3秒
        - 改善前の応答時間: 5-8秒
    """
    # 実装...
    

{
  "title": "機械学習を解釈する技術"
  "author": "森下光之助"
  "published_year": "2021"
  "category": "機械学習"
  "available_copies": 2
  "total_copies": 2
}
    

{
  "title": "機械学習を解釈する技術"
  "author": "森下光之助"
  "publisher": "技術評論社"
  "published_date": "2021-08"
  "isbn": "9784297119485"
  "category": "機械学習"
  "pages": 272
  "description": "あらゆる予測モデルを解釈する4つの手法PFI、PD、ICE、SHAP/特徴量の重要度/特徴量と予測値の関係性/インスタンスごとの異質性/予測の理由",
  "total_copies": 2,
  "available_copies": 2,
  "borrowed_by": [],
  "related_books": [
    {
      "title": "機械学習デザインパターン",
      "author": "Valliappa Lakshmanan",
      "available": true
    },
    {
      "title": "Kaggle Grandmasterに学ぶ機械学習実践アプローチ",
      "author": "門脇大輔",
      "available": true
    }
  ]
}
    

# シナリオ1: 簡易検索（conciseで十分）
ユーザー: 「Pythonの本ある？」
エージェント: search_books("Python", response_format="concise")
→ 720トークンで10冊の情報取得
→ 「Pythonの本が15冊見つかりました。最新の『退屈なことはPythonにやらせよう』がお勧めです」

# シナリオ2: 詳細確認が必要（detailedを使用）
ユーザー: 「『機械学習を解釈する技術』について詳しく教えて。
         関連する本も知りたい」
エージェント: search_books("機械学習を解釈する技術", 
                           response_format="detailed",
                           max_results=1)
→ 206トークンで詳細情報+関連書籍3件取得
→ 詳細な説明と次に読むべき本の提案

# シナリオ3: 在庫確認のみ（最もconcise）
ユーザー: 「『イシューからはじめよ』は今借りられる？」
エージェント: search_books("イシューからはじめよ", 
                           response_format="concise",
                           max_results=1)
→ 72トークンで在庫状況のみ取得
→ 「はい、2冊とも貸出可能です」
    

# 初期実装 - 7つの個別ツール
1. search_books(query)         # 書籍検索
2. get_book_details(title)     # 詳細取得
3. check_availability(title)   # 在庫確認
4. get_related_books(title)    # 関連書籍
5. borrow_book(title)          # 借りる
6. return_book(title)          # 返却
7. get_borrower_info(title)    # 借りている人の情報
    

【改善前：7回のツール呼び出し】
1. search_books("機械学習") 
   → 20冊のリスト取得

2. check_availability("機械学習を解釈する技術")
   → 貸出可能

3. check_availability("機械学習デザインパターン")
   → 貸出中

4. check_availability("Kaggle Grandmasterに学ぶ...")
   → 貸出可能

5. get_related_books("機械学習を解釈する技術")
   → 関連書籍3冊

6. check_availability(関連書籍1)
   → 貸出可能

7. check_availability(関連書籍2)
   → 貸出中

所要時間: 約12秒
トークン消費: 約15,000トークン
    

@mcp.tool()
def find_available_books(
    query: str,
    category: Optional[str] = None,
    include_related: bool = True,
    max_results: int = 5
) -> dict:
    """
    貸出可能な書籍を検索し、関連書籍も合わせて提案します。
    
    このツールは以下を自動的に行います：
    1. クエリに基づいて書籍を検索
    2. 貸出可能な書籍のみをフィルタリング
    3. 各書籍の関連書籍を自動的に取得（include_related=Trueの場合）
    4. 関連書籍の在庫状況も確認
    
    つまり、このツール1回の呼び出しで、
    「借りられる本」と「次に読むべき本」の両方が分かります。
    
    Args:
        query: 検索キーワード
        category: カテゴリフィルタ
        include_related: 関連書籍も含めるか（デフォルト: True）
        max_results: 返却する最大件数
        
    Returns:
        {
            "available_books": [
                {
                    "title": "機械学習を解釈する技術",
                    "author": "森下光之助",
                    "available_copies": 2,
                    "related_books": [  # include_related=Trueの場合のみ
                        {
                            "title": "機械学習デザインパターン",
                            "available": false,  # 貸出中
                            "return_date": "2025-10-15"  # 返却予定日
                        }
                    ]
                }
            ],
            "total_found": 15,  # 貸出可能な書籍の総数
            "suggestions": [
                "カテゴリ「深層学習」でさらに5冊が貸出可能です",
                "『機械学習デザインパターン』は10月15日に返却予定です"
            ]
        }
    
    Note:
        在庫確認のみが目的なら、search_books(availability="available")
        を使用する方が効率的です。
        このツールは「借りたい本を探す」という具体的なタスク向けです。
    """
    # 内部で複数のAPI呼び出しを統合
    books = search_books_api(query, availability="available")
    
    if include_related:
        for book in books:
            book["related_books"] = get_related_books_api(book["isbn"])
            # 関連書籍の在庫状況も自動チェック
            for related in book["related_books"]:
                related["available"] = check_availability_api(related["isbn"])
    
    return format_response(books)
    

ユーザー: 「機械学習の本で今借りられるものを探して。
         次に読むべき本も知りたい」

【改善前】
search_books() → check_availability() × 3 → 
get_related_books() → check_availability() × 2
= 7回のツール呼び出し

【改善後】
find_available_books(query="機械学習", include_related=True)
= 1回のツール呼び出しで完結

エージェント: 「機械学習に関する貸出可能な本が5冊見つかりました。
お勧めは『機械学習を解釈する技術』です。
この本を読んだ後は、『機械学習デザインパターン』が良いでしょう。
ただし、現在貸出中で、10月15日に返却予定です。」
    

def borrow_book(title: str):
    book = find_book(title)
    if not book:
        return {"error": "Not found"}
    
    if book.available_copies == 0:
        return {"error": "Not available"}
    
    # 借りる処理...
    

ユーザー: 「機械学習デザインパターンを借りたい」

エージェント: borrow_book("機械学習デザインパターン")
→ {"error": "Not available"}

エージェント: 「申し訳ございません。その本は現在貸出できません。」

ユーザー（心の声）: 「いつ返却されるの？予約できるの？
                  代わりの本は？何も分からない...」
    

@mcp.tool()
def borrow_book(title: str) -> dict:
    """
    書籍を借ります。
    
    エラーハンドリング:
        このツールは、エラーが発生した場合でも、
        次に取るべきアクションを明確に示します。
    """
    # 書籍の存在確認
    book = find_book_by_title(title)
    if not book:
        # 類似タイトルを検索して提案
        similar_books = search_similar_titles(title)
        
        if similar_books:
            return {
                "success": False,
                "error_type": "book_not_found",
                "message": f"'{title}'という書籍が見つかりませんでした。",
                "reason": "タイトルが正確に一致していない可能性があります。",
                "diagnostic": {
                    "searched_for": title,
                    "common_causes": [
                        "副題が省略されている",
                        "記号（：、！など）が異なる",
                        "誤字がある"
                    ]
                },
                "suggested_action": "以下の類似タイトルのいずれかではありませんか？",
                "suggestions": [
                    {
                        "title": book.title,
                        "author": book.author,
                        "match_score": 0.85,
                        "available": book.available_copies > 0
                    }
                    for book in similar_books[:3]
                ],
                "next_step": "正確なタイトルが分かったら、再度borrow_book()を呼び出してください。",
                "how_to_find_exact_title": "search_books()で部分一致検索すると正確なタイトルが分かります"
            }
        else:
            return {
                "success": False,
                "error_type": "book_not_found",
                "message": f"'{title}'という書籍が見つかりませんでした。",
                "reason": "図書館の蔵書にない可能性があります。",
                "suggested_action": "search_books()で利用可能な書籍を探してください。",
                "search_hint": f"search_books('{title.split()[0]}')を試してみてください。",
                "alternative_option": {
                    "description": "この本の購入リクエストを出すこともできます",
                    "tool_to_call": "library_request_purchase(title, reason='業務に必要')"
                }
            }
    
    # 在庫確認
    if book.available_copies == 0:
        # 誰が借りているか、いつ返却予定かを調べる
        borrowers = get_current_borrowers(book.isbn)
        earliest_return = min([b.return_date for b in borrowers])
        
        return {
            "success": False,
            "error_type": "not_available",
            "message": f"'{title}'は現在全て貸出中です。",
            "availability_details": {
                "total_copies": book.total_copies,
                "borrowed_copies": book.total_copies,
                "earliest_return_date": earliest_return.strftime("%Y-%m-%d"),
                "days_until_return": (earliest_return - datetime.now()).days,
                "all_borrowers": [
                    {
                        "name": b.name,
                        "division": b.division,
                        "borrow_date": b.borrow_date.strftime("%Y-%m-%d"),
                        "return_date": b.return_date.strftime("%Y-%m-%d")
                    }
                    for b in borrowers
                ]
            },
            "alternative_actions": [
                {
                    "option": 1,
                    "action": "reserve",
                    "title": "この本を予約する",
                    "description": "返却され次第、自動的にあなたに貸出されます",
                    "tool_to_call": "reserve_book(title)",
                    "estimated_wait": f"{(earliest_return - datetime.now()).days}日",
                    "pros": ["確実に借りられる", "手間なし"],
                    "cons": ["待ち時間が必要"]
                },
                {
                    "option": 2,
                    "action": "find_alternatives",
                    "title": "類似の貸出可能な本を探す",
                    "description": "同じトピックで今すぐ借りられる本",
                    "tool_to_call": f"find_available_books(query='{book.category}', exclude_title='{title}')",
                    "preview": get_related_available_books(book.isbn, limit=2),
                    "pros": ["今すぐ読める", "新しい視点が得られる"],
                    "cons": ["完全に同じ内容ではない"]
                },
                {
                    "option": 3,
                    "action": "contact_borrower",
                    "title": f"{borrowers[0].name}さんに早期返却を相談する",
                    "description": "緊急性が高い場合の最終手段",
                    "contact_method": f"Slack: @{borrowers[0].slack_id}",
                    "template_message": f"『{title}』を緊急で読む必要があります。もし読み終わっていれば、早めに返却いただけないでしょうか？",
                    "pros": ["最短で入手可能"],
                    "cons": ["相手の都合を考慮必要", "緊急時のみ推奨"],
                    "note": "本当に緊急の場合のみ使用してください"
                }
            ],
            "related_available_books": [
                {
                    "title": "信頼性の高い機械学習",
                    "author": "...",
                    "why_similar": "MLOpsと運用に焦点、実践的",
                    "available_copies": 1,
                    "similarity_score": 0.78
                },
                {
                    "title": "Kaggle Grandmasterに学ぶ機械学習実践アプローチ",
                    "author": "...",
                    "why_similar": "実践的なML手法を解説",
                    "available_copies": 1,
                    "similarity_score": 0.72
                }
            ],
            "user_guidance": {
                "recommendation": "オプション2の代替書籍を読むことを推奨します",
                "reasoning": "『信頼性の高い機械学習』は類似度が高く、今すぐ借りられます"
            }
        }
    
    # 貸出処理...
    

【改善前】
ユーザー: 「イシューからはじめよを借りたい」
エージェント: borrow_book("イシューからはじめよ")
→ {"error": "Not found"}
エージェント: 「その本は見つかりませんでした。」
ユーザー: 「正確なタイトルは？」（追加質問）
→ さらに2-3回のやり取りが必要

【改善後】
ユーザー: 「イシューからはじめよを借りたい」
エージェント: borrow_book("イシューからはじめよ")
→ 類似タイトル3件を含む詳細エラー
エージェント: 「『イシューからはじめよ』という書籍は見つかりませんでしたが、
以下のタイトルと一致する可能性があります：
1. 『イシューからはじめよ：知的生産の「シンプルな本質」』（一致度: 95%）
   - 著者：安宅和人
   - 貸出可能：2冊

こちらの本でしょうか？」
→ 1回のやり取りで解決
    

【改善前】
ユーザー: 「機械学習デザインパターンを借りたい」
エージェント: borrow_book("機械学習デザインパターン")
→ {"error": "Not available"}
エージェント: 「その本は貸出できません。」
ユーザー: 「いつ借りられるの？」（追加質問が必要）
エージェント: get_return_date("機械学習デザインパターン")
→ さらに1ツール呼び出し
ユーザー: 「代わりになる本は？」（さらに追加質問）
→ さらに1ツール呼び出し

【改善後】
ユーザー: 「機械学習デザインパターンを借りたい」
エージェント: borrow_book("機械学習デザインパターン")
→ 詳細なエラー情報を受信
エージェント: 「その本は現在貸出中で、10月15日（3日後）に返却予定です。
以下の選択肢があります：

【オプション1】この本を予約する
  - 返却され次第、自動的に貸出されます
  - 予想待ち時間：3日
  
【オプション2】類似の本を今すぐ借りる
  - 『信頼性の高い機械学習』（貸出可能）
    同じMLOpsトピック、実践的な内容
  - 『Kaggle Grandmasterに学ぶ機械学習実践アプローチ』（貸出可能）
    
【オプション3】借りている人に相談する
  - 山田花子さん（Data Science部門）
  - Slack: @yamada.hanako
  - 注：緊急の場合のみ推奨

どうされますか？」

→ 1回のツール呼び出しで、全ての情報と選択肢を提示