@maka/maka-cli 5.142.0 → 5.143.1

package/bundle/typescript/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maka/maka-cli",
-  "version": "5.142.0",
+  "version": "5.143.1",
   "type": "module",
   "summary": "A command line tool for scaffolding Meteor 3.x applications using either React.",
   "description": "A command line tool for scaffolding Meteor 3.x applications using React.",
@@ -49,6 +49,7 @@
     "@inquirer/prompts": "^8.5.2",
     "@maka/meteor-sdk": "^0.2.13",
     "@maka/tar": "^6.2.2",
+    "@modelcontextprotocol/sdk": "^1.30.0",
     "blessed": "^0.1.81",
     "chalk": "^4.1.2",
     "change-case": "^5.4.4",
@@ -70,7 +71,8 @@
     "tar": "^7.4.3",
     "uuid": "^14.0.1",
     "ws": "^8.21.3",
-    "xtend": "^4.0.2"
+    "xtend": "^4.0.2",
+    "zod": "^4.5.4"
   },
   "devDependencies": {
     "@aws-sdk/types": "^3.974.4",

package/bundle/typescript/src/commands/game/sideQuest/utilities/backlog.js

@@ -115,8 +115,15 @@ export async function fetchReviewQueue() {
 }
 /** Answer, ask, or annotate one item. `kind` defaults to a plain note;
  *  a play-tester replying to a question posts an 'answer'. */
-export async function postBacklogComment(itemId, text, opts = {}) {
-    const token = authToken();
+export async function postBacklogComment(itemId, text, opts = {}, 
+// ADMIN OVERRIDE (2026-09-08). The MCP admin server (mcp.sub.cmd.ts)
+// reuses this for notes/questions posted as the service account,
+// which holds no entry in ~/.maka/global-config.json for authToken()
+// to find. Optional and trailing so every existing human-CLI call
+// site is untouched -- omitted, this is exactly the function it always
+// was.
+tokenOverride) {
+    const token = tokenOverride ?? authToken();
     if (!token)
         return 'no-login';
     try {
@@ -375,8 +382,12 @@ export async function setRole(action, email, role) {
  * in-review first, then open. `all` asks for everything anyway; a
  * specific `status` is always honoured exactly.
  */
-export async function fetchBacklog(status, opts = {}) {
-    const token = authToken();
+export async function fetchBacklog(status, opts = {}, 
+// ADMIN OVERRIDE, same reasoning as postBacklogComment's: the MCP
+// admin server has no human login for authToken() to find. Optional
+// and trailing so every existing call site is untouched.
+tokenOverride) {
+    const token = tokenOverride ?? authToken();
     if (!token)
         return { outcome: 'no-login' };
     try {
@@ -395,4 +406,162 @@ export async function fetchBacklog(status, opts = {}) {
         return { outcome: 'offline' };
     }
 }
+// ---------------------------------------------------------------------
+// ADMIN CALLS (2026-09-08), added for the MCP admin server
+// (sideQuest-backlog-mcp.sub.cmd.ts). Every function below takes its
+// token EXPLICITLY rather than falling back to authToken() -- these are
+// only ever called with the M2M service account's session, never a
+// human's, and a silent fallback to whichever human happens to be
+// logged in on this machine would be exactly the wrong default for an
+// admin action. All of them are the same house shape as everything
+// above: swallow errors, return an outcome, let the caller turn it into
+// prose (or, here, into an MCP tool error).
+// ---------------------------------------------------------------------
+/** One item, in full -- including fields /list withholds from a caller
+ *  who is not its reporter or an admin. `GET item/:id` is gated the same
+ *  as /list (mayUseBacklog), so this never needs a special admin path
+ *  server-side; the token being an admin's is what gets it the fuller
+ *  read. */
+export async function fetchBacklogItemById(itemId, token) {
+    try {
+        const res = await request('GET', `/${API_BASE}/item/${encodeURIComponent(itemId)}`, token);
+        if (res.statusCode === 401)
+            return { outcome: 'expired' };
+        if (res.statusCode === 403)
+            return { outcome: 'forbidden' };
+        if (res.statusCode === 404)
+            return { outcome: 'rejected' };
+        if (res.statusCode !== 200)
+            return { outcome: 'offline' };
+        const parsed = parseData(res.data);
+        return { outcome: 'ok', item: parsed?.item };
+    }
+    catch {
+        return { outcome: 'offline' };
+    }
+}
+/** THE ACTUAL RESOLUTION MOVE: attach evidence and/or advance status.
+ *  Admin-only server-side (`PATCH item/:id`), and gated there exactly as
+ *  documented in game-backlog-v1-rest-api.ts -- entering `in-review` or
+ *  `complete` without commits is refused with a `message` this function
+ *  passes straight through rather than flattening into a generic
+ *  "rejected", because that message is the instruction for what to do
+ *  differently (the MCP tool surfaces it verbatim to whoever is holding
+ *  the AI's hand at that point). */
+export async function patchBacklogItem(itemId, body, token) {
+    try {
+        const res = await request('PATCH', `/${API_BASE}/item/${encodeURIComponent(itemId)}`, token, body);
+        if (res.statusCode === 200 || res.statusCode === 201) {
+            const parsed = parseData(res.data);
+            return { outcome: 'ok', status: parsed?.status, commits: parsed?.commits };
+        }
+        if (res.statusCode === 401)
+            return { outcome: 'expired' };
+        if (res.statusCode === 403)
+            return { outcome: 'forbidden' };
+        if (res.statusCode === 400 || res.statusCode === 404) {
+            const parsed = parseData(res.data);
+            return { outcome: 'rejected', message: parsed?.message };
+        }
+        return { outcome: 'offline' };
+    }
+    catch {
+        return { outcome: 'offline' };
+    }
+}
+/** ASK THE SERVER TO DRAFT A BENCH for one item. Lands in `reproDraft`,
+ *  never `repro` -- promoting a draft to a real bench is a separate,
+ *  deliberate PATCH (patchBacklogItem with a `repro` body), same as the
+ *  web board and the REST route's own doc comment describe. Admin-only,
+ *  costs a model call server-side. */
+export async function draftBacklogBench(itemId, token, verbs) {
+    try {
+        const res = await request('POST', `/${API_BASE}/item/${encodeURIComponent(itemId)}/bench-draft`, token, verbs ? { verbs } : undefined);
+        if (res.statusCode === 200 || res.statusCode === 201) {
+            const parsed = parseData(res.data);
+            return { outcome: 'ok', reproDraft: parsed?.reproDraft };
+        }
+        if (res.statusCode === 401)
+            return { outcome: 'expired' };
+        if (res.statusCode === 403)
+            return { outcome: 'forbidden' };
+        if (res.statusCode === 400 || res.statusCode === 404) {
+            const parsed = parseData(res.data);
+            return { outcome: 'rejected', message: parsed?.message, code: parsed?.code };
+        }
+        return { outcome: 'offline' };
+    }
+    catch {
+        return { outcome: 'offline' };
+    }
+}
+/** THE BATCH FORM -- named ids only, never a selector (see the route's
+ *  own doc comment on why: a sweep over a spend path is exactly the
+ *  failure mode the per-item rule exists to prevent). Capped at 20 by
+ *  the server; this does not re-enforce that limit, so a caller sees the
+ *  server's own refusal if it is exceeded. */
+export async function draftBacklogBenches(ids, token) {
+    try {
+        const res = await request('POST', `/${API_BASE}/bench-drafts`, token, { ids });
+        if (res.statusCode === 200 || res.statusCode === 201) {
+            const parsed = parseData(res.data);
+            return { outcome: 'ok', drafted: parsed?.drafted, attempted: parsed?.attempted, results: parsed?.results };
+        }
+        if (res.statusCode === 401)
+            return { outcome: 'expired' };
+        if (res.statusCode === 403)
+            return { outcome: 'forbidden' };
+        if (res.statusCode === 400) {
+            const parsed = parseData(res.data);
+            return { outcome: 'rejected', message: parsed?.message };
+        }
+        return { outcome: 'offline' };
+    }
+    catch {
+        return { outcome: 'offline' };
+    }
+}
+/** RE-JUDGE ITEMS AGAINST THE RULEBOOKS. `all: true` re-grades the whole
+ *  board (a model call per item -- see the route's own doc comment on
+ *  why that is opt-in); the default only catches items whose first pass
+ *  ran without session context and now has one. */
+export async function revetBacklog(token, opts = {}) {
+    try {
+        const res = await request('POST', `/${API_BASE}/revet`, token, opts);
+        if (res.statusCode === 200 || res.statusCode === 201) {
+            const parsed = parseData(res.data);
+            return { outcome: 'ok', ...parsed };
+        }
+        if (res.statusCode === 401)
+            return { outcome: 'expired' };
+        if (res.statusCode === 403)
+            return { outcome: 'forbidden' };
+        return { outcome: 'offline' };
+    }
+    catch {
+        return { outcome: 'offline' };
+    }
+}
+/** THE M2M TOKEN EXCHANGE. Not gated behind authToken() at all -- there
+ *  is no Meteor session yet at the point this is called, that is
+ *  precisely what it establishes. Hits `/api/v1/auth`, not
+ *  `/api/v1/game-backlog`; `request()` takes a raw path, so this is the
+ *  one caller in the file that does not go through API_BASE. See
+ *  utilities/service-account-auth.ts for what obtains the Auth0 token
+ *  this expects and what caches the result. */
+export async function mintServiceAccountToken(auth0Token) {
+    try {
+        const res = await request('POST', '/api/v1/auth/m2m-login', '', { auth0Token });
+        if (res.statusCode === 200) {
+            const parsed = parseData(res.data);
+            return { outcome: 'ok', authToken: parsed?.authToken, userId: parsed?.userId, when: parsed?.when };
+        }
+        if (res.statusCode === 401)
+            return { outcome: 'expired' };
+        return { outcome: 'offline' };
+    }
+    catch {
+        return { outcome: 'offline' };
+    }
+}
 //# sourceMappingURL=backlog.js.map

package/bundle/typescript/src/commands/game/sideQuest/utilities/service-account-auth.js

@@ -0,0 +1,68 @@
+import https from 'https';
+import { mintServiceAccountToken } from './backlog.js';
+/** Client-credentials grant, direct to Auth0. Throws on any failure --
+ *  there is no partial-success shape worth returning here, and the
+ *  caller (ensureServiceSession below) is the one place that decides
+ *  what a failure means for the MCP server's own state. */
+async function getAuth0AccessToken(creds) {
+    const body = new URLSearchParams({
+        grant_type: 'client_credentials',
+        client_id: creds.clientId,
+        client_secret: creds.clientSecret,
+        audience: creds.audience,
+    }).toString();
+    return new Promise((resolve, reject) => {
+        const req = https.request({
+            hostname: creds.domain,
+            port: 443,
+            path: '/oauth/token',
+            method: 'POST',
+            timeout: 10000,
+            headers: {
+                'Content-Type': 'application/x-www-form-urlencoded',
+                'Content-Length': Buffer.byteLength(body),
+            },
+        }, (res) => {
+            let data = '';
+            res.on('data', (chunk) => { data += chunk; });
+            res.on('end', () => {
+                if (res.statusCode !== 200) {
+                    reject(new Error(`Auth0 token request failed (${res.statusCode}): ${data.slice(0, 300)}`));
+                    return;
+                }
+                try {
+                    const parsed = JSON.parse(data);
+                    if (!parsed.access_token)
+                        throw new Error('no access_token in Auth0 response');
+                    resolve(parsed.access_token);
+                }
+                catch (e) {
+                    reject(e instanceof Error ? e : new Error(String(e)));
+                }
+            });
+        });
+        req.on('timeout', () => req.destroy(new Error('Auth0 token request timeout')));
+        req.on('error', reject);
+        req.write(body);
+        req.end();
+    });
+}
+let cachedToken;
+/** THE ONE ENTRY POINT mcp.sub.cmd.ts calls. Returns a Meteor
+ *  x-auth-token for the service account, minting one on first use and
+ *  reusing it after that. `force: true` is what a 401 from any admin
+ *  call should trigger -- the cached token may have been revoked
+ *  (logoutAll, expiry) and one retry with a freshly minted token is
+ *  cheap insurance against surfacing a spurious failure. */
+export async function ensureServiceSession(creds, opts = {}) {
+    if (cachedToken && !opts.force)
+        return cachedToken;
+    const auth0Token = await getAuth0AccessToken(creds);
+    const minted = await mintServiceAccountToken(auth0Token);
+    if (minted.outcome !== 'ok' || !minted.authToken) {
+        throw new Error(`Could not establish a service-account session (${minted.outcome}).`);
+    }
+    cachedToken = minted.authToken;
+    return cachedToken;
+}
+//# sourceMappingURL=service-account-auth.js.map

package/bundle/typescript/src/commands/game/sideQuest-backlog-mcp.sub.cmd.js

@@ -0,0 +1,175 @@
+import fs from 'fs';
+import path from 'path';
+import { Command } from '../../command.js';
+import { UsageError } from '../../error.js';
+export function registerBacklogMcp(parent) {
+    return Command.create({
+        name: 'mcp',
+        usage: 'maka play:backlog:mcp [--env <env>] [--site <path>]',
+        // OFF, DELIBERATELY -- see the file header. The framework's own
+        // check fires before this handler runs at all and only knows how
+        // to look at process.cwd(); --site is this command's own way to
+        // satisfy the same requirement, so it needs the chance to try that
+        // first rather than being refused upstream of ever seeing it.
+        mustBeInMakaProject: false,
+        // NO maxArgLength HERE, DELIBERATELY. Command's own arg-length check
+        // is `args.length >= maxArgLength` (command.ts), so `maxArgLength: 0`
+        // refuses EVERY invocation regardless of what was typed -- an
+        // off-by-one in the shared framework, not something to work around
+        // per-command. No command in this codebase sets it to 0 for exactly
+        // that reason. This command takes no positionals; any stray one is
+        // simply ignored rather than rejected.
+        validOpts: [
+            {
+                name: 'env',
+                description: 'Which maka-cli.com config/<env>/process.env supplies the Auth0 M2M credentials (default: production).',
+            },
+            {
+                name: 'site',
+                description: 'Path to a maka-cli.com checkout. Defaults to resolving one from the current working directory if omitted -- pass this explicitly when the launching MCP client does not set cwd reliably.',
+            },
+        ],
+        shortDesc: 'Run an MCP server exposing game-backlog admin tools, authenticated as the M2M service account.',
+        description: `Starts a local MCP server (stdio transport) with tools for listing and reading
+    backlog items, attaching evidence and advancing status, drafting an AI bench, and posting
+    admin notes -- all against maka-cli.com's existing game-backlog REST API, authenticated as
+    the claude-agent@maka-cli.com service account via the Auth0 M2M token exchange
+    (api/v1/auth/m2m-login). Needs a maka-cli.com checkout to read AUTHZERO_DOMAIN /
+    AUTHZERO_CLIENT_ID / AUTHZERO_SECRET / AUTHZERO_AUDIENCE from config/<env>/process.env --
+    pass --site explicitly, or run with cwd already set to one.`,
+        examples: [
+            'maka play:backlog:mcp --site C:\\path\\to\\maka-cli.com',
+            'maka play:backlog:mcp --env local --site C:\\path\\to\\maka-cli.com',
+        ],
+    }, async function (_args, opts) {
+        const env = opts.env ?? 'production';
+        let processEnvPath;
+        if (opts.site) {
+            const siteConfigDir = path.join(path.resolve(opts.site), 'config', env);
+            processEnvPath = path.join(siteConfigDir, 'process.env');
+            if (!fs.existsSync(processEnvPath)) {
+                throw new UsageError(`No config/${env}/process.env under --site ${opts.site} (looked for ${processEnvPath}).`);
+            }
+        }
+        else {
+            if (!this.cfg.checkConfigExists(env)) {
+                // Pre-handshake failure -- nothing has touched stdout as MCP
+                // protocol yet, so a plain thrown Error (which Command's own
+                // wrapper reports via Log.error) is fine here.
+                throw new UsageError(`Not in a maka-cli.com checkout and no --site given (looked for config/${env} under ${process.cwd()}).`);
+            }
+            const configPath = this.cfg.getAppConfigPath(env);
+            processEnvPath = path.join(configPath, 'process.env');
+        }
+        const [domain, clientId, clientSecret, audience] = await Promise.all([
+            this.dotenvx.get('AUTHZERO_DOMAIN', processEnvPath),
+            this.dotenvx.get('AUTHZERO_CLIENT_ID', processEnvPath),
+            this.dotenvx.get('AUTHZERO_SECRET', processEnvPath),
+            this.dotenvx.get('AUTHZERO_AUDIENCE', processEnvPath),
+        ]);
+        if (!domain || !clientId || !clientSecret || !audience) {
+            throw new Error(`AUTHZERO_DOMAIN/CLIENT_ID/SECRET/AUDIENCE must all be set in config/${env}/process.env`);
+        }
+        const creds = { domain, clientId, clientSecret, audience };
+        // WHICH HOSTNAME THE HTTP TRANSPORT HITS is a SEPARATE switch from
+        // which config supplied these credentials -- utilities/backlog.ts's
+        // request() picks localhost vs www.maka-cli.com off `MAKA_DEV`
+        // (read once, at that module's first import), which is this CLI's
+        // own long-standing convention and has nothing to do with `--env`
+        // by default. Without this, `--env local` would mint a token
+        // against maka-cli.com's real local Auth0 credentials and then
+        // still call PRODUCTION with it. Only `local` flips it -- there is
+        // no separately-served "development" host in this cluster today
+        // (nothing deploys that environment; see maka-cli.com's CLAUDE.md),
+        // so that one still targets production same as the default.
+        if (env === 'local' && !process.env.MAKA_DEV) {
+            process.env.MAKA_DEV = 'True';
+        }
+        // Heavy/optional imports, lazily loaded inside the handler -- the
+        // same discipline sideQuest-backlog.sub.cmd.ts documents for the
+        // game graph, so `maka --help` and unrelated commands never pay for
+        // these.
+        const { McpServer } = await import('@modelcontextprotocol/sdk/server/mcp.js');
+        const { StdioServerTransport } = await import('@modelcontextprotocol/sdk/server/stdio.js');
+        const { z } = await import('zod');
+        const { ensureServiceSession } = await import('./sideQuest/utilities/service-account-auth.js');
+        const { fetchBacklog, fetchBacklogItemById, patchBacklogItem, draftBacklogBench, postBacklogComment, BACKLOG_STATUSES, } = await import('./sideQuest/utilities/backlog.js');
+        const statusEnum = BACKLOG_STATUSES;
+        /** Every tool call goes through this: reuse the cached session, and
+         *  on the first `expired` outcome, mint a fresh one and retry
+         *  exactly once. A second failure is surfaced rather than looping
+         *  forever. */
+        async function withSession(call) {
+            const token = await ensureServiceSession(creds);
+            const result = await call(token);
+            if (result.outcome !== 'expired')
+                return result;
+            const fresh = await ensureServiceSession(creds, { force: true });
+            return call(fresh);
+        }
+        /** House shape for a tool result: JSON in, MCP text-content out. A
+         *  non-'ok' outcome is reported as `isError` so the calling model
+         *  sees a refusal it can act on (or explain to the human) rather
+         *  than a raw protocol exception. */
+        function toolResult(value) {
+            return {
+                content: [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+                isError: value.outcome !== 'ok',
+            };
+        }
+        const server = new McpServer({ name: 'maka-play-backlog', version: '1.0.0' });
+        server.registerTool('backlog_list', {
+            title: 'List backlog items',
+            description: 'List game-backlog items, optionally filtered by status. Closed (complete) items are excluded unless a status is given explicitly.',
+            inputSchema: {
+                status: z.enum(statusEnum).optional()
+                    .describe('Filter to one status. Omit to see everything not yet complete.'),
+            },
+        }, async ({ status }) => toolResult(await withSession((token) => fetchBacklog(status, { all: false }, token))));
+        server.registerTool('backlog_get', {
+            title: 'Read one backlog item',
+            description: 'Read a single game-backlog item in full, by id.',
+            inputSchema: { itemId: z.string().describe('The backlog item id.') },
+        }, async ({ itemId }) => toolResult(await withSession((token) => fetchBacklogItemById(itemId, token))));
+        server.registerTool('backlog_comment', {
+            title: 'Comment on a backlog item',
+            description: 'Post an admin note or a question to the reporter on a backlog item. A "question" with awaitingReporter puts it in the reporter\'s review queue and tomorrow\'s digest; a "note" does neither.',
+            inputSchema: {
+                itemId: z.string(),
+                text: z.string().min(1),
+                kind: z.enum(['question', 'note']).default('note'),
+                awaitingReporter: z.boolean().optional()
+                    .describe('Only meaningful with kind "question" -- puts this item in the reporter\'s queue.'),
+            },
+        }, async ({ itemId, text, kind, awaitingReporter }) => toolResult(await withSession(async (token) => ({
+            outcome: await postBacklogComment(itemId, text, { kind, awaitingReporter }, token),
+        }))));
+        server.registerTool('backlog_advance', {
+            title: 'Advance a backlog item (attach evidence / change status)',
+            description: `Move a backlog item's status and/or attach fix-commit evidence. This is the
+        actual resolution action -- it will be refused by the server (with a message explaining
+        why) if you try to enter "in-review" or "complete" without at least one commit attached,
+        or "complete" without the reporter's sign-off already on the item. This tool never signs
+        off or rejects a fix on the reporter's behalf -- only the person who filed the item can
+        do that, in-game.`,
+            inputSchema: {
+                itemId: z.string(),
+                status: z.enum(statusEnum),
+                commits: z.array(z.string()).optional()
+                    .describe('Fix-commit SHAs to attach (merged with whatever is already there).'),
+            },
+        }, async ({ itemId, status, commits }) => toolResult(await withSession((token) => patchBacklogItem(itemId, { status, commits }, token))));
+        server.registerTool('backlog_draft_bench', {
+            title: 'Draft an AI bench for a backlog item',
+            description: 'Ask the server to AI-draft a two-room repro bench for one item (lands in reproDraft, not repro -- a human has to dry-run and promote it separately via backlog_advance with a repro body). Costs a model call server-side.',
+            inputSchema: {
+                itemId: z.string(),
+                verbs: z.array(z.string()).optional().describe('The verbs available to reference in the bench steps.'),
+            },
+        }, async ({ itemId, verbs }) => toolResult(await withSession((token) => draftBacklogBench(itemId, token, verbs))));
+        const transport = new StdioServerTransport();
+        await server.connect(transport);
+        console.error('[play:backlog:mcp] ready');
+    }, parent);
+}
+//# sourceMappingURL=sideQuest-backlog-mcp.sub.cmd.js.map

package/bundle/typescript/src/commands/game/sideQuest-backlog.sub.cmd.js

@@ -1,5 +1,6 @@
 import ShadowrunCommand, { ShadowrunCompat } from './sideQuest.sub.cmd.js';
 import { Command } from '../../command.js';
+import { registerBacklogMcp } from './sideQuest-backlog-mcp.sub.cmd.js';
 // Registered under BOTH the new spelling (play:backlog) and the compat
 // sub (play:shadowrun:backlog) from ONE definition -- two commands, one
 // options object, one handler, so the pair cannot drift.
@@ -62,6 +63,9 @@ const registerBacklog = (parent) => Command.create({
         detachAsked,
     });
 }, parent);
-registerBacklog(ShadowrunCommand);
+const backlogCmd = registerBacklog(ShadowrunCommand);
 registerBacklog(ShadowrunCompat);
+// mcp: only under the live `play:` spelling -- a brand-new command has
+// no compat surface to preserve under `play:shadowrun:backlog:mcp`.
+registerBacklogMcp(backlogCmd);
 //# sourceMappingURL=sideQuest-backlog.sub.cmd.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maka/maka-cli",
-  "version": "5.142.0",
+  "version": "5.143.1",
   "type": "module",
   "summary": "A command line tool for scaffolding Meteor 3.x applications using either React.",
   "description": "A command line tool for scaffolding Meteor 3.x applications using React.",
@@ -49,6 +49,7 @@
     "@inquirer/prompts": "^8.5.2",
     "@maka/meteor-sdk": "^0.2.13",
     "@maka/tar": "^6.2.2",
+    "@modelcontextprotocol/sdk": "^1.30.0",
     "blessed": "^0.1.81",
     "chalk": "^4.1.2",
     "change-case": "^5.4.4",
@@ -70,7 +71,8 @@
     "tar": "^7.4.3",
     "uuid": "^14.0.1",
     "ws": "^8.21.3",
-    "xtend": "^4.0.2"
+    "xtend": "^4.0.2",
+    "zod": "^4.5.4"
   },
   "devDependencies": {
     "@aws-sdk/types": "^3.974.4",