Skip to content

ClasCat® AI Research

クラスキャット – 生成 AI, AI エージェント, MCP

Menu
  • ホーム
    • ClassCat® AI Research ホーム
    • クラスキャット・ホーム
  • OpenAI API
    • OpenAI Python ライブラリ 1.x : 概要
    • OpenAI ブログ
      • GPT の紹介
      • GPT ストアの紹介
      • ChatGPT Team の紹介
    • OpenAI platform 1.x
      • Get Started : イントロダクション
      • Get Started : クイックスタート (Python)
      • Get Started : クイックスタート (Node.js)
      • Get Started : モデル
      • 機能 : 埋め込み
      • 機能 : 埋め込み (ユースケース)
      • ChatGPT : アクション – イントロダクション
      • ChatGPT : アクション – Getting started
      • ChatGPT : アクション – アクション認証
    • OpenAI ヘルプ : ChatGPT
      • ChatGPTとは何ですか?
      • ChatGPT は真実を語っていますか?
      • GPT の作成
      • GPT FAQ
      • GPT vs アシスタント
      • GPT ビルダー
    • OpenAI ヘルプ : ChatGPT > メモリ
      • FAQ
    • OpenAI ヘルプ : GPT ストア
      • 貴方の GPT をフィーチャーする
    • OpenAI Python ライブラリ 0.27 : 概要
    • OpenAI platform
      • Get Started : イントロダクション
      • Get Started : クイックスタート
      • Get Started : モデル
      • ガイド : GPT モデル
      • ガイド : 画像生成 (DALL·E)
      • ガイド : GPT-3.5 Turbo 対応 微調整
      • ガイド : 微調整 1.イントロダクション
      • ガイド : 微調整 2. データセットの準備 / ケーススタディ
      • ガイド : 埋め込み
      • ガイド : 音声テキスト変換
      • ガイド : モデレーション
      • ChatGPT プラグイン : イントロダクション
    • OpenAI Cookbook
      • 概要
      • API 使用方法 : レート制限の操作
      • API 使用方法 : tiktoken でトークンを数える方法
      • GPT : ChatGPT モデルへの入力をフォーマットする方法
      • GPT : 補完をストリームする方法
      • GPT : 大規模言語モデルを扱う方法
      • 埋め込み : 埋め込みの取得
      • GPT-3 の微調整 : 分類サンプルの微調整
      • DALL-E : DALL·E で 画像を生成して編集する方法
      • DALL·E と Segment Anything で動的マスクを作成する方法
      • Whisper プロンプティング・ガイド
  • Gemini API
    • Tutorials : クイックスタート with Python (1) テキスト-to-テキスト生成
    • (2) マルチモーダル入力 / 日本語チャット
    • (3) 埋め込みの使用
    • (4) 高度なユースケース
    • クイックスタート with Node.js
    • クイックスタート with Dart or Flutter (1) 日本語動作確認
    • Gemma
      • 概要 (README)
      • Tutorials : サンプリング
      • Tutorials : KerasNLP による Getting Started
  • Keras 3
    • 新しいマルチバックエンド Keras
    • Keras 3 について
    • Getting Started : エンジニアのための Keras 入門
    • Google Colab 上のインストールと Stable Diffusion デモ
    • コンピュータビジョン – ゼロからの画像分類
    • コンピュータビジョン – 単純な MNIST convnet
    • コンピュータビジョン – EfficientNet を使用した微調整による画像分類
    • コンピュータビジョン – Vision Transformer による画像分類
    • コンピュータビジョン – 最新の MLPモデルによる画像分類
    • コンピュータビジョン – コンパクトな畳込み Transformer
    • Keras Core
      • Keras Core 0.1
        • 新しいマルチバックエンド Keras (README)
        • Keras for TensorFlow, JAX, & PyTorch
        • 開発者ガイド : Getting started with Keras Core
        • 開発者ガイド : 関数型 API
        • 開発者ガイド : シーケンシャル・モデル
        • 開発者ガイド : サブクラス化で新しい層とモデルを作成する
        • 開発者ガイド : 独自のコールバックを書く
      • Keras Core 0.1.1 & 0.1.2 : リリースノート
      • 開発者ガイド
      • Code examples
      • Keras Stable Diffusion
        • 概要
        • 基本的な使い方 (テキスト-to-画像 / 画像-to-画像変換)
        • 混合精度のパフォーマンス
        • インペインティングの簡易アプリケーション
        • (参考) KerasCV – Stable Diffusion を使用した高性能画像生成
  • TensorFlow
    • TF 2 : 初級チュートリアル
    • TF 2 : 上級チュートリアル
    • TF 2 : ガイド
    • TF 1 : チュートリアル
    • TF 1 : ガイド
  • その他
    • 🦜️🔗 LangChain ドキュメント / ユースケース
    • Stable Diffusion WebUI
      • Google Colab で Stable Diffusion WebUI 入門
      • HuggingFace モデル / VAE の導入
      • LoRA の利用
    • Diffusion Models / 拡散モデル
  • クラスキャット
    • 会社案内
    • お問合せ
    • Facebook
    • ClassCat® Blog
Menu

MCP コンセプト : ツール – 実装 & パターン例 / アノテーション

Posted on 05/26/2025 by Masashi Okumura

ツールは、サーバが実行可能な機能をクライアントに公開することを可能にする、Model Context Protocol (MCP) の強力なプリミティブです。ツールを通して、LLM は外部システムと相互作用し、計算を実行し、そして現実世界でアクションを実行できます。

Model Context Protocol (MCP) : コンセプト : ツール – 実装 & パターン例 / アノテーション

作成 : クラスキャット・セールスインフォメーション
作成日時 : 05/26/2025

* 本記事は github modelcontextprotocol の以下のページを独自に翻訳した上でまとめ直し、補足説明を加えています :

  • Model Context Protocol : Concepts : Tools

* サンプルコードの動作確認はしておりますが、必要な場合には適宜、追加改変しています。
* ご自由にリンクを張って頂いてかまいませんが、sales-info@classcat.com までご一報いただけると嬉しいです。

 

クラスキャット 人工知能 研究開発支援サービス ⭐️ リニューアルしました 😉

◆ クラスキャット は人工知能に関する各種サービスを提供しています。お気軽にご相談ください :

  • 人工知能導入個別相談会(無償)実施中! [詳細]

  • 人工知能研究開発支援 [詳細]
    1. 自社特有情報を含むチャットボット構築支援
    2. 画像認識 (医療系含む) / 画像生成

  • PoC(概念実証)を失敗させないための支援 [詳細]

◆ お問合せ : 下記までお願いします。

  • クラスキャット セールス・インフォメーション
  • sales-info@classcat.com
  • ClassCatJP

 

 

Model Context Protocol (MCP) : コンセプト : ツール – 実装 & パターン例 / アノテーション

LLM がサーバを通してアクションを実行できるようにします

ツールは、サーバが実行可能な機能をクライアントに公開することを可能にする、Model Context Protocol (MCP) の強力なプリミティブです。ツールを通して、LLM は外部システムと相互作用し、計算を実行し、そして現実世界でアクションを実行できます。

Note : ツールは、モデルにより制御可能 (model-controlled) であるように設計されています、つまりツールは、AI モデルが (承認を与えるため人間介在型で) 自動的にツールを呼び出せるような意図をもって、サーバからクライアントに公開されます。

 

概要

MCP のツールは、サーバが実行可能な関数を公開することを可能にします、これらの関数はクライアントにより呼び出され、LLM により使用されてアクションを実行できます。ツールの主要な観点は :

  • 検出 (Discovery) : クライアントは tools/list エンドポイント経由で利用可能なツールをリストアップできます。

  • 呼び出し (Invocation) : ツールは tools/call エンドポイントを使用して呼び出されます、そこではサーバはリクエストされた操作を実行して結果を返します。

  • 柔軟性 (Flexibility) : ツールは単純な計算から複雑な API インタラクションまで多岐に渡ります。

リソース のように、ツールは一意の名前で識別され、使用方法を案内するための説明を含めることができます。但し、リソースとは異なり、ツールは状態を変更したり外部システムと相互作用可能な動的操作を表します。

 

ツール定義の構造

各ツールは以下の構造で定義されます :

{
  name: string;          // Unique identifier for the tool
  description?: string;  // Human-readable description
  inputSchema: {         // JSON Schema for the tool's parameters
    type: "object",
    properties: { ... }  // Tool-specific parameters
  },
  annotations?: {        // Optional hints about tool behavior
    title?: string;      // Human-readable title for the tool
    readOnlyHint?: boolean;    // If true, the tool does not modify its environment
    destructiveHint?: boolean; // If true, the tool may perform destructive updates
    idempotentHint?: boolean;  // If true, repeated calls with same args have no additional effect
    openWorldHint?: boolean;   // If true, tool interacts with external entities
  }
}

 

ツールの実装

MCP サーバで基本的なツールを実装するサンプルが以下です :

TypeScript

const server = new Server({
  name: "example-server",
  version: "1.0.0"
}, {
  capabilities: {
    tools: {}
  }
});

// Define available tools
server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [{
      name: "calculate_sum",
      description: "Add two numbers together",
      inputSchema: {
        type: "object",
        properties: {
          a: { type: "number" },
          b: { type: "number" }
        },
        required: ["a", "b"]
      }
    }]
  };
});

// Handle tool execution
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  if (request.params.name === "calculate_sum") {
    const { a, b } = request.params.arguments;
    return {
      content: [
        {
          type: "text",
          text: String(a + b)
        }
      ]
    };
  }
  throw new Error("Tool not found");
});

Python

app = Server("example-server")

@app.list_tools()
async def list_tools() -> list[types.Tool]:
    return [
        types.Tool(
            name="calculate_sum",
            description="Add two numbers together",
            inputSchema={
                "type": "object",
                "properties": {
                    "a": {"type": "number"},
                    "b": {"type": "number"}
                },
                "required": ["a", "b"]
            }
        )
    ]

@app.call_tool()
async def call_tool(
    name: str,
    arguments: dict
) -> list[types.TextContent | types.ImageContent | types.EmbeddedResource]:
    if name == "calculate_sum":
        a = arguments["a"]
        b = arguments["b"]
        result = a + b
        return [types.TextContent(type="text", text=str(result))]
    raise ValueError(f"Tool not found: {name}")

 

ツールパターンの例

サーバが提供できるツールの種類の幾つかの例が以下です :

 

システム操作

ローカルシステムと相互作用するツール :
​

{
  name: "execute_command",
  description: "Run a shell command",
  inputSchema: {
    type: "object",
    properties: {
      command: { type: "string" },
      args: { type: "array", items: { type: "string" } }
    }
  }
}

 

API 統合

外部 API をラップするツール :

{
  name: "github_create_issue",
  description: "Create a GitHub issue",
  inputSchema: {
    type: "object",
    properties: {
      title: { type: "string" },
      body: { type: "string" },
      labels: { type: "array", items: { type: "string" } }
    }
  }
}

 

データ処理

データを変換や分析するツール :

{
  name: "analyze_csv",
  description: "Analyze a CSV file",
  inputSchema: {
    type: "object",
    properties: {
      filepath: { type: "string" },
      operations: {
        type: "array",
        items: {
          enum: ["sum", "average", "count"]
        }
      }
    }
  }
}

 

ベスト・プラクティス

ツールを実装する際には :

  1. 明確で、説明的な名前と説明を提供する

  2. パラメータ用に詳細な JSON スキーマ定義を使用する

  3. ツール説明に例を含めてモデルが使用する方法を示す

  4. 適切なエラー処理と検証を実装する

  5. 長時間の操作の進捗レポートを使用する

  6. ツール操作に焦点を当てて単一機能 (atomic) に保つ

  7. 想定される戻り値の構造を文書化する

  8. 適切なタイムアウトの実装

  9. リソース集約的な操作にはレート制限を考慮する

  10. デバッグと監視用にツール使用量をログ記録する

 

セキュリティの考慮事項

ツールを公開する際 :

 

入力の検証

​

  • スキーマに対してすべてのパラメータを検証する

  • ファイルパスとシステムコマンドをサニタイズする

  • URL と外部識別子を検証する

  • パラメータサイズと範囲を確認する

  • コマンドインジェクションを防止する

 

アクセス制御

  • 必要に応じて認証を実装する

  • 適切な認可 (authorization) チェックを使用する

  • ツールの使用状況を監査する (audit)

  • レート制限リクエスト

  • 不正利用 (abuse) を監視する

 

エラー処理

  • 内部エラーをクライアントに公開しない

  • セキュリティ関連エラーをログ記録する

  • タイムアウトを適切に処理する

  • エラー後にリソースをクリーンアップする

  • 戻り値を検証する

 

ツールの検出と更新

MCP は動的ツール検出をサポートします :

  1. クライアントは利用可能なツールをいつでもリストアップできます

  2. サーバは、notifications/tools/list_changed を使用してツールが変更された場合、クライアントに通知できます

  3. ツールは実行中に追加または削除できます。

  4. ツール定義は更新できます (注意深く行われる必要がありますが)

 

エラー処理

ツールのエラーは MCP プロトコルレベルのエラーとしてではなく、結果 (result) オブジェクト内で報告する必要があります。これは LLM がエラーを確認して場合によっては処理することを可能にします。ツールがエラーに遭遇する場合 :

  1. 結果で isError を true に設定する
  2. content 配列にエラーの詳細を含める

Here’s an example of proper error handling for tools:

TypeScript

try {
  // Tool operation
  const result = performOperation();
  return {
    content: [
      {
        type: "text",
        text: `Operation successful: ${result}`
      }
    ]
  };
} catch (error) {
  return {
    isError: true,
    content: [
      {
        type: "text",
        text: `Error: ${error.message}`
      }
    ]
  };
}

Python

try:
    # Tool operation
    result = perform_operation()
    return types.CallToolResult(
        content=[
            types.TextContent(
                type="text",
                text=f"Operation successful: {result}"
            )
        ]
    )
except Exception as error:
    return types.CallToolResult(
        isError=True,
        content=[
            types.TextContent(
                type="text",
                text=f"Error: {str(error)}"
            )
        ]
    )

このアプローチは、LLM がエラーが発生したことを確認し、場合によっては是正措置を取ったり人間の介入をリクエストすることを可能にします。

 

ツール・アノテーション

ツール・アノテーションはツールの動作に関する追加のメタデータを提供し、クライアントがツールを提示して管理する方法を理解するのに役立ちます。これらのアノテーションはツールの性質と影響を説明するヒントですが、セキュリティ上の判断のために依存するべきではありません。

 

ツール・アノテーションの目的

ツール・アノテーションは幾つかの主要な目的を果たします :

  1. モデルコンテキストに影響を与えることなく UX 固有の情報を提供します。

  2. クライアントがツールを適切に分類して提示するのに役立ちます。

  3. ツールの潜在的な副作用についての情報を伝えます。

  4. ツール承認のための直感的なインターフェイスを開発することを支援する。

 

利用可能なツール・アノテーション

MCP 仕様はツール用に以下のアノテーションを定義しています :

アノテーション タイプ デフォルト 説明
title string – ツールのための可読なタイトル、UI 表示に有用です
readOnlyHint boolean false true の場合、ツールは環境を変更しないことを示します
destructiveHint boolean true true の場合、ツールは破壊的な更新を実行する可能性があります (readOnlyHint が false の場合だけ意味があります)
idempotentHint boolean false true の場合、同じ引数でツールを繰り返し呼び出しても、追加の効果はありません (readOnlyHint が false の場合だけ意味があります)
openWorldHint boolean true true の場合、ツールは外部エンティティの “open world” と相互作用する可能性があります

 

使用例

様々なシナリオのためにアノテーション付きのツールを定義する方法は以下です :

TypeScript

// A read-only search tool
{
  name: "web_search",
  description: "Search the web for information",
  inputSchema: {
    type: "object",
    properties: {
      query: { type: "string" }
    },
    required: ["query"]
  },
  annotations: {
    title: "Web Search",
    readOnlyHint: true,
    openWorldHint: true
  }
}

// A destructive file deletion tool
{
  name: "delete_file",
  description: "Delete a file from the filesystem",
  inputSchema: {
    type: "object",
    properties: {
      path: { type: "string" }
    },
    required: ["path"]
  },
  annotations: {
    title: "Delete File",
    readOnlyHint: false,
    destructiveHint: true,
    idempotentHint: true,
    openWorldHint: false
  }
}

// A non-destructive database record creation tool
{
  name: "create_record",
  description: "Create a new record in the database",
  inputSchema: {
    type: "object",
    properties: {
      table: { type: "string" },
      data: { type: "object" }
    },
    required: ["table", "data"]
  },
  annotations: {
    title: "Create Database Record",
    readOnlyHint: false,
    destructiveHint: false,
    idempotentHint: false,
    openWorldHint: false
  }
}

 

サーバ実装へのアノテーションの統合

TypeScript

server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [{
      name: "calculate_sum",
      description: "Add two numbers together",
      inputSchema: {
        type: "object",
        properties: {
          a: { type: "number" },
          b: { type: "number" }
        },
        required: ["a", "b"]
      },
      annotations: {
        title: "Calculate Sum",
        readOnlyHint: true,
        openWorldHint: false
      }
    }]
  };
});

Python

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("example-server")

@mcp.tool(
    annotations={
        "title": "Calculate Sum",
        "readOnlyHint": True,
        "openWorldHint": False
    }
)
async def calculate_sum(a: float, b: float) -> str:
    """Add two numbers together.
    
    Args:
        a: First number to add
        b: Second number to add
    """
    result = a + b
    return str(result)

 

以上



クラスキャット

最近の投稿

  • LangGraph 0.5 : エージェント開発 : ワークフローとエージェント
  • LangGraph 0.5 : エージェント開発 : エージェントの実行
  • LangGraph 0.5 : エージェント開発 : prebuilt コンポーネントを使用したエージェント開発
  • LangGraph 0.5 : Get started : ローカルサーバの実行
  • LangGraph 0.5 on Colab : Get started : human-in-the-loop 制御の追加

タグ

AutoGen (13) ClassCat Press Release (20) ClassCat TF/ONNX Hub (11) DGL 0.5 (14) Eager Execution (7) Edward (17) FLUX.1 (16) Gemini (20) HuggingFace Transformers 4.5 (10) HuggingFace Transformers 4.6 (7) HuggingFace Transformers 4.29 (9) Keras 2 Examples (98) Keras 2 Guide (16) Keras 3 (10) Keras Release Note (17) Kubeflow 1.0 (10) LangChain (45) LangGraph (24) LangGraph 0.5 (8) MediaPipe 0.8 (11) Model Context Protocol (16) NNI 1.5 (16) OpenAI Agents SDK (8) OpenAI Cookbook (13) OpenAI platform (10) OpenAI platform 1.x (10) OpenAI ヘルプ (8) TensorFlow 2.0 Advanced Tutorials (33) TensorFlow 2.0 Advanced Tutorials (Alpha) (15) TensorFlow 2.0 Advanced Tutorials (Beta) (16) TensorFlow 2.0 Guide (10) TensorFlow 2.0 Guide (Alpha) (16) TensorFlow 2.0 Guide (Beta) (9) TensorFlow 2.0 Release Note (12) TensorFlow 2.0 Tutorials (20) TensorFlow 2.0 Tutorials (Alpha) (14) TensorFlow 2.0 Tutorials (Beta) (12) TensorFlow 2.4 Guide (24) TensorFlow Deploy (8) TensorFlow Get Started (7) TensorFlow Probability (9) TensorFlow Programmer's Guide (22) TensorFlow Release Note (18) TensorFlow Tutorials (33) TF-Agents 0.4 (11)
2025年5月
月 火 水 木 金 土 日
 1234
567891011
12131415161718
19202122232425
262728293031  
« 4月   6月 »
© 2025 ClasCat® AI Research | Powered by Minimalist Blog WordPress Theme