claude-spotter 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,71 @@
 # Changelog
 
+## 0.9.0
+
+**`.mcp.json` を真実源として読み込み、user-registered HTTP/stdio MCP の認証情報を live fetch に活用**。v0.8.0 で HTTP transport を実装したが、`claude mcp list` / `claude mcp get` は bearer token や headers を CLI 出力に含めないため、認証が必要な MCP サーバー (x-api) は依然 401 で落ちていた。`~/.claude/.mcp.json` を直接読んで env / headers を取得、stdio なら spawn 時の env に、HTTP なら fetch request header に渡す。
+
+### 事の発端
+
+v0.8.0 の `spotter db refresh` 実測で x-api (HTTP MCP) が 401 Unauthorized で落ちていた。`claude mcp list` では `x-api: https://kitepon.dynv6.net/mcp (HTTP)` と表示され URL は拾えるが、Spotter の refresh プロセスから叩くと認証情報がないため拒否。ユーザーの指摘で `.mcp.json` を直接 cat したところ、実態は **stdio** で `env: {X_BEARER_TOKEN: "..."}` を持つ設定だった。CLI 表示と actual config が食い違っていた (CLI の cache の古さと思われる)。
+
+判明した設計上の転換点:
+
+- **`.mcp.json` はユーザーが自己申告した MCP 設定ファイル** — ここに secrets が書かれているのはユーザーの意思。Anthropic の OAuth token を保持する `.credentials.json` とは性格が違う。`.mcp.json` を読むことは v0.8.0 で引いた境界線 (credentials は触らない) に抵触しない
+- **`claude mcp list` は scope 統合ビュー、`.mcp.json` は user scope の詳細**。前者で名前を取り、後者で詳細を当てる併用が最も抜け漏れない
+
+### 変更点
+
+- **新規 [src/tool-db/mcp-config.mjs](src/tool-db/mcp-config.mjs)**: `~/.claude/.mcp.json` をパース、`describeServer()` で `{command, args, env}` (stdio) または `{url, headers}` (http/sse) のディスクリプタに正規化
+- **編集 [src/tool-db/investigate-mcp.mjs](src/tool-db/investigate-mcp.mjs)**: `listMcpServers` を `claude mcp list` + `.mcp.json` の併用へ。CLI で得た name ごとに `.mcp.json` のエントリを優先使用し、なければ CLI 情報にフォールバック。`spawnAndQuery` が `env` を受け取って `{...process.env, ...env}` で spawn 時に merge
+- **編集 [src/tool-db/investigate-mcp-http.mjs](src/tool-db/investigate-mcp-http.mjs)**: `listToolsHttp` が `headers` パラメータを受け取って fetch の HTTP headers に merge
+- **編集 [test/tool-db.test.mjs](test/tool-db.test.mjs)**: `describeServer` の unit test 5 件追加 (stdio + env、stdio 最小、http + headers、sse 判別、未知エントリ)
+
+### 実測
+
+`spotter db rebuild` で x-api の 9 ツール (get_trends / search_tweets / fetch_tweet 等) が **live fetch で投入される** ようになった (`investigated=9`)。手書き baseline は不要。`describeServer` テスト 5 件追加で total 97 tests。
+
+### 残る課題
+
+- **project scope `.mcp.json` 未対応**: プロジェクト直下の `.mcp.json` は読んでいない。v0.9.0 では user scope のみ
+- **claude.ai baseline は維持**: Gmail/Calendar/Drive は `.mcp.json` に登録されない (OAuth proxy 経由) ので hardcoded のまま
+
+## 0.8.0
+
+**HTTP/SSE MCP transport 対応 + Windows `.cmd` 経路の ENOENT fix + claude.ai 系 MCP の hardcoded baseline**。v0.7.0 を実測したら Windows で `spotter db refresh` が `spawn claude ENOENT` で起動すらせず、fix した上で動かしたら今度は Gmail / Google Calendar / Google Drive / x-api が丸ごと抜け落ちて Haiku の視野に入らない状態だった。この 3 本を同時に潰した。
+
+### 事の発端
+
+v0.7.0 リリース直後、新規セッションで `spotter db refresh` を打ったら即失敗:
+
+1. **Windows で `spawn claude ENOENT`**: Node の `execFile` / `spawn` は Windows で `.cmd` 拡張子のラッパーを直接起動できない。`doctor` は `cmd.exe /c claude` 経由で回避していたが、新規コード [src/tool-db/investigate-mcp.mjs](src/tool-db/investigate-mcp.mjs) は `execFileP(claudeBin, ...)` をそのまま使っていて全 Windows 環境で DB refresh 不可。
+2. **HTTP/SSE transport 全滅**: v0.7.0 は stdio しか実装していなかったため、`claude.ai Google Drive` / `claude.ai Google Calendar` / `claude.ai Gmail` / `x-api` の 4 サーバーが `sse transport not yet supported` / `http transport not yet supported` でスキップされ、Haiku は Gmail や Calendar のツールを推奨できない状態だった。
+3. **claude.ai 系 MCP は `claude mcp get` で取得不可**: `claude mcp get "claude.ai Gmail"` は `No MCP server found` を返す。Anthropic 提供の MCP は `.mcp.json` に登録されず、Claude Code は `~/.claude/.credentials.json` の OAuth token を使って `mcp-proxy.anthropic.com` に直接アクセスしている。Spotter は credentials を読まない方針なので、これらは **hardcoded baseline** でカバーする。
+
+### 変更点
+
+- **新規 [src/tool-db/investigate-mcp-http.mjs](src/tool-db/investigate-mcp-http.mjs)**: MCP Streamable HTTP transport 実装。POST + `Content-Type: application/json` + `Accept: application/json, text/event-stream` で JSON-RPC 往復、`Mcp-Session-Id` header で session 維持、SSE 形式レスポンスも parse。`initialize` → `notifications/initialized` → `tools/list` を 10 秒 timeout で実行
+- **新規 [src/tool-db/claude-ai-baseline.mjs](src/tool-db/claude-ai-baseline.mjs)**: `claude.ai Gmail` (10) / `claude.ai Google Calendar` (8) / `claude.ai Google Drive` (7) の合計 25 件の {name, description} を手書き baseline として保持。deferred-baseline と同じ設計パターン
+- **編集 [src/tool-db/investigate-mcp.mjs](src/tool-db/investigate-mcp.mjs)**:
+  - `execClaude()` helper 追加: Windows では `execFileP('cmd.exe', ['/c', claudeBin, ...args])` 経由、他は `execFileP(claudeBin, args)` そのまま。`listMcpServers` と `getStdioConfig` の 2 箇所で利用
+  - `buildStdioSpawn()` helper 追加: MCP stdio サーバーの Command が Windows で `.cmd` / `.bat` 拡張子なら `cmd.exe /c` 経由で spawn (caveat 等 `.exe` は影響なし)
+  - `listMcpToolsOne` の HTTP/SSE 分岐を `listToolsHttp` に dispatch
+- **編集 [src/tool-db/refresh.mjs](src/tool-db/refresh.mjs)**: `buildInvestigationSnapshot` に claude.ai baseline を deferred の直後に merge。後続の live HTTP investigate が成功すれば上書き
+- **編集 [package.json](package.json), [src/version.mjs](src/version.mjs)**: `0.7.0` → `0.8.0`
+
+### 実測
+
+`spotter db rebuild` で **48 tools resolved**:
+- deferred baseline: 17 (Claude Code 組込み遅延ツール)
+- claude.ai baseline: 25 (Gmail 10 + Calendar 8 + Drive 7)
+- stdio MCP (Caveat): 6
+
+`claude.ai Gmail/Calendar/Drive` への live HTTP fetch は **HTTP 403 Forbidden** (認証 token なしで直接叩けない、想定通り) → baseline がカバー。`x-api` は **HTTP 401 Unauthorized** (ユーザー設定 MCP で Authorization header 未対応、次回課題)。`caveat` は stdio で正常 fetch。
+
+### 残る課題
+
+- **ユーザー設定 HTTP MCP の認証 header**: `claude mcp get <name>` の出力から Authorization 等を抽出して fetch に付与する仕組みが未実装。v0.8.0 では x-api が落ちる (baseline でも救えない、公開情報でない)
+- **claude.ai baseline の手動メンテ**: Anthropic が tool を追加・変更したら手で追従。deferred baseline と同じ trade-off
+
 ## 0.7.0
 
 **カタログを tool-db に置き換え**。手書きの `tools.yaml` (5 つの抽象ツール) を捨て、**実際にセッションで使えるツール (MCP + Claude Code 組込み 遅延ツール) の name + description を自動収集してキャッシュする** 仕組みに置き換え。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-spotter",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Audit agent running alongside Claude Code that catches missed tool calls — 気づく役と実行する役の分離",
   "type": "module",
   "bin": {

package/src/tool-db/claude-ai-baseline.mjs

@@ -0,0 +1,86 @@
+// Hardcoded description baseline for Anthropic-provided `claude.ai ...` MCP servers
+// (Gmail / Google Calendar / Google Drive).
+//
+// Why hardcoded, not fetched:
+//   These servers are NOT registered in local `.mcp.json`. Claude Code calls them via
+//   its own mcp-proxy.anthropic.com endpoint using the OAuth token in
+//   ~/.claude/.credentials.json. Spotter deliberately does NOT read credentials — so
+//   we cannot dynamically invoke tools/list against the proxy. The tool surface is
+//   public (the same deferred-tool list Claude Code exposes) and changes slowly.
+//
+// Maintenance:
+//   When Anthropic adds new tools to these MCP servers, append them here. The daemon
+//   merges this baseline into the tool-db during `spotter db refresh`.
+//
+// Bell-visible names follow the convention `mcp__<server-id>__<tool-name>` where
+// <server-id> is the `claude.ai ...` server name with non-[A-Za-z0-9_-] chars replaced
+// by `_` — e.g. "claude.ai Gmail" → "claude_ai_Gmail".
+
+const GMAIL = {
+  mcp__claude_ai_Gmail__search_threads:
+    'Search Gmail threads matching a query (e.g. from:alice subject:invoice, is:unread, after:2024-01-01). Use when the user asks to find, read, or reference specific mail.',
+  mcp__claude_ai_Gmail__get_thread:
+    'Fetch the full body of a Gmail thread by id — all messages, headers, and text. Use after search_threads to read the actual content.',
+  mcp__claude_ai_Gmail__list_drafts:
+    'List existing Gmail drafts. Use before create_draft when the user asks about pending unsent mail or wants to resume a draft.',
+  mcp__claude_ai_Gmail__create_draft:
+    'Create a new Gmail draft (to, subject, body, optional cc/bcc). Does NOT send. Use when the user asks Claude to compose a message for later review.',
+  mcp__claude_ai_Gmail__list_labels:
+    'List all Gmail labels (both system and user-created). Use before label_message / label_thread to find the correct label id.',
+  mcp__claude_ai_Gmail__create_label:
+    'Create a new Gmail label. Use when the user wants to organize mail into a category that does not yet exist.',
+  mcp__claude_ai_Gmail__label_message:
+    'Apply a label to a single Gmail message by id.',
+  mcp__claude_ai_Gmail__unlabel_message:
+    'Remove a label from a single Gmail message by id.',
+  mcp__claude_ai_Gmail__label_thread:
+    'Apply a label to an entire Gmail thread (all messages in the thread).',
+  mcp__claude_ai_Gmail__unlabel_thread:
+    'Remove a label from an entire Gmail thread.',
+};
+
+const CALENDAR = {
+  mcp__claude_ai_Google_Calendar__list_calendars:
+    'List all Google Calendars the user has access to (primary, shared, subscribed). Use first when the user does not specify which calendar.',
+  mcp__claude_ai_Google_Calendar__list_events:
+    'List events in a calendar over a time range. Use when the user asks about upcoming meetings, schedule conflicts, or "what is on my calendar".',
+  mcp__claude_ai_Google_Calendar__get_event:
+    'Fetch a single event by id with full details (attendees, description, attachments).',
+  mcp__claude_ai_Google_Calendar__create_event:
+    'Create a new Google Calendar event (title, start/end, attendees, optional location/description). Use when the user asks to schedule something.',
+  mcp__claude_ai_Google_Calendar__update_event:
+    'Modify an existing event (reschedule, change attendees, update description). Use when the user asks to move or edit a meeting.',
+  mcp__claude_ai_Google_Calendar__delete_event:
+    'Delete an event from Google Calendar. Use when the user asks to cancel a meeting.',
+  mcp__claude_ai_Google_Calendar__respond_to_event:
+    'RSVP to an event invitation (accept / decline / tentative).',
+  mcp__claude_ai_Google_Calendar__suggest_time:
+    'Find free time slots across multiple calendars / attendees. Use when the user asks to find a mutually available meeting time.',
+};
+
+const DRIVE = {
+  mcp__claude_ai_Google_Drive__search_files:
+    'Search Google Drive for files matching a query (name, content, mimeType). Use when the user asks to find a doc/sheet/slide by topic or title.',
+  mcp__claude_ai_Google_Drive__list_recent_files:
+    'List recently accessed Google Drive files. Use when the user asks "what was I just working on in Drive?" or similar.',
+  mcp__claude_ai_Google_Drive__get_file_metadata:
+    'Fetch metadata (name, mimeType, owner, modified time, sharing) for a Drive file by id — NOT the content. Use before read_file_content to verify the file type.',
+  mcp__claude_ai_Google_Drive__read_file_content:
+    'Read the textual content of a Drive file (Docs, Sheets, plain text). Use when the user asks Claude to reference or summarize a file.',
+  mcp__claude_ai_Google_Drive__download_file_content:
+    'Download binary file content from Drive (PDF, image, zip). Use when the user needs the raw bytes rather than extracted text.',
+  mcp__claude_ai_Google_Drive__create_file:
+    'Create a new file in Google Drive (text content or uploaded blob). Use when the user asks to save something to Drive.',
+  mcp__claude_ai_Google_Drive__get_file_permissions:
+    'List who has access to a Drive file and their role (reader/commenter/writer/owner). Use when the user asks who can see or edit a file.',
+};
+
+const ALL = { ...GMAIL, ...CALENDAR, ...DRIVE };
+
+export function listClaudeAiNames() {
+  return Object.keys(ALL);
+}
+
+export function getClaudeAiDescription(name) {
+  return ALL[name] ?? null;
+}

package/src/tool-db/investigate-mcp-http.mjs

@@ -0,0 +1,136 @@
+// HTTP (Streamable HTTP transport) MCP investigation.
+//
+// Spec: https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http
+// Wire:
+//   POST <url> with JSON-RPC body + Content-Type: application/json
+//   Accept: application/json, text/event-stream  (server may reply with either)
+//   First response may set Mcp-Session-Id; echo it on subsequent requests.
+//
+// We only need initialize → notifications/initialized → tools/list; the handshake is
+// plain request/response, no long-lived SSE stream required.
+//
+// Auth: `claude mcp get <name>` does NOT expose bearer tokens for user-configured
+// servers. If a server requires auth beyond public URL access, investigate will fail
+// with a descriptive error — caller logs and skips that server.
+
+const PROTOCOL_VERSION = '2025-03-26';
+const REQUEST_TIMEOUT_MS = 10_000;
+
+export class McpHttpError extends Error {
+  constructor(message, server) {
+    super(message);
+    this.name = 'McpHttpError';
+    this.server = server;
+  }
+}
+
+export async function listToolsHttp({ url, serverName, headers: staticHeaders = {} }) {
+  let sessionId = null;
+
+  const post = async (body) => {
+    const ctl = new AbortController();
+    const t = setTimeout(() => ctl.abort(), REQUEST_TIMEOUT_MS);
+    try {
+      const headers = {
+        'Content-Type': 'application/json',
+        'Accept': 'application/json, text/event-stream',
+        ...staticHeaders,
+      };
+      if (sessionId) headers['Mcp-Session-Id'] = sessionId;
+      const res = await fetch(url, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify(body),
+        signal: ctl.signal,
+      });
+      const sid = res.headers.get('mcp-session-id');
+      if (sid && !sessionId) sessionId = sid;
+      if (!res.ok) {
+        throw new McpHttpError(`HTTP ${res.status} ${res.statusText}`, serverName);
+      }
+      // Response may be application/json or text/event-stream.
+      const contentType = res.headers.get('content-type') ?? '';
+      if (contentType.includes('text/event-stream')) {
+        return parseSseSingle(await res.text(), serverName);
+      }
+      if (contentType.includes('application/json')) {
+        return await res.json();
+      }
+      // Some servers omit content-type; try JSON.
+      const text = await res.text();
+      if (text.trim().length === 0) return null;
+      try {
+        return JSON.parse(text);
+      } catch {
+        throw new McpHttpError(`unexpected response content-type "${contentType}"`, serverName);
+      }
+    } finally {
+      clearTimeout(t);
+    }
+  };
+
+  const postNotification = async (body) => {
+    // Notifications may return 202 Accepted with empty body; swallow the result.
+    await post(body).catch((err) => {
+      // Some servers reject notifications with no body response as non-2xx; treat as OK
+      // only if the error is clearly a parse issue on empty body.
+      if (err instanceof McpHttpError) throw err;
+      throw err;
+    });
+  };
+
+  // 1. initialize
+  const initResult = await post({
+    jsonrpc: '2.0',
+    id: 1,
+    method: 'initialize',
+    params: {
+      protocolVersion: PROTOCOL_VERSION,
+      capabilities: {},
+      clientInfo: { name: 'spotter', version: '0.9.0' },
+    },
+  });
+  if (!initResult || initResult.error) {
+    throw new McpHttpError(`initialize failed: ${JSON.stringify(initResult?.error ?? initResult)}`, serverName);
+  }
+
+  // 2. notifications/initialized
+  await postNotification({
+    jsonrpc: '2.0',
+    method: 'notifications/initialized',
+  });
+
+  // 3. tools/list
+  const listResult = await post({
+    jsonrpc: '2.0',
+    id: 2,
+    method: 'tools/list',
+    params: {},
+  });
+  if (!listResult || listResult.error) {
+    throw new McpHttpError(`tools/list failed: ${JSON.stringify(listResult?.error ?? listResult)}`, serverName);
+  }
+
+  const tools = (listResult.result?.tools ?? []).map((t) => ({
+    name: t.name,
+    description: typeof t.description === 'string' ? t.description : '',
+  }));
+  return tools;
+}
+
+// SSE responses wrap a single JSON message in one `data:` event. Parse it out.
+function parseSseSingle(sseText, serverName) {
+  for (const rawLine of sseText.split('\n')) {
+    const line = rawLine.trim();
+    if (line.startsWith('data:')) {
+      const payload = line.slice('data:'.length).trim();
+      if (payload.length === 0) continue;
+      try {
+        return JSON.parse(payload);
+      } catch {
+        throw new McpHttpError(`failed to parse SSE data payload`, serverName);
+      }
+    }
+  }
+  throw new McpHttpError(`no data event in SSE response`, serverName);
+}

package/src/tool-db/investigate-mcp.mjs

@@ -12,12 +12,24 @@
 import { spawn } from 'node:child_process';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
+import { listToolsHttp } from './investigate-mcp-http.mjs';
+import { readMcpServers, describeServer } from './mcp-config.mjs';
 
 const execFileP = promisify(execFile);
 
 const PROTOCOL_VERSION = '2025-03-26'; // MCP protocol version we claim to speak.
 const HANDSHAKE_TIMEOUT_MS = 10_000;
 
+// On Windows, `claude` is a .cmd shim; Node's execFile cannot locate it directly without
+// going through cmd.exe. Matches the pattern in src/daemon/haiku-caller.mjs buildSpawnArgs.
+// We use cmd.exe /c rather than shell:true to avoid DEP0190 on Node 24+.
+async function execClaude(claudeBin, args, opts) {
+  if (process.platform === 'win32') {
+    return execFileP('cmd.exe', ['/c', claudeBin, ...args], opts);
+  }
+  return execFileP(claudeBin, args, opts);
+}
+
 export class McpInvestigationError extends Error {
   constructor(message, server) {
     super(message);
@@ -42,11 +54,30 @@ export async function listMcpToolsAll({ logFn = () => {}, claudeBin = 'claude' }
   return out;
 }
 
-// Parse `claude mcp list` output. Returns array of {name, transport, command, url}.
-// stdio servers have command, http/sse servers have url.
+// Returns the list of MCP servers to investigate. Merges two sources:
+//   - `claude mcp list` — authoritative for *which* servers exist in this session
+//     (covers all scopes: user, project, local, enterprise)
+//   - `~/.claude/.mcp.json` — authoritative for transport details + auth secrets
+//     (stdio env, http headers). The CLI hides these on purpose.
+//
+// For each server named by the CLI, if `.mcp.json` has a matching entry we use that
+// full descriptor (with env/headers). Otherwise we fall back to the parsed CLI line,
+// which at minimum gives us name + transport + url (or triggers `claude mcp get` for
+// stdio command tokenisation).
 export async function listMcpServers({ claudeBin = 'claude' } = {}) {
-  const { stdout } = await execFileP(claudeBin, ['mcp', 'list'], { encoding: 'utf8' });
-  return parseMcpListOutput(stdout);
+  const [{ stdout }, mcpServers] = await Promise.all([
+    execClaude(claudeBin, ['mcp', 'list'], { encoding: 'utf8' }),
+    readMcpServers(),
+  ]);
+  const cliList = parseMcpListOutput(stdout);
+  return cliList.map((cliEntry) => {
+    const configEntry = mcpServers[cliEntry.name];
+    if (configEntry) {
+      const described = describeServer(cliEntry.name, configEntry);
+      if (described) return described;
+    }
+    return cliEntry;
+  });
 }
 
 // `claude mcp list` output lines look like:
@@ -81,25 +112,31 @@ export function parseMcpListOutput(text) {
   return out;
 }
 
-// Fetch tools/list from a single MCP server. HTTP/SSE servers are not yet supported here
-// (we'd need to speak the HTTP+SSE MCP transport); we throw so the caller can log+skip.
+// Fetch tools/list from a single MCP server. The `server` descriptor either came
+// from `.mcp.json` (carries env / headers) or from CLI output (bare). For stdio
+// entries without full config we fall back to `claude mcp get`.
 export async function listMcpToolsOne({ server, logFn = () => {}, claudeBin = 'claude' }) {
   if (server.transport === 'stdio') {
-    const config = await getStdioConfig({ name: server.name, claudeBin });
+    const hasFullConfig = server.command !== undefined;
+    const config = hasFullConfig
+      ? { command: server.command, args: server.args ?? [], env: server.env ?? {} }
+      : await getStdioConfig({ name: server.name, claudeBin });
     return spawnAndQuery(config, server.name);
   }
   if (server.transport === 'http' || server.transport === 'sse') {
-    throw new McpInvestigationError(
-      `${server.transport} transport not yet supported (need HTTP MCP client)`,
-      server.name
-    );
+    // For `claude.ai ...` servers, CLI reports http/sse but they are NOT in local
+    // .mcp.json — covered by src/tool-db/claude-ai-baseline.mjs at a higher layer.
+    if (!server.url) {
+      throw new McpInvestigationError(`no URL available for ${server.transport} server`, server.name);
+    }
+    return listToolsHttp({ url: server.url, serverName: server.name, headers: server.headers ?? {} });
   }
   throw new McpInvestigationError(`unknown transport: ${server.transport}`, server.name);
 }
 
 // Parse `claude mcp get <name>` to extract Command + Args for stdio servers.
 async function getStdioConfig({ name, claudeBin }) {
-  const { stdout } = await execFileP(claudeBin, ['mcp', 'get', name], { encoding: 'utf8' });
+  const { stdout } = await execClaude(claudeBin, ['mcp', 'get', name], { encoding: 'utf8' });
   let command = null;
   let argsRaw = null;
   for (const rawLine of stdout.split('\n')) {
@@ -119,11 +156,22 @@ function splitArgs(s) {
   return s.split(/\s+/).filter((t) => t.length > 0);
 }
 
-async function spawnAndQuery({ command, args }, serverName) {
+// On Windows, `.cmd` / `.bat` shims cannot be spawned directly without cmd.exe.
+// Unix-like paths or `.exe` binaries go through spawn as-is.
+function buildStdioSpawn(command, args) {
+  if (process.platform === 'win32' && /\.(cmd|bat)$/i.test(command)) {
+    return { cmd: 'cmd.exe', cmdArgs: ['/c', command, ...args] };
+  }
+  return { cmd: command, cmdArgs: args };
+}
+
+async function spawnAndQuery({ command, args, env = {} }, serverName) {
   return new Promise((resolve, reject) => {
-    const child = spawn(command, args, {
+    const { cmd, cmdArgs } = buildStdioSpawn(command, args);
+    const child = spawn(cmd, cmdArgs, {
       stdio: ['pipe', 'pipe', 'pipe'],
       windowsHide: true,
+      env: { ...process.env, ...env },
     });
     let buffer = '';
     let nextId = 1;
@@ -199,7 +247,7 @@ async function spawnAndQuery({ command, args }, serverName) {
         await request('initialize', {
           protocolVersion: PROTOCOL_VERSION,
           capabilities: {},
-          clientInfo: { name: 'spotter', version: '0.7.0' },
+          clientInfo: { name: 'spotter', version: '0.9.0' },
         });
         send({ jsonrpc: '2.0', method: 'notifications/initialized' });
         initializedSent = true;

package/src/tool-db/mcp-config.mjs

@@ -0,0 +1,62 @@
+// Read MCP server definitions directly from `.mcp.json` rather than parsing
+// `claude mcp list` text output.
+//
+// Why: `.mcp.json` is the authoritative source for stdio env vars (e.g. bearer tokens
+// passed to the MCP subprocess) and HTTP headers (e.g. Authorization). The CLI output
+// of `claude mcp list` / `claude mcp get` hides those secrets. Without them, an HTTP
+// MCP server returns 401 and a stdio MCP server spawns without its API key.
+//
+// Scope: reads user-level `~/.claude/.mcp.json`. Project-level `.mcp.json` and
+// `settings.local.json` are not yet consulted — user scope covers the common case
+// (globally-installed MCP servers) and is the scope that Spotter's tool-db is
+// global-first anyway.
+//
+// This file does NOT read ~/.claude/.credentials.json (Anthropic OAuth token). That
+// remains off-limits per the v0.8.0 design decision. `.mcp.json` is user-authored
+// configuration where the user has already chosen to persist their own MCP credentials.
+
+import { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export function userMcpConfigPath() {
+  return join(homedir(), '.claude', '.mcp.json');
+}
+
+// Returns the raw `mcpServers` object from ~/.claude/.mcp.json, or {} if missing.
+// Throws only on malformed JSON (not on missing file).
+export async function readMcpServers() {
+  try {
+    const text = await readFile(userMcpConfigPath(), 'utf8');
+    const data = JSON.parse(text);
+    return data.mcpServers ?? {};
+  } catch (err) {
+    if (err.code === 'ENOENT') return {};
+    throw err;
+  }
+}
+
+// Normalise an `.mcp.json` entry into a server descriptor the investigator can use.
+// Returns { name, transport: 'stdio'|'http'|'sse', ...transport-specific fields } or
+// null if the entry is not recognisable.
+export function describeServer(name, entry) {
+  if (entry.command) {
+    return {
+      name,
+      transport: 'stdio',
+      command: entry.command,
+      args: Array.isArray(entry.args) ? entry.args : [],
+      env: entry.env && typeof entry.env === 'object' ? entry.env : {},
+    };
+  }
+  if (entry.url) {
+    const transport = entry.type === 'sse' ? 'sse' : 'http';
+    return {
+      name,
+      transport,
+      url: entry.url,
+      headers: entry.headers && typeof entry.headers === 'object' ? entry.headers : {},
+    };
+  }
+  return null;
+}

package/src/tool-db/refresh.mjs

@@ -8,6 +8,7 @@
 import { resolveAll } from './lookup.mjs';
 import { listMcpToolsAll, bellVisibleName } from './investigate-mcp.mjs';
 import { getDeferredDescription, listDeferredNames } from './deferred-baseline.mjs';
+import { getClaudeAiDescription, listClaudeAiNames } from './claude-ai-baseline.mjs';
 import { localDbPath, globalDbPath } from './loader.mjs';
 
 // Build the (name → description) map for an investigation pass:
@@ -19,12 +20,19 @@ import { localDbPath, globalDbPath } from './loader.mjs';
 export async function buildInvestigationSnapshot({ logFn = () => {}, claudeBin = 'claude' } = {}) {
   const snapshot = new Map();
 
-  // Deferred built-ins.
+  // Deferred built-ins (Claude Code deferred tools like WebFetch, TodoWrite, etc.).
   for (const name of listDeferredNames()) {
     snapshot.set(name, getDeferredDescription(name));
   }
 
-  // MCP servers.
+  // Anthropic-provided `claude.ai ...` MCP servers — hardcoded because the OAuth proxy
+  // is not reachable without reading ~/.claude/.credentials.json (deliberately avoided).
+  // If a live HTTP investigate for the same name later succeeds below, it overrides.
+  for (const name of listClaudeAiNames()) {
+    snapshot.set(name, getClaudeAiDescription(name));
+  }
+
+  // MCP servers (stdio + user-registered HTTP/SSE).
   const mcp = await listMcpToolsAll({ logFn, claudeBin });
   for (const [serverName, tools] of mcp.entries()) {
     for (const tool of tools) {

package/src/version.mjs

@@ -1 +1 @@
-export const version = '0.7.0';
+export const version = '0.9.0';