概要: MCP プロトコルの 3 つの基本要素
Nel 最初の記事 このシリーズの を紹介しました モデルコンテキストプロトコル (MCP) およびそのホスト/クライアント/サーバー アーキテクチャ。 今こそそれらを詳細に分析する時です 3つのプリミティブ MCP サーバーが公開できるもの: ツール, リソース e プロンプト.
各プリミティブは、AI と外界との間の相互作用において明確な役割を果たします。違いを理解して、 効果的な MCP サーバーを設計するには、それぞれのユースケースと内部構造が重要です そしてよく構成されています。この記事では、理論と検証スキームについて説明します。 ゾッド、 JSON-RPC ペイロードと TypeScript ハンドラー、プロジェクトの具体的な例の分析 テックMCP.
この記事で学べること
- ツール、リソース、プロンプトの違い: 役割、制御、使用例
- Zod 検証と非同期ハンドラーを使用してツールを定義する方法
- URI テンプレートと読み取り専用データを使用してリソースを公開する方法
- パラメータ化された再利用可能なプロンプトを作成する方法
- 各プリミティブの JSON-RPC ペイロードの形式
- 検出から終了までの MCP セッションのライフサイクル
- ツールの説明と命名規則のベスト プラクティス
3 つのプリミティブの比較
各プリミティブについて詳しく説明する前に、概要を理解しておくと役立ちます。 それらの根本的な違い。各プリミティブは特定のニーズに対応します MCP エコシステム内:
MCP プリミティブの概要
| 原生的 | 役割 | 誰がコントロールするのか | 副作用 | Esempio |
|---|---|---|---|---|
| ツール | AIが呼び出せる機能 | AIが自律的に判断する | はい (ステータスを変更可能) | create-sprint, analyze-diff |
| リソース | 読み取り可能なデータ | ホストアプリケーション | いいえ (読み取り専用) | sprint://{id}, file:///config |
| プロンプト | 再利用可能な事前定義テンプレート | ユーザーが選択します | いいえ (メッセージが生成されます) | sprint-review, code-analysis |
この区別は重要です: ツール それらはプロトコルの運用の中心であり、 ル リソース 彼らはコンテキストとデータを提供します。 プロンプト 彼らはAIを導入します 構造化されたタスク。それぞれのプリミティブを詳しく見てみましょう。
1. ツール：AIが呼び出せる機能
I ツール それらは MCP インタラクションの中心を表します。 AIができる機能です 会話中に自分自身を呼び出して、現実世界で具体的なアクションを実行します。 単純な API 呼び出しとは異なり、MCP ツールはパラメーターを明示的に宣言します。 型付きスキーマを使用して AI が理解できるようにする いつ e として 彼を呼んでください。
ツールの基本的な機能
- AIがいつ電話をかけるかを決定します: 会話のコンテキストに基づいて、言語モデルがどのツールをどのパラメータで呼び出すかを自律的に選択します。
- Zod で入力されたパラメータ: 各ツールは Zod スキーマを使用して入力を宣言し、実行時の自動検証を保証します。
- 構造化された結果: 結果は常に次の配列になります。
contentタイプ付きtext,imageoresource - 副作用がある可能性があります: ファイルの作成、データベースへの書き込み、外部 API の呼び出し、通知の送信
- コンポーザブル：AIは複数のツールを順番に組み合わせて複雑なタスクを完了できます
TypeScript のツールの構造
ツールの登録は、一意の名前、 AI、Zod パラメーター スキーム、および非同期ハンドラーの説明。ここに例があります プロジェクトから完了する テックMCP:
import { z } from 'zod';
server.tool(
'create-sprint', // Nome univoco del tool
'Create a new sprint with a name, date range, and goals. ' +
'Returns the created sprint object with id, status, and dates. ' +
'Use this when the user wants to start planning a new iteration.',
{ // Schema parametri (Zod)
name: z.string().describe('Sprint name, e.g. Sprint-15'),
startDate: z.string().describe('Start date in ISO format'),
endDate: z.string().describe('End date in ISO format'),
goals: z.array(z.string()).describe('List of sprint goals'),
},
async ({ name, startDate, endDate, goals }) => { // Handler
const sprint = store.createSprint({
name,
startDate,
endDate,
goals
});
return {
content: [{
type: 'text',
text: JSON.stringify(sprint, null, 2)
}]
};
}
);
なぜ検証に Zod を使用するのでしょうか?
ゾッド 包括的なタイプ セーフティを提供する TypeScript ファーストの検証ライブラリ コンパイル時と実行時の検証です。 MCP SDK は Zod スキーマを自動的に変換します で JSONスキーマ、AI がツールのパラメーターを理解するために使用する形式。 これは、Zod スキーマを宣言することで、入力の自動検証が得られることを意味します。 AI のドキュメント生成と TypeScript での型推論を 1 つにまとめたもの 定義。
ツールの応答形式
各ツール ハンドラーは配列を含むオブジェクトを返す必要があります content。あらゆる要素
配列には type これはコンテンツの形式を示します。
// Risposta testuale (più comune)
return {
content: [{
type: 'text',
text: 'Sprint creato con successo: Sprint-15 (ID: 42)'
}]
};
// Risposta con immagine
return {
content: [{
type: 'image',
data: base64EncodedImage,
mimeType: 'image/png'
}]
};
// Risposta con errore
return {
content: [{
type: 'text',
text: 'Errore: sprint non trovato'
}],
isError: true
};
Tech-MCPプロジェクトのツールカテゴリ
プロジェクトでは テックMCP、 85 以上のツールは、実行する操作の種類に基づいて機能カテゴリに分類されています。
作業の種類によるツールの分類
| カテゴリ | ツール例 | 効果 | 説明 |
|---|---|---|---|
| 創造 | create-sprint, save-snippet |
彼らはデータベースに書き込みます | 新しい永続エンティティを作成します |
| 読む | get-sprint, search-snippets |
読み取り専用 | 既存のデータを回復します |
| 分析 | analyze-diff, find-bottlenecks |
副作用なし | 入力を処理し、洞察を生成します |
| 世代 | generate-unit-tests, generate-compose |
彼らはアウトプットを生み出す | コード、構成、テンプレートを生成します |
| 監視 | list-pipelines, get-budget-status |
外部状態を読み取ります | 外部システムのステータスを確認します |
2. リソース: 読み取り可能なデータ
Le リソース これらは 2 番目の MCP プリミティブです。これらはアプリケーションがホストするデータを表します 読み取り、コンテキストとして AI に提供できます。ツールとは異なり、リソースは呼び出されません AI から直接: およびホスト アプリケーション (Claude Desktop、Cursor など) がいつ、どのアプリケーションを実行するかを決定します。 リソースは会話のコンテキストで読み込まれます。
リソースの基本的な特性
- URIで識別: 各リソースには、次のような一意の識別子があります。
file:///path/to/file,db://schema/tableosprint://{id} - アプリケーションにはそれらが必要です：AIが判断するツールとは異なり、リソースやホストアプリケーションがアクセスを制御するため
- 読み取り専用: リソースはサーバーの状態を変更せず、データを提供することのみを目的としています。
- URI テンプレートをサポートします: パラメトリックリソースの場合、次のようなテンプレートを定義できます
sprint://{id} - 明示的な MIME タイプ: 各リソースはコンテンツ タイプを宣言します (
application/json,text/plain、など）
URIテンプレートによるリソースの定義
これは、スプリントの詳細を公開するパラメトリック リソースを定義する方法です。 ID で識別されます:
server.resource(
'sprint://{id}', // URI template
'Get sprint details by ID', // Descrizione
async (uri) => { // Handler
const id = extractIdFromUri(uri);
const sprint = store.getSprint(id);
if (!sprint) {
throw new Error(`Sprint ${id} not found`);
}
return {
contents: [{
uri: uri.href,
mimeType: 'application/json',
text: JSON.stringify(sprint, null, 2)
}]
};
}
);
静的リソースと動的リソース
MCP リソースは、次の 2 つのカテゴリに分類されます。 静的 e ダイナミクス。 静的リソースには固定 URI があり、常に同じエンドポイントからデータを返します。 動的リソースは、URI テンプレートを使用してパラメータを受け入れます。
// Resource statica: URI fisso, dati globali
server.resource(
'config://app-settings',
'Application configuration settings',
async (uri) => {
return {
contents: [{
uri: uri.href,
mimeType: 'application/json',
text: JSON.stringify(config.getAll())
}]
};
}
);
// Resource dinamica: URI template con parametro
server.resource(
'user://{userId}/profile',
'User profile data',
async (uri) => {
const userId = extractParam(uri, 'userId');
const profile = await db.getProfile(userId);
return {
contents: [{
uri: uri.href,
mimeType: 'application/json',
text: JSON.stringify(profile)
}]
};
}
);
リソースの JSON-RPC ペイロード
ホスト アプリケーションがリソースを要求すると、MCP プロトコルは 2 つの JSON-RPC メソッドを使用します。
resources/list 利用可能なリソースを発見するため resources/read
その内容を読むには。
// Richiesta: elenco delle resources disponibili
{ "method": "resources/list" }
// Risposta del server
{
"resources": [
{
"uri": "config://app-settings",
"name": "App Settings",
"mimeType": "application/json"
}
],
"resourceTemplates": [
{
"uriTemplate": "sprint://{id}",
"name": "Sprint Details",
"mimeType": "application/json"
}
]
}
// Richiesta: lettura di una resource specifica
{ "method": "resources/read",
"params": { "uri": "sprint://42" } }
// Risposta del server
{
"contents": [{
"uri": "sprint://42",
"mimeType": "application/json",
"text": "{ \"id\": 42, \"name\": \"Sprint-15\" }"
}]
}
Tech-MCPプロジェクトに関する注意事項
プロジェクトでは テックMCP、 データとのやり取りは主に i を通じて行われます。 ツール。 リソースは、プロジェクト構成を公開するなど、将来の開発のために計画されています。 AI の読み取り専用コンテキストとしてのデータベース スキーマまたは API ドキュメント。
3. プロンプト: 再利用可能な定義済みテンプレート
I プロンプト これらは 3 番目の MCP プリミティブです。これらは、ガイドとなる事前定義されたテンプレートを表します。 複雑で構造化されたタスクを実行する AI。 （AIが判断する）ツールとは異なり、 リソース (アプリケーションが決定する)、プロンプトは次のとおりです。 ユーザーが選択した のために 特定のワークフローを開始します。
プロンプトの基本的な機能
- AI を推進するのは彼らです: 言語モデルを特定の目標に向けて指示する構造化された指示を提供します。
- 彼らは議論を受け入れます: ユーザー入力でパラメータ化可能
- ツールとの組み合わせも可能: プロンプトは、順番に呼び出す一連のツールを AI に提案できます
- 再利用可能: 定義すると、さまざまなパラメーターを使用してさまざまな会話で使用できます。
- ユーザーが選択した: AI ではなく、ユーザーがどのプロンプトをアクティブにするかを選択します。
引数を伴うプロンプトの定義
MCP プロンプトは、名前、説明、引数のリスト、および関数で定義されます。 AI に送信するメッセージを生成します。
server.prompt(
'sprint-review', // Nome univoco
'Generate a comprehensive sprint review report', // Descrizione
[ // Argomenti
{
name: 'sprintId',
description: 'ID of the sprint to review',
required: true
},
{
name: 'format',
description: 'Output format: summary, detailed, or metrics-only',
required: false
}
],
async ({ sprintId, format }) => ({ // Handler
messages: [{
role: 'user',
content: {
type: 'text',
text: `Analizza lo sprint ${sprintId} con i seguenti passaggi:
1. Usa il tool get-sprint per recuperare i dati dello sprint
2. Usa calculate-velocity per calcolare la velocity del team
3. Usa get-sprint-stories per l'elenco delle storie completate
4. Genera un report in formato ${format || 'detailed'} con:
- Obiettivi raggiunti vs pianificati
- Velocity e trend rispetto agli sprint precedenti
- Storie completate e non completate
- Raccomandazioni per il prossimo sprint`
}
}]
}))
);
プロンプトの JSON-RPC ペイロード
他のプリミティブと同様に、プロンプトは検出に専用の JSON-RPC メソッドを使用します。 そして呼び出し:
// Discovery: elenco dei prompts disponibili
{ "method": "prompts/list" }
// Risposta del server
{
"prompts": [
{
"name": "sprint-review",
"description": "Generate a comprehensive sprint review report",
"arguments": [
{
"name": "sprintId",
"description": "ID of the sprint to review",
"required": true
},
{
"name": "format",
"description": "Output format: summary, detailed, or metrics-only",
"required": false
}
]
}
]
}
// Invocazione di un prompt
{ "method": "prompts/get",
"params": {
"name": "sprint-review",
"arguments": { "sprintId": "42", "format": "detailed" }
}
}
// Risposta: messaggi generati dal prompt
{
"messages": [{
"role": "user",
"content": {
"type": "text",
"text": "Analizza lo sprint 42 con i seguenti passaggi..."
}
}]
}
ツールを調整するプロンプト
プロンプトの真の力は、複雑なシーケンスを調整するために使用されるときに現れます。 ツールの。適切に設計されたプロンプトは、複数ステップのワークフローを通じて AI をガイドできます。
server.prompt(
'full-code-review',
'Perform a comprehensive code review workflow',
[
{ name: 'filePath', description: 'Path to the file to review', required: true },
{ name: 'language', description: 'Programming language', required: true }
],
async ({ filePath, language }) => ({
messages: [{
role: 'user',
content: {
type: 'text',
text: `Esegui una code review completa del file ${filePath} (${language}):
STEP 1 - Analisi statica:
Usa analyze-diff per identificare problemi nel codice
STEP 2 - Generazione test:
Usa generate-unit-tests per creare test per le funzioni trovate
STEP 3 - Verifica stile:
Controlla che il codice segua le convenzioni del progetto
STEP 4 - Report finale:
Genera un report con: problemi trovati, test suggeriti,
miglioramenti proposti, severity di ogni issue`
}
}]
}))
);
注: Tech-MCP プロジェクトのプロンプト
リソースと同様に、プロジェクトも テックMCP 現在私を使用しています ツール メインプリミティブとして。プロンプトは将来の開発に予定されており、 スプリントレビュー、オンボーディングなどの繰り返しのシナリオ向けに事前定義されたワークフローを作成することを目的としています。 新しい開発者の数とチームのパフォーマンス分析。
AI はどのようにツールを選択するか: 説明の役割
MCP サーバーがクライアントに登録すると、次の経由で利用可能なツールのリストが公開されます。
方法 tools/list。 AI はツールごとに 3 つの重要な情報を受け取ります。
- 名前: 一意の識別子 (例:
create-sprint) - 説明: ツールの機能を説明する自然言語テキスト
- パラメータスキーム: 入力パラメータの構造とタイプと説明
La 説明 そして最も重要な要素: よく書かれた説明により AI が可能になります 理解する いつ ツールを使用して、 cosa 結果として期待される どの中の シナリオ そしてそれを呼び出すのが適切です。
ツールの説明のベスト プラクティス
OTTIMO (spiega cosa fa, cosa ritorna, quando usarlo):
"Create a new sprint with a name, date range, and goals.
Returns the created sprint object with id, name, dates, status.
Use this when the user wants to start planning a new iteration."
BUONO (spiega cosa fa e gli input):
"Create a new sprint with a name, date range, and goals"
VAGO (l'AI potrebbe non capire quando usarlo):
"Sprint creation tool"
効果的な説明のためのチェックリスト
| 要素 | リクエスト | Esempio |
|---|---|---|
| アクション | ツールは何をするのでしょうか? | 「新しいスプリントを作成します...」 |
| 入力 | どのようなパラメータが必要ですか? | 「...名前、日付範囲、目標付き」 |
| 出力 | 何が戻ってくるのでしょうか？ | 「作成されたスプリント オブジェクトを ID で返します...」 |
| コンテクスト | いつ使用しますか? | 「ユーザーが新しい反復を計画したい場合に使用します」 |
MCP セッションのライフサイクル
各 MCP インタラクションは、4 つのフェーズに構造化されたライフサイクルに従います。これを理解してください フローは、あらゆるシナリオで正しく動作するサーバーを設計するために不可欠です。
[1] INIZIALIZZAZIONE
Client --> Server: initialize (versione protocollo, capabilities)
Server --> Client: capabilities (tool list, resource templates, prompts)
[2] DISCOVERY
Client --> Server: tools/list
Server --> Client: [{ name, description, inputSchema }, ...]
Client --> Server: resources/list
Server --> Client: [{ uri, name, mimeType }, ...]
Client --> Server: prompts/list
Server --> Client: [{ name, description, arguments }, ...]
[3] UTILIZZO (ripetuto N volte durante la sessione)
Client --> Server: tools/call { name, arguments }
Server --> Client: { content: [...] }
Client --> Server: resources/read { uri }
Server --> Client: { contents: [...] }
Client --> Server: prompts/get { name, arguments }
Server --> Client: { messages: [...] }
[4] CHIUSURA
Client --> Server: close
フェーズの詳細
- 初期化: クライアントはプロトコルのバージョンとその機能を送信します。 サーバーは、サポートするプリミティブ (ツール、リソース、プロンプト) と独自のプリミティブを宣言することで応答します。 機能 (通知、ログ記録など)。
- 発見: クライアントはサーバーにクエリを実行して、利用可能なすべてのプリミティブを検出します。 このフェーズは、AI に決定に必要な情報を提供するため、基本的なフェーズです。 どのツールを使用するか。
- 使用法: セッション中に N 回繰り返される操作フェーズ。クライアント ツールを呼び出し、リソースを読み取り、任意の順序および組み合わせでプロンプトをトリガーできます。
- 閉鎖: クライアントはセッションの終了を通知します。サーバーがリソースを解放します そして接続を閉じます。
Zod を使用したパラメータ検証: 高度な例
Zod は、パラメータの正確なパターンを定義できる幅広いバリデータを提供します ツールの。プロジェクトで使用されている高度なパターンをいくつか紹介します。 テックMCP:
import { z } from 'zod';
// Schema con enum e valori opzionali
const createTaskSchema = {
title: z.string().min(1).max(200)
.describe('Task title'),
priority: z.enum(['low', 'medium', 'high', 'critical'])
.describe('Task priority level'),
assignee: z.string().optional()
.describe('Username of the assignee'),
labels: z.array(z.string()).default([])
.describe('List of labels to apply'),
estimate: z.number().positive().optional()
.describe('Estimated hours to complete'),
};
// Schema con oggetti nested
const deployConfigSchema = {
environment: z.enum(['staging', 'production']),
version: z.string().regex(/^\d+\.\d+\.\d+$/),
options: z.object({
rollback: z.boolean().default(true),
healthCheck: z.boolean().default(true),
notifySlack: z.boolean().default(false),
}).optional(),
};
// Schema con union types
const searchSchema = {
query: z.string().min(1),
scope: z.union([
z.literal('code'),
z.literal('docs'),
z.literal('issues'),
z.literal('all'),
]).default('all'),
limit: z.number().int().min(1).max(100).default(20),
};
プリミティブ間の相互作用: 完全な例
3 つの MCP プリミティブは、単独では動作しません。実際のシナリオでは、ワークフローは 3 つのプリミティブをすべて相乗的に組み合わせることができます。
- ユーザーがプロンプトを選択します: パラメータ付きの「スプリントレビュー」
sprintId: 42 - プロンプトは指示を生成します: メッセージは AI に特定のツールの使用を示唆しています
- AIがツールを呼び出す: 呼び出す
get-sprint,calculate-velocity,get-sprint-stories - アプリケーションがリソースをロードします: コンテキストとして追加
config://team-settings - AIがレポートを生成: 収集したすべてのデータを構造化レポートに結合します
この構成可能性は MCP プロトコルの強みの 1 つであり、すべてのプリミティブが貢献します。 複雑で明確なワークフローにおける特定の役割を備えています。
結論
3 つの MCP プリミティブ -- ツール, リソース e プロンプト -- プロトコルの基本的な語彙を構成します。各プリミティブには明確な役割があります。 ツールはアクションを実行し、リソースはデータを提供し、プロンプトは構造化されたタスクで AI をガイドします。
による検証 ゾッド タイプセーフティと自動ドキュメントを保証します。 MCP セッションのライフサイクルにより、クライアントとサーバー間の秩序ある予測可能な対話が保証されます。 プリミティブ間の構成可能性により、以下から始まる複雑なワークフローを構築できます。 シンプルで明確に定義された構成要素。
次の記事ではさらに詳しく掘り下げていきますモノリポジトリのアーキテクチャ そして私 プロジェクトパターン で使用される テックMCP: 31 個の MCP サーバーを単一のリポジトリに編成し、Turborepo で共有依存関係を管理する方法 および pnpm を使用して、再利用性と保守性を最大限に高めるコードを構造化します。
すべての例を含む完全なコードはリポジトリで入手できます。 GitHub 上の Tech-MCP.