whywhy-mcp 0.1.0

package/dist/git.js

@@ -0,0 +1,121 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { simpleGit } from "simple-git";
+/**
+ * Captures git evidence (branch, commits, working diff) for a decision.
+ *
+ * Everything here is best-effort: a repo with no git, no commits, or no
+ * changes still produces a valid (mostly-null) DiffEvidence rather than
+ * throwing, so recording a decision never fails because of git state.
+ */
+export async function captureGitEvidence(repoRoot) {
+    const git = simpleGit(repoRoot);
+    let isRepo = false;
+    try {
+        isRepo = await git.checkIsRepo();
+    }
+    catch {
+        isRepo = false;
+    }
+    if (!isRepo)
+        return null;
+    const evidence = {
+        branch: null,
+        base_commit: null,
+        head_commit: null,
+        files_changed: [],
+        summary: "",
+    };
+    try {
+        evidence.branch = (await git.revparse(["--abbrev-ref", "HEAD"])).trim() || null;
+    }
+    catch {
+        /* detached or no branch */
+    }
+    try {
+        evidence.head_commit = (await git.revparse(["HEAD"])).trim().slice(0, 40) || null;
+    }
+    catch {
+        /* no commits yet */
+    }
+    // base_commit = parent of HEAD when available; otherwise HEAD itself.
+    try {
+        evidence.base_commit = (await git.revparse(["HEAD~1"])).trim().slice(0, 40) || null;
+    }
+    catch {
+        evidence.base_commit = evidence.head_commit;
+    }
+    try {
+        const status = await git.status();
+        const changed = new Set([
+            ...status.modified,
+            ...status.created,
+            ...status.deleted,
+            ...status.renamed.map((r) => r.to),
+            ...status.not_added,
+            ...status.staged,
+        ]);
+        evidence.files_changed = [...changed].sort();
+    }
+    catch {
+        /* ignore */
+    }
+    try {
+        const stat = await git.raw(["diff", "--stat"]);
+        const stagedStat = await git.raw(["diff", "--stat", "--cached"]);
+        const combined = [stat.trim(), stagedStat.trim()].filter(Boolean).join("\n");
+        evidence.summary = combined
+            ? truncate(combined, 4000)
+            : "No uncommitted changes in the working tree at capture time.";
+    }
+    catch {
+        evidence.summary = "Diff summary unavailable.";
+    }
+    return evidence;
+}
+function truncate(s, max) {
+    return s.length > max ? s.slice(0, max) + "\n...(truncated)" : s;
+}
+/** Matches common single-line comment markers across languages. */
+const COMMENT_PATTERNS = [
+    /\/\/\s?(.*)$/, // // ...
+    /#\s?(.*)$/, // # ...
+    /--\s?(.*)$/, // -- ... (SQL)
+    /\/\*\s?(.*?)\s?\*\//, // /* ... */ on one line
+    /<!--\s?(.*?)\s?-->/, // <!-- ... -->
+];
+/**
+ * Scans the given files for code comments, returning a small sample so a
+ * decision record can point at the in-code rationale without bloating.
+ */
+export async function scanCodeComments(repoRoot, files, maxPerFile = 5) {
+    const results = [];
+    for (const rel of files) {
+        const abs = path.resolve(repoRoot, rel);
+        let content;
+        try {
+            const stat = await fs.stat(abs);
+            if (!stat.isFile() || stat.size > 512 * 1024)
+                continue; // skip huge/binary-ish
+            content = await fs.readFile(abs, "utf8");
+        }
+        catch {
+            continue;
+        }
+        const lines = content.split(/\r?\n/);
+        let found = 0;
+        for (let i = 0; i < lines.length && found < maxPerFile; i++) {
+            const line = lines[i];
+            for (const pattern of COMMENT_PATTERNS) {
+                const m = line.match(pattern);
+                if (m && m[1] && m[1].trim().length > 0) {
+                    results.push({ file: rel, line: i + 1, text: m[1].trim().slice(0, 300) });
+                    found++;
+                    break;
+                }
+            }
+        }
+    }
+    return results;
+}
+//# sourceMappingURL=git.js.map

package/dist/git.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git.js","sourceRoot":"","sources":["../src/git.ts"],"names":[],"mappings":"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"}

package/dist/guidance.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The agent-guidance snippet. This is the agent-agnostic glue: it tells any
+ * MCP-capable coding agent WHEN to call the whywhy tools. `init` appends it to
+ * CLAUDE.md (and prints it for pasting into Cursor rules, etc.).
+ */
+export declare const GUIDANCE_SNIPPET = "<!-- whywhy:begin -->\n## Decision logging (whywhy)\n\nThis repo uses **whywhy** to record *why* decisions are made. Whenever you and\nthe user reach a meaningful decision, call the whywhy MCP tools so the reasoning\nis preserved alongside the code.\n\n**Log a decision when you settle any of:**\n- Architecture or system design (boundaries, patterns, data flow)\n- Infrastructure or deployment (databases, hosting, queues, CI)\n- A dependency / library choice (and what you rejected)\n- An API shape or contract\n- A data-model / schema decision\n- A UI / UX direction with real trade-offs\n- A product or scope decision\n- Security, performance, or process choices\n\n**Do NOT log:** trivial edits, formatting, renames, obvious one-way-door\nfixes, or anything with no meaningful alternative.\n\n**How:**\n- When a decision is reached, call `record_decision` *before moving on*.\n  Include the alternatives you weighed and why you rejected them, and pass the\n  relevant `files` so whywhy can capture the diff and code comments.\n- If you are reversing a past decision, call `supersede_decision` with the old\n  decision's id instead of recording a fresh, disconnected one.\n- To fix or extend an existing record, use `update_decision`.\n- To retire a decision with no replacement, use `deprecate_decision`.\n- When the user asks \"why did we \u2026?\", call `query_decisions` and answer from\n  the returned records.\n\nIf you prefer not to interrupt flow, batch decisions and record them at the end\nof the session -- but never lose them.\n<!-- whywhy:end -->\n";
+export declare const GUIDANCE_BEGIN = "<!-- whywhy:begin -->";
+export declare const GUIDANCE_END = "<!-- whywhy:end -->";

package/dist/guidance.js

@@ -0,0 +1,43 @@
+/**
+ * The agent-guidance snippet. This is the agent-agnostic glue: it tells any
+ * MCP-capable coding agent WHEN to call the whywhy tools. `init` appends it to
+ * CLAUDE.md (and prints it for pasting into Cursor rules, etc.).
+ */
+export const GUIDANCE_SNIPPET = `<!-- whywhy:begin -->
+## Decision logging (whywhy)
+
+This repo uses **whywhy** to record *why* decisions are made. Whenever you and
+the user reach a meaningful decision, call the whywhy MCP tools so the reasoning
+is preserved alongside the code.
+
+**Log a decision when you settle any of:**
+- Architecture or system design (boundaries, patterns, data flow)
+- Infrastructure or deployment (databases, hosting, queues, CI)
+- A dependency / library choice (and what you rejected)
+- An API shape or contract
+- A data-model / schema decision
+- A UI / UX direction with real trade-offs
+- A product or scope decision
+- Security, performance, or process choices
+
+**Do NOT log:** trivial edits, formatting, renames, obvious one-way-door
+fixes, or anything with no meaningful alternative.
+
+**How:**
+- When a decision is reached, call \`record_decision\` *before moving on*.
+  Include the alternatives you weighed and why you rejected them, and pass the
+  relevant \`files\` so whywhy can capture the diff and code comments.
+- If you are reversing a past decision, call \`supersede_decision\` with the old
+  decision's id instead of recording a fresh, disconnected one.
+- To fix or extend an existing record, use \`update_decision\`.
+- To retire a decision with no replacement, use \`deprecate_decision\`.
+- When the user asks "why did we …?", call \`query_decisions\` and answer from
+  the returned records.
+
+If you prefer not to interrupt flow, batch decisions and record them at the end
+of the session -- but never lose them.
+<!-- whywhy:end -->
+`;
+export const GUIDANCE_BEGIN = "<!-- whywhy:begin -->";
+export const GUIDANCE_END = "<!-- whywhy:end -->";
+//# sourceMappingURL=guidance.js.map

package/dist/guidance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guidance.js","sourceRoot":"","sources":["../src/guidance.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkC/B,CAAC;AAEF,MAAM,CAAC,MAAM,cAAc,GAAG,uBAAuB,CAAC;AACtD,MAAM,CAAC,MAAM,YAAY,GAAG,qBAAqB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { CategorySchema, StatusSchema, AlternativeSchema, } from "./schema.js";
+import { DecisionStore } from "./store.js";
+import { createDecision, deprecateDecision, listDecisions, queryDecisions, supersedeDecision, updateDecision, } from "./decisions.js";
+/**
+ * whywhy MCP server (stdio).
+ *
+ * Exposes the decision-capture/query tools described in the PRD. The repo root
+ * defaults to the process working directory (where the agent launches the
+ * server) and can be overridden with WHYWHY_ROOT.
+ */
+const REPO_ROOT = process.env.WHYWHY_ROOT || process.cwd();
+/** Lazily ensure the store exists and return it with the resolved config. */
+async function getContext() {
+    // Resolve store path from an existing config if present.
+    let store = new DecisionStore(REPO_ROOT);
+    let config;
+    try {
+        config = await store.readConfig();
+        store = new DecisionStore(REPO_ROOT, config.store_path);
+    }
+    catch {
+        config = await store.init();
+    }
+    await store.init(config);
+    return { store, config };
+}
+function ok(text, data) {
+    const body = data !== undefined ? `${text}\n\n${JSON.stringify(data, null, 2)}` : text;
+    return { content: [{ type: "text", text: body }] };
+}
+function fail(text) {
+    return { isError: true, content: [{ type: "text", text }] };
+}
+const server = new McpServer({
+    name: "whywhy",
+    version: "0.1.0",
+});
+/* ---- record_decision ------------------------------------------------ */
+server.tool("record_decision", "Log a new architectural/product/development decision with its reasoning. " +
+    "Automatically captures the current git diff and any related code comments as evidence. " +
+    "Call this whenever you and the user settle a meaningful decision.", {
+    title: z.string().min(1),
+    category: CategorySchema,
+    decision: z.string().min(1),
+    rationale: z.string().min(1),
+    alternatives_considered: z.array(AlternativeSchema).optional(),
+    consequences: z.string().optional(),
+    tags: z.array(z.string()).optional(),
+    conversation_summary: z.string().optional(),
+    conversation_excerpt: z.string().optional(),
+    files: z.array(z.string()).optional(),
+    session_id: z.string().optional(),
+}, async (input) => {
+    const { store, config } = await getContext();
+    const record = await createDecision(store, config, input);
+    return ok(`Recorded decision ${record.id}: "${record.title}" (status: active).`, record);
+});
+/* ---- supersede_decision --------------------------------------------- */
+server.tool("supersede_decision", "Replace an existing decision with a new one. Creates a fresh record, links " +
+    "the two, and flips the old decision's status to 'superseded'. Use this when " +
+    "reversing or changing a previously recorded decision instead of recording a new disconnected one.", {
+    old_id: z.string().describe("The id of the decision being replaced, e.g. DR-0003."),
+    title: z.string().min(1),
+    category: CategorySchema,
+    decision: z.string().min(1),
+    rationale: z.string().min(1),
+    alternatives_considered: z.array(AlternativeSchema).optional(),
+    consequences: z.string().optional(),
+    tags: z.array(z.string()).optional(),
+    conversation_summary: z.string().optional(),
+    conversation_excerpt: z.string().optional(),
+    files: z.array(z.string()).optional(),
+    session_id: z.string().optional(),
+}, async (input) => {
+    const { store, config } = await getContext();
+    const { old_id, ...rest } = input;
+    const existing = await store.tryReadRecord(old_id);
+    if (!existing)
+        return fail(`No decision found with id ${old_id}.`);
+    const { newRecord, oldRecord } = await supersedeDecision(store, config, old_id, rest);
+    return ok(`Created ${newRecord.id} superseding ${oldRecord.id}. ${oldRecord.id} is now 'superseded'.`, { new: newRecord, superseded: oldRecord });
+});
+/* ---- update_decision ------------------------------------------------ */
+server.tool("update_decision", "Edit an existing decision record in place (fix a typo, add a consequence, " +
+    "refine the rationale). Bumps the record's version. Does NOT change identity " +
+    "or status; use supersede_decision to replace a decision.", {
+    id: z.string(),
+    title: z.string().optional(),
+    category: CategorySchema.optional(),
+    decision: z.string().optional(),
+    rationale: z.string().optional(),
+    alternatives_considered: z.array(AlternativeSchema).optional(),
+    consequences: z.string().optional(),
+    tags: z.array(z.string()).optional(),
+    conversation_summary: z.string().optional(),
+}, async (input) => {
+    const { store } = await getContext();
+    const { id, ...edits } = input;
+    const existing = await store.tryReadRecord(id);
+    if (!existing)
+        return fail(`No decision found with id ${id}.`);
+    const record = await updateDecision(store, id, edits);
+    return ok(`Updated ${record.id} (now version ${record.version}).`, record);
+});
+/* ---- deprecate_decision --------------------------------------------- */
+server.tool("deprecate_decision", "Retire a decision that no longer applies and has no direct replacement " +
+    "(e.g. a removed feature). Sets status to 'deprecated'. The record is kept.", {
+    id: z.string(),
+    reason: z.string().optional(),
+}, async ({ id, reason }) => {
+    const { store } = await getContext();
+    const existing = await store.tryReadRecord(id);
+    if (!existing)
+        return fail(`No decision found with id ${id}.`);
+    const record = await deprecateDecision(store, id, reason);
+    return ok(`Deprecated ${record.id}.`, record);
+});
+/* ---- query_decisions ------------------------------------------------ */
+server.tool("query_decisions", "Search recorded decisions to answer 'why did we …?' questions. Combine a " +
+    "free-text query with optional category/status/tag filters. Returns matching " +
+    "full records (ranked by keyword relevance) for you to reason over.", {
+    query: z.string().optional(),
+    category: CategorySchema.optional(),
+    status: StatusSchema.optional(),
+    tags: z.array(z.string()).optional(),
+}, async (filter) => {
+    const { store } = await getContext();
+    const results = await queryDecisions(store, filter);
+    if (results.length === 0)
+        return ok("No matching decisions found.", []);
+    return ok(`Found ${results.length} matching decision(s).`, results);
+});
+/* ---- get_decision --------------------------------------------------- */
+server.tool("get_decision", "Fetch one decision record in full by its id.", { id: z.string() }, async ({ id }) => {
+    const { store } = await getContext();
+    const record = await store.tryReadRecord(id);
+    if (!record)
+        return fail(`No decision found with id ${id}.`);
+    return ok(`Decision ${record.id}:`, record);
+});
+/* ---- list_decisions ------------------------------------------------- */
+server.tool("list_decisions", "List/browse decisions from the index (lightweight entries, not full records). " +
+    "Optionally filter by status or category.", {
+    status: StatusSchema.optional(),
+    category: CategorySchema.optional(),
+}, async (filter) => {
+    const { store } = await getContext();
+    const entries = await listDecisions(store, filter);
+    return ok(`${entries.length} decision(s).`, entries);
+});
+/* ---- resources ------------------------------------------------------ */
+server.resource("whywhy-index", "whywhy://index", async () => {
+    const { store } = await getContext();
+    const index = await store.readIndex();
+    return {
+        contents: [
+            {
+                uri: "whywhy://index",
+                mimeType: "application/json",
+                text: JSON.stringify(index, null, 2),
+            },
+        ],
+    };
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Stderr is safe for logs; stdout is the MCP channel.
+    console.error(`whywhy MCP server running (root: ${REPO_ROOT})`);
+}
+main().catch((err) => {
+    console.error("whywhy fatal error:", err);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}