melchizedek-agents 1.2.0 → 1.3.1

package/dist/scripts/mcp_server.js

@@ -0,0 +1,345 @@
+#!/usr/bin/env node
+/**
+ * scripts/mcp_server.ts — the `melchizedek-mcp` bin: syndicates as MCP tools
+ * (ADR 0125). Thin: it reads flags and the environment, loads the syndicates,
+ * refuses unsafe binds, and hands everything to lib/mcp/server.ts.
+ *
+ *   claude mcp add melch -- npx melchizedek-mcp
+ *   melchizedek-mcp --syndicate research_desk --syndicate tutor
+ *   melchizedek-mcp --http --port 4100
+ *
+ * Every console line goes to stderr: on stdio, stdout is the protocol.
+ *
+ * Flags:
+ *   --syndicate <id>      serve this syndicate (repeatable; a bare id may also
+ *                         resolve to the shipped examples/ and templates/).
+ *                         Positional ids work too. None: every YAML at the
+ *                         agents directory's root.
+ *   --agents-dir <dir>    the agents directory (MELCHIZEDEK_AGENTS_DIR, else
+ *                         <cwd>/config/agents)
+ *   --http                Streamable HTTP at /mcp instead of stdio
+ *   --host <addr>         HTTP bind (MCP_HOST, default 127.0.0.1)
+ *   --port <n>            HTTP port (MCP_PORT, default 4100)
+ *
+ * Environment (all optional):
+ *   MCP_SERVER_SECRET     bearer every HTTP request presents; required, 32+
+ *                         characters, on a bind beyond loopback
+ *   MCP_ALLOWED_HOSTS     comma list: Host names a non-loopback bind answers to
+ *   MCP_TRUST_PROXY       Express trust proxy (hop count, true/false, subnets)
+ *   MCP_RATE_LIMIT_PER_MINUTE   HTTP requests per minute per IP (240)
+ *   MCP_USER_ID           the scope a stdio client's sessions are stored under (default)
+ *   DATABASE_URL          Postgres for sessions, memory, turn locks, audit, credentials
+ *   A2A_TASK_TIMEOUT_MS, A2A_MAX_CONCURRENT_TASKS, A2A_MAX_CONCURRENT_PER_SCOPE,
+ *   A2A_MAX_CONCURRENT_PER_CALLER, A2A_TURN_LOCK_WAIT_MS, A2A_BUDGETS,
+ *   A2A_SHUTDOWN_GRACE_MS, MELCHIZEDEK_CREDENTIAL_KEY, OAUTH_REDIRECT_URI,
+ *   OAUTH_CALLBACK_IDENTITY, MELCHIZEDEK_OAUTH_HOSTS, MELCHIZEDEK_CREDENTIAL_HOSTS
+ *                         as melchizedek-serve reads them (scripts/a2a_server.ts)
+ */
+import { readdirSync, realpathSync } from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+/** The bin's flags. Throws, naming the flag, on one it does not know. */
+export function parseMcpArgs(argv) {
+    const out = { syndicates: [], http: false, help: false };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        const value = () => {
+            const v = argv[++i];
+            if (v === undefined || v.startsWith('--'))
+                throw new Error(`${a} needs a value`);
+            return v;
+        };
+        if (a === '--help' || a === '-h')
+            out.help = true;
+        else if (a === '--http')
+            out.http = true;
+        else if (a === '--stdio')
+            out.http = false;
+        else if (a === '--syndicate')
+            out.syndicates.push(value());
+        else if (a === '--agents-dir')
+            out.agentsDir = value();
+        else if (a === '--host')
+            out.host = value();
+        else if (a === '--port') {
+            const n = Number(value());
+            if (!Number.isInteger(n) || n < 0 || n > 65535)
+                throw new Error('--port must be a port number');
+            out.port = n;
+        }
+        else if (a.startsWith('-'))
+            throw new Error(`Unknown flag ${a} (see --help)`);
+        else
+            out.syndicates.push(a);
+    }
+    return out;
+}
+const HELP = [
+    'Usage: melchizedek-mcp [--syndicate <id>]... [--agents-dir <dir>] [--http [--host <addr>] [--port <n>]]',
+    '',
+    'Serves syndicates as MCP tools: one tool per syndicate ({ message, session_id? }),',
+    'plus melch_resume for a turn that paused (an approval, a question, an authorization).',
+    'stdio by default (Claude Code: claude mcp add melch -- npx melchizedek-mcp);',
+    '--http serves Streamable HTTP at /mcp on 127.0.0.1; a wider --host needs MCP_SERVER_SECRET.',
+    'Environment variables are listed at the top of scripts/mcp_server.ts.',
+].join('\n');
+function envInt(name, fallback) {
+    const raw = process.env[name]?.trim();
+    if (!raw)
+        return fallback;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n < 0)
+        throw new Error(`${name} must be a non-negative number`);
+    return Math.floor(n);
+}
+function trustProxy() {
+    const raw = process.env.MCP_TRUST_PROXY?.trim();
+    if (!raw)
+        return false;
+    if (/^\d+$/.test(raw))
+        return Number(raw);
+    if (raw === 'true')
+        return true;
+    if (raw === 'false')
+        return false;
+    return raw;
+}
+function fatal(message) {
+    console.error(`[MCP] ✗ FATAL: ${message}`);
+    process.exit(1);
+}
+export async function startMcpServer(argv = process.argv.slice(2)) {
+    let args;
+    try {
+        args = parseMcpArgs(argv);
+    }
+    catch (err) {
+        fatal(err instanceof Error ? err.message : String(err));
+    }
+    if (args.help) {
+        console.error(HELP);
+        process.exit(0);
+    }
+    if (args.agentsDir)
+        process.env.MELCHIZEDEK_AGENTS_DIR = path.resolve(args.agentsDir);
+    const { loadEnv, isPlaceholderValue } = await import('../lib/loadEnv.js');
+    loadEnv(import.meta.url);
+    // Sign in with ChatGPT is local only (ADR 0126). Over stdio this bin is one person's process, spawned by
+    // their own MCP client; --http can be reached by others, so it refuses like melchizedek-serve.
+    if (args.http) {
+        const { refuseChatGptSignInOnServedSurface } = await import('../lib/chatgpt/state.js');
+        try {
+            refuseChatGptSignInOnServedSurface('melchizedek-mcp --http');
+        }
+        catch (err) {
+            fatal(err instanceof Error ? err.message : String(err));
+        }
+    }
+    if (process.env.OTEL_CONSOLE_SPANS === undefined)
+        process.env.OTEL_CONSOLE_SPANS = 'false';
+    const { setLogLevel } = await import('../lib/runtime/logging.js');
+    setLogLevel('warn');
+    const log = (m) => console.error(`[MCP] ${m}`);
+    const warn = (m) => console.error(`[MCP] ⚠ ${m}`);
+    const { createMcpServer, mcpBindProblem, mcpHttpApp, serveMcpStdio, toolNameFor } = await import('../lib/mcp/server.js');
+    const { loadSyndicate, nestedLoader } = await import('../lib/loadSyndicate.js');
+    const { syndicateOAuthHostProblems } = await import('../lib/tools/oauthTools.js');
+    const { syndicateCredentialHostProblems } = await import('../lib/tools/credentialUses.js');
+    // ── Transport posture first: a refused bind loads nothing ────────────────
+    const host = args.host ?? (process.env.MCP_HOST?.trim() || '127.0.0.1');
+    const port = args.port ?? envInt('MCP_PORT', 4100);
+    let secret = process.env.MCP_SERVER_SECRET?.trim() || undefined;
+    if (secret && isPlaceholderValue(secret))
+        fatal('MCP_SERVER_SECRET is still a placeholder. Generate one: openssl rand -hex 32');
+    if (args.http) {
+        const problem = mcpBindProblem({ host, ...(secret ? { secret } : {}) });
+        if (problem)
+            fatal(problem);
+    }
+    // ── The syndicates: the exposure ──────────────────────────────────────────
+    const bindings = () => ({
+        current_date: new Date().toLocaleDateString('en-US', { year: 'numeric', month: 'long', day: 'numeric' }),
+    });
+    const agentsDir = path.resolve(process.env.MELCHIZEDEK_AGENTS_DIR ?? path.join(process.cwd(), 'config', 'agents'));
+    let files = args.syndicates.map((id) => (id.endsWith('.yaml') || id.endsWith('.yml') ? id : `${id}.yaml`));
+    const named = files.length > 0;
+    if (!named) {
+        try {
+            files = readdirSync(agentsDir)
+                .filter((f) => (f.endsWith('.yaml') || f.endsWith('.yml')) && f !== 'syndicateSchema.yaml')
+                .sort();
+        }
+        catch {
+            files = [];
+        }
+        if (!files.length)
+            fatal(`No syndicates at the root of ${agentsDir}. Name one: melchizedek-mcp --syndicate <id> (a shipped example works: --syndicate tutor).`);
+    }
+    const syndicates = [];
+    for (const file of files) {
+        try {
+            const config = loadSyndicate(file, { bindings: bindings(), shippedFallback: named });
+            // The operator's host allowlists hold here as on the A2A server (ADR 0114, ADR 0122).
+            const nested = nestedLoader(config, (ref) => loadSyndicate(ref, { bindings: bindings() }));
+            const load = (ref) => {
+                try {
+                    return nested(ref);
+                }
+                catch {
+                    return {};
+                }
+            };
+            const problems = [...syndicateOAuthHostProblems([config], { load }), ...syndicateCredentialHostProblems([config], { load })];
+            if (problems.length)
+                throw new Error(`refused by the operator's host allowlists:\n  - ${problems.join('\n  - ')}`);
+            syndicates.push({ id: toolNameFor(path.basename(file)), config });
+        }
+        catch (err) {
+            const why = err?.code === 'ENOENT' ? 'not found' : err instanceof Error ? err.message : String(err);
+            if (named)
+                fatal(`${file}: ${why}`);
+            warn(`Skipped ${file}: ${why.split('\n')[0]}`);
+        }
+    }
+    if (!syndicates.length)
+        fatal('No syndicate loaded.');
+    // ── Storage, budgets, tool credentials: as melchizedek-serve ─────────────
+    const databaseUrl = process.env.DATABASE_URL?.trim() || undefined;
+    let pg;
+    if (databaseUrl) {
+        const { postgresStorage } = await import('../lib/storage/postgres/index.js');
+        const { dbSchema } = await import('../lib/storage/schema.js');
+        pg = postgresStorage({
+            connectionString: databaseUrl,
+            schema: dbSchema(),
+            memory: { apiKey: process.env.GOOGLE_GENAI_API_KEY || process.env.GEMINI_API_KEY || '' },
+        });
+        const { compareSchema, schemaBehindMessage, shippedSchemaVersion } = await import('../lib/storage/schemaVersion.js');
+        const check = compareSchema(await pg.schemaVersion(), shippedSchemaVersion());
+        if (check.state === 'behind' && process.env.ALLOW_SCHEMA_MISMATCH?.trim().toLowerCase() !== 'true')
+            fatal(schemaBehindMessage(check));
+    }
+    let policy;
+    const budgetsJson = process.env.A2A_BUDGETS?.trim();
+    if (budgetsJson) {
+        const { budgets, memoryUsageStore, parseBudgets, postgresUsageStore } = await import('../lib/a2a/policy.js');
+        try {
+            policy = budgets(parseBudgets(budgetsJson), { store: pg ? postgresUsageStore(pg.pool) : memoryUsageStore() });
+        }
+        catch (err) {
+            fatal(err instanceof Error ? err.message : String(err));
+        }
+    }
+    const { oauthServerSetup, callbackIdentity } = await import('../lib/a2a/oauthSetup.js');
+    const { postgresCredentialRows } = await import('../lib/storage/postgres/credentialStore.js');
+    let oauth;
+    try {
+        oauth = oauthServerSetup({
+            configs: syndicates.map((s) => s.config),
+            load: (ref) => loadSyndicate(ref),
+            env: process.env,
+            ...(pg ? { rows: postgresCredentialRows(pg.pool), audit: pg.audit } : {}),
+            allowPrivate: process.env.ALLOW_PRIVATE_OPENAPI === 'true' || process.env.ALLOW_PRIVATE_MCP === 'true',
+        });
+    }
+    catch (err) {
+        fatal(err instanceof Error ? err.message : String(err));
+    }
+    for (const w of oauth.warnings)
+        warn(w);
+    const consent = oauth.toolCredentials?.consent;
+    if (consent && !args.http) {
+        warn('stdio serves no OAuth consent callback: a consent pause completes only where OAUTH_REDIRECT_URI is served by a server sharing this credential store.');
+    }
+    const mcp = createMcpServer({
+        syndicates,
+        ...(pg ? { sessionService: pg.sessionService, turnLock: pg.turnLock, audit: pg.audit } : {}),
+        ...(pg?.memoryService ? { memoryService: pg.memoryService } : {}),
+        taskTimeoutMs: envInt('A2A_TASK_TIMEOUT_MS', 15 * 60 * 1000),
+        maxConcurrentTasks: envInt('A2A_MAX_CONCURRENT_TASKS', 0),
+        maxConcurrentPerScope: envInt('A2A_MAX_CONCURRENT_PER_SCOPE', 4),
+        maxConcurrentPerCaller: envInt('A2A_MAX_CONCURRENT_PER_CALLER', 0),
+        turnLockWaitMs: envInt('A2A_TURN_LOCK_WAIT_MS', 30_000),
+        ...(policy ? { policy } : {}),
+        ...(oauth.toolCredentials ? { toolCredentials: oauth.toolCredentials } : {}),
+        log,
+        warn,
+    });
+    const toolList = syndicates.map((s) => s.id).join(', ');
+    const graceMs = envInt('A2A_SHUTDOWN_GRACE_MS', 25_000);
+    let stopping = false;
+    let closeHttp;
+    const stop = async (why) => {
+        if (stopping)
+            return;
+        stopping = true;
+        log(`${why}: waiting up to ${graceMs} ms for running turns.`);
+        const canceled = await mcp.shutdown(graceMs);
+        if (canceled > 0)
+            warn(`${canceled} turn(s) did not finish in time and were canceled.`);
+        await closeHttp?.().catch(() => { });
+        const { flushTracing } = await import('../lib/observability/tracer.js');
+        await flushTracing().catch(() => { });
+        await pg?.close().catch(() => { });
+        process.exit(0);
+    };
+    process.on('SIGTERM', () => void stop('SIGTERM'));
+    process.on('SIGINT', () => void stop('SIGINT'));
+    if (!args.http) {
+        const scope = process.env.MCP_USER_ID?.trim() || 'default';
+        const { HEADER_VALUE_PATTERN } = await import('../lib/a2a/identity.js');
+        if (!HEADER_VALUE_PATTERN.test(scope))
+            fatal('MCP_USER_ID must match [A-Za-z0-9._-]{1,64}');
+        await serveMcpStdio(mcp, { caller: { scopeKey: scope, caller: 'local' } });
+        log(`✓ Serving ${syndicates.length} syndicate tool(s) over stdio: ${toolList}`);
+        process.stdin.on('end', () => void stop('stdin closed'));
+        return;
+    }
+    const allowedHosts = process.env.MCP_ALLOWED_HOSTS?.split(',').map((s) => s.trim()).filter(Boolean);
+    const { consentCallback } = await import('../lib/a2a/app.js');
+    const app = mcpHttpApp(mcp, {
+        host,
+        port,
+        ...(secret ? { secret } : {}),
+        ...(allowedHosts?.length ? { allowedHosts } : {}),
+        trustProxy: trustProxy(),
+        rateLimitPerMinute: envInt('MCP_RATE_LIMIT_PER_MINUTE', 240),
+        ...(consent
+            ? {
+                beforeAuth: (a) => a.get(new URL(consent.redirectUri).pathname, consentCallback(consent, { requireCallerIdentity: callbackIdentity(process.env) === 'required', log, warn })),
+            }
+            : {}),
+        warn,
+    });
+    closeHttp = app.closeSessions;
+    // The secret is not needed past this point.
+    secret = undefined;
+    await new Promise((resolve) => {
+        app.listen(port, host, () => resolve());
+    });
+    log(`✓ Serving ${syndicates.length} syndicate tool(s) at http://${host.includes(':') ? `[${host}]` : host}:${port}/mcp: ${toolList}`);
+    log(`  auth     ${process.env.MCP_SERVER_SECRET?.trim() ? 'bearer MCP_SERVER_SECRET' : 'none (loopback only)'}`);
+    log(`  storage  ${pg ? 'postgres' : 'in-memory (lost on restart)'}`);
+    log(`  oauth    ${oauth.summary}`);
+}
+// Run-as-main guard on the realpath of argv[1] (the bin is a symlink; see a2a_server.ts).
+const invokedAsMain = (() => {
+    if (!process.argv[1])
+        return false;
+    try {
+        return import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href;
+    }
+    catch {
+        return import.meta.url === `file://${process.argv[1]}`;
+    }
+})();
+if (invokedAsMain) {
+    // Before anything else loads: stdout is the stdio protocol channel.
+    console.log = console.error;
+    console.info = console.error;
+    console.debug = console.error;
+    startMcpServer().catch((error) => {
+        console.error(`[MCP] ✗ ${error instanceof Error ? error.message : String(error)}`);
+        process.exit(1);
+    });
+}

package/dist/scripts/setup.d.ts

@@ -16,6 +16,8 @@
  *   npx melchizedek-setup --level 2 --write-env   # also create .env from .env.example
  *   npx melchizedek-setup --list
  *   npx melchizedek-setup --markdown          # ONBOARDING.md, regenerated
+ *   npx melchizedek-setup --chatgpt-signin    # Sign in with ChatGPT, local only (ADR 0126)
+ *   npx melchizedek-setup --chatgpt-signout | --chatgpt-status
  *
  * Never prints a value. `--write-env` never overwrites `.env`, leaves every
  * name blank, and refuses unless `git check-ignore` confirms `.env` is ignored.

package/dist/scripts/setup.js

@@ -16,6 +16,8 @@
  *   npx melchizedek-setup --level 2 --write-env   # also create .env from .env.example
  *   npx melchizedek-setup --list
  *   npx melchizedek-setup --markdown          # ONBOARDING.md, regenerated
+ *   npx melchizedek-setup --chatgpt-signin    # Sign in with ChatGPT, local only (ADR 0126)
+ *   npx melchizedek-setup --chatgpt-signout | --chatgpt-status
  *
  * Never prints a value. `--write-env` never overwrites `.env`, leaves every
  * name blank, and refuses unless `git check-ignore` confirms `.env` is ignored.
@@ -24,6 +26,7 @@ import { realpathSync } from 'node:fs';
 import { createInterface } from 'node:readline/promises';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { loadEnv } from '../lib/loadEnv.js';
+import { runChatGptSignIn, runChatGptSignOut, runChatGptStatus } from '../lib/chatgpt/cli.js';
 import { runDoctor } from '../lib/doctor.js';
 import { detectLevels, highestLevel, LEVELS, levelById, renderAuto, renderGuide, renderMenu, renderOnboardingDoc, writeEnvForLevel, } from '../lib/onboarding.js';
 const USAGE = `melchizedek-setup — start from what you have
@@ -34,6 +37,12 @@ const USAGE = `melchizedek-setup — start from what you have
   melchizedek-setup --list                the levels
   melchizedek-setup --markdown            every guide as Markdown (ONBOARDING.md)
 
+  melchizedek-setup --chatgpt-signin [--port <n>]
+                                          sign in with ChatGPT in your browser; OpenAI ids then run
+                                          on your ChatGPT plan on this machine (local only)
+  melchizedek-setup --chatgpt-signout     remove the stored tokens and revoke them at OpenAI
+  melchizedek-setup --chatgpt-status      where the sign-in is stored, and whether it is used
+
   --write-env   with --level or --auto: create .env from .env.example with the level's
                 names left blank (never overwrites; requires git to ignore .env)
   --clone | --package   spell commands for a clone or an installed package (default: detected)
@@ -80,6 +89,24 @@ export async function main(argv = process.argv.slice(2)) {
         console.log(renderMenu());
         return 0;
     }
+    if (args.includes('--chatgpt-signin')) {
+        loadEnv();
+        const port = flag('port');
+        const n = port === undefined ? undefined : Number(port);
+        if (n !== undefined && !(Number.isInteger(n) && n >= 0 && n <= 65535)) {
+            console.error('✗ --port must be a port number (0 picks a free one)');
+            return 2;
+        }
+        return runChatGptSignIn(n !== undefined ? { port: n } : {});
+    }
+    if (args.includes('--chatgpt-signout')) {
+        loadEnv();
+        return runChatGptSignOut();
+    }
+    if (args.includes('--chatgpt-status')) {
+        loadEnv();
+        return runChatGptStatus();
+    }
     if (args.includes('--markdown')) {
         process.stdout.write(renderOnboardingDoc());
         return 0;

package/dist/scripts/syndicate_chat.js

@@ -11,6 +11,8 @@ import { runtimeSetting } from '../lib/runtime/runtimeFlag.js';
 import { setLogLevel } from '../lib/runtime/logging.js';
 import { randomUUID } from 'node:crypto';
 import { loadEnv } from '../lib/loadEnv.js';
+import { runChatGptSignIn } from '../lib/chatgpt/cli.js';
+import { chatGptSignInRoutesOpenAi } from '../lib/chatgpt/state.js';
 // ── Model routing ─────────────────────────────────────────────────────────────
 // A model id resolves when an agent first calls it (lib/models/registry.ts),
 // after loadEnv() has read the keys from .env.
@@ -97,6 +99,11 @@ async function main() {
         process.env.OTEL_CONSOLE_SPANS = 'false';
     // MELCHIZEDEK_RUNTIME=adk (removed in 1.0.0) stops the chat here, naming the release.
     runtimeSetting();
+    // --chatgpt-signin: the browser sign-in first, then the chat (ADR 0126, local only).
+    if (process.argv.includes('--chatgpt-signin')) {
+        if ((await runChatGptSignIn()) !== 0)
+            process.exit(1);
+    }
     const apiKey = process.env.GOOGLE_GENAI_API_KEY || process.env.GEMINI_API_KEY;
     if (apiKey) {
         process.env.GEMINI_API_KEY = apiKey;
@@ -148,10 +155,12 @@ async function main() {
         : ['gemini']);
     if (!config.orchestrator.model)
         requiredProviders.add('gemini');
-    const missingKeys = [...requiredProviders].filter((p) => !providerKeyPresent(p));
+    const missingKeys = [...requiredProviders].filter((p) => !providerKeyPresent(p) && !(p === 'openai' && chatGptSignInRoutesOpenAi()));
     if (missingKeys.length > 0) {
         for (const p of missingKeys) {
             console.error(`${c.yellow}⚠ ${PROVIDERS[p].label} requires ${PROVIDERS[p].keyEnv}, which is not set.${c.reset}`);
+            if (p === 'openai')
+                console.error(`${c.dim}  (Or sign in with ChatGPT on this machine: add --chatgpt-signin, or run melchizedek-setup --chatgpt-signin.)${c.reset}`);
         }
         console.error(`${c.dim}  (Only syndicates whose every agent uses an ollama/* model run keyless.)${c.reset}`);
         process.exit(1);
@@ -202,8 +211,8 @@ async function main() {
     const rawArgs = process.argv.slice(2);
     const queryParts = [];
     for (let i = 0; i < rawArgs.length; i++) {
-        if (rawArgs[i] === '--')
-            continue; // drop bare separator
+        if (rawArgs[i] === '--' || rawArgs[i] === '--chatgpt-signin')
+            continue; // drop bare separator and the sign-in flag
         if ((rawArgs[i] === '--bind' || rawArgs[i] === '--bindings' || rawArgs[i] === '--syndicate') && i + 1 < rawArgs.length) {
             i++; // skip the value
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "melchizedek-agents",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "description": "A multi-model, multi-agent orchestration framework — YAML-defined syndicates on the engine's own agent loop, Supabase or Postgres session persistence, pgvector long-term memory. Companion repo to the lyceumagents.com curriculum.",
   "type": "module",
   "license": "MIT",
@@ -29,6 +29,7 @@
     "./a2a/identity": "./dist/lib/a2a/identity.js",
     "./a2a/policy": "./dist/lib/a2a/policy.js",
     "./a2a/limits": "./dist/lib/a2a/redisLimits.js",
+    "./mcp": "./dist/lib/mcp/server.js",
     "./registry": "./dist/lib/registry.js",
     "./server": "./dist/scripts/a2a_server.js",
     "./guards": "./dist/lib/guards/index.js",
@@ -47,16 +48,17 @@
     "./package.json": "./package.json"
   },
   "bin": {
-    "melchizedek-serve": "./dist/scripts/a2a_server.js",
-    "melchizedek-chat": "./dist/scripts/syndicate_chat.js",
-    "melchizedek-doctor": "./dist/scripts/doctor.js",
-    "melchizedek-skills": "./dist/scripts/skills_install.js",
-    "melchizedek-worker": "./dist/scripts/assistant_worker.js",
-    "melchizedek-db": "./dist/scripts/db.js",
-    "melchizedek-init": "./dist/scripts/init.js",
-    "melchizedek-setup": "./dist/scripts/setup.js",
-    "melchizedek-registry": "./dist/scripts/registry.js",
-    "melchizedek-codemod": "./dist/scripts/yaml_codemod.js"
+    "melchizedek-serve": "dist/scripts/a2a_server.js",
+    "melchizedek-mcp": "dist/scripts/mcp_server.js",
+    "melchizedek-chat": "dist/scripts/syndicate_chat.js",
+    "melchizedek-doctor": "dist/scripts/doctor.js",
+    "melchizedek-skills": "dist/scripts/skills_install.js",
+    "melchizedek-worker": "dist/scripts/assistant_worker.js",
+    "melchizedek-db": "dist/scripts/db.js",
+    "melchizedek-init": "dist/scripts/init.js",
+    "melchizedek-setup": "dist/scripts/setup.js",
+    "melchizedek-registry": "dist/scripts/registry.js",
+    "melchizedek-codemod": "dist/scripts/yaml_codemod.js"
   },
   "files": [
     "dist",
@@ -112,13 +114,14 @@
     "mcp:demo": "node --disable-warning=DEP0040 --experimental-strip-types scripts/demo_mcp_server.ts",
     "mcp:wiki": "node --disable-warning=DEP0040 --experimental-strip-types scripts/wiki/mcp_server.ts",
     "mcp:science": "node --disable-warning=DEP0040 --experimental-strip-types scripts/science_mcp_server.ts",
+    "mcp:serve": "node --disable-warning=DEP0040 --experimental-strip-types scripts/mcp_server.ts",
     "wiki:init": "node --disable-warning=DEP0040 --experimental-strip-types scripts/wiki/init.ts",
     "wiki:build": "node --disable-warning=DEP0040 --experimental-strip-types scripts/wiki/build.ts",
     "wiki:check": "node --disable-warning=DEP0040 --experimental-strip-types scripts/wiki/check.ts",
     "schema:gen": "node --disable-warning=DEP0040 --experimental-strip-types scripts/gen_syndicate_schema.ts",
     "yaml:codemod": "node --disable-warning=DEP0040 --experimental-strip-types scripts/yaml_codemod.ts",
     "start:a2a": "node --disable-warning=DEP0040 --experimental-strip-types scripts/a2a_server.ts",
-    "test": "node --disable-warning=DEP0040 --experimental-strip-types --test tests/**/*.test.ts",
+    "test": "node --disable-warning=DEP0040 --experimental-strip-types --import ./tests/helpers/isolateLocalState.ts --test tests/**/*.test.ts",
     "setup": "node --disable-warning=DEP0040 --experimental-strip-types scripts/setup.ts",
     "init": "node --disable-warning=DEP0040 --experimental-strip-types scripts/init.ts",
     "db": "node --disable-warning=DEP0040 --experimental-strip-types scripts/db.ts",

package/skills/README.md

@@ -15,9 +15,9 @@ This directory contains a suite of eleven Agent Skills built to the open SKILL.m
 
 Five onboarding skills route a person by what they have and walk the startup guide for it (`npx melchizedek-setup --level <id>` prints each guide):
 
-- `melchizedek-onboard`: The triage. Asks what the person has and routes to one of nine authentication levels and the skill below that owns it.
+- `melchizedek-onboard`: The triage. Asks what the person has and routes to one of ten authentication levels and the skill below that owns it.
 - `melchizedek-onboard-local`: No key: Ollama and the keyless syndicates.
-- `melchizedek-onboard-keys`: One provider's key, several, a gateway key, and the honest answer for a ChatGPT / Codex, Claude.ai or Gemini CLI sign-in.
+- `melchizedek-onboard-keys`: One provider's key, several, a gateway key, Sign in with ChatGPT on the person's own machine, and the honest answer for a Codex, Claude.ai or Gemini CLI sign-in.
 - `melchizedek-onboard-cloud`: Vertex AI, Amazon Bedrock and Azure OpenAI credentials.
 - `melchizedek-onboard-serve`: Serving to others: per-caller keys (BYOK), caller identities (`A2A_AUTH`), and OAuth tool grants.
 

package/skills/briefs/skills-readme.md

@@ -14,7 +14,7 @@ The skills (name → what it teaches):
 - `melchizedek-memory` → Supabase sessions and long-term memory: modes, schema, tools, extraction rules, inspection, erasure.
 - `melchizedek-models` → model ids and providers, keys, keyless Ollama, the gateway fallback, per-agent settings, the errors.
 - `melchizedek-scribe` → writing documents from a brief with the Scribe syndicate.
-- Five onboarding skills, written by hand rather than by the Scribe (they print their facts from `npx melchizedek-setup --level <id>`): `melchizedek-onboard` (triage to one of nine authentication levels), `melchizedek-onboard-local`, `melchizedek-onboard-keys`, `melchizedek-onboard-cloud`, `melchizedek-onboard-serve`.
+- Five onboarding skills, written by hand rather than by the Scribe (they print their facts from `npx melchizedek-setup --level <id>`): `melchizedek-onboard` (triage to one of ten authentication levels), `melchizedek-onboard-local`, `melchizedek-onboard-keys`, `melchizedek-onboard-cloud`, `melchizedek-onboard-serve`.
 - `--agents-md` also writes a pointer block into the project's `AGENTS.md`.
 Install (three ways):
 - From the package, into this project's `.claude/skills/` and `.agents/skills/` (the two locations that between them reach Claude Code, Codex, Cursor, OpenCode and Gemini CLI): `npx melchizedek-skills install` after `npm install melchizedek-agents`. `--for <targets>` picks platforms from `claude, agents, codex, cursor, opencode, gemini, all`; `--global` writes the home-directory locations instead; `--dir <path>` writes one explicit directory; `--only <names>` installs a subset; `--force` overwrites a file that differs; `--dry-run` prints without writing. `npx melchizedek-skills paths` prints the locations; `npx melchizedek-skills list` prints the skills. In a clone: `npm run skills:install -- <same flags>`.

package/skills/melchizedek-onboard/SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: melchizedek-onboard
-description: "Onboard a person to Melchizedek from whatever credentials they have: ask what they have (nothing, one or several provider API keys, a gateway key, Vertex AI / Bedrock / Azure access, a server to put in front of other people, OAuth tools, or a ChatGPT / Codex, Claude.ai or Gemini CLI sign-in), route them to one authentication level, and walk its startup guide without ever handling a key. Use when someone is setting up melchizedek-agents for the first time, asks which keys they need, says 'I have an X key' or 'I have a Codex login', or asks how to get started."
+description: "Onboard a person to Melchizedek from whatever credentials they have: ask what they have (nothing, one or several provider API keys, a gateway key, Vertex AI / Bedrock / Azure access, a server to put in front of other people, OAuth tools, a ChatGPT plan to use on their own machine, or a Codex, Claude.ai or Gemini CLI sign-in), route them to one authentication level, and walk its startup guide without ever handling a key. Use when someone is setting up melchizedek-agents for the first time, asks which keys they need, says 'I have an X key', 'I have ChatGPT Plus' or 'I have a Codex login', or asks how to get started."
 ---
 
 ## What this skill does
 
-It turns "what do you have?" into one of nine authentication levels and the startup guide for it. The guides are generated by the engine itself, so you print them instead of restating them:
+It turns "what do you have?" into one of ten authentication levels and the startup guide for it. The guides are generated by the engine itself, so you print them instead of restating them:
 
 ```bash
-npx melchizedek-setup --list                 # the nine levels
+npx melchizedek-setup --list                 # the ten levels
 npx melchizedek-setup --level <id|number>    # one level's guide
 npx melchizedek-setup --auto                 # detect from the environment, names only
 ```
@@ -20,12 +20,13 @@ In a clone of the repository, use `npm run setup -- <flags>` instead of `npx mel
 - Never ask the person to paste a key, token or secret into the chat, and never read one from their files or shell history. A pasted key lives in the transcript forever.
 - Never print a value from `.env`. To check what is set, run `npx melchizedek-setup --auto` or `npx melchizedek-doctor`; both report names and set or unset only.
 - The person types every value into `.env` in their own editor. You may create `.env` with names left blank: `npx melchizedek-setup --level <id> --write-env`. It never overwrites an existing `.env` and refuses unless git ignores `.env`.
-- Never reuse a consumer subscription sign-in (ChatGPT / Codex, Claude.ai, Gemini CLI) as a model credential. Route that person to level 9, which names the sanctioned alternative.
+- Never reuse another app's sign-in (the Codex CLI's login, Claude.ai, Gemini CLI) as a model credential, and never read its token files. Route that person to level 10, which names the sanctioned alternative.
+- A ChatGPT plan is used only through the engine's own Sign in with ChatGPT (level 9): the person runs `npx melchizedek-setup --chatgpt-signin` and approves in their own browser. It is for their own machine only; never set it up for a server.
 
 ## Triage
 
 1. Run `npx melchizedek-setup --auto`. If it already detects a level beyond 1, confirm with the person that this is what they want and continue from that guide.
-2. Otherwise ask one question: "What do you have: nothing yet, an API key from a model provider, a gateway key, cloud platform access, or a ChatGPT, Claude or Gemini sign-in? And will other people or backends call your agents?"
+2. Otherwise ask one question: "What do you have: nothing yet, an API key from a model provider, a gateway key, cloud platform access, a ChatGPT plan, or a Claude or Gemini sign-in? And will other people or backends call your agents?"
 3. Route by the answer:
 
 | They have | Level | Follow |
@@ -38,12 +39,33 @@ In a clone of the repository, use `npm run setup -- <flags>` instead of `npx mel
 | Callers who fund their own model calls | 6 `byok` | `melchizedek-onboard-serve` |
 | Other backends or users calling the server | 7 `caller-tokens` | `melchizedek-onboard-serve` |
 | Tools that act for each user on a third-party API | 8 `oauth-grants` | `melchizedek-onboard-serve` |
-| A ChatGPT / Codex, Claude.ai or Gemini CLI sign-in only | 9 `subscription-signin` | `melchizedek-onboard-keys` |
+| A ChatGPT plan, to use on their own machine | 9 `chatgpt-signin` | `melchizedek-onboard-keys` |
+| A Codex CLI login, a Claude.ai or a Gemini CLI sign-in only | 10 `subscription-signin` | `melchizedek-onboard-keys` |
 
 Levels 6 to 8 sit on top of a model level (1 to 5): settle how models are paid for first.
 
 4. Print the level's guide with `--level <id>` and walk it step by step: the person sets the variables, you run the doctor command the guide names and read its verdicts back to them, then you run the first command.
 
+## Use melch from Claude Code or Codex
+
+Once a level is confirmed, the person can call their syndicates from inside their coding agent: `melchizedek-mcp` makes each syndicate an MCP tool (`{ message, session_id? }`), plus `melch_resume` for a turn that pauses. Register it from the project directory, where `.env` and `config/agents/` live:
+
+```bash
+claude mcp add melch -- npx melchizedek-mcp --syndicate <id>
+```
+
+For Codex, add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.melch]
+command = "npx"
+args = ["-y", "-p", "melchizedek-agents", "melchizedek-mcp", "--syndicate", "<id>"]
+cwd = "/path/to/the/project"
+tool_timeout_sec = 900
+```
+
+When a result says an approval is waiting, ask the person and pass their decision to `melch_resume` with `approve`; never approve on their behalf. Keys stay in `.env`: the MCP registration names no key.
+
 ## Done when
 
 The doctor shows the level's confirmation (the guide's **Confirm** line), and the first command has answered once. Then hand over to the `melchizedek` skill for the catalog of syndicates.