readfirst 0.5.0 → 0.6.0

package/README.md

@@ -63,6 +63,31 @@ Labels for yourself: `npx readfirst prompt --labels ko` (or `en`, ...) gives you
 to the code. The view then has a switch between the two. `.readfirst/local/` is added to `.git/info/exclude`, so labels
 stay on your machine and never reach the team's map.
 
+### Any agent, through MCP
+
+`npx readfirst mcp` is an MCP server on stdio with three tools: `read_list` (files → what to read and check before
+changing them), `changed_read_list` (the same for everything changed on the branch) and `check_map`. It answers from the
+checkout as it is and writes nothing.
+
+```sh
+claude mcp add readfirst -- npx --yes readfirst mcp          # Claude Code
+```
+
+```json
+// Cursor: .cursor/mcp.json · Windsurf: ~/.codeium/windsurf/mcp_config.json
+{ "mcpServers": { "readfirst": { "command": "npx", "args": ["--yes", "readfirst", "mcp"] } } }
+```
+
+```toml
+# Codex: ~/.codex/config.toml
+[mcp_servers.readfirst]
+command = "npx"
+args = ["--yes", "readfirst", "mcp"]
+```
+
+The server reads the git repository it is started in. If your agent starts it elsewhere, add `"--root", "/path/to/repo"`
+to the arguments.
+
 ## On every pull request (GitHub Action)
 
 ```yaml

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "readfirst",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "What to read and check before you (or your AI agent) change a file: project rules, risks and tests tied to code.",
   "type": "module",
   "license": "MIT",

package/src/cli.mjs

@@ -8,6 +8,7 @@
 //   readfirst diff [--base <ref>]  the read list for the files changed since <ref> (default: origin/main, else main)
 //   readfirst verify [--base <ref>] run the checks the read list names for the changed files; exit 1 if one fails
 //   readfirst hook [--install]     a Claude Code PreToolUse hook: the read list for the file an Edit or Write is about to change
+//   readfirst mcp                  an MCP server on stdio: read_list, changed_read_list and check_map as tools for any agent
 //   readfirst view [--out <file>]  the map as a city in one HTML page (default .readfirst/local/view.html)
 // Options: --root <dir> (default: the current git repository), --json, --limit <n>.
 import { execFileSync, spawnSync } from 'node:child_process';
@@ -19,6 +20,7 @@ import { assertMap, draftMap, fixMap, MAP_PATH, mapProblems } from './map.mjs';
 import { agentBrief } from './prompt.mjs';
 import { keepLocal, labelsBrief, LOCAL_DIR, readLabels } from './labels.mjs';
 import { viewData } from './view.mjs';
+import { mcpHandler, serveMcp } from './mcp.mjs';
 import { cityData, viewHtmlCity } from './view-city.mjs';
 import { emptyList, readList, toMarkdown } from './readlist.mjs';
 
@@ -33,6 +35,7 @@ const HELP = `readfirst — what to read and check before changing a file
   readfirst verify [--base <ref>]  run the checks for the files changed since <ref> (--dry-run lists them)
   readfirst hook [--install]     Claude Code hook: the read list before each edit (--install adds it to .claude/settings.json)
   readfirst view [--out <file>]  the map as a city in one HTML page
+  readfirst mcp                  MCP server on stdio for Cursor, Codex, Windsurf and other agents
   readfirst prompt --labels <lang>  brief for your agent to write personal labels for the view (e.g. ko, en)
 
 Options: --root <dir>, --json, --limit <n>, --timeout <s> (verify, per check; default 900), --force (init: replace the map),
@@ -107,7 +110,10 @@ function addAgentLine(root) {
 function changedFiles(root, base) {
   const ref = base ?? ['origin/main', 'main', 'origin/master', 'master'].find((r) => { try { git(root, 'rev-parse', '--verify', '--quiet', r); return true; } catch { return false; } });
   if (!ref) throw new Error('no base branch found: pass --base <ref>');
-  const since = git(root, 'merge-base', ref, 'HEAD').trim();
+  let since;
+  try { since = git(root, 'merge-base', ref, 'HEAD').trim(); } catch {
+    throw new Error(`cannot find where this branch left ${ref}, often because the clone is shallow: fetch more history (git fetch --deepen=100, or fetch-depth: 0 in actions/checkout) or pass --base <ref>`);
+  }
   const names = new Set([
     ...git(root, 'diff', '--name-only', since).split('\n'),
     ...git(root, 'ls-files', '--others', '--exclude-standard').split('\n'),
@@ -292,6 +298,16 @@ export function main(argv, io = { out: (s) => process.stdout.write(s), err: (s)
     io.out(args.json ? `${JSON.stringify(list, null, 2)}\n` : `${toMarkdown(list)}\n`);
     return 0;
   }
+  if (cmd === 'mcp') {
+    const version = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+    const run = (argv) => {
+      let out = ''; let err = ''; let code;
+      try { code = main(['--root', root, ...argv], { out: (s) => { out += s; }, err: (s) => { err += s; } }); } catch (e) { code = 2; err += e.message; }
+      return { code, out, err };
+    };
+    serveMcp({ handle: mcpHandler({ run, version }), input: process.stdin, output: process.stdout });
+    return 0;
+  }
   if (cmd === 'verify') {
     const map = loadMapLenient(root, files, io);
     const changed = changedFiles(root, args.base);

package/src/mcp.mjs

@@ -0,0 +1,77 @@
+// readfirst as an MCP server over stdio, so any agent that speaks MCP (Cursor, Codex, Windsurf, Claude Code...) can ask
+// what to read before it changes a file. JSON-RPC 2.0, one message per line, written by hand: no dependencies.
+// Every tool call runs the same code as the command line, on the checkout as it is at that moment, and writes nothing.
+const VERSIONS = ['2025-06-18', '2025-03-26', '2024-11-05'];
+
+const TOOLS = [
+  {
+    name: 'read_list',
+    description: 'What to read and check before changing these files: the project rules and risks that apply, the checks to run, the tests that reach the code and the files that use it. Call it before editing.',
+    inputSchema: { type: 'object', properties: { files: { type: 'array', items: { type: 'string' }, description: 'paths relative to the repository root' } }, required: ['files'] },
+    args: (a) => {
+      if (!Array.isArray(a.files) || !a.files.length || a.files.some((f) => typeof f !== 'string' || !f)) throw new Error('files must be a non-empty list of paths');
+      return ['read', ...a.files];
+    },
+  },
+  {
+    name: 'changed_read_list',
+    description: 'The same read list for every file changed on this branch since the base (default origin/main, else main). Call it before finishing, then run the checks it lists.',
+    inputSchema: { type: 'object', properties: { base: { type: 'string', description: 'git ref to compare against' } } },
+    args: (a) => ['diff', ...(typeof a.base === 'string' && a.base ? ['--base', a.base] : [])],
+  },
+  {
+    name: 'check_map',
+    description: 'Whether .readfirst/map.json still covers the code: files in no group, patterns that match nothing, broken rules.',
+    inputSchema: { type: 'object', properties: {} },
+    args: () => ['check'],
+  },
+];
+
+// One request in, one response out (null for notifications). run(argv) runs the CLI and returns { code, out, err }.
+export function mcpHandler({ run, version }) {
+  return (msg) => {
+    const reply = (result) => ({ jsonrpc: '2.0', id: msg.id, result });
+    const fail = (code, message) => ({ jsonrpc: '2.0', id: msg.id ?? null, error: { code, message } });
+    if (!msg || msg.jsonrpc !== '2.0' || typeof msg.method !== 'string') return fail(-32600, 'invalid request');
+    if (msg.id === undefined) return null; // notifications (initialized, cancelled) need no answer
+    if (msg.method === 'initialize') {
+      const asked = msg.params?.protocolVersion;
+      return reply({
+        protocolVersion: VERSIONS.includes(asked) ? asked : VERSIONS[0],
+        capabilities: { tools: {} },
+        serverInfo: { name: 'readfirst', version },
+        instructions: 'Before changing a file, call read_list with it and follow what it says. Before you finish, call changed_read_list and run the checks it lists (or run `npx readfirst verify`).',
+      });
+    }
+    if (msg.method === 'ping') return reply({});
+    if (msg.method === 'tools/list') return reply({ tools: TOOLS.map(({ args, ...t }) => t) });
+    if (msg.method === 'tools/call') {
+      const tool = TOOLS.find((t) => t.name === msg.params?.name);
+      if (!tool) return fail(-32602, `unknown tool ${msg.params?.name}`);
+      let r;
+      try { r = run(tool.args(msg.params?.arguments ?? {})); } catch (e) { r = { code: 2, out: '', err: e.message }; }
+      const text = [r.out.trimEnd(), r.err.trimEnd()].filter(Boolean).join('\n\n') || '(nothing)';
+      return reply({ content: [{ type: 'text', text }], isError: r.code === 2 });
+    }
+    return fail(-32601, `unknown method ${msg.method}`);
+  };
+}
+
+// Reads newline-delimited JSON-RPC from input and writes answers to output until input ends.
+export function serveMcp({ handle, input, output }) {
+  let buf = '';
+  input.setEncoding('utf8');
+  input.on('data', (chunk) => {
+    buf += chunk;
+    let nl;
+    while ((nl = buf.indexOf('\n')) >= 0) {
+      const line = buf.slice(0, nl).trim();
+      buf = buf.slice(nl + 1);
+      if (!line) continue;
+      let msg;
+      try { msg = JSON.parse(line); } catch { output.write(`${JSON.stringify({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'parse error' } })}\n`); continue; }
+      const res = handle(msg);
+      if (res) output.write(`${JSON.stringify(res)}\n`);
+    }
+  });
+}