# MCP Template

[![MCP](https://img.shields.io/badge/MCP-Server-blue)](https://modelcontextprotocol.io/)
[![Cloudflare Workers](https://img.shields.io/badge/Cloudflare_Workers-Wrangler_4.126.0-orange?logo=cloudflareworkers&logoColor=white)](https://workers.cloudflare.com/)
[![Hono](https://img.shields.io/badge/Hono-4.13.5-E36002?logo=hono&logoColor=white)](https://hono.dev/)
[![TypeScript](https://img.shields.io/badge/TypeScript-7.0.2-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
[![pnpm](https://img.shields.io/badge/pnpm-11.24.0-F69220?logo=pnpm&logoColor=white)](https://pnpm.io/)

Better Authのパスキー認証と、認証済み接続を確認するMCP Toolを備えたCloudflare Workers用テンプレートです。公開サインアップは行わず、手動登録したUserだけが利用できます。

## 含まれるもの

- Cloudflare Workers、Hono、TypeScript strict
- Better Auth、Passkey、OAuth、CIMD
- Cloudflare D1のBetter Auth用Migration
- 認証済みUserだけが実行できる`get_server_status`
- 初回パスキー登録用の24時間・一度限りURL

## 事前準備

- Node.js 24以上とpnpm 11
- CloudflareアカウントとWranglerのログイン
- Passkeyで使うHTTPS公開URL

## セットアップ

### 1. サービス名と公開URLを決める

以下を実際のサービスに合わせて変更します。

| ファイル | 変更内容 |
| --- | --- |
| `package.json` | パッケージ名 |
| `wrangler.jsonc` | Worker名、`PUBLIC_ORIGIN`、D1の名前とID |
| `src/auth.ts` | Passkey表示名とCookie prefix |

`PUBLIC_ORIGIN`にはHTTPSの公開URLを設定します。Passkeyを使う際は、設定値と実際にアクセスするURLを一致させてください。

### 2. 依存関係とD1を準備する

```powershell
pnpm install
pnpm wrangler d1 create mcp-template-db
```

作成結果の`database_id`を`wrangler.jsonc`へ設定します。D1名を変更した場合は、以降のコマンドにも同じ名前を使います。

### 3. SecretとMigrationを設定する

ローカル開発用に`.dev.vars.example`を`.dev.vars`へ複製し、十分にランダムな`BETTER_AUTH_SECRET`を設定します。

```powershell
Copy-Item .dev.vars.example .dev.vars
pnpm wrangler d1 migrations apply mcp-template-db --remote
pnpm wrangler secret put BETTER_AUTH_SECRET
```

リモートの`BETTER_AUTH_SECRET`には、ローカルと同じ値を設定します。

### 4. デプロイする

```powershell
pnpm deploy
```

デプロイ後の主なエンドポイントです。

- MCP: `https://mcp.example.com/mcp`
- ヘルスチェック: `https://mcp.example.com/health`
- 認証: `https://mcp.example.com/auth/*`
- パスキー登録: `https://mcp.example.com/passkey/register?token=...`

## 初回Userとパスキー登録

公開サインアップはありません。D1へUserを手動登録してから、登録URLを発行します。User作成は要件ごとに安全な運用手順を決めるため、テンプレには自動作成スクリプトを含めていません。

```powershell
pnpm user:issue-passkey-url user@example.com mcp-template-db https://mcp.example.com
```

URLは1回だけ使用でき、24時間で失効します。

## ローカル開発

```powershell
pnpm dev
```

`/health`でWorkerの起動を確認できます。Passkeyを使うローカル検証では、`PUBLIC_ORIGIN`とアクセスURLを一致させてください。

## 開発時の確認

```powershell
pnpm format
pnpm format:check
pnpm lint
pnpm lines:check
pnpm typecheck
```

- `pnpm format` は対象ファイルを整形します。
- `pnpm format:check` はフォーマット済みか確認します。
- `pnpm lint` はlintとimport整理を確認します。
- `pnpm lines:check` は`src/`・`scripts/`の500行上限を検証します。
- GitHub ActionsはpushとPull Requestでフォーマット、lint、行数、型を確認します。

## ドキュメント

- [アーキテクチャ](./docs/architecture.md)
- [認証](./docs/authentication.md)
- [MCP Tool](./docs/tools.md)
- [セキュリティ](./docs/security.md)
- [作業ルール](./AGENTS.md)

実装・ドキュメント更新時のルールは [AGENTS.md](./AGENTS.md) を参照してください。