# Python MCP Server Blueprint

`uv` と `ruff` を使用した、Python製 Model Context Protocol (MCP) サーバーのテンプレートプロジェクト。
フレームワークとして、Anthropic公式の直感的な高レベルAPIである **FastMCP** を採用している。

## 機能・特徴

- **FastMCP**: 最小限のコードで MCP Tool, Resource, Prompt を定義可能。
- **uv**: 高速なパッケージマネージャーによる依存関係管理と仮想環境構築。
- **ruff**: 超高速なリンター＆フォーマッターによるコード品質管理。

## 開発の準備

### 1. 依存関係のインストール

プロジェクトルートディレクトリで以下のコマンドを実行し、仮想環境の構築と依存関係の同期を行う。

```bash
uv sync
```

## コード品質の維持 (Ruff)

### コードの静的解析 (Lint)

```bash
uv run ruff check .
```

自動修正を実行する場合：

```bash
uv run ruff check --fix .
```

### コードのフォーマット

```bash
uv run ruff format .
```

## サーバーの起動

標準入出力 (stdio) モードでサーバーを起動する。

```bash
uv run python-mcp-server
```

## ビルドとクリーンアップ

### パッケージのビルド

配布用パッケージ（WheelおよびSdist）をビルドする。

```bash
uv build
```

### プロジェクトのクリーンアップ

ビルド生成物（`dist/`, `build/`）、パッケージ情報（`*.egg-info`）、キャッシュファイル（`__pycache__`, `.ruff_cache`）を削除する。

```bash
uv run clean-project
```

---

## MCP クライアントへの登録例 (Claude Desktop)

Claude Desktop でこのサーバーを動作させるには、設定ファイル（通常は `%APPDATA%\Claude\claude_desktop_config.json`）に以下のように登録する。

```json
{
  "mcpServers": {
    "python-mcp-server-blueprint": {
      "command": "uv",
      "args": [
        "--directory",
        "D:\\Sources\\python_mcp_server_blueprint",
        "run",
        "python-mcp-server"
      ]
    }
  }
}
```

> [!IMPORTANT]
> `D:\\Sources\\python_mcp_server_blueprint` の部分は、実際のプロジェクトの絶対パスに合わせて修正すること。また、Windowsのパス区切り文字は `\\` にエスケープする必要がある。

---

## Docker / nerdctl での実行

プロジェクトをコンテナイメージとしてビルドし、実行することができる。

### 1. イメージのビルド

```bash
nerdctl build -t python-mcp-server-blueprint .
```

### 2. コンテナの起動

#### 標準入出力 (stdio) モードで起動する場合
標準入出力の対話が必要なため、インタラクティブモード（`-i`）を有効にして起動する。

```bash
nerdctl run -i --rm python-mcp-server-blueprint
```

#### SSE (HTTP) モードで起動する場合
ポート `8000` をフォワードし、ホストを `0.0.0.0` に指定して起動する。

```bash
nerdctl run -d -p 8000:8000 --name mcp-server python-mcp-server-blueprint --transport sse --host 0.0.0.0
```

### 3. 開発用コンテナ（ホットリロード対応）での起動

`Dockerfile` のマルチステージビルド機能を使用すると、ホスト側のソースコードの変更が自動的にコンテナ内へ反映され、サーバープロセスが自動再起動（ホットリロード）する開発用環境を構築できる。

#### 開発用イメージのビルド

`Dockerfile` の `development` ターゲットを指定してビルドする。

```bash
nerdctl build --target development -t python-mcp-server-blueprint-dev .
```

#### ボリュームマウントによるホットリロード起動

ホストの `src` ディレクトリをコンテナ内の `/app/src` にボリュームマウントして起動する。

```bash
nerdctl run -d -p 8000:8000 --name mcp-server-dev -v D:\Sources\python_mcp_server_blueprint\src:/app/src python-mcp-server-blueprint-dev
```

起動後、ホスト側の `src/` 配下のコードを書き換えるだけで、コンテナ内のサーバーが自動で再起動して即座に変更が反映される。

---

## Docker Compose での実行

`compose.yaml` を使用することで、ホットリロード有効の開発用コンテナをより簡単に起動・停止できる。

### 開発環境の起動 (ホットリロード有効)

```bash
# 起動 (初回は自動でビルドされる)
nerdctl compose up -d

# ログの確認 (ホットリロードのログ等)
nerdctl compose logs -f

# 停止
nerdctl compose down
```

- **Swagger UI**: `http://localhost:8000/docs`