claude-spotter 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # Changelog
 
+## 0.10.0
+
+**project scope `.mcp.json` 対応**。v0.9.0 は `~/.claude/.mcp.json` (user scope) だけを読んでいたため、プロジェクト直下の `.mcp.json` に登録された MCP サーバーの認証情報 (env / headers) を拾えなかった。`<projectRoot>/.mcp.json` も読んで user scope に merge (project 勝ち = Claude Code 本体の precedence と整合) するよう変更。
+
+### 変更点
+
+- **編集 [src/tool-db/mcp-config.mjs](src/tool-db/mcp-config.mjs)**: `readMcpServers({projectRoot})` シグネチャへ変更。`projectRoot` が渡されれば user scope に project scope を merge して返す。missing file は空として扱う
+- **編集 [src/tool-db/investigate-mcp.mjs](src/tool-db/investigate-mcp.mjs)**: `listMcpServers` / `listMcpToolsAll` が `projectRoot` を受け取って伝搬
+- **編集 [src/tool-db/refresh.mjs](src/tool-db/refresh.mjs)**: `buildInvestigationSnapshot` / `refresh` が `projectRoot` を伝搬 (CLI からは既に渡されている、経路が繋がった)
+- **編集 [test/tool-db.test.mjs](test/tool-db.test.mjs)**: project-scope override + missing-file fallback の 2 ケース追加 (total 99 tests)
+
+### 非互換
+
+- `readMcpServers()` → `readMcpServers({projectRoot})`: 引数なしも引き続き動く (user scope のみ) ので既存コードは影響なし
+
+## 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 本を同時に潰した。

package/package.json

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

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

@@ -24,7 +24,7 @@ export class McpHttpError extends Error {
   }
 }
 
-export async function listToolsHttp({ url, serverName }) {
+export async function listToolsHttp({ url, serverName, headers: staticHeaders = {} }) {
   let sessionId = null;
 
   const post = async (body) => {
@@ -34,6 +34,7 @@ export async function listToolsHttp({ url, serverName }) {
       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, {
@@ -86,7 +87,7 @@ export async function listToolsHttp({ url, serverName }) {
     params: {
       protocolVersion: PROTOCOL_VERSION,
       capabilities: {},
-      clientInfo: { name: 'spotter', version: '0.8.0' },
+      clientInfo: { name: 'spotter', version: '0.10.0' },
     },
   });
   if (!initResult || initResult.error) {

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

@@ -13,6 +13,7 @@ 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);
 
@@ -39,8 +40,8 @@ export class McpInvestigationError extends Error {
 
 // Returns: Map<server-name, Array<{name, description}>>.
 // Skips servers that fail (logs the failure) so one broken server doesn't block the rest.
-export async function listMcpToolsAll({ logFn = () => {}, claudeBin = 'claude' } = {}) {
-  const servers = await listMcpServers({ claudeBin });
+export async function listMcpToolsAll({ logFn = () => {}, claudeBin = 'claude', projectRoot } = {}) {
+  const servers = await listMcpServers({ claudeBin, projectRoot });
   const out = new Map();
   for (const server of servers) {
     try {
@@ -53,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.
-export async function listMcpServers({ claudeBin = 'claude' } = {}) {
-  const { stdout } = await execClaude(claudeBin, ['mcp', 'list'], { encoding: 'utf8' });
-  return parseMcpListOutput(stdout);
+// 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', projectRoot } = {}) {
+  const [{ stdout }, mcpServers] = await Promise.all([
+    execClaude(claudeBin, ['mcp', 'list'], { encoding: 'utf8' }),
+    readMcpServers({ projectRoot }),
+  ]);
+  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:
@@ -92,21 +112,24 @@ 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') {
-    // 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.
+    // 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 });
+    return listToolsHttp({ url: server.url, serverName: server.name, headers: server.headers ?? {} });
   }
   throw new McpInvestigationError(`unknown transport: ${server.transport}`, server.name);
 }
@@ -142,12 +165,13 @@ function buildStdioSpawn(command, args) {
   return { cmd: command, cmdArgs: args };
 }
 
-async function spawnAndQuery({ command, args }, serverName) {
+async function spawnAndQuery({ command, args, env = {} }, serverName) {
   return new Promise((resolve, reject) => {
     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;
@@ -223,7 +247,7 @@ async function spawnAndQuery({ command, args }, serverName) {
         await request('initialize', {
           protocolVersion: PROTOCOL_VERSION,
           capabilities: {},
-          clientInfo: { name: 'spotter', version: '0.8.0' },
+          clientInfo: { name: 'spotter', version: '0.10.0' },
         });
         send({ jsonrpc: '2.0', method: 'notifications/initialized' });
         initializedSent = true;

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

@@ -0,0 +1,74 @@
+// 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: merges user-level `~/.claude/.mcp.json` with optional project-level
+// `<projectRoot>/.mcp.json`. Project scope overrides user scope on name collision
+// (matches Claude Code's own precedence — more-specific scope wins).
+// `settings.local.json` (local scope) is not yet consulted.
+//
+// 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');
+}
+
+export function projectMcpConfigPath(projectRoot) {
+  return join(projectRoot, '.mcp.json');
+}
+
+async function readOne(path) {
+  try {
+    const text = await readFile(path, 'utf8');
+    const data = JSON.parse(text);
+    return data.mcpServers ?? {};
+  } catch (err) {
+    if (err.code === 'ENOENT') return {};
+    throw err;
+  }
+}
+
+// Returns the merged `mcpServers` object: user scope as base, project scope overrides
+// on name collision. Missing files are treated as empty (not an error). If projectRoot
+// is not supplied, only user scope is read.
+export async function readMcpServers({ projectRoot } = {}) {
+  const user = await readOne(userMcpConfigPath());
+  if (!projectRoot) return user;
+  const project = await readOne(projectMcpConfigPath(projectRoot));
+  return { ...user, ...project };
+}
+
+// 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

@@ -17,7 +17,7 @@ import { localDbPath, globalDbPath } from './loader.mjs';
 // - Deferred: from the hardcoded baseline
 //
 // Returns an in-memory snapshot the caller can use as the investigate() backend.
-export async function buildInvestigationSnapshot({ logFn = () => {}, claudeBin = 'claude' } = {}) {
+export async function buildInvestigationSnapshot({ logFn = () => {}, claudeBin = 'claude', projectRoot } = {}) {
   const snapshot = new Map();
 
   // Deferred built-ins (Claude Code deferred tools like WebFetch, TodoWrite, etc.).
@@ -32,8 +32,9 @@ export async function buildInvestigationSnapshot({ logFn = () => {}, claudeBin =
     snapshot.set(name, getClaudeAiDescription(name));
   }
 
-  // MCP servers (stdio + user-registered HTTP/SSE).
-  const mcp = await listMcpToolsAll({ logFn, claudeBin });
+  // MCP servers (stdio + user-registered HTTP/SSE). projectRoot forwards for
+  // project-scope `.mcp.json` merge (see mcp-config.mjs).
+  const mcp = await listMcpToolsAll({ logFn, claudeBin, projectRoot });
   for (const [serverName, tools] of mcp.entries()) {
     for (const tool of tools) {
       if (!tool.description || tool.description.length === 0) continue;
@@ -47,7 +48,7 @@ export async function buildInvestigationSnapshot({ logFn = () => {}, claudeBin =
 // Refresh the tool-db. Discovers all currently available tools, resolves each via the
 // 3-tier lookup, writes through. Returns the resolved Map.
 export async function refresh({ projectRoot, logFn = () => {}, claudeBin = 'claude' }) {
-  const snapshot = await buildInvestigationSnapshot({ logFn, claudeBin });
+  const snapshot = await buildInvestigationSnapshot({ logFn, claudeBin, projectRoot });
   const toolNames = Array.from(snapshot.keys());
   const investigate = async (name) => snapshot.get(name) ?? null;
 

package/src/version.mjs

@@ -1 +1 @@
-export const version = '0.8.0';
+export const version = '0.10.0';