@xcraftmind/mastermind 0.22.0 → 0.23.0

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.
Files changed (2) hide show
  1. package/README.md +91 -37
  2. package/package.json +9 -8
package/README.md CHANGED
@@ -1,30 +1,75 @@
1
1
  # @xcraftmind/mastermind
2
2
 
3
+ [![npm version](https://img.shields.io/npm/v/@xcraftmind/mastermind.svg)](https://www.npmjs.com/package/@xcraftmind/mastermind)
4
+ [![CI](https://github.com/xcrft/mastermind/actions/workflows/ci-mmcg.yml/badge.svg)](https://github.com/xcrft/mastermind/actions/workflows/ci-mmcg.yml)
5
+ [![license: MIT](https://img.shields.io/npm/l/@xcraftmind/mastermind.svg)](./LICENSE)
6
+
3
7
  Mastermind workflow CLI + mmcg codegraph for AI coding agents — verify-spec / audit-spec gates, MCP server, multi-language tree-sitter indexer (Python, TypeScript, JavaScript, Rust, C#, Go, Java, PHP, C/C++).
4
8
 
5
9
  Prebuilt native binaries via optional platform packages — **no Rust toolchain required**.
6
10
 
7
- ## Install
11
+ ## What it does
12
+
13
+ `mastermind` parses your codebase into a queryable graph (definitions, callers/callees, imports, blast radius) with tree-sitter, and serves it to Claude Code over MCP — so the agent asks structural questions instead of grepping. It also ships the Mastermind workflow gates: `verify-spec` (pre-flight) and `audit-spec` (post-flight) for running coding tasks against mechanical checks.
14
+
15
+ ## Quick start
16
+
17
+ Requires **Node.js 18+**. The CLI is a thin JS wrapper over a prebuilt native binary — no Rust toolchain needed.
8
18
 
9
- ### One-shot (no install)
19
+ **1. Install**
10
20
 
11
21
  ```sh
12
- npx -y @xcraftmind/mastermind doctor
13
- npx -y @xcraftmind/mastermind init --profile typescript-api
14
- npx -y @xcraftmind/mastermind run-task .mastermind/tasks/042-feature.md
22
+ npm install -g @xcraftmind/mastermind
23
+ ```
24
+
25
+ **2. Set up your project** — run inside each repo you want Claude to understand:
26
+
27
+ ```sh
28
+ cd your-project
29
+ mastermind init # scaffold .mastermind/, build the index, draft CONTEXT.md
30
+ echo ".mastermind/" >> .gitignore # index + local specs are local state
31
+ ```
32
+
33
+ `init` builds the index and drafts `CONTEXT.md` from your code via `claude -p` (pass `--no-claude` or `--no-index` to skip). Re-run `mastermind index .` to refresh, or `mastermind watch` to keep it live.
34
+
35
+ **3. Register with Claude Code** — once, globally:
36
+
37
+ ```sh
38
+ mastermind setup claude --write-mcp
15
39
  ```
16
40
 
17
- `npx` is great for these one-shot commands. **Avoid it for the MCP server**, though: an MCP config that runs `npx ... serve` pays an npm-cache/network resolution cost on every Claude Code launch and is less deterministic than a real install. For `setup claude`, prefer **global** or **project-local** (below). If you do register via npx, `setup claude` pins the version (`npx -y @xcraftmind/mastermind@<ver> serve`) so at least the version is stable — but it's an escape hatch, not the recommended path.
41
+ **4. Verify**
42
+
43
+ ```sh
44
+ mastermind doctor # should now be all green
45
+ ```
46
+
47
+ Restart Claude Code — the codegraph tools (search, callers, callees, impact, …) are now available in any project you've indexed.
48
+
49
+ ## What gets set up where
18
50
 
19
- ### Global (recommended for most users)
51
+ Two separate things — and the split is the part that trips people up:
52
+
53
+ | | Scope | Lives in | How often |
54
+ |---|---|---|---|
55
+ | **Index** — `init` + `index` | **per project** | `.mastermind/mmcg.db` in each repo | once per repo, refresh with `index` / `watch` |
56
+ | **MCP registration** — `setup claude` | once | `~/.claude/.mcp.json` (global) | once for all projects |
57
+
58
+ - **The index is always per-project.** Run `mastermind init && mastermind index .` in *every* repo you want indexed. `doctor` reporting `index database not found` just means you haven't done this in the current directory yet (the exact situation if you run `doctor` from `/tmp` or a fresh shell).
59
+ - **The MCP registration is usually once, globally.** The global entry launches `mastermind serve` from whichever project you open in Claude Code, so it picks up *that* project's `.mastermind/mmcg.db` automatically. You do **not** re-run `setup claude` per repo.
60
+ - Use **per-project registration** only if you want the MCP config committed with the repo and version-pinned: `mastermind setup claude --project . --write-mcp` writes `./.mcp.json` with `command: "./node_modules/.bin/mastermind"` (pair it with a project-local install — see below).
61
+
62
+ > `setup claude` is safe by default: without `--write-mcp` it prints the diff and exits without touching anything.
63
+
64
+ ## Install options
65
+
66
+ ### Global (recommended)
20
67
 
21
68
  ```sh
22
69
  npm install -g @xcraftmind/mastermind
23
- mastermind setup claude --write-mcp # register mmcg as an MCP server
24
- mastermind doctor # verify the environment
25
70
  ```
26
71
 
27
- `setup claude` writes `~/.claude/.mcp.json` with `command: "mastermind"` so Claude Code launches the wrapper from PATH.
72
+ Puts `mastermind` on your PATH. `setup claude --write-mcp` registers `command: "mastermind"` in `~/.claude/.mcp.json`.
28
73
 
29
74
  ### Project-local
30
75
 
@@ -33,15 +78,43 @@ npm install -D @xcraftmind/mastermind
33
78
  npx mastermind setup claude --project . --write-mcp
34
79
  ```
35
80
 
36
- `setup claude --project .` writes `./.mcp.json` with `command: "./node_modules/.bin/mastermind"` so the project gets a reproducible, version-pinned MCP server.
81
+ Writes `./.mcp.json` with `command: "./node_modules/.bin/mastermind"` — reproducible and version-pinned with the repo. Commit `./.mcp.json`; keep ignoring `.mastermind/`.
82
+
83
+ ### One-shot with npx (no install)
84
+
85
+ ```sh
86
+ npx -y @xcraftmind/mastermind doctor
87
+ npx -y @xcraftmind/mastermind init --profile typescript-api
88
+ ```
89
+
90
+ Fine for one-off commands. **Avoid npx for the MCP server** — running `npx … serve` on every Claude Code launch pays an npm-resolution cost and is less deterministic than a real install. For `serve` / `setup claude`, prefer global or project-local.
37
91
 
38
92
  ### Build from source (contributors / unsupported platforms)
39
93
 
40
94
  ```sh
41
- cargo install mmcg
95
+ cargo install mmcg # requires Rust 1.75+
96
+ ```
97
+
98
+ The cargo-installed binary is `mmcg`, not `mastermind` — same code, same subcommands, only the wrapper name differs.
99
+
100
+ ## Commands
101
+
102
+ ```sh
103
+ mastermind init [--profile <p>] # scaffold .mastermind/, build index, draft CONTEXT.md (--no-index / --no-claude to skip)
104
+ mastermind index . # build/refresh the codegraph (incremental; --force to re-parse all)
105
+ mastermind watch # long-running watcher — re-indexes on file changes
106
+ mastermind status # file count, symbol count, db path
107
+ mastermind doctor # environment health check
108
+ mastermind serve # MCP stdio server (this is what Claude Code launches)
109
+ mastermind setup claude --write-mcp # register with Claude Code's MCP layer
110
+ mastermind verify-spec <path> # pre-execution mechanical gate on a task spec
111
+ mastermind audit-spec <path> --since main # post-execution audit vs a git baseline
112
+ mastermind run-task <path> # two-phase orchestrator: verify → executor → audit
113
+ mastermind query callers <symbol> # one-shot CLI query (agents use the MCP tools instead)
114
+ mastermind uninstall [--scope <s>] # remove project setup (.mastermind/ + project .mcp.json); --scope global|all for the global MCP entry
42
115
  ```
43
116
 
44
- Requires Rust 1.75+. The cargo-installed binary is `mmcg`, not `mastermind` — same code, same subcommands, only the wrapper name differs.
117
+ `mmcg` is a legacy alias for the same binary (cargo installs expose it under that name) — prefer `mastermind`. See `mastermind <subcommand> --help` for full options.
45
118
 
46
119
  ## Supported platforms
47
120
 
@@ -57,30 +130,6 @@ Prebuilt binaries ship for:
57
130
 
58
131
  Other targets fall back to `cargo install mmcg`.
59
132
 
60
- ## What's in the box
61
-
62
- - `mastermind` — public CLI command (alias for `mmcg` with install-mode hints)
63
- - `mmcg` — compatibility command (same binary, same subcommands as cargo-installed `mmcg`)
64
-
65
- Both commands resolve to the same native binary. Use whichever your team has documented.
66
-
67
- ### Top-level subcommands
68
-
69
- ```sh
70
- mastermind init --profile typescript-api # scaffold .mastermind/ with stack-specific CONTEXT.md
71
- mastermind index . # build/refresh the codegraph index
72
- mastermind watch # long-running watcher (re-indexes on file changes)
73
- mastermind doctor # environment health check
74
- mastermind serve # MCP stdio server
75
- mastermind setup claude --write-mcp # register with Claude Code's MCP layer
76
- mastermind verify-spec <path> # pre-execution mechanical gate on a task spec
77
- mastermind audit-spec <path> --since main # post-execution audit vs git baseline
78
- mastermind run-task <path> # two-phase orchestrator: verify → executor → audit
79
- mastermind query callers <symbol> # one-shot CLI query (use MCP for agents)
80
- ```
81
-
82
- See `mastermind <subcommand> --help` for full options.
83
-
84
133
  ## Architecture
85
134
 
86
135
  The npm package uses the prebuilt-platform-package pattern (same as `esbuild`, `swc`, `lefthook`, `turbo`). The root `@xcraftmind/mastermind` package contains only JavaScript wrappers and lists all seven platform packages as `optionalDependencies`. npm installs only the package matching the host's `os` + `cpu` (+ `libc` for Linux); the others are skipped.
@@ -101,5 +150,10 @@ No `postinstall` script. No network calls beyond the npm registry itself.
101
150
  ## Links
102
151
 
103
152
  - Source: [github.com/xcrft/mastermind](https://github.com/xcrft/mastermind)
153
+ - Changelog: [CHANGELOG.md](https://github.com/xcrft/mastermind/blob/main/CHANGELOG.md)
104
154
  - mmcg Rust crate: [crates.io/crates/mmcg](https://crates.io/crates/mmcg)
105
155
  - MCP protocol: [modelcontextprotocol.io](https://modelcontextprotocol.io)
156
+
157
+ ## License
158
+
159
+ MIT — see [LICENSE](./LICENSE).
package/package.json CHANGED
@@ -1,8 +1,9 @@
1
1
  {
2
2
  "name": "@xcraftmind/mastermind",
3
- "version": "0.22.0",
3
+ "version": "0.23.0",
4
4
  "description": "Mastermind workflow CLI + mmcg codegraph for AI coding agents — verify-spec / audit-spec gates, MCP server, multi-language tree-sitter indexer (Python, TypeScript, JavaScript, Rust, C#, Go, Java, PHP, C/C++). Prebuilt native binaries via optional platform packages — no Rust toolchain required.",
5
5
  "license": "MIT",
6
+ "author": "xcraftmind",
6
7
  "type": "module",
7
8
  "repository": {
8
9
  "type": "git",
@@ -36,12 +37,12 @@
36
37
  "mastermind"
37
38
  ],
38
39
  "optionalDependencies": {
39
- "@xcraftmind/mmcg-darwin-arm64": "0.22.0",
40
- "@xcraftmind/mmcg-darwin-x64": "0.22.0",
41
- "@xcraftmind/mmcg-linux-x64-gnu": "0.22.0",
42
- "@xcraftmind/mmcg-linux-arm64-gnu": "0.22.0",
43
- "@xcraftmind/mmcg-linux-x64-musl": "0.22.0",
44
- "@xcraftmind/mmcg-linux-arm64-musl": "0.22.0",
45
- "@xcraftmind/mmcg-win32-x64-msvc": "0.22.0"
40
+ "@xcraftmind/mmcg-darwin-arm64": "0.23.0",
41
+ "@xcraftmind/mmcg-darwin-x64": "0.23.0",
42
+ "@xcraftmind/mmcg-linux-x64-gnu": "0.23.0",
43
+ "@xcraftmind/mmcg-linux-arm64-gnu": "0.23.0",
44
+ "@xcraftmind/mmcg-linux-x64-musl": "0.23.0",
45
+ "@xcraftmind/mmcg-linux-arm64-musl": "0.23.0",
46
+ "@xcraftmind/mmcg-win32-x64-msvc": "0.23.0"
46
47
  }
47
48
  }