whywhy-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Micky Multani
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,213 @@
+# whywhy
+
+**Record _why_ decisions are made during AI-assisted coding.**
+
+`whywhy` is an agent-agnostic [MCP](https://modelcontextprotocol.io) server. When
+you and a coding agent (Claude Code, Cursor, Copilot-via-MCP, …) settle a
+meaningful decision — a library choice, a schema, an API shape, an infra call —
+the agent records it through whywhy. Each decision is stored as a clean,
+versioned JSON record that lives in your repo, correlated with the conversation
+reasoning, the git diff, and any related code comments — **without cluttering
+your source files**.
+
+Months later you (or a new teammate) can ask _"why did we pick Postgres?"_ and
+get the real answer, including the alternatives that were rejected.
+
+---
+
+## Why
+
+The reasoning behind decisions usually leaks into three lossy places: inline
+comments (clutter, decay), commit messages (terse, disconnected), and the agent
+chat transcript (ephemeral, unsearchable). whywhy captures decisions as
+first-class, structured, versioned artifacts instead.
+
+## Install & set up
+
+Requires Node ≥ 18.
+
+```bash
+# In your project root:
+npx -y whywhy-mcp init
+```
+
+`init` creates a `.whywhy/` store and appends an agent-guidance block to
+`CLAUDE.md` (telling the agent when to log decisions).
+
+Then register the server with your agent.
+
+### Claude Code (project scope, so the team shares it)
+
+```bash
+claude mcp add --scope project --transport stdio whywhy -- npx -y whywhy-mcp
+```
+
+`--scope project` writes to `.mcp.json` at the repo root — commit it so
+teammates inherit the server. Verify with `claude mcp list` or `/mcp` in a
+session.
+
+### Other MCP agents (Cursor, etc.)
+
+```json
+{
+  "mcpServers": {
+    "whywhy": { "command": "npx", "args": ["-y", "whywhy-mcp"] }
+  }
+}
+```
+
+Paste the guidance block (`npx whywhy-mcp guidance`) into that agent's rules file.
+
+## How it works
+
+An MCP server can't passively eavesdrop on your conversation — the agent decides
+when to call tools. So whywhy exposes **tools the agent is instructed to call**
+when a decision is reached (via the guidance snippet `init` installs), and the
+server gathers the diff/comment evidence automatically at that moment.
+
+```
+Agent reaches a decision ──▶ calls record_decision(...)
+                                      │
+                                      ▼
+                          whywhy MCP server
+                          • captures branch/HEAD/working diff
+                          • scans referenced files for comments
+                          • assigns DR-id, status=active
+                          • writes .whywhy/decisions/DR-XXXX.json
+                          • updates index.json
+```
+
+## MCP tools
+
+| Tool | Purpose |
+|---|---|
+| `record_decision` | Log a new decision; auto-captures git diff + code comments. |
+| `supersede_decision` | Replace a decision; links both, flips the old to `superseded`. |
+| `update_decision` | Edit a record in place; bumps its `version`. |
+| `deprecate_decision` | Retire a decision with no replacement (`deprecated`). |
+| `query_decisions` | Keyword + filter search; powers "why did we…?". |
+| `get_decision` | Fetch one full record by id. |
+| `list_decisions` | Browse lightweight index entries. |
+
+A `whywhy://index` MCP **resource** also exposes `index.json` directly.
+
+## Storage layout
+
+```
+<repo-root>/
+└── .whywhy/
+    ├── config.json        # categories, store path, capture mode, privacy toggles
+    ├── index.json         # rolled-up list for fast lookup
+    └── decisions/
+        ├── DR-0001.json
+        └── DR-0002.json
+```
+
+Everything is plain JSON, committed to git, and reviewable in PRs. **Records are
+never deleted** — the history is the value.
+
+### A decision record
+
+```jsonc
+{
+  "id": "DR-0007",
+  "schema_version": 1,
+  "title": "Use PostgreSQL for primary datastore",
+  "category": "infrastructure",        // architecture | infrastructure | dependency |
+                                       // api | data-model | ui | product | security |
+                                       // performance | process | other
+  "status": "active",                  // active | superseded | deprecated
+  "decision": "Adopt PostgreSQL 16 …",
+  "rationale": "Need strong relational integrity …",
+  "alternatives_considered": [
+    { "option": "MongoDB", "reason_rejected": "Weaker multi-doc transactions." }
+  ],
+  "consequences": "Adds an ops dependency; requires connection pooling.",
+  "tags": ["database", "backend"],
+  "evidence": {
+    "conversation": { "summary": "…", "excerpt": "…" },
+    "diff": { "branch": "main", "base_commit": "…", "head_commit": "…",
+              "files_changed": ["prisma/schema.prisma"], "summary": "…" },
+    "code_comments": [{ "file": "prisma/schema.prisma", "line": 3, "text": "…" }]
+  },
+  "version": 1,
+  "supersedes": null,
+  "superseded_by": null,
+  "created_at": "2026-06-08T17:22:31Z",
+  "updated_at": "2026-06-08T17:22:31Z",
+  "created_by": "claude-code",
+  "session_id": "sess_8c2f"
+}
+```
+
+## Versioning & status
+
+- **Record edits** (`update_decision`) bump the `version` field — same identity.
+- **Supersession** (`supersede_decision`) creates a _new_ record, flips the old
+  one to `superseded`, and cross-links them (`supersedes` / `superseded_by`).
+- **Deprecation** (`deprecate_decision`) retires a decision with no replacement.
+
+```
+record_decision ─▶ active ──supersede──▶ superseded
+                      │
+                      └────deprecate────▶ deprecated
+```
+
+## Configuration (`.whywhy/config.json`)
+
+| Key | Default | Meaning |
+|---|---|---|
+| `store_path` | `.whywhy` | Where records live. |
+| `categories` | (the 11 above) | Allowed categories. |
+| `capture_mode` | `inline` | `inline` or `session-summary`. |
+| `store_excerpts` | `false` | If true, verbatim conversation excerpts are stored. |
+| `capture_git` | `true` | If false, skips git diff capture. |
+
+## CLI
+
+```bash
+whywhy-mcp [serve]        # start the stdio MCP server (default)
+whywhy-mcp init           # create .whywhy/ + add guidance to CLAUDE.md
+whywhy-mcp guidance       # print the agent-guidance snippet
+whywhy-mcp rebuild-index  # rebuild index.json from the decision files
+```
+
+## Development
+
+```bash
+npm install
+npm run build      # compile to dist/
+npm run server     # run the server from source (tsx)
+node scripts/smoke.mjs   # end-to-end stdio smoke test
+```
+
+## Releasing (maintainers)
+
+Publishing is automated via GitHub Actions ([.github/workflows/publish.yml](.github/workflows/publish.yml)).
+
+**One-time setup:** create an npm **Automation** token (npmjs.com → Access
+Tokens), then add it as a repo secret named `NPM_TOKEN`
+(GitHub repo → Settings → Secrets and variables → Actions).
+
+**To cut a release:**
+
+```bash
+npm version patch        # or minor / major — bumps package.json + creates a git tag
+git push --follow-tags
+```
+
+Then publish a GitHub Release for that tag (`gh release create vX.Y.Z --generate-notes`).
+The workflow builds, verifies the tag matches `package.json`, and runs
+`npm publish --provenance`.
+
+Prefer to publish manually instead? `npm login && npm publish` works too
+(`prepublishOnly` builds first).
+
+## Status
+
+v0.1 (MVP). Deferred: VS Code extension, HTTP transport, semantic search,
+multi-repo aggregation, Claude Code auto-flush hooks. See `whywhy-PRD.md`.
+
+## License
+
+MIT

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { DecisionStore } from "./store.js";
+import { GUIDANCE_SNIPPET, GUIDANCE_BEGIN, GUIDANCE_END } from "./guidance.js";
+/**
+ * whywhy CLI.
+ *
+ * With no args (or `serve`), it launches the stdio MCP server -- this is what
+ * `npx -y whywhy-mcp` does when an agent spawns it. `init` sets up the store
+ * and writes the agent-guidance snippet.
+ */
+async function runServer() {
+    await import("./index.js");
+}
+async function init(repoRoot) {
+    const store = new DecisionStore(repoRoot);
+    const config = await store.init();
+    console.log(`Initialized whywhy store at ${path.relative(repoRoot, store.storeDir) || "."}/`);
+    console.log(`  - config.json`);
+    console.log(`  - index.json`);
+    console.log(`  - decisions/`);
+    await appendGuidance(repoRoot, "CLAUDE.md");
+    console.log("");
+    console.log("Next steps:");
+    console.log("  1. Register the MCP server with your agent. For Claude Code:");
+    console.log("       claude mcp add --scope project --transport stdio whywhy -- npx -y whywhy-mcp");
+    console.log("  2. Commit the .whywhy/ folder and .mcp.json so your team inherits it.");
+    console.log("");
+    void config;
+}
+/** Append the guidance snippet to a rules file, replacing any prior block. */
+async function appendGuidance(repoRoot, fileName) {
+    const target = path.resolve(repoRoot, fileName);
+    let existing = "";
+    try {
+        existing = await fs.readFile(target, "utf8");
+    }
+    catch {
+        existing = "";
+    }
+    let next;
+    if (existing.includes(GUIDANCE_BEGIN) && existing.includes(GUIDANCE_END)) {
+        // Replace the existing whywhy block in place.
+        const before = existing.slice(0, existing.indexOf(GUIDANCE_BEGIN));
+        const after = existing.slice(existing.indexOf(GUIDANCE_END) + GUIDANCE_END.length);
+        next = `${before}${GUIDANCE_SNIPPET.trim()}${after}`;
+        console.log(`Updated whywhy guidance block in ${fileName}.`);
+    }
+    else {
+        const sep = existing && !existing.endsWith("\n") ? "\n\n" : existing ? "\n" : "";
+        next = `${existing}${sep}${GUIDANCE_SNIPPET}`;
+        console.log(`Appended whywhy guidance to ${fileName}.`);
+    }
+    await fs.writeFile(target, next, "utf8");
+}
+async function printGuidance() {
+    console.log(GUIDANCE_SNIPPET);
+}
+async function main() {
+    const [, , cmd, ...rest] = process.argv;
+    const repoRoot = process.env.WHYWHY_ROOT || process.cwd();
+    switch (cmd) {
+        case undefined:
+        case "serve":
+            await runServer();
+            break;
+        case "init":
+            await init(repoRoot);
+            break;
+        case "guidance":
+            await printGuidance();
+            break;
+        case "rebuild-index": {
+            const store = new DecisionStore(repoRoot);
+            const index = await store.rebuildIndex();
+            console.log(`Rebuilt index.json with ${index.decisions.length} decision(s).`);
+            break;
+        }
+        case "help":
+        case "--help":
+        case "-h":
+            printHelp();
+            break;
+        default:
+            console.error(`Unknown command: ${cmd}\n`);
+            printHelp();
+            process.exit(1);
+    }
+    void rest;
+}
+function printHelp() {
+    console.log(`whywhy-mcp -- record WHY decisions are made during AI-assisted coding
+
+Usage:
+  whywhy-mcp [serve]      Start the stdio MCP server (default)
+  whywhy-mcp init         Create .whywhy/ store and add agent guidance to CLAUDE.md
+  whywhy-mcp guidance     Print the agent-guidance snippet (for Cursor rules, etc.)
+  whywhy-mcp rebuild-index  Rebuild index.json from the decision files
+  whywhy-mcp help         Show this help
+
+Environment:
+  WHYWHY_ROOT             Override the repo root (defaults to current directory)
+`);
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

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

package/dist/decisions.d.ts

@@ -0,0 +1,63 @@
+import { Config, DecisionRecord, IndexEntry, Status } from "./schema.js";
+import { DecisionStore } from "./store.js";
+/** Normalized input for creating a new decision (from record/supersede tools). */
+export interface NewDecisionInput {
+    title: string;
+    category: DecisionRecord["category"];
+    decision: string;
+    rationale: string;
+    alternatives_considered?: {
+        option: string;
+        reason_rejected: string;
+    }[];
+    consequences?: string;
+    tags?: string[];
+    conversation_summary?: string;
+    conversation_excerpt?: string;
+    files?: string[];
+    session_id?: string;
+    created_by?: string;
+}
+/** Create and persist a brand-new decision record (status=active). */
+export declare function createDecision(store: DecisionStore, config: Config, input: NewDecisionInput, opts?: {
+    supersedes?: string;
+}): Promise<DecisionRecord>;
+/** Create a replacement decision and flip the old one to `superseded`. */
+export declare function supersedeDecision(store: DecisionStore, config: Config, oldId: string, input: NewDecisionInput): Promise<{
+    newRecord: DecisionRecord;
+    oldRecord: DecisionRecord;
+}>;
+/** Editable fields for update_decision. */
+export interface DecisionEdits {
+    title?: string;
+    category?: DecisionRecord["category"];
+    decision?: string;
+    rationale?: string;
+    alternatives_considered?: {
+        option: string;
+        reason_rejected: string;
+    }[];
+    consequences?: string;
+    tags?: string[];
+    conversation_summary?: string;
+}
+/** Apply small corrections to an existing record; bumps version + updated_at. */
+export declare function updateDecision(store: DecisionStore, id: string, edits: DecisionEdits): Promise<DecisionRecord>;
+/** Retire a decision with no replacement. */
+export declare function deprecateDecision(store: DecisionStore, id: string, reason?: string): Promise<DecisionRecord>;
+export interface QueryFilter {
+    query?: string;
+    category?: string;
+    status?: Status;
+    tags?: string[];
+}
+/**
+ * Filtered + keyword search over the store. The calling agent does the
+ * natural-language reasoning; this just narrows the candidate set and ranks
+ * by simple keyword overlap so the most relevant records surface first.
+ */
+export declare function queryDecisions(store: DecisionStore, filter: QueryFilter): Promise<DecisionRecord[]>;
+export declare function listDecisions(store: DecisionStore, filter?: {
+    status?: Status;
+    category?: string;
+}): Promise<IndexEntry[]>;

package/dist/decisions.js

@@ -0,0 +1,174 @@
+import { SCHEMA_VERSION, } from "./schema.js";
+import { captureGitEvidence, scanCodeComments } from "./git.js";
+/** Assemble evidence (git diff + code comments) honoring config toggles. */
+async function buildEvidence(store, config, input) {
+    const diff = config.capture_git ? await captureGitEvidence(store.root) : null;
+    const code_comments = input.files && input.files.length > 0
+        ? await scanCodeComments(store.root, input.files)
+        : [];
+    const excerpt = config.store_excerpts && input.conversation_excerpt
+        ? input.conversation_excerpt
+        : undefined;
+    return {
+        conversation: {
+            summary: input.conversation_summary ?? "",
+            ...(excerpt ? { excerpt } : {}),
+        },
+        diff,
+        code_comments,
+    };
+}
+/** Create and persist a brand-new decision record (status=active). */
+export async function createDecision(store, config, input, opts = {}) {
+    const { id } = await store.allocateId();
+    const now = new Date().toISOString();
+    const evidence = await buildEvidence(store, config, input);
+    const record = {
+        id,
+        schema_version: SCHEMA_VERSION,
+        title: input.title,
+        category: input.category,
+        status: "active",
+        decision: input.decision,
+        rationale: input.rationale,
+        alternatives_considered: input.alternatives_considered ?? [],
+        consequences: input.consequences ?? "",
+        tags: input.tags ?? [],
+        evidence,
+        version: 1,
+        supersedes: opts.supersedes ?? null,
+        superseded_by: null,
+        created_at: now,
+        updated_at: now,
+        created_by: input.created_by ?? "agent",
+        session_id: input.session_id ?? null,
+    };
+    await store.writeRecord(record);
+    return record;
+}
+/** Create a replacement decision and flip the old one to `superseded`. */
+export async function supersedeDecision(store, config, oldId, input) {
+    const oldRecord = await store.readRecord(oldId);
+    const newRecord = await createDecision(store, config, input, { supersedes: oldId });
+    const updatedOld = {
+        ...oldRecord,
+        status: "superseded",
+        superseded_by: newRecord.id,
+        version: oldRecord.version + 1,
+        updated_at: new Date().toISOString(),
+    };
+    await store.writeRecord(updatedOld);
+    return { newRecord, oldRecord: updatedOld };
+}
+/** Apply small corrections to an existing record; bumps version + updated_at. */
+export async function updateDecision(store, id, edits) {
+    const existing = await store.readRecord(id);
+    const updated = {
+        ...existing,
+        ...("title" in edits && edits.title !== undefined ? { title: edits.title } : {}),
+        ...("category" in edits && edits.category !== undefined
+            ? { category: edits.category }
+            : {}),
+        ...("decision" in edits && edits.decision !== undefined
+            ? { decision: edits.decision }
+            : {}),
+        ...("rationale" in edits && edits.rationale !== undefined
+            ? { rationale: edits.rationale }
+            : {}),
+        ...("alternatives_considered" in edits && edits.alternatives_considered !== undefined
+            ? { alternatives_considered: edits.alternatives_considered }
+            : {}),
+        ...("consequences" in edits && edits.consequences !== undefined
+            ? { consequences: edits.consequences }
+            : {}),
+        ...("tags" in edits && edits.tags !== undefined ? { tags: edits.tags } : {}),
+        version: existing.version + 1,
+        updated_at: new Date().toISOString(),
+    };
+    if (edits.conversation_summary !== undefined) {
+        updated.evidence = {
+            ...existing.evidence,
+            conversation: {
+                ...existing.evidence.conversation,
+                summary: edits.conversation_summary,
+            },
+        };
+    }
+    await store.writeRecord(updated);
+    return updated;
+}
+/** Retire a decision with no replacement. */
+export async function deprecateDecision(store, id, reason) {
+    const existing = await store.readRecord(id);
+    const updated = {
+        ...existing,
+        status: "deprecated",
+        consequences: reason
+            ? `${existing.consequences}\n\n[Deprecated] ${reason}`.trim()
+            : existing.consequences,
+        version: existing.version + 1,
+        updated_at: new Date().toISOString(),
+    };
+    await store.writeRecord(updated);
+    return updated;
+}
+/**
+ * Filtered + keyword search over the store. The calling agent does the
+ * natural-language reasoning; this just narrows the candidate set and ranks
+ * by simple keyword overlap so the most relevant records surface first.
+ */
+export async function queryDecisions(store, filter) {
+    let records = await store.readAllRecords();
+    if (filter.category) {
+        records = records.filter((r) => r.category === filter.category);
+    }
+    if (filter.status) {
+        records = records.filter((r) => r.status === filter.status);
+    }
+    if (filter.tags && filter.tags.length > 0) {
+        const wanted = filter.tags.map((t) => t.toLowerCase());
+        records = records.filter((r) => r.tags.some((t) => wanted.includes(t.toLowerCase())));
+    }
+    if (filter.query && filter.query.trim()) {
+        const terms = filter.query.toLowerCase().split(/\s+/).filter(Boolean);
+        const scored = records
+            .map((r) => ({ r, score: keywordScore(r, terms) }))
+            .filter((s) => s.score > 0)
+            .sort((a, b) => b.score - a.score);
+        return scored.map((s) => s.r);
+    }
+    // No query: most-recently-updated first.
+    return records.sort((a, b) => b.updated_at.localeCompare(a.updated_at));
+}
+function keywordScore(record, terms) {
+    const haystack = [
+        record.title,
+        record.decision,
+        record.rationale,
+        record.consequences,
+        record.tags.join(" "),
+        record.category,
+        record.evidence.conversation.summary,
+        record.alternatives_considered.map((a) => `${a.option} ${a.reason_rejected}`).join(" "),
+    ]
+        .join(" ")
+        .toLowerCase();
+    let score = 0;
+    for (const term of terms) {
+        if (haystack.includes(term))
+            score += 1;
+        // Title matches are worth more.
+        if (record.title.toLowerCase().includes(term))
+            score += 2;
+    }
+    return score;
+}
+export async function listDecisions(store, filter = {}) {
+    let entries = await store.listEntries();
+    if (filter.status)
+        entries = entries.filter((e) => e.status === filter.status);
+    if (filter.category)
+        entries = entries.filter((e) => e.category === filter.category);
+    return entries.sort((a, b) => a.id.localeCompare(b.id));
+}
+//# sourceMappingURL=decisions.js.map

package/dist/decisions.js.map

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

package/dist/git.d.ts

@@ -0,0 +1,14 @@
+import { CodeComment, DiffEvidence } from "./schema.js";
+/**
+ * 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 declare function captureGitEvidence(repoRoot: string): Promise<DiffEvidence | null>;
+/**
+ * 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 declare function scanCodeComments(repoRoot: string, files: string[], maxPerFile?: number): Promise<CodeComment[]>;