try-mcp-server
MCP(Model Context Protocol)を「作る側」と「使う側」の両方から、手を動かして理解するためのお試し用リポジトリ。
概要
- 作る: MCP サーバーを TypeScript/Node.js で自作し、伝送方式(stdio / Streamable HTTP など)・ツール・リソース・プロンプトなどを小さな実験単位で試す
- 実験は
experiments/配下に 1 実験 1 フォルダ(NN-<テーマ>/)で置き、それぞれが独立して動く - 実験の一覧は experiments/README.md を参照
- 使う: 既製の MCP サーバーを
.mcp.jsonに登録し、Claude Code と GitHub Copilot CLI の両方から同じ設定で動かす(下記「MCP クライアントから既製のサーバーを使う」) - claude.ai のコネクタやユーザー設定で既に使える MCP でも、
.mcp.jsonに載せる。確かめたいのは「リポジトリの設定だけで、どのクライアントからも再現できるか」であるため。理由の正本は docs/01-business-requirements.md
矢印は流れる向きにアニメーションする。編集の仕方は「図を作り直す」を参照。```text
.
├── CLAUDE.md / AGENTS.md AI エージェント向けの入口
├── .claude/rules/ 開発ルールの正本
├── .mcp.json MCP クライアント(Claude Code / Copilot CLI)向けのサーバー設定(Playwright / Atlassian / draw.io)
├── docs/ リポジトリ全体の仕様書(README.md が目次)
├── experiments/ MCP サーバーの実験(1 実験 1 フォルダ)
│ └── 01-echo-stdio/ 最初に作った最小構成のサーバー(stdio / echo / 固定リソース)
└── scripts/ 検査スクリプト(markdownlint / shellcheck / 秘匿ファイル検出)と図の生成スクリプト
## セットアップ
前提:
- Node.js(LTS 推奨)
- 検査スクリプトを動かす場合: `npx` が使えること、shellcheck 0.11.0 または Docker
各実験のセットアップ手順は、その実験フォルダの `README.md` に書く。
## 使い方
### 実験を動かす```bash
cd experiments/01-echo-stdio/server
npm install
npm run build
npm run client # 簡易クライアントから echo ツールと example://readme リソースを呼び出す
このとき簡易クライアントと自作サーバーの間では、次の順に JSON-RPC のメッセージが標準入出力を流れる。
新しい実験を追加する
experiments/NN-<テーマ>/を作る(連番は既存の最大値 + 1)- その中に
README.md(目的・実行手順・確認できること)とコードを置く - experiments/README.md の一覧に 1 行追加する
MCP クライアントから既製のサーバーを使う
リポジトリ直下の .mcp.json に、既製の MCP サーバーを登録している。
| 名前 | サーバー | 方式 | 認証 |
|---|---|---|---|
playwright |
Playwright MCP(@playwright/mcp、版固定) |
stdio(手元で npx が起動する) |
不要 |
atlassian |
Atlassian Rovo MCP Server(Jira / Confluence) | リモート HTTP(https://mcp.atlassian.com/v2/mcp) |
OAuth(クライアントごとにブラウザでログインする) |
drawio |
draw.io MCP(図の作成) | リモート HTTP(https://mcp.draw.io/mcp) |
不要 |
同じファイルを次の 2 つのクライアントが読む(<名前> は上の表の名前)。
| クライアント | .mcp.json の扱い |
確認コマンド | OAuth のログイン |
|---|---|---|---|
| Claude Code | project スコープ。初回は使用の承認を求められる。承認後は、同名のサーバーがユーザー設定にあってもこのリポジトリ内では .mcp.json 側が優先される(承認前はユーザー設定側が使われる) |
claude mcp get <名前>(Scope: Project config と表示される)。Claude Code 内では /mcp |
Claude Code 内で /mcp → サーバーを選んで認証 |
| GitHub Copilot CLI | Workspace 設定。初回はフォルダの信頼を求められる(信頼していないフォルダでは読み飛ばされる) | copilot mcp get <名前>(Source: Workspace と表示される) |
初回の利用時に案内が出る。やり直しは Copilot CLI 内で /mcp auth <名前> |
- リポジトリに認証情報を書かない。 リモートのサーバーは OAuth でログインし、トークンは各クライアントが利用者ごとに保持する。
.mcp.jsonには URL だけを書く。ログインは Claude Code と Copilot CLI で共有されないため、それぞれで行う。 - Playwright MCP の版を上げるときは
.mcp.jsonの@playwright/mcp@<版>を書き換える。@latestにすると起動のたびに版が変わり、挙動が再現しなくなるため使わない。 - Playwright MCP のスナップショットやスクリーンショットは
.playwright-mcp/に出力される(.gitignore済み)。 - draw.io MCP の
create_diagramは、図をその場に表示できるクライアント向けのツールである。CLI では図は表示されず、draw.io エディタで開くリンク(https://app.diagrams.net/?...#create=...)が返る。図の中身はリンクの#以降に圧縮して埋め込まれており、ブラウザで開くとエディタに図が読み込まれる(保存するまでファイルにはならない)。 - Claude Code で claude.ai の Atlassian コネクタも有効にしている場合、Claude Code はコネクタと
.mcp.jsonのサーバーを URL で同一か判定する。コネクタが廃止予定の V1(/v1/mcp)のままだと別のサーバーとして両方が起動し、同じツールが 2 組並ぶ。コネクタを V2 で接続し直すと、このリポジトリでは.mcp.json側だけが使われる。 - Copilot CLI で実行するには、GitHub の Copilot 設定()で MCP サーバーの利用が許可されている必要がある。許可されていないと、設定は読まれても
Third-party MCP servers are disabled by your organization's Copilot policyで実行が拒否される。 - Codex は
.mcp.jsonを読まない(設定の形式が別)。
OAuth が必要なリモートのサーバー(atlassian)には、次の流れで接続する。
検査```bash
./scripts/lint-docs.sh # Markdown の検査(--fix で自動修正)
./scripts/lint-shell.sh # シェルスクリプトの検査
./scripts/check-secret-files.sh # 鍵・.env などの混入検出
```
図を作り直す
docs/images/ の図は、種類によって作り直し方が違う。どれも PNG などの書き出しを別に置かない(表示用と編集用がずれるため)。
| 図 | 正本 | 作り直し方 |
|---|---|---|
mcp-overview.drawio.svg(全体図) |
SVG 自身(draw.io の図データを埋め込んでいる) | draw.io(デスクトップ版・Web 版)で直接開いて編集し、同じファイルに保存し直す。矢印の動きは線のスタイルの flowAnimation=1 |
mcp-jsonrpc-stdio.svg / mcp-oauth-atlassian.svg(通信の流れ) |
scripts/gen-sequence-svgs.py |
スクリプトの SEQUENCES を直して python3 scripts/gen-sequence-svgs.py で再生成する。SVG を直接編集しない。--check を付けると、コミット済みの SVG が生成結果と一致するかを確かめる |
- アニメーションは CSS だけで動く(`` を使わない)ため、GitHub の README の画像としてもそのまま動く。
- 通信の流れの 2 枚は、OS の「視差効果を減らす」設定(
prefers-reduced-motion)で静止画になる。全体図は draw.io の書き出しがこの設定に対応していないため、設定にかかわらず動く。
AI エージェント向けルール
開発ルールの正本は .claude/rules/ です。Claude Code は CLAUDE.md、Codex は AGENTS.md からこのルールを参照します。ルール本文は各入口へ複製しません。