From a22af8dd30726a1a10e778934c74f9a8cbde3e02 Mon Sep 17 00:00:00 2001 From: hideyukiMORI Date: Tue, 19 May 2026 22:58:21 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20Field=20Trial=203=20=E3=83=AC=E3=83=9D?= =?UTF-8?q?=E3=83=BC=E3=83=88=E3=82=92=E8=BF=BD=E5=8A=A0=EF=BC=88Bearer=20?= =?UTF-8?q?Token=E8=AA=8D=E8=A8=BC=20+=20MCP=20DX=E6=A4=9C=E8=A8=BC?= =?UTF-8?q?=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Closes #80 Co-Authored-By: Claude Sonnet 4.6 --- docs/field-trials/2026-05-field-trial-3.md | 127 +++++++++++++++++++++ 1 file changed, 127 insertions(+) create mode 100644 docs/field-trials/2026-05-field-trial-3.md diff --git a/docs/field-trials/2026-05-field-trial-3.md b/docs/field-trials/2026-05-field-trial-3.md new file mode 100644 index 0000000..1d89c75 --- /dev/null +++ b/docs/field-trials/2026-05-field-trial-3.md @@ -0,0 +1,127 @@ +# Field Trial 3 — tasklist: Bearer Token認証 + MCP サーバーの DX 検証 + +## Date + +2026-05-19 + +## Baseline + +- nene2-python v0.1.0 (`uv add git+https://github.com/hideyukiMORI/nene2-python.git`) +- Python 3.14.5（uv managed） +- プロジェクト: **tasklist** — タスク管理 JSON API +- エンティティ: `Task`（title, status, priority）— 5 エンドポイント（CRUD） +- **`BearerTokenMiddleware`** ← FT1/FT2 との差分① +- **`LocalMcpServer`（stdio）** ← FT1/FT2 との差分② + +## Goal + +1. `BearerTokenMiddleware` の設定・動作確認 +2. `LocalMcpServer` を外部プロジェクトから設定し stdio 経由で動作確認 +3. 両者の DX 摩擦を洗い出す + +--- + +## Steps Taken + +### 1. プロジェクト初期化・インストール + +FT1/FT2 と同様、問題なし。 + +### 2. ドメイン層・HTTP ハンドラ実装 + +FT1〜FT2 で修正されたドキュメントを参照。ミドルウェアスタックは一発で正しく組めた。 + +### 3. Bearer Token 認証の設定 + +`.env` に `BEARER_TOKENS=dev-secret-token-1` と記述して起動 → **起動失敗**（F-1）。 + +JSON 形式 `BEARER_TOKENS=["dev-secret-token-1"]` に修正して解決。 + +動作確認： +- 認証なし → 401（`unauthorized` Problem Details）✓ +- 間違ったトークン → 401（`The provided token is invalid or expired.`）✓ +- 正しいトークン → 200 ✓ + +### 4. MCP サーバー実装 + +`LocalMcpServer` を使い `mcp_server.py` を実装。ツール登録はデコレータで直感的に書けた。 + +MCP プロトコルハンドシェイク（initialize → initialized → tools/list / tools/call）を +Python スクリプトで確認： + +- `tools/list` → 5 ツール（list/get/create/update/delete）が正常に返る ✓ +- `create_task` → `{"id":1,"title":"FT3 MCPテスト","status":"open","priority":"high"}` ✓ +- `list_tasks` → 作成したタスクが返る ✓ + +### 5. Claude Desktop 接続 + +WSL2 環境で Claude Desktop が未インストールのため実機確認不可。 +設定ファイルのサンプルをドキュメントに記載する形で代替。 + +--- + +## Friction Points + +### F-1 `.env` で `list[str]` フィールドに JSON 形式が必要なのに記載なし + +**severity**: 高 +**type**: ドキュメント不足 + +`BEARER_TOKENS` / `API_KEYS` / `CORS_ORIGINS` など `list[str]` 型のフィールドは、 +`.env` に plain text で書くと `JSONDecodeError` で起動失敗する。 +JSON 形式（`["value1","value2"]`）が正解だが、`.env.example` やドキュメントに記載がない。 + +```dotenv +# NG — JSONDecodeError で起動失敗 +BEARER_TOKENS=token-1,token-2 + +# OK +BEARER_TOKENS=["token-1","token-2"] +``` + +**Follow-up**: `docs/reference/configuration.md` と `.env.example` に list 型フィールドの +正しい書き方を明記する。 + +--- + +### F-2 MCP サーバーと HTTP API がメモリを共有しないことが不明確 + +**severity**: 中 +**type**: ドキュメント / 設計説明不足 + +`mcp_server.py` が別プロセスとして動くため、HTTP API の `InMemoryTaskRepository` と +MCP サーバーの `InMemoryTaskRepository` は別インスタンスになる。 +「MCP で作ったタスクが HTTP API から見えない」という混乱が起きやすい。 + +解決策は SQLite 等の永続化リポジトリを使うことだが、その指針がドキュメントにない。 + +**Follow-up**: MCP ハウツーに「InMemory は開発専用。MCP と HTTP で状態を共有するには +SQLite 等の永続化リポジトリを使う」旨を追記する。 + +--- + +### F-3 Claude Desktop の MCP 設定例（WSL2 パス）がない + +**severity**: 中 +**type**: ドキュメント不足 + +既存の `docs/howto/mcp-setup.md` に MCP 設定例はあるが、WSL2 からの uv コマンド呼び出し +パターン（`"command": "wsl"`, `"args": ["-e", "uv", ...]`）の記載がない。 + +Windows 上の Claude Desktop から WSL2 の uv プロジェクトを呼ぶには特殊なパス指定が必要。 + +**Follow-up**: `docs/howto/mcp-setup.md` に WSL2 向け設定例を追加する。 + +--- + +## Summary + +| ID | 摩擦 | 深刻度 | 種別 | Follow-up Issue | +|-----|-----------------------------------------------|--------|------------------|-----------------| +| F-1 | `list[str]` の `.env` 書き方が JSON 形式と知らない | 高 | ドキュメント不足 | TBD | +| F-2 | MCP と HTTP API がメモリ共有しないことが不明確 | 中 | 設計説明不足 | TBD | +| F-3 | Claude Desktop WSL2 設定例がない | 中 | ドキュメント不足 | TBD | + +FT2 で修正した SQLite 関連ドキュメント（#73〜#75）の効果は確認できた。 + +次回 FT4 は SQLite 永続化 + MCP 統合（MCP と HTTP で DB 共有）を推奨。