@brutalsystems/muster 1.2.2 → 2.0.0

package/README.md

@@ -114,6 +114,35 @@ What that verification covers is in [Verification](docs/verification.md).
 | [MCP servers and plugins](docs/mcp.md)               | tools for launched agents, and Muster's own MCP server |
 | [Verification](docs/verification.md)                 | what is tested, what is checked by hand                |
 
+## Use with Claude Code
+
+1. **Install the plugin.** Its `muster` skill teaches a Claude session to use
+   Muster well: choosing a kind and level, reaching and stopping what it
+   launched, and the traps. It is versioned with Muster, so it describes the
+   release it came from.
+
+   ```sh
+   claude plugin marketplace add BrutalSystems/muster
+   claude plugin install muster@muster
+   ```
+
+   Or, inside a session, `/plugin marketplace add BrutalSystems/muster` and
+   then `/plugin install muster@muster`.
+
+2. **Register the MCP server** for the current Claude profile:
+
+   ```sh
+   muster mcp install
+   ```
+
+   It is read-only by default (`list`, `output`), so registering it at user
+   scope grants no launch authority. `muster mcp install --allow-launch` adds
+   `run`, `stop` and `title`, and every session in that profile can then
+   launch and stop sessions. `muster mcp status` shows which you have.
+   Details: [MCP installation](docs/mcp.md#mcp-installation).
+
+3. **Restart Claude Code** (or start a new session) to load it.
+
 ## Keeping it up to date
 
 Publishing a release does not touch an installed copy: `muster --version` keeps

package/dist/help.js

@@ -176,13 +176,22 @@ export const COMMANDS = [
     },
     {
         name: "mcp",
-        summary: "start the MCP server on stdio",
-        synopsis: "muster mcp",
-        options: [],
+        summary: "serve MCP on stdio, or register it with Claude Code",
+        synopsis: "muster mcp [--allow-launch] | mcp install|uninstall|status",
+        options: [
+            ["--allow-launch", "also expose run, stop and title (launch authority)"],
+            ["--force", "install: replace a different existing registration"],
+        ],
         notes: [
-            "Exposes run, list, stop and output. No arguments does the same when stdin is not a terminal, which is what an MCP client provides.",
+            "Read-only by default: exposes list and output only. --allow-launch is the deliberate grant. No arguments starts the read-only server when stdin is not a terminal, which is what an MCP client provides.",
+            "install registers the server with Claude Code at user scope for the current profile (CLAUDE_CONFIG_DIR) via `claude mcp add`. Without --allow-launch it asks at a terminal, defaulting to no; without a terminal it does not grant. Restart Claude Code afterwards.",
+        ],
+        examples: [
+            "muster mcp",
+            "muster mcp install",
+            "muster mcp install --allow-launch --force",
+            "muster mcp status",
         ],
-        examples: ["muster mcp"],
     },
 ];
 export function topLevelHelp() {
@@ -204,7 +213,7 @@ export function topLevelHelp() {
         // Kept here rather than moved to the README: this is a safety statement
         // about who gets launch authority, not reference detail, and it is only
         // load-bearing where someone is about to install.
-        ...wrap("MCP: install deliberately in the one authorized session, never at user scope.", WIDTH),
+        ...wrap("MCP: `muster mcp install` registers a read-only server with Claude Code. Launch authority is granted only by --allow-launch.", WIDTH),
     ];
     return lines.join("\n") + "\n";
 }

package/dist/mcp-bridge.js

@@ -6,13 +6,14 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
-import { mcpServerSchema, mcpName, mcpTransport } from "./mcp.js";
+import { mcpServerSchema, mcpName, mcpTransport, toolGate } from "./mcp.js";
 async function main() {
     const [path, name] = process.argv.slice(2);
     if (!path || !name || !mcpName.safeParse(name).success)
         throw new Error("Invalid MCP bridge arguments");
     const definitions = JSON.parse(await readFile(path, "utf8"));
     const config = mcpServerSchema.parse(definitions[name]);
+    const gate = toolGate(config.tools);
     const client = new Client({ name: "muster-tool-bridge", version: "1" }, { capabilities: {} });
     const server = new Server({ name: `muster-${name}`, version: "1" }, { capabilities: { tools: {} } });
     let shutdown;
@@ -59,13 +60,13 @@ async function main() {
         let cursor;
         do {
             const page = await client.listTools(cursor ? { cursor } : {});
-            tools.push(...page.tools.filter((t) => config.tools.includes(t.name)));
+            tools.push(...gate.expose(page.tools));
             cursor = page.nextCursor;
         } while (cursor);
         return { tools };
     });
     server.setRequestHandler(CallToolRequestSchema, async ({ params }) => {
-        if (!config.tools.includes(params.name))
+        if (!gate.allows(params.name))
             return {
                 isError: true,
                 content: [

package/dist/mcp-install.js

@@ -0,0 +1,207 @@
+/**
+ * `muster mcp install | uninstall | status` — registering Muster's own MCP
+ * server with Claude Code at user scope, for the profile `CLAUDE_CONFIG_DIR`
+ * names (or the default one).
+ *
+ * Every write goes through `claude mcp add` / `claude mcp remove`, so Muster
+ * never edits Claude's configuration itself. Reading is different: the current
+ * definition is read straight from the profile's `.claude.json`, because
+ * `claude mcp get` health-checks a server by starting it and reports whichever
+ * scope wins, where this needs the user-scope entry exactly as written.
+ */
+import { execFile } from "node:child_process";
+import { access, constants, readFile, realpath } from "node:fs/promises";
+import { homedir } from "node:os";
+import { delimiter, join } from "node:path";
+import { parseArgs } from "node:util";
+import { LAUNCH_TOOLS, mcpToolNames } from "./mcp-tools.js";
+export const SERVER_NAME = "muster";
+export const ALLOW_LAUNCH = "--allow-launch";
+export const LAUNCH_QUESTION = "Let this Claude launch and stop sessions? [y/N] ";
+export const MCP_SUBCOMMANDS = ["install", "uninstall", "status"];
+/** The first executable called `name` on PATH, as PATH spells it. */
+export async function onPath(name, env) {
+    for (const dir of (env.PATH ?? "").split(delimiter)) {
+        if (!dir)
+            continue;
+        const candidate = join(dir, name);
+        try {
+            await access(candidate, constants.X_OK);
+            return candidate;
+        }
+        catch { }
+    }
+    return undefined;
+}
+/**
+ * The command a client should run to reach this muster. The installed `muster`
+ * bin when the one on PATH is this very script — its PATH spelling, not its
+ * resolved target, so a package-manager link survives an upgrade. Otherwise
+ * (a source checkout, or a different install first on PATH) this node and this
+ * script, absolutely, so the registration runs what the person just ran.
+ */
+export async function selfInvocation(env, script = process.argv[1], node = process.execPath) {
+    const resolved = await realpath(script);
+    const found = await onPath("muster", env);
+    if (found && (await realpath(found).catch(() => undefined)) === resolved)
+        return { command: found, args: [] };
+    return { command: node, args: [resolved] };
+}
+export function claudeConfigFile(env) {
+    return join(env.CLAUDE_CONFIG_DIR || env.HOME || homedir(), ".claude.json");
+}
+/** The user-scope `muster` entry, or undefined when there is none. */
+export async function registered(env) {
+    const file = claudeConfigFile(env);
+    let raw;
+    try {
+        raw = await readFile(file, "utf8");
+    }
+    catch (e) {
+        if (e.code === "ENOENT")
+            return undefined;
+        throw e;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`Cannot read ${file}: it is not valid JSON`);
+    }
+    const entry = parsed?.mcpServers?.[SERVER_NAME];
+    if (!entry || typeof entry !== "object")
+        return undefined;
+    return {
+        command: typeof entry.command === "string" ? entry.command : "",
+        args: Array.isArray(entry.args) ? entry.args.map(String) : [],
+    };
+}
+export function desired(self, allowLaunch) {
+    return {
+        command: self.command,
+        args: [...self.args, "mcp", ...(allowLaunch ? [ALLOW_LAUNCH] : [])],
+    };
+}
+const same = (a, b) => a.command === b.command &&
+    a.args.length === b.args.length &&
+    a.args.every((arg, i) => arg === b.args[i]);
+const quote = (s) => /^[\w@%+=:,./-]+$/.test(s) ? s : JSON.stringify(s);
+export const render = (d) => [d.command, ...d.args].map(quote).join(" ");
+const launchAllowed = (d) => d.args.includes(ALLOW_LAUNCH);
+function toolsLine(allowLaunch) {
+    return allowLaunch
+        ? `Tools: ${mcpToolNames(true).join(", ")} — this Claude can launch and stop sessions.`
+        : `Tools: ${mcpToolNames(false).join(", ")} — read-only; it cannot launch or stop anything.`;
+}
+async function defaultRunClaude(binary, args, env) {
+    return new Promise((resolve) => {
+        execFile(binary, args, { env, timeout: 60_000 }, (error, stdout, stderr) => resolve({
+            code: error ? (typeof error.code === "number" ? error.code : 1) : 0,
+            stdout: String(stdout),
+            stderr: String(stderr),
+        }));
+    });
+}
+async function claude(deps) {
+    const binary = await onPath("claude", deps.env);
+    if (!binary)
+        throw new Error("`claude` is not on PATH. Install Claude Code, or put it on PATH, and run this again.");
+    const run = deps.runClaude ?? defaultRunClaude;
+    return async (args, what) => {
+        const result = await run(binary, args, deps.env);
+        if (result.code !== 0)
+            throw new Error(`\`claude ${args.join(" ")}\` failed while ${what}: ${(result.stderr || result.stdout).trim() || `exit ${result.code}`}`);
+        return result;
+    };
+}
+async function install(opts, deps) {
+    const run = await claude(deps);
+    let allowLaunch = opts.allowLaunch;
+    // Default no, and no question at all without a terminal: the grant is made
+    // by a person typing the flag or answering yes, never by a script's silence.
+    if (!allowLaunch && deps.ask)
+        allowLaunch = /^y(es)?$/i.test((await deps.ask(LAUNCH_QUESTION)).trim());
+    const want = desired(await deps.self(), allowLaunch);
+    const file = claudeConfigFile(deps.env);
+    const have = await registered(deps.env);
+    if (have && same(have, want)) {
+        deps.write(`Already registered at user scope in ${file}; nothing changed.\n  ${render(want)}\n${toolsLine(allowLaunch)}\n`);
+        return;
+    }
+    if (have && !opts.force)
+        throw new Error(`A different "${SERVER_NAME}" MCP server is already registered at user scope in ${file}:\n` +
+            `  have: ${render(have)}\n  want: ${render(want)}\n` +
+            `Run again with --force to replace it, or \`muster mcp uninstall\` first.`);
+    if (have)
+        await run(["mcp", "remove", "--scope", "user", SERVER_NAME], "removing the existing definition");
+    await run([
+        "mcp",
+        "add",
+        "--scope",
+        "user",
+        SERVER_NAME,
+        "--",
+        want.command,
+        ...want.args,
+    ], "registering the server");
+    deps.write(`${have ? "Replaced" : "Registered"} the "${SERVER_NAME}" MCP server at user scope in ${file}.\n` +
+        `  ${render(want)}\n${toolsLine(allowLaunch)}\n` +
+        "Restart Claude Code (or start a new session) to load it.\n");
+}
+async function uninstall(deps) {
+    const run = await claude(deps);
+    const file = claudeConfigFile(deps.env);
+    if (!(await registered(deps.env))) {
+        deps.write(`No "${SERVER_NAME}" MCP server at user scope in ${file}; nothing to remove.\n`);
+        return;
+    }
+    await run(["mcp", "remove", "--scope", "user", SERVER_NAME], "removing the server");
+    deps.write(`Removed the "${SERVER_NAME}" MCP server from user scope in ${file}.\n` +
+        "Restart Claude Code (or start a new session) to drop it.\n");
+}
+async function status(deps) {
+    const file = claudeConfigFile(deps.env);
+    const have = await registered(deps.env);
+    if (!have) {
+        deps.write(`Not registered: no "${SERVER_NAME}" MCP server at user scope in ${file}.\n` +
+            "Run `muster mcp install` to add it.\n");
+        return;
+    }
+    const allowed = launchAllowed(have);
+    deps.write(`Registered at user scope in ${file}.\n  ${render(have)}\n` +
+        `Launch allowed: ${allowed ? "yes" : "no"}\n${toolsLine(allowed)}\n`);
+}
+/** `muster mcp <subcommand> ...`, already known to name a subcommand. */
+export async function mcpCommand(argv, deps) {
+    const [sub, ...rest] = argv;
+    const { values, positionals } = parseArgs({
+        args: rest,
+        allowPositionals: true,
+        strict: true,
+        options: {
+            "allow-launch": { type: "boolean" },
+            force: { type: "boolean" },
+        },
+    });
+    if (positionals.length)
+        throw new Error(`mcp ${sub} takes no positional arguments`);
+    if (sub !== "install" && (values["allow-launch"] || values.force))
+        throw new Error(`--allow-launch and --force apply only to mcp install`);
+    if (sub === "install")
+        return install({
+            allowLaunch: Boolean(values["allow-launch"]),
+            force: Boolean(values.force),
+        }, deps);
+    if (sub === "uninstall")
+        return uninstall(deps);
+    if (sub === "status")
+        return status(deps);
+    throw new Error(`Unknown mcp subcommand: ${sub}`);
+}
+/** The refusal for a tool the running server does not expose. */
+export function notEnabled(name) {
+    return LAUNCH_TOOLS.includes(name)
+        ? `Tool ${name} is not enabled: this Muster MCP server is read-only. Start it with \`muster mcp --allow-launch\` (or register it with \`muster mcp install --allow-launch\`) to expose ${LAUNCH_TOOLS.join(", ")}.`
+        : `Unknown tool ${name}`;
+}

package/dist/mcp-tools.js

@@ -165,3 +165,20 @@ export const MCP_TOOLS = [
  * callers may not set the field, not a place to park an oversight.
  */
 export const RUN_MCP_OMITTED = [];
+/**
+ * What `muster mcp` serves by default: reading what Muster already owns.
+ * Nothing here can start, stop or change a run, so registering the server
+ * where every Claude session sees it grants no launch authority.
+ */
+export const READ_ONLY_TOOLS = ["list", "output"];
+/**
+ * Added by `muster mcp --allow-launch`, the deliberate grant. `title` is here
+ * rather than above because it changes a running session, and the read-only
+ * set is defined as changing nothing.
+ */
+export const LAUNCH_TOOLS = ["run", "stop", "title"];
+export function mcpToolNames(allowLaunch) {
+    return allowLaunch
+        ? [...READ_ONLY_TOOLS, ...LAUNCH_TOOLS]
+        : [...READ_ONLY_TOOLS];
+}

package/dist/mcp.js

@@ -39,6 +39,21 @@ export const mcpServerSchema = z
             message: "args, env and env_vars require a stdio server",
         });
 });
+/**
+ * One allowlist, applied to both halves of an MCP server: what `tools/list`
+ * advertises and what `tools/call` will dispatch. Used by the Claude bridge
+ * (the operator's selected tools of an upstream server) and by Muster's own
+ * server (read-only unless started with `--allow-launch`). Filtering the
+ * listing alone is not enough — a client can call a name it was never shown —
+ * so every call is checked against the same set.
+ */
+export function toolGate(enabled) {
+    const names = new Set(enabled);
+    return {
+        expose: (tools) => tools.filter((tool) => names.has(tool.name)),
+        allows: (name) => names.has(name),
+    };
+}
 export function selectMcp(req, config) {
     // Personal defaults apply to sessions, not unattended one-shot tasks.
     const names = req.mcp ?? (req.kind === "session" ? config.default_mcp : []);

package/dist/muster.js

@@ -12,7 +12,9 @@ import { checkPlugins, npmRegistry } from "./doctor.js";
 import { loadConfig, musterHome } from "./config.js";
 import { describeIdentities, interactiveSetup, setupIdentity, } from "./identity-cli.js";
 import { IdentityError } from "./identity-store.js";
-import { MCP_TOOLS } from "./mcp-tools.js";
+import { MCP_TOOLS, mcpToolNames } from "./mcp-tools.js";
+import { toolGate } from "./mcp.js";
+import { ALLOW_LAUNCH, MCP_SUBCOMMANDS, mcpCommand, notEnabled, selfInvocation, } from "./mcp-install.js";
 import { normalizeOpenFlag, usesTerminalFlag } from "./guard.js";
 import { commandHelp, topLevelHelp } from "./help.js";
 import { promptForMissing, terminalReader } from "./prompt.js";
@@ -75,8 +77,28 @@ async function main() {
     // driven by hand in a terminal to debug it.
     const bareAtTerminal = argv.length === 0 && Boolean(process.stdin.isTTY);
     const mcp = !bareAtTerminal && (argv.length === 0 || argv[0] === "mcp");
-    if (argv[0] === "mcp" && argv.length > 1)
-        throw new Error("mcp takes no arguments");
+    // `muster mcp install|uninstall|status` registers the server with Claude
+    // Code rather than serving it. Handled before Muster.create(): none of them
+    // touches a run.
+    if (argv[0] === "mcp" &&
+        MCP_SUBCOMMANDS.includes(argv[1] ?? "")) {
+        if (argv.includes("--help") || argv.includes("-h")) {
+            process.stdout.write(commandHelp("mcp"));
+            return;
+        }
+        await mcpCommand(argv.slice(1), {
+            env: process.env,
+            write: (s) => process.stdout.write(s),
+            ...(process.stdin.isTTY ? { ask: terminalReader() } : {}),
+            self: () => selfInvocation(process.env),
+        });
+        return;
+    }
+    // Read-only unless launching is granted by the flag. Bare `muster` down a
+    // pipe is the same server, so it is read-only too.
+    const allowLaunch = argv[0] === "mcp" && argv[1] === ALLOW_LAUNCH;
+    if (argv[0] === "mcp" && argv.length > (allowLaunch ? 2 : 1))
+        throw new Error(`mcp takes ${ALLOW_LAUNCH}, or one of ${MCP_SUBCOMMANDS.join(", ")}`);
     const muster = await Muster.create();
     let shutdown;
     const close = () => (shutdown ??= (async () => {
@@ -107,10 +129,16 @@ async function main() {
         });
     if (mcp) {
         const server = new Server({ name: "muster", version }, { capabilities: { tools: {} } });
+        const gate = toolGate(mcpToolNames(allowLaunch));
         server.setRequestHandler(ListToolsRequestSchema, async () => ({
-            tools: MCP_TOOLS,
+            tools: gate.expose(MCP_TOOLS),
         }));
         server.setRequestHandler(CallToolRequestSchema, async ({ params }) => {
+            if (!gate.allows(params.name))
+                return {
+                    content: [{ type: "text", text: notEnabled(params.name) }],
+                    isError: true,
+                };
             try {
                 const args = params.arguments ?? {};
                 switch (params.name) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brutalsystems/muster",
-  "version": "1.2.2",
+  "version": "2.0.0",
   "description": "Launch instructed, reachable local agent sessions",
   "type": "module",
   "engines": {
@@ -21,7 +21,7 @@
     "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
     "prepack": "npm run build",
     "prepublishOnly": "npm test",
-    "version": "node scripts/stamp-release-notes.mjs && git add RELEASE_NOTES.md",
+    "version": "node scripts/stamp-release-notes.mjs && node scripts/stamp-plugin-version.mjs && git add RELEASE_NOTES.md plugins/claude-code/.claude-plugin/plugin.json",
     "postversion": "git push origin HEAD --follow-tags"
   },
   "dependencies": {