changebook 0.2.0

package/dist/tools.js

@@ -0,0 +1,338 @@
+/**
+ * Tool registrations for the ChangeBook MCP server.
+ *
+ * All tools are read-only queries over the user's own ChangeBook data
+ * (Row Level Security scopes every request to the signed-in user).
+ */
+import { z } from "zod";
+import { SupabaseError } from "./supabase.js";
+const CHARACTER_LIMIT = 25_000;
+// ── Helpers ───────────────────────────────────────────────────────────────────
+function errorResult(error) {
+    const message = error instanceof SupabaseError || error instanceof Error
+        ? error.message
+        : String(error);
+    // isError lets the MCP client (and the agent) tell a failed call from a valid
+    // result whose text happens to start with "Error:".
+    return {
+        isError: true,
+        content: [{ type: "text", text: `Error: ${message}` }],
+    };
+}
+function truncate(text) {
+    if (text.length <= CHARACTER_LIMIT)
+        return text;
+    return (text.slice(0, CHARACTER_LIMIT) +
+        "\n\n[Truncated. Use a smaller `limit`, an `offset`, or filters to narrow the result.]");
+}
+// Build a tool result. structuredContent duplicates the rendered text, so when
+// the text has to be truncated we drop it — otherwise the full, unbounded object
+// would be sent anyway and defeat the very CHARACTER_LIMIT that truncated it.
+function toolResult(text, structured) {
+    if (text.length <= CHARACTER_LIMIT) {
+        return {
+            content: [{ type: "text", text }],
+            structuredContent: structured,
+        };
+    }
+    return { content: [{ type: "text", text: truncate(text) }] };
+}
+function fileList(files) {
+    return Array.isArray(files) ? files.map(String) : [];
+}
+// Summary-first excerpts: the stored diff excerpts are the most expensive part
+// of atlas_module_detail (~1.5k chars each), and most calls only need to know
+// WHAT changed. Default to a short preview; `full: true` returns them verbatim.
+const EXCERPT_PREVIEW_LINES = 4;
+const EXCERPT_PREVIEW_CHARS = 320;
+function previewExcerpt(excerpt) {
+    let text = excerpt.split("\n").slice(0, EXCERPT_PREVIEW_LINES).join("\n");
+    if (text.length > EXCERPT_PREVIEW_CHARS) {
+        text = text.slice(0, EXCERPT_PREVIEW_CHARS);
+    }
+    return { text: text.trimEnd(), truncated: text.length < excerpt.length };
+}
+function day(iso) {
+    return iso.slice(0, 10);
+}
+/** PostgREST `or=(...ilike...)` needs the pattern URL-encoded once. */
+function ilikePattern(search) {
+    return encodeURIComponent(`*${search.replace(/[%*,()]/g, " ").trim()}*`);
+}
+// ── Registration ──────────────────────────────────────────────────────────────
+export function registerTools(server, db) {
+    server.registerTool("atlas_recent_changes", {
+        title: "Recent ChangeBook changes",
+        description: `List the most recent analyzed code changes from the ChangeBook changelog (newest first).
+
+Each entry has a business-level impact summary, an optional technical summary, and the modules it touched. Use this to catch up on what changed in the product without re-reading the codebase.
+
+Args:
+  - limit (1-50, default 10): entries to return.
+  - offset (default 0): pagination offset.
+  - search (optional): case-insensitive text filter over the business and technical summaries.
+
+Returns (structured): { count, offset, has_more, changes: [{ id, date, business_impact, summary_tech, diff_chars, modules: [{ module, risk }] }] }
+
+Don't use for per-module deep dives — use atlas_module_detail for that.`,
+        inputSchema: {
+            limit: z.number().int().min(1).max(50).default(10)
+                .describe("Entries to return (1-50)"),
+            offset: z.number().int().min(0).default(0)
+                .describe("Pagination offset"),
+            search: z.string().min(2).max(120).optional()
+                .describe("Case-insensitive filter over summaries"),
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ limit, offset, search }) => {
+        try {
+            let query = `changelog?select=id,business_impact,summary_tech,created_at,diff_character_count` +
+                `&order=created_at.desc&limit=${limit}&offset=${offset}` +
+                (await db.projectFilter());
+            if (search) {
+                const p = ilikePattern(search);
+                query += `&or=(business_impact.ilike.${p},summary_tech.ilike.${p})`;
+            }
+            const rows = await db.rest(query);
+            const modulesByChange = new Map();
+            if (rows.length > 0) {
+                const ids = rows.map((r) => r.id).join(",");
+                const mods = await db.rest(
+                // Only the module name and risk are used below; don't pull note/tech/
+                // excerpt/files (up to ~1.5k each) for every row of every change.
+                `change_module?select=changelog_id,module,risk&changelog_id=in.(${ids})`);
+                for (const m of mods) {
+                    const list = modulesByChange.get(m.changelog_id);
+                    if (list)
+                        list.push(m);
+                    else
+                        modulesByChange.set(m.changelog_id, [m]);
+                }
+            }
+            const changes = rows.map((r) => ({
+                id: r.id,
+                date: day(r.created_at),
+                business_impact: r.business_impact ?? "",
+                summary_tech: r.summary_tech ?? null,
+                diff_chars: r.diff_character_count ?? null,
+                modules: (modulesByChange.get(r.id) ?? []).map((m) => ({
+                    module: m.module,
+                    risk: m.risk,
+                })),
+            }));
+            const output = {
+                count: changes.length,
+                offset,
+                has_more: rows.length === limit,
+                changes,
+            };
+            const lines = [`# Recent ChangeBook changes (${changes.length})`, ""];
+            for (const c of changes) {
+                const mods = c.modules
+                    .map((m) => m.module + (m.risk ? ` [${m.risk}]` : ""))
+                    .join(", ");
+                lines.push(`## ${c.date} — ${c.business_impact}`);
+                if (c.summary_tech)
+                    lines.push(`- Tech: ${c.summary_tech}`);
+                if (mods)
+                    lines.push(`- Modules: ${mods}`);
+                lines.push("");
+            }
+            if (changes.length === 0) {
+                lines.push(search
+                    ? `No changes match "${search}". Try a broader search or omit it.`
+                    : "No analyzed changes yet. Analyze a diff from the ChangeBook extension first.");
+            }
+            return toolResult(lines.join("\n"), output);
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+    server.registerTool("atlas_modules", {
+        title: "ChangeBook module map",
+        description: `List the modules of the product as known by ChangeBook, aggregated from the change history.
+
+For each module: domain, category, latest risk level, number of analyzed changes, last-change date and the files touched most recently. Use this to orient yourself in an unfamiliar codebase or to pick a module for atlas_module_detail.
+
+Args:
+  - domain (optional): filter by domain (e.g. "billing").
+
+Returns (structured): { count, modules: [{ module, domain, category, risk, changes, last_changed, files }] }`,
+        inputSchema: {
+            domain: z.string().min(1).max(80).optional()
+                .describe("Only modules in this domain"),
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ domain }) => {
+        try {
+            let query = 
+            // The aggregation below uses only these columns; note/tech/excerpt
+            // (up to ~1.5k each × 1000 rows) would move 1-2 MB per call for nothing.
+            `change_module?select=module,domain,category,risk,files,created_at` +
+                `&order=created_at.desc&limit=1000` +
+                (await db.projectFilter());
+            if (domain)
+                query += `&domain=eq.${encodeURIComponent(domain)}`;
+            const rows = await db.rest(query);
+            const byModule = new Map();
+            for (const row of rows) {
+                const list = byModule.get(row.module);
+                if (list)
+                    list.push(row);
+                else
+                    byModule.set(row.module, [row]);
+            }
+            const modules = [...byModule.entries()].map(([name, list]) => {
+                const latest = list[0]; // rows arrive newest-first
+                return {
+                    module: name,
+                    domain: latest.domain,
+                    category: latest.category,
+                    risk: latest.risk,
+                    changes: list.length,
+                    last_changed: day(latest.created_at),
+                    files: fileList(latest.files),
+                };
+            });
+            modules.sort((a, b) => (a.last_changed < b.last_changed ? 1 : -1));
+            const output = { count: modules.length, modules };
+            const lines = [`# ChangeBook module map (${modules.length} modules)`, ""];
+            for (const m of modules) {
+                lines.push(`- **${m.module}**${m.domain ? ` (${m.domain})` : ""} — ` +
+                    `${m.changes} change(s), last ${m.last_changed}` +
+                    (m.risk ? `, risk: ${m.risk}` : "") +
+                    (m.files.length ? ` — files: ${m.files.join(", ")}` : ""));
+            }
+            if (modules.length === 0) {
+                lines.push(domain
+                    ? `No modules in domain "${domain}". Call atlas_modules without a domain to see all.`
+                    : "No modules yet. Analyze a diff from the ChangeBook extension first.");
+            }
+            return toolResult(lines.join("\n"), output);
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+    server.registerTool("atlas_module_detail", {
+        title: "ChangeBook module detail",
+        description: `Get the change history of one module: what changed, why it matters, the files touched and (when available) a verbatim excerpt of each diff.
+
+This is the token-saving alternative to re-reading a module's source: it gives an agent the recent evolution and risk picture in one call.
+
+Args:
+  - module (required): exact module name as returned by atlas_modules.
+  - limit (1-20, default 5): number of recent changes to include.
+  - include_excerpts (default true): include diff excerpts (short previews unless full is set).
+  - full (default false): return the diff excerpts verbatim instead of the token-saving previews. Only pass it when you actually need the code lines.
+
+Returns (structured): { module, count, changes: [{ date, risk, note, tech, files, business_impact, excerpt, excerpt_truncated }] }`,
+        inputSchema: {
+            module: z.string().min(1).max(120)
+                .describe("Exact module name (see atlas_modules)"),
+            limit: z.number().int().min(1).max(20).default(5)
+                .describe("Recent changes to include (1-20)"),
+            include_excerpts: z.boolean().default(true)
+                .describe("Include diff excerpts (previews unless full)"),
+            full: z.boolean().default(false)
+                .describe("Verbatim excerpts instead of short previews"),
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ module, limit, include_excerpts, full }) => {
+        try {
+            const rows = await db.rest(`change_module?select=changelog_id,module,domain,category,risk,files,note,tech,excerpt,created_at` +
+                `&module=eq.${encodeURIComponent(module)}&order=created_at.desc&limit=${limit}` +
+                (await db.projectFilter()));
+            if (rows.length === 0) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `No module named "${module}". Call atlas_modules to list the exact module names.`,
+                        },
+                    ],
+                };
+            }
+            const ids = [...new Set(rows.map((r) => r.changelog_id))].join(",");
+            const logs = await db.rest(`changelog?select=id,business_impact,summary_tech,created_at,diff_character_count&id=in.(${ids})`);
+            const logById = new Map(logs.map((l) => [l.id, l]));
+            const changes = rows.map((r) => {
+                let excerpt = null;
+                let excerptTruncated = false;
+                if (include_excerpts && r.excerpt) {
+                    if (full) {
+                        excerpt = r.excerpt;
+                    }
+                    else {
+                        const preview = previewExcerpt(r.excerpt);
+                        excerpt = preview.text;
+                        excerptTruncated = preview.truncated;
+                    }
+                }
+                return {
+                    date: day(r.created_at),
+                    risk: r.risk,
+                    note: r.note,
+                    tech: r.tech,
+                    files: fileList(r.files),
+                    business_impact: logById.get(r.changelog_id)?.business_impact ?? null,
+                    excerpt,
+                    excerpt_truncated: excerptTruncated,
+                };
+            });
+            const latest = rows[0];
+            const output = {
+                module,
+                domain: latest.domain,
+                category: latest.category,
+                count: changes.length,
+                changes,
+            };
+            const lines = [
+                `# Module: ${module}` +
+                    (latest.domain ? ` (${latest.domain}` +
+                        (latest.category ? ` / ${latest.category}` : "") + ")" : ""),
+                "",
+            ];
+            for (const c of changes) {
+                lines.push(`## ${c.date}${c.risk ? ` — risk: ${c.risk}` : ""}`);
+                if (c.business_impact)
+                    lines.push(`- Impact: ${c.business_impact}`);
+                if (c.note)
+                    lines.push(`- Note: ${c.note}`);
+                if (c.tech)
+                    lines.push(`- Tech: ${c.tech}`);
+                if (c.files.length)
+                    lines.push(`- Files: ${c.files.join(", ")}`);
+                if (c.excerpt) {
+                    lines.push("", "```diff", c.excerpt, "```");
+                    if (c.excerpt_truncated) {
+                        lines.push("_Excerpt preview — call again with `full: true` for the verbatim diff._");
+                    }
+                }
+                lines.push("");
+            }
+            return toolResult(lines.join("\n"), output);
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+}
+//# sourceMappingURL=tools.js.map

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "changebook",
+  "version": "0.2.0",
+  "description": "ChangeBook for coding agents: MCP server (product memory for Claude Code/Codex) + CLI to sign in, analyze changes and sync the product map.",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "changebook": "dist/index.js",
+    "changebook-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map",
+    "README.md"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/raulbr90/appatlas.git",
+    "directory": "changebook-mcp"
+  },
+  "homepage": "https://changebook.dev",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "claude-code",
+    "changelog",
+    "product-map",
+    "ai",
+    "cli"
+  ],
+  "scripts": {
+    "start": "node dist/index.js",
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.6.1",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.2"
+  }
+}