---
name: feedback-mcp-server-verify-3layer-diagnosis-2026-08-13
description: Claude Desktop 経由の MCP server verify で 「使える tool を全部挙げて」 が期待通りにならなかったときの 3 層診断 template。 藤本さん 2026-08-13 benchtop-mcp v0.2.3 review 締めで 指摘された 3 分離 (server 起動 / tool 登録 / Claude 拾い) を 汎用診断 flow として 保存。 benchtop-mcp を 起点に、 将来の Rei stack MCP server 全般 (rei-solver-mcp / research-radar-mcp / etc.) にも適用可能。 v0.2.4 予告でも 実装計画でもなく、 verify 結果到達時に すぐ引くための事前準備 template。
metadata: 
  node_type: memory
  type: feedback
  originSessionId: 76881bd4-5f34-41f3-bdf8-75d61ecec2b8
  modified: 2026-08-12T23:26:06.624Z
---

# MCP server verify 失敗時の 3 層診断 template

## Why (この template の由来)

藤本さん 2026-08-13 benchtop-mcp v0.2.3 review 締めで 指摘: 「§3.5-a で 9 tool が挙がらなかった場合、 原因は 3 層に分かれる。 どれかで 打ち手が全く違うので、 失敗報告が来たら中身を切り分けてから修正に入ってください」。 verify 結果が届いた瞬間に 「原因層はどれか」 を 藤本さんに聞くべきか、 私 (Claude Code) が 独自に 診断するか、 各層で どの情報を欲しがるべきか、 の 事前 template。

## How to apply

verify 結果が Claude Desktop 側から 返ってきたとき、 まず以下の 3 層に分類してから 打ち手を選ぶ。 打ち手が層ごとに 全く違うので、 症状だけ聞いて 修正提案を 走らせない。

### 層 1: MCP server が起動していない (or 起動未試行)

**症状**:
- 「使える tool を全部挙げて」 で benchtop 系の tool が 1 個も現れない
- Claude Desktop の 設定 UI (Settings → Developer → MCP servers) で benchtop が listed されていない or red/error indicator
- server 追加直後の 再起動が 未実施

**層 1 の sub-cause 3 種** (2026-08-13 経験 per):
- **1a: 起動 spawn 失敗** — command / path / Python interpreter / dependency 側 (下記 「典型原因」 参照)
- **1b: 起動未試行** — config file が Claude Desktop から 読まれていない、 そもそも 起動 attempt すら されない (Store 版 sandbox 分岐、 typo、 syntax error 等)
- **1c: server 名重複 or key 誤配置** — mcpServers 直下ではなく nested key に 書かれている等 (JSON structure 誤)

**判別**: **既存 server の 一部が listed されているか** で 1a vs 1b を 切り分け。 「一部 listed だが 新規追加のみ 反映されない」 = 1b (config は 読まれているが 新編集が 別 file、 or 部分 syntax error で 該当 entry のみ skip)。 「1 個も listed されない」 = 1c or config file 自体が 存在しない。 log に spawn 記録あれば 1a 確定。

**切り分け質問** (藤本さんに 聞くべきこと):
1. Claude Desktop を 完全 quit → 再起動 したか (task tray から exit、 単なる window close ではない)
2. `%APPDATA%\Claude\claude_desktop_config.json` に benchtop entry が 実存しているか (backup-20260812-102358 と一緒に 3 mcpServers あるはず)
3. Claude Desktop の Settings UI で benchtop が listed されているか、 色は何か
4. `%APPDATA%\Claude\logs\` (or macOS では `~/Library/Logs/Claude/`) 系に MCP server 起動 log があるか、 error message は何か

**典型原因** & **打ち手**:
- config の path が 誤 → 藤本さん実行環境の `C:\Users\user\benchtop-mcp\benchtop_mcp.py` の 絶対 path が 正しいか確認、 スペース含む path は quote
- `python` が PATH にない → 絶対 path 指定 (`C:\Python311\python.exe` or 藤本さん環境の python.exe path) or `python3` 明示
- `mcp>=2.0.0` の pip install 忘れ → `pip install "mcp>=2.0.0" pyserial` 実行
- Python version mismatch (3.10 未満だと `dict[str, Any]` 等の PEP 604 syntax で 落ちる) → 3.10+ 要求

### 層 2: 起動したが tool 登録で落ちた

**症状**:
- Claude Desktop 設定 UI で benchtop が listed + green だが、 実 prompt で tool 一覧に 一部 tool しか現れない (例: 6 個だけ、 9 個ではない)
- 或いは server は起動しているが tool listing が 空
- MCP server log に import error / decorator error / signature error が 記録

**切り分け質問**:
1. `python C:\Users\user\benchtop-mcp\benchtop_mcp.py --selftest` を 藤本さん環境で 実行、 14 phase all green か (=我々の環境と 差異ないか)
2. server 起動 log に `@server.tool()` 系の 例外あるか
3. `mcp` package version 確認 (`pip show mcp` の Version)、 2.0.0 以上か
4. 手動で stdio JSON-RPC を叩く: `echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | python benchtop_mcp.py` (面倒だが 決定的)

**典型原因** & **打ち手**:
- `mcp` package version が 我々の想定 (`mcp>=2.0.0`) と異なる → `from mcp.server import MCPServer` API が動かない可能性、 藤本さん環境の version を先に確認
- 特定 tool の signature で 落ちる (例: `str | None` type hint が 古い Python で 落ちる) → 該当 tool の signature を `Optional[str]` に書き換え or Python 3.10+ 要求明示
- import error (`pyserial` は optional のはずだが try/except が抜けている場所ある) → import 系の 起動時 error 確認

### 層 3: 登録されたが Claude 側が拾っていない

**症状**:
- 設定 UI + tool 一覧に 9 tool 全 listed される
- 実 prompt (§3.5-c 相当) で Claude が 「そんな tool ありません」 or 存在する tool を 呼ばずに 自分で応答して 終わる
- 或いは 期待と 違う tool を呼ぶ (`measure` を呼ばずに 自前で fabricated data を返す等)

**切り分け質問**:
1. 会話 log で Claude が tool_use ブロックを 実際に生成しているか (or 素の テキスト応答だけか)
2. tool の docstring が 藤本さんの 日本語 prompt から 「これを使うべき」 と 認識される 表現か
3. server-level `instructions` に 藤本さんの 想定 use case が 明示されているか

**典型原因** & **打ち手**:
- docstring の 「これは何をする tool か」 冒頭 1 行が 曖昧 → 「装置操作」 「計測」 「セッション記録」 等の keyword を 冒頭に置く
- server `instructions` の 「典型的な流れ」 記述が 具体性不足 → 実 use case を 1-2 例 追加
- Claude が 「MCP tool を優先的に使う」 mode に 入っていない → prompt 側で 明示的に 「benchtop の tool を 使って」 と 指示 (この場合 tool 側の問題ではなく prompt engineering 側の問題)

## 診断順序

**★★ 大原則: path を推測せず 「設定を編集」 ボタンから開く (2026-08-13 藤本さん Store 版 config incident 教訓)**

Claude Desktop の 開発者画面 (Settings → Developer → ローカル MCP サーバー) の **「設定を編集」 ボタン**が、 **アプリが実際に読んでいる config file を 直接開く**。 Store 版 (MSIX) か installer 版 かに関わらず 正しい file に届くので、 config path を 推測せずに ここから開くのが 最速で確実。

**path を 推測して失敗する pattern の 実例 (2026-08-13、 benchtop v0.2.3 verify)**:
- Windows Store 版 Claude Desktop は **ファイルシステム仮想化** で `%APPDATA%\Claude\` への書き込みを sandbox の `%LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\` に 振り替える
- 外部エディタで 標準 `%APPDATA%\Claude\claude_desktop_config.json` を 直接編集しても Store 版 Claude Desktop からは 見えない (別 file を 読む)
- 症状: UI に 一部 server (rei-project + rei-aios) は listed されるが 新規追加 (benchtop) だけ 反映されない = **既存 config は 読まれている が 内容が 新しい編集に 追いついていない** 状況証拠
- 診断 shortcut: **「設定を編集」 ボタンで開いた path を そのまま覚える** → 以降の 上書きは そこに直接

**★ 最優先 (path 分岐は 上で解決): log を先に読む (2026-08-13 藤本さん指摘 per)**

層 1 (server 起動失敗) と 層 2 (tool 登録失敗) の切り分けは、 藤本さんへの 質問より **MCP server の stderr / Claude Desktop の log を 直接読む** ほうが速い。 起動失敗と 登録失敗は log 上で 見分けがつくので、 質問往復が 1 回減る。 藤本さんに 送ってもらう file:

- Windows: `%APPDATA%\Claude\logs\` (通常 `mcp-server-benchtop.log` 等 server 別 file)
- macOS: `~/Library/Logs/Claude/`
- Linux: `~/.config/Claude/logs/`

**log 上の signature**:
- **層 1 (server spawn 失敗)**: `Failed to spawn` / `command not found` / `no such file or directory` / `permission denied` / `python: not found` / config parse error 系。 tool 登録 log は 一切ない。
- **層 2 (server 起動後 tool 登録失敗)**: server 起動成功 log あり + `tool registration failed` / `schema validation error` / `decorator raised` / `ImportError` / `TypeError in @server.tool()` 系。 一部 tool のみ log にあれば 部分登録。
- **層 3 (server + tool 登録は成功、 Claude 側が呼ばない)**: server log は clean、 Claude 側の会話 log に tool_use ブロックが 現れないか、 現れても 期待外の tool を呼んでいる。

log が手に入らない / 送ってもらえない場合の fallback として 下の質問順で 進める:

1. **まず層 1 かを確認**: 「Claude Desktop 完全再起動 したか」 + 「9 tool 全 listed か」 の 2 質問だけで 層 1 vs 層 2-3 を 分離
2. **層 2 か 3 か**: 「tool 一覧に 9 tool 全部あるか」 で 層 2 (欠けている) vs 層 3 (全 listed だが 呼ばれない) を 分離
3. **層 2 内**: どの tool が 欠けているかで 個別 tool 側の 問題を 絞る
4. **層 3 内**: どの prompt で どの応答が 返ってきたかで docstring 磨き vs prompt engineering vs Claude 側 model 挙動 を 分離

## 避けるべき pattern

- 症状 (「tool が動かない」) だけで 修正提案 loop に入る → 3 層のどれかを 確認せずに v0.2.4 実装計画を 書き始める
- 層 1 (config / path / version) を 層 3 (docstring) と 混同して docstring を いじる → 修正しても症状が消えないので 更に revision 波が 発生
- 層 3 で 「Claude Desktop 側 model の挙動」 を tool 側 の 修正で 解決しようとする → 一般的に model 側の判断は tool docstring から 完全に予測できない、 prompt engineering 側の 対応を 併走させる

## この template の scope 外

- Claude Desktop 自体の 起動不能 / config file 権限問題 / Windows Defender 干渉 → 藤本さん環境の システム管理領域
- Claude 側 model version の 動作差 (Sonnet vs Opus vs Haiku) → tool 側 修正で 吸収できない範囲
- 実装置接続 (SerialException / device timeout / baudrate mismatch) → 別 diagnostic template (v0.3+ で 実機接続系 tool 拡張時に 別 memory 化)

## 関連 memory

- [[project-benchtop-mcp-v022-review-2-pack-2026-08-13]] — 本 template の 起源 project、 藤本さん第 3 波 review 締めで 3 層分離指摘
- [[feedback-critique-response-pattern]] — verify 結果を 症状だけ聞いて修正 loop に入らない discipline
- [[project-session-2026-08-12-tools-launch-arc]] — benchtop-mcp v0.1 origin、 Claude Desktop MCP 3rd server 登録経緯 (backup-20260812-102358)

## Version

- v1 initial: 2026-08-13 v0.2.3 freeze 直後 (藤本さん 「失敗報告が来たら中身を切り分けてから修正に入ってください」 指摘 per、 verify 結果到達時に すぐ引くための事前準備 template)