A Template MCP Server

MCP サーバーのテンプレート

このリポジトリは、MCP（Model Context Protocol）サーバーの実装方法を示すテンプレートです。MCP は、AI エージェントや Claude などのサービスをツールやデータソースに接続するために設計されたオープン標準です。このリポジトリの主な目的は、基本的な MCP サーバーの構築、設定、実行方法を説明することです。 ツールは簡略化されたサンプルであり、本番環境での使用を目的としていません。

このサンプルサーバーは、ユーザーデータを管理するためにシンプルな PostgreSQL データベースをバックエンドとして使用し、MCP が AI エージェントと外部リソースの橋渡しをする方法を示しています。

概要

このサーバーは、MCP クライアント（例：AI エージェント）と外部データソース（この場合は users テーブルを含むサンプル PostgreSQL データベース）をつなぐ安全なゲートウェイとして機能します。次の方法を示します。

• MCP 標準を通じてカスタムツールを定義し、公開する。
• MCP クライアントからのリクエストを処理する。
• それらのリクエストをバックエンドリソースに対する操作（例：データベースクエリ）に変換する。
• 構造化された結果やエラーをクライアントに返す。

この例で使用するデモ用の users テーブルは、次の構造です。

• id（整数、主キー）
• name（テキスト）
• email（テキスト、一意）

サーバーが公開するツールの例

ツールの定義と公開方法を示すため、このサーバーではユーザーデータベースを操作する次のサンプル関数を実装しています。

• add_user：データベースに新しいユーザーを追加します。
  • パラメーター：name（文字列）、email（文字列）
  • 戻り値：確認メッセージ（文字列）またはエラー。
• get_all_users：データベースからすべてのユーザーのリストを取得します。
  • パラメーター：なし
  • 戻り値：ユーザーオブジェクトのリスト（各オブジェクトは id、name、email を持つ辞書）またはエラー。
• find_user_by_email：メールアドレスで特定のユーザーを検索します。
  • パラメーター：email（文字列）
  • 戻り値：単一のユーザーオブジェクト（辞書）または、見つからない場合はエラー。
• delete_user_by_email：メールアドレスを指定して、データベースからユーザーを削除します。
  • パラメーター：email（文字列）
  • 戻り値：確認メッセージ（文字列）またはエラー。

これらのツールは、MCP サーバーが利用可能にする操作の具体例です。

前提条件

• Python 3.10+
• PostgreSQL データベースへのアクセス。サーバーには接続情報が必要です。
• Docker（サーバーを手軽に実行するため推奨）。
• uv（ローカル開発での依存関係管理用）。

設定

データベース接続とサーバー設定には環境変数を使用します。.env.example ファイルを .env にコピーし、値を更新してください。

cp .env.example .env
# Edit .env with your database details and desired server settings

主な変数：

変数	説明	例	必須	デフォルト
DB_URL	PostgreSQL の完全な接続 URL。	postgresql+asyncpg://user:pass@host:5432/dbname	はい
DB_HOST	MCP サーバーがリッスンするホストアドレス。	0.0.0.0	いいえ	0.0.0.0
DB_PORT	MCP サーバーがリッスンするポート。	8051	いいえ	8051
MCP_SIGNING_KEY	クライアントとサーバー間のリクエスト署名に使用する任意のシークレットキー。	your_very_secret_key	いいえ

注： DB_URL には、postgresql+asyncpg:// のような asyncpg 対応のドライバープレフィックスを指定してください。

使用方法

Docker の使用（推奨）

1. イメージをビルドする： （Docker がインストールされ、実行中であることを確認してください）

   # プロジェクトのルートディレクトリ（agents-mcp-demo）に移動します
   docker build -t sql-mcp-demo-server --build-arg PORT=${DB_PORT:-8051} .
   

2. コンテナーを実行する：

   docker run --rm -d --env-file .env -p ${DB_PORT:-8051}:${DB_PORT:-8051} --name sql-mcp-server sql-mcp-demo-server
   

ローカル開発

1. 依存関係をインストールする：uv が必要です。プロジェクトのルートディレクトリに移動してください。

   # 仮想環境を作成します（推奨）
   python -m venv .venv
   source .venv/bin/activate # または Windows では .\.venv\Scripts\activate
   # uv を使用してインストールします
   uv pip install -e .[dev]
   

2. 環境変数を設定する：必要な DB_URL がシェル環境に設定されているか、ルートディレクトリの .env ファイルに記載されていることを確認してください（dotenv を使用します）。
3. サーバーを起動する：

   uv run python sqlmcp/server.py
   

   （サーバーは環境変数のホスト／ポート、またはデフォルト値を使用します）

MCP クライアントとの接続

実行中のサーバーに接続するよう、MCP クライアントを設定してください。接続の詳細は、サーバーの実行方法によって異なります。

SSE 設定例（Docker／Compose で実行する場合）：

{
  "mcpServers": {
    "sqlDemoServer": { // Choose a name for this server connection
      "transport": "sse",
      "url": "http://localhost:8051/sse", // Adjust port if changed from default
    }
  }
}

Stdio 設定例（ローカル開発の場合）：

これにより、クライアントがサーバープロセスを直接管理できます。

{
  "mcpServers": {
    "sqlDemoServerLocal": { // Choose a name
      "command": "python", // Or path to python in your venv e.g., ".venv/bin/python"
      "args": ["sqlmcp/server.py"], // Path relative to workspace root
      "env": {
        "TRANSPORT": "stdio", // Crucial: Tells server to use stdio
        "DB_URL": "postgresql+asyncpg://user:pass@host:5432/dbname", // MUST provide DB URL
      },
      "workingDirectory": "." // Ensure paths are resolved correctly
    }
  }
}

（ご利用の環境に合わせて、パス、URL、ポート、接続の詳細を調整してください）

開発プラクティス

• リンティング／フォーマット：Ruff を使用します（pyproject.toml で設定済み）。

  uv run ruff check .
  uv run ruff format .
  

• テスト：Pytest を使用します。（テストはまだ実装されていません）

  # プレースホルダーコマンドです。tests/ ディレクトリにテストを追加してください
  # uv run pytest
  

  • テストは sqlmcp の構造に合わせて、tests/ ディレクトリの下に追加してください。標準的な Pytest の規約に従ってください。

コントリビューション

これは主にサンプルリポジトリです。MCP サーバー開発の明確さや正確性を高めるもの、またはベストプラクティスを示すものは、プルリクエストで歓迎します。提出前に、コードがフォーマットされ、リンティングされていることを確認してください。

ライセンス

このプロジェクトは MIT License の下でライセンスされています。詳細については LICENSE ファイルを参照するか、https://opensource.org/licenses/MIT をご覧ください。