claude-spotter 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## 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.8.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,135 @@
+// 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 }) {
+  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',
+      };
+      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.8.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,23 @@
 import { spawn } from 'node:child_process';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
+import { listToolsHttp } from './investigate-mcp-http.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);
@@ -45,7 +56,7 @@ export async function listMcpToolsAll({ logFn = () => {}, claudeBin = 'claude' }
 // Parse `claude mcp list` output. Returns array of {name, transport, command, url}.
 // stdio servers have command, http/sse servers have url.
 export async function listMcpServers({ claudeBin = 'claude' } = {}) {
-  const { stdout } = await execFileP(claudeBin, ['mcp', 'list'], { encoding: 'utf8' });
+  const { stdout } = await execClaude(claudeBin, ['mcp', 'list'], { encoding: 'utf8' });
   return parseMcpListOutput(stdout);
 }
 
@@ -89,17 +100,20 @@ export async function listMcpToolsOne({ server, logFn = () => {}, claudeBin = 'c
     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
-    );
+    // Streamable HTTP transport. For `claude.ai ...` servers, `claude mcp get` rejects
+    // them (they are not in local .mcp.json) so server.url is unavailable — those are
+    // 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 });
   }
   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,9 +133,19 @@ function splitArgs(s) {
   return s.split(/\s+/).filter((t) => t.length > 0);
 }
 
+// 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 }, 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,
     });
@@ -199,7 +223,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.8.0' },
         });
         send({ jsonrpc: '2.0', method: 'notifications/initialized' });
         initializedSent = true;

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.8.0';