whywhy-mcp 0.1.1 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,6 +1,7 @@
1
1
  # whywhy
2
2
 
3
3
  [![npm version](https://img.shields.io/npm/v/whywhy-mcp.svg)](https://www.npmjs.com/package/whywhy-mcp)
4
+ [![npm downloads](https://img.shields.io/npm/dm/whywhy-mcp.svg)](https://www.npmjs.com/package/whywhy-mcp)
4
5
  [![CI](https://github.com/mickymultani/whywhy/actions/workflows/ci.yml/badge.svg)](https://github.com/mickymultani/whywhy/actions/workflows/ci.yml)
5
6
  [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
6
7
  [![Node](https://img.shields.io/node/v/whywhy-mcp.svg)](https://www.npmjs.com/package/whywhy-mcp)
@@ -18,6 +19,10 @@ your source files**.
18
19
  Months later you (or a new teammate) can ask _"why did we pick Postgres?"_ and
19
20
  get the real answer, including the alternatives that were rejected.
20
21
 
22
+ ![whywhy records a decision as you code, then answers "why did we…?" later](assets/demo.svg)
23
+
24
+ > The demo above is an animated SVG and plays on GitHub. (Source: [assets/demo.cast](assets/demo.cast).)
25
+
21
26
  ---
22
27
 
23
28
  ## Why
@@ -29,39 +34,67 @@ first-class, structured, versioned artifacts instead.
29
34
 
30
35
  ## Install & set up
31
36
 
32
- Requires Node ≥ 18.
37
+ Requires Node ≥ 18 and works on **macOS, Linux, and Windows**.
33
38
 
34
39
  ```bash
35
40
  # In your project root:
36
41
  npx -y whywhy-mcp init
37
42
  ```
38
43
 
39
- `init` creates a `.whywhy/` store and appends an agent-guidance block to
40
- `CLAUDE.md` (telling the agent when to log decisions).
44
+ That one command does everything needed to wire up the MCP server:
41
45
 
42
- Then register the server with your agent.
46
+ 1. Creates the `.whywhy/` store (`config.json`, `index.json`, `decisions/`).
47
+ 2. Appends an agent-guidance block to `CLAUDE.md` (tells the agent *when* to log).
48
+ 3. Writes a **`.mcp.json`** registering the server — with the **OS-correct launch
49
+ command** baked in (Windows needs `cmd /c npx`; macOS/Linux use `npx`
50
+ directly). You don't have to know the difference.
43
51
 
44
- ### Claude Code (project scope, so the team shares it)
52
+ Then **reload your agent** so it picks up the new server:
45
53
 
46
- ```bash
47
- claude mcp add --scope project --transport stdio whywhy -- npx -y whywhy-mcp
54
+ - **Claude Code (VS Code):** Command Palette → **Developer: Reload Window**
55
+ - **Claude Code (CLI):** restart the session
56
+
57
+ Approve the `whywhy` server when prompted, then run **`/mcp`** — you should see
58
+ `whywhy` with its tools. That's it.
59
+
60
+ > Already have a `.mcp.json` with other servers? `init` merges `whywhy` in and
61
+ > leaves the rest untouched. Don't want it touched at all? Use `init --no-mcp`.
62
+
63
+ ### What `.mcp.json` looks like
64
+
65
+ ```jsonc
66
+ // macOS / Linux
67
+ { "mcpServers": { "whywhy": { "command": "npx", "args": ["-y", "whywhy-mcp"] } } }
68
+
69
+ // Windows (generated automatically on Windows)
70
+ { "mcpServers": { "whywhy": { "command": "cmd", "args": ["/c", "npx", "-y", "whywhy-mcp"] } } }
48
71
  ```
49
72
 
50
- `--scope project` writes to `.mcp.json` at the repo root — commit it so
51
- teammates inherit the server. Verify with `claude mcp list` or `/mcp` in a
52
- session.
73
+ ### Committing it for your team
74
+
75
+ - **Solo or single-OS team:** commit `.mcp.json` and everyone inherits the server.
76
+ - **Mixed macOS/Windows team:** the launch command is OS-specific, so add
77
+ `.mcp.json` to `.gitignore` and have each teammate run `npx -y whywhy-mcp init`
78
+ once (it generates the right file for their OS). Always commit `.whywhy/` and
79
+ `CLAUDE.md`.
53
80
 
54
81
  ### Other MCP agents (Cursor, etc.)
55
82
 
83
+ whywhy is a standard stdio MCP server, so any MCP client works. Add this to the
84
+ client's MCP config (use the Windows variant above on Windows) and paste the
85
+ guidance block (`npx whywhy-mcp guidance`) into that agent's rules file:
86
+
56
87
  ```json
57
- {
58
- "mcpServers": {
59
- "whywhy": { "command": "npx", "args": ["-y", "whywhy-mcp"] }
60
- }
61
- }
88
+ { "mcpServers": { "whywhy": { "command": "npx", "args": ["-y", "whywhy-mcp"] } } }
62
89
  ```
63
90
 
64
- Paste the guidance block (`npx whywhy-mcp guidance`) into that agent's rules file.
91
+ ### Troubleshooting
92
+
93
+ - **`/mcp` shows nothing** → you didn't reload after `init`. MCP servers load at
94
+ session start.
95
+ - **`whywhy` shows as "failed" on Windows** → your `.mcp.json` is using bare
96
+ `npx`; re-run `npx -y whywhy-mcp init` to regenerate it with the `cmd /c`
97
+ wrapper.
65
98
 
66
99
  ## How it works
67
100
 
@@ -208,6 +241,14 @@ The workflow builds, verifies the tag matches `package.json`, and runs
208
241
  Prefer to publish manually instead? `npm login && npm publish` works too
209
242
  (`prepublishOnly` builds first).
210
243
 
244
+ ## Dogfooding
245
+
246
+ whywhy records its own design decisions. Browse
247
+ [.whywhy/decisions/](.whywhy/decisions/) to see real records — the JSON-store
248
+ choice, the stdio transport, the tool-call capture model, and a genuine
249
+ `superseded` chain where token-based npm publishing was replaced by OIDC trusted
250
+ publishing. That folder is exactly what whywhy produces for any repo.
251
+
211
252
  ## Contributing
212
253
 
213
254
  Contributions are very welcome — see [CONTRIBUTING.md](CONTRIBUTING.md). The
package/dist/cli.js CHANGED
@@ -3,6 +3,7 @@ import { promises as fs } from "node:fs";
3
3
  import path from "node:path";
4
4
  import { DecisionStore } from "./store.js";
5
5
  import { GUIDANCE_SNIPPET, GUIDANCE_BEGIN, GUIDANCE_END } from "./guidance.js";
6
+ import { writeMcpConfig, whywhyServerSpec } from "./mcpconfig.js";
6
7
  /**
7
8
  * whywhy CLI.
8
9
  *
@@ -13,21 +14,28 @@ import { GUIDANCE_SNIPPET, GUIDANCE_BEGIN, GUIDANCE_END } from "./guidance.js";
13
14
  async function runServer() {
14
15
  await import("./index.js");
15
16
  }
16
- async function init(repoRoot) {
17
+ async function init(repoRoot, opts = { mcp: true }) {
17
18
  const store = new DecisionStore(repoRoot);
18
- const config = await store.init();
19
+ await store.init();
19
20
  console.log(`Initialized whywhy store at ${path.relative(repoRoot, store.storeDir) || "."}/`);
20
21
  console.log(` - config.json`);
21
22
  console.log(` - index.json`);
22
23
  console.log(` - decisions/`);
23
24
  await appendGuidance(repoRoot, "CLAUDE.md");
25
+ if (opts.mcp) {
26
+ const { alreadyHad, mergedIntoExisting } = await writeMcpConfig(repoRoot);
27
+ const spec = whywhyServerSpec();
28
+ const verb = alreadyHad ? "Refreshed" : mergedIntoExisting ? "Added whywhy to" : "Wrote";
29
+ console.log(`${verb} .mcp.json (command for ${process.platform}: ${spec.command} ${spec.args.join(" ")}).`);
30
+ }
24
31
  console.log("");
25
32
  console.log("Next steps:");
26
- console.log(" 1. Register the MCP server with your agent. For Claude Code:");
27
- console.log(" claude mcp add --scope project --transport stdio whywhy -- npx -y whywhy-mcp");
28
- console.log(" 2. Commit the .whywhy/ folder and .mcp.json so your team inherits it.");
33
+ console.log(" 1. Reload your agent so it picks up the MCP server:");
34
+ console.log(" - Claude Code (VS Code): Command Palette -> 'Developer: Reload Window'");
35
+ console.log(" - Claude Code (CLI): restart the session");
36
+ console.log(" Approve the 'whywhy' server when prompted, then run /mcp to confirm.");
37
+ console.log(" 2. Commit .whywhy/, CLAUDE.md, and .mcp.json so your team inherits it.");
29
38
  console.log("");
30
- void config;
31
39
  }
32
40
  /** Append the guidance snippet to a rules file, replacing any prior block. */
33
41
  async function appendGuidance(repoRoot, fileName) {
@@ -66,7 +74,7 @@ async function main() {
66
74
  await runServer();
67
75
  break;
68
76
  case "init":
69
- await init(repoRoot);
77
+ await init(repoRoot, { mcp: !rest.includes("--no-mcp") });
70
78
  break;
71
79
  case "guidance":
72
80
  await printGuidance();
@@ -94,7 +102,10 @@ function printHelp() {
94
102
 
95
103
  Usage:
96
104
  whywhy-mcp [serve] Start the stdio MCP server (default)
97
- whywhy-mcp init Create .whywhy/ store and add agent guidance to CLAUDE.md
105
+ whywhy-mcp init Set up whywhy in this repo: create .whywhy/ store,
106
+ add agent guidance to CLAUDE.md, and write an
107
+ OS-correct .mcp.json so your agent can find the server
108
+ whywhy-mcp init --no-mcp Same as init, but don't touch .mcp.json
98
109
  whywhy-mcp guidance Print the agent-guidance snippet (for Cursor rules, etc.)
99
110
  whywhy-mcp rebuild-index Rebuild index.json from the decision files
100
111
  whywhy-mcp help Show this help
package/dist/cli.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,24 @@
1
+ /**
2
+ * Generates and maintains the agent's MCP server registration (.mcp.json).
3
+ *
4
+ * The command differs by OS: native Windows can't spawn `npx` directly through
5
+ * an MCP client, so it must go through `cmd /c`. macOS/Linux use `npx` directly.
6
+ * Generating this at `init` time means users never have to know the difference.
7
+ */
8
+ export interface McpServerSpec {
9
+ command: string;
10
+ args: string[];
11
+ }
12
+ /** The whywhy MCP server entry, correct for the given platform. */
13
+ export declare function whywhyServerSpec(platform?: NodeJS.Platform): McpServerSpec;
14
+ export interface McpWriteResult {
15
+ /** True if a whywhy entry already existed (and was refreshed). */
16
+ alreadyHad: boolean;
17
+ /** True if a .mcp.json with other servers was found and preserved. */
18
+ mergedIntoExisting: boolean;
19
+ }
20
+ /**
21
+ * Writes (or merges) the whywhy server into `.mcp.json` at the repo root,
22
+ * preserving any other MCP servers already configured there.
23
+ */
24
+ export declare function writeMcpConfig(repoRoot: string, platform?: NodeJS.Platform): Promise<McpWriteResult>;
@@ -0,0 +1,38 @@
1
+ import { promises as fs } from "node:fs";
2
+ import path from "node:path";
3
+ /** The whywhy MCP server entry, correct for the given platform. */
4
+ export function whywhyServerSpec(platform = process.platform) {
5
+ if (platform === "win32") {
6
+ return { command: "cmd", args: ["/c", "npx", "-y", "whywhy-mcp"] };
7
+ }
8
+ return { command: "npx", args: ["-y", "whywhy-mcp"] };
9
+ }
10
+ /**
11
+ * Writes (or merges) the whywhy server into `.mcp.json` at the repo root,
12
+ * preserving any other MCP servers already configured there.
13
+ */
14
+ export async function writeMcpConfig(repoRoot, platform = process.platform) {
15
+ const file = path.resolve(repoRoot, ".mcp.json");
16
+ let json = {};
17
+ let mergedIntoExisting = false;
18
+ try {
19
+ const raw = await fs.readFile(file, "utf8");
20
+ const parsed = JSON.parse(raw);
21
+ if (parsed && typeof parsed === "object") {
22
+ json = parsed;
23
+ mergedIntoExisting = true;
24
+ }
25
+ }
26
+ catch {
27
+ /* no existing file, or invalid -> start fresh */
28
+ }
29
+ if (!json.mcpServers || typeof json.mcpServers !== "object") {
30
+ json.mcpServers = {};
31
+ }
32
+ const servers = json.mcpServers;
33
+ const alreadyHad = Boolean(servers.whywhy);
34
+ servers.whywhy = whywhyServerSpec(platform);
35
+ await fs.writeFile(file, JSON.stringify(json, null, 2) + "\n", "utf8");
36
+ return { alreadyHad, mergedIntoExisting };
37
+ }
38
+ //# sourceMappingURL=mcpconfig.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"mcpconfig.js","sourceRoot":"","sources":["../src/mcpconfig.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,IAAI,MAAM,WAAW,CAAC;AAe7B,mEAAmE;AACnE,MAAM,UAAU,gBAAgB,CAAC,WAA4B,OAAO,CAAC,QAAQ;IAC3E,IAAI,QAAQ,KAAK,OAAO,EAAE,CAAC;QACzB,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,YAAY,CAAC,EAAE,CAAC;IACrE,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,IAAI,EAAE,YAAY,CAAC,EAAE,CAAC;AACxD,CAAC;AASD;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,QAAgB,EAChB,WAA4B,OAAO,CAAC,QAAQ;IAE5C,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;IAEjD,IAAI,IAAI,GAAuE,EAAE,CAAC;IAClF,IAAI,kBAAkB,GAAG,KAAK,CAAC;IAC/B,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC5C,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC/B,IAAI,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;YACzC,IAAI,GAAG,MAAM,CAAC;YACd,kBAAkB,GAAG,IAAI,CAAC;QAC5B,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,iDAAiD;IACnD,CAAC;IAED,IAAI,CAAC,IAAI,CAAC,UAAU,IAAI,OAAO,IAAI,CAAC,UAAU,KAAK,QAAQ,EAAE,CAAC;QAC5D,IAAI,CAAC,UAAU,GAAG,EAAE,CAAC;IACvB,CAAC;IACD,MAAM,OAAO,GAAG,IAAI,CAAC,UAAqC,CAAC;IAC3D,MAAM,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAC3C,OAAO,CAAC,MAAM,GAAG,gBAAgB,CAAC,QAAQ,CAAC,CAAC;IAE5C,MAAM,EAAE,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,MAAM,CAAC,CAAC;IACvE,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,CAAC;AAC5C,CAAC"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "whywhy-mcp",
3
- "version": "0.1.1",
3
+ "version": "0.1.2",
4
4
  "description": "Agent-agnostic MCP server that records WHY architectural, product, and development decisions are made during AI-assisted coding.",
5
5
  "license": "MIT",
6
6
  "author": "Micky Multani",