mcp

MCP：プロトコルサーバーの構築と管理

API と連携する MCP サーバーを構築し、設定済みのサーバーからツールを実行します。

使用する場面

構築：MCP サーバー（Python/TypeScript）の作成、API との連携、エージェント中心のツール設計、検証／エラー処理の実装、評価の作成

管理：Gemini CLI によるツールの検出／実行、タスクに応じたツールの絞り込み、複数サーバーの設定管理

基本概念

MCP は、AI エージェントが外部のツール／データにアクセスするための標準化されたプロトコルです。

コンポーネント：ツール（実行可能な関数）、リソース（読み取り専用データ）、プロンプト（テンプレート） トランスポート：Stdio（ローカル）、HTTP（リモート）、SSE（リアルタイム）

読み込み：プロトコルの詳細については references/protocol-basics.md を読み込みます

---

パート 1：MCP サーバーの構築

LLM が現実世界のタスクを達成できる、高品質な MCP サーバーを構築します。

開発ワークフロー

フェーズ 1：調査と計画

1. エージェント中心の設計原則を学びます（エンドポイントよりもワークフローを重視）
2. 対象 API のドキュメントを徹底的に調査します
3. フレームワークのドキュメント（Python SDK または TypeScript SDK）を読み込みます
4. ツールの選定、共有ユーティリティ、入出力の設計、エラー処理を計画します

フェーズ 2：実装

1. プロジェクト構成を設定します（Python は単一ファイル、TypeScript は完全な構成）
2. コアとなるインフラストラクチャを実装します（API クライアント、エラーハンドラー、フォーマッター）
3. 適切なスキーマとアノテーションを指定してツールを登録します
4. 各言語固有のベストプラクティスに従います

フェーズ 3：テストと品質

1. コード品質をレビューします（DRY、合成可能性、一貫性）
2. ビルドと構文チェックを実行します
3. 品質チェックリストを使用します

フェーズ 4：評価

1. 複雑で現実的な評価用の質問を 10 個作成します
2. 質問は読み取り専用で、互いに独立しており、検証可能である必要があります
3. LLM がサーバーを効果的に使用できるかテストします

リファレンス：references/building-servers.md — 次の内容を含む開発ガイド全体を読み込みます。

• エージェント中心の設計原則
• Pydantic モデルを使用した Python（FastMCP）の実装ガイド
• Zod スキーマを使用した TypeScript（MCP SDK）の実装ガイド
• ツールの命名規則、応答形式、ページネーションのパターン
• 文字数制限、エラー処理、セキュリティのベストプラクティス
• 実用的な完全版サンプルと品質チェックリスト
• 評価の作成とテストの方法

主なベストプラクティス

ツール設計：

• サービス名を接頭辞にした名前を使用します（send_message ではなく slack_send_message）
• JSON と Markdown の両方の応答形式をサポートします
• limit、offset、has_more を使ってページネーションを実装します
• CHARACTER_LIMIT 定数を設定します（通常は 25,000）
• エージェントの対応を導く、実行可能なエラーメッセージを提示します

コード品質：

• 共通機能を再利用可能な関数に切り出します
• すべての I/O 操作で async/await を使用します
• Python では型ヒントを、TypeScript では全体を通じて厳格な型付けを使用します
• スキーマを明示した包括的な docstring を記述します

リファレンス：包括的なガイドラインについては references/best-practices.md を読み込みます

---

パート 2：MCP ツールの使用

設定済みの MCP サーバーからツールを効率的に実行、管理します。

設定

MCP サーバーは .claude/.mcp.json で設定されています。

{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "package-name"],
      "env": {"API_KEY": "${ENV_VAR}"}
    }
  }
}

Gemini CLI との連携：設定を共有するためのシンボリックリンクを作成します。

mkdir -p .gemini && ln -sf .claude/.mcp.json .gemini/settings.json

リファレンス：設定と使用方法のガイド全体については references/using-tools.md を読み込みます

実行方法（優先順位順）

1. Gemini CLI（主要な方法）

自然言語を使用して、ツールの自動検出と実行を行います。

# CRITICAL: Use stdin piping, NOT -p flag (deprecated, skips MCP init)
echo "Take a screenshot of https://example.com" | gemini -y -m gemini-2.5-flash

メリット：

• ツールの自動検出と選択
• 構造化された JSON レスポンス（GEMINI.md が設定されている場合）
• 最速の実行
• ツールを手動で指定する必要がありません

GEMINI.md のレスポンス形式：JSON のみのレスポンスを強制するには、プロジェクトのルートに配置します。

# Gemini CLI Instructions
Always respond in this exact JSON format:
{"server":"name","tool":"name","success":true,"result":<data>,"error":null}
Maximum 500 characters. No markdown, no explanations.

2. 直接 CLI スクリプト（副次的な方法）

必要なサーバーやツールが正確にわかっている場合に、ツールを手動で指定します。

npx tsx scripts/cli.ts call-tool memory create_entities '{"entities":[...]}'

3. mcp-manager サブエージェント（フォールバック）

Gemini を利用できない場合や、複雑な複数ツールのワークフローでは、サブエージェントに委任します。

参照：references/using-tools.md を読み込むと、以下を確認できます。

• 例を含む Gemini CLI の完全ガイド
• 直接スクリプトを使用する方法とオプション
• サブエージェントへの委任パターン
• ツールの検出とフィルタリングの方法
• 複数サーバーのオーケストレーション
• トラブルシューティングとデバッグ

ツールの検出

利用可能なツールを一覧表示して、機能を確認します。

# Saves to assets/tools.json for offline reference
npx tsx scripts/cli.ts list-tools

# List prompts and resources
npx tsx scripts/cli.ts list-prompts
npx tsx scripts/cli.ts list-resources

インテリジェントな選択：LLM は assets/tools.json を直接読み取り、コンテキストに応じてツールをフィルタリングします（キーワードマッチングより優れています）。

---

クイックスタートの例

サーバーの構築

Python：

from mcp.server.fastmcp import FastMCP
from pydantic import BaseModel, Field

mcp = FastMCP("github_mcp")

class SearchInput(BaseModel):
    query: str = Field(..., min_length=2, max_length=200)
    limit: int = Field(default=20, ge=1, le=100)

@mcp.tool(name="github_search_repos", annotations={"readOnlyHint": True})
async def search_repos(params: SearchInput) -> str:
    # Implementation
    pass

if __name__ == "__main__":
    mcp.run()

TypeScript：

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

const server = new McpServer({name: "github-mcp-server", version: "1.0.0"});

const SearchSchema = z.object({
  query: z.string().min(2).max(200),
  limit: z.number().int().min(1).max(100).default(20)
}).strict();

server.registerTool("github_search_repos", {
  description: "Search GitHub repositories",
  inputSchema: SearchSchema,
  annotations: {readOnlyHint: true}
}, async (params) => {
  // Implementation
});

完全な実装ガイドについては、references/building-servers.md を読み込みます。

ツールの使用

Gemini CLI：

# IMPORTANT: Use stdin piping, NOT -p flag
echo "Search GitHub for MCP servers and summarize top 3" | gemini -y -m gemini-2.5-flash

直接スクリプト：

npx tsx scripts/cli.ts call-tool github search_repos '{"query":"mcp","limit":3}'

使用パターンの全容については、references/using-tools.md を読み込みます。

---

リファレンスファイル

作業中、必要に応じて以下を読み込みます。

コアリファレンス

• references/building-servers.md - MCP サーバー開発の完全ガイド

  • エージェント中心の設計原則
  • Python（FastMCP）と TypeScript（MCP SDK）の実装
  • ツールのパターン、レスポンス形式、ページネーション、エラー処理
  • 完全な例と品質チェックリスト
  • 評価の作成方法

• references/using-tools.md - MCP ツール実行の完全ガイド

  • Gemini CLI の統合と設定
  • 直接スクリプトを実行するパターン
  • サブエージェントへの委任戦略
  • ツールの検出とフィルタリング
  • 複数サーバーのオーケストレーション

• references/best-practices.md - MCP の汎用ガイドライン

  • サーバーとツールの命名規則
  • レスポンス形式の標準（JSON と Markdown）
  • ページネーション、文字数制限、切り詰め
  • セキュリティとプライバシーに関する考慮事項
  • テストとコンプライアンスの要件

補足リファレンス

• references/protocol-basics.md - JSON-RPC プロトコルの詳細
• references/python-guide.md - Python／FastMCP の詳細（Pydantic モデル、非同期処理のパターン）
• references/typescript-guide.md - TypeScript／Zod の詳細（厳密な型、プロジェクト構成）
• references/evaluation-guide.md - 効果的な MCP サーバー評価の作成

---

段階的な情報開示

この SKILL.md では概要を説明しています。以下の場合にリファレンスファイルを読み込みます。

サーバーの構築：

• 実装を開始する → references/building-servers.md を読み込む
• 言語固有の詳細が必要 → references/python-guide.md または references/typescript-guide.md を読み込む
• 評価を作成する → references/evaluation-guide.md を読み込む

ツールの使用：

• Gemini CLI を設定する → references/using-tools.md を読み込む
• ツールの実行をデバッグする → references/using-tools.md を読み込む
• 複数サーバーを設定する → references/using-tools.md を読み込む

ベストプラクティス：

• 標準を確認する → references/best-practices.md を読み込む
• セキュリティ上の考慮事項を確認する → references/best-practices.md を読み込む

---

統合パターン

構築＋使用：MCP サーバーを作成し、Gemini CLI でテストします
複数サーバー：複数のサーバーを設定し、Gemini CLI を介してオーケストレーションします
評価主導：サーバーを構築し、評価を作成して、LLM のフィードバックに基づいて反復します

---

境界

対応すること：

• Python または TypeScript での MCP サーバー開発を案内します
• Gemini CLI またはスクリプトを使ったツール実行戦略を提供します
• エージェント中心の設計に関するベストプラクティスを確保します
• 効果的な評価の作成を支援します
• 複数サーバーのセットアップを構成します

対応しないこと：

• メインスレッドで長時間実行されるサーバープロセスを実行しません（tmux または評価ハーネスを使用してください）
• 入力検証やエラー処理を省略しません
• 包括的なドキュメントなしでツールを作成しません
• エージェントのコンテキスト制限を考慮せずにサーバーを構築しません