@josfox/jos 4.0.8 → 5.0.0

package/src/mcp.js

@@ -0,0 +1,734 @@
+/**
+ * JOS MCP Server - Model Context Protocol Implementation
+ * JSON-RPC 2.0 over stdio for AI assistant integration
+ *
+ * Security model (SECURITY-MCP.md):
+ * - One root: the working directory, or the directory given with --root (its real path). The server refuses to
+ *   start when the root would be "/", the home directory or an ancestor of it, unless --root says so explicitly.
+ *   ~/.jos is no longer a root of its own.
+ * - Read-only by default: write_file exists only with --allow-write, and never writes under ~/.jos.
+ * - Every path is resolved to its real path (fs.realpathSync.native; for a path that does not exist yet, the real
+ *   path of its deepest existing ancestor) before it is compared with the root, and the file is then opened by that
+ *   real path with O_NOFOLLOW. `..`, symlinks, repeated slashes and other spellings all end at the same real path.
+ * - ~/.jos/secrets and everything in it, and any `.master` or `vault.json` under ~/.jos, are denied for reading,
+ *   writing, listing and searching, compared without regard to case (APFS and NTFS ignore case), whether the path
+ *   is spelled out or reached through a symlink. Besides the real path, the device and inode of the path and of
+ *   each of its ancestors are compared with ~/.jos/secrets and its entries (hard links, APFS case folding).
+ * - Out of root and protected give the same error, whether the file exists or not; no error carries file content.
+ * - The module tools (list_modules, hot_reload, list_processes) only read fixed files under ~/.jos (modules.json,
+ *   modules/, runs/) with the same denial: a link there into secrets reads as missing. toggle_module, which wrote
+ *   ~/.jos/modules.json, is removed.
+ * - run_command is off unless the server was started with `jos serve --mcp --allow-shell`: it is not listed and a
+ *   call is an unknown tool. With the flag it starts a program with an argv array (no shell), in a cwd inside the
+ *   root (never "/"), every command is announced on stderr and the child's environment drops every variable named
+ *   like a secret in ~/.jos/secrets (vault.json and keychain.json). It still runs as the user and can read
+ *   ~/.jos/secrets itself (`cat`). That is why it is off by default.
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const readline = require('readline');
+const ui = require('./ui');
+const guide = require('./mcp-guide');
+
+// MCP Protocol version
+const PROTOCOL_VERSION = '2024-11-05';
+const SERVER_NAME = 'jos-mcp-server';
+const SERVER_VERSION = '1.0.0';
+const SHELL_TOOL = 'run_command';
+// Tools that exist only with a flag: tool name -> context switch.
+const GATED = { run_command: 'allowShell', write_file: 'allowWrite' };
+
+// Flags a platform lacks (Windows) are 0: `undefined | 0` is 0.
+const O_NOFOLLOW = fs.constants.O_NOFOLLOW | 0;
+const O_NONBLOCK = fs.constants.O_NONBLOCK | 0; // a FIFO in the root must not hang the server
+const MAX_READ = 10 * 1024 * 1024;
+const MAX_TIMEOUT = 10 * 60 * 1000;
+const DENIED = 'Access denied: path is outside the working directory or protected';
+const SHELL_REFUSED = 'run_command refused: cannot tell which variables are secrets: ~/.jos/secrets/';
+
+const isPlainObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+const hasOwn = (o, k) => Object.prototype.hasOwnProperty.call(o, k);
+const strings = (v) => (Array.isArray(v) ? v.filter((x) => typeof x === 'string') : []);
+
+// ------------------------------------------------------------------------------------------- path policy
+
+// Case and Unicode form folded, for the denial only (never to widen the root).
+const fold = (p) => p.normalize('NFC').toLowerCase();
+
+// p equals base or lies under it. Trailing separators are stripped first so that a root of "/" works.
+function within(p, base) {
+    return p === base || p.startsWith(base.replace(/[\\/]+$/, '') + path.sep);
+}
+
+// The real path of `abs`; for a path that does not exist yet, the real path of its deepest existing ancestor
+// joined with the missing components. null when the way there is a dangling symlink, a loop, a component that
+// is not a directory or anything unreadable: such a path is denied.
+function canonical(abs) {
+    const rest = [];
+    let cur = abs;
+    for (;;) {
+        try {
+            return path.join(fs.realpathSync.native(cur), ...rest);
+        } catch (e) {
+            if (e.code !== 'ENOENT' || isLink(cur)) return null;
+            rest.unshift(path.basename(cur));
+            cur = path.dirname(cur);
+        }
+    }
+}
+
+function isLink(p) {
+    try { return fs.lstatSync(p).isSymbolicLink(); } catch (e) { return false; }
+}
+
+const inodeKey = (st) => st.dev + ':' + st.ino;
+
+// The protected locations for one tool call, recomputed every time (a vault created while the server runs is
+// protected from its first byte). Lexical and real forms of ~/.jos and ~/.jos/secrets, folded.
+function guard(ctx) {
+    const jos = ctx.home;
+    const secrets = path.join(jos, 'secrets');
+    const josForms = [jos, canonical(jos)].filter(Boolean).map(fold);
+    const secretForms = [secrets, canonical(secrets)].filter(Boolean).map(fold);
+    let inodes = null;
+    return {
+        josForms,
+        // A write never lands under ~/.jos (lexical or real form).
+        underJos(p) { const f = fold(p); return josForms.some((j) => within(f, j)); },
+        isProtected(p) {
+            const f = fold(p);
+            if (secretForms.some((s) => within(f, s))) return true;
+            const base = path.basename(f);
+            return (base === '.master' || base === 'vault.json') && josForms.some((j) => within(f, j));
+        },
+        // dev:ino of ~/.jos/secrets and of every entry in it: a path whose own inode or any ancestor's is one of
+        // these is inside the secrets, whatever its name (hard link, case folding, a bind or firmlink).
+        inodes() {
+            if (inodes) return inodes;
+            inodes = new Set();
+            const dir = canonical(secrets);
+            let names = [];
+            try {
+                inodes.add(inodeKey(fs.statSync(dir)));
+                names = fs.readdirSync(dir);
+            } catch (e) { /* no secrets directory: nothing to match */ }
+            for (const n of names) {
+                try { inodes.add(inodeKey(fs.statSync(path.join(dir, n)))); } catch (e) { /* a dangling entry */ }
+            }
+            return inodes;
+        },
+        // dev:ino of ~/.jos itself, for writes.
+        josInode() {
+            const st = fs.statSync(jos, { throwIfNoEntry: false });
+            return st ? inodeKey(st) : null;
+        },
+    };
+}
+
+// True when `real` or one of its existing ancestors has one of the given dev:ino keys.
+function ancestorHits(real, keys) {
+    let cur = real, prev = null;
+    while (cur !== prev) {
+        const st = fs.statSync(cur, { throwIfNoEntry: false });
+        if (st && keys.has(inodeKey(st))) return true;
+        prev = cur;
+        cur = path.dirname(cur);
+    }
+    return false;
+}
+
+// A path given by the client, checked: its real path, inside the root, not protected by name nor by the inode of
+// itself or an ancestor, and for a write not under ~/.jos at all. Otherwise DENIED, whether the file exists or not.
+function checkedPath(ctx, g, input, what, write) {
+    if (typeof input !== 'string' || input.includes('\0')) throw new Error('Invalid params: ' + what + ' must be a string');
+    const abs = path.resolve(ctx.root, input);
+    const real = canonical(abs);
+    if (real === null || !within(real, ctx.root) || g.isProtected(abs) || g.isProtected(real)) throw new Error(DENIED);
+    const keys = new Set(g.inodes());
+    if (write) {
+        if (g.underJos(abs) || g.underJos(real)) throw new Error(DENIED);
+        keys.add(g.josInode());
+    }
+    if (ancestorHits(real, keys)) throw new Error(DENIED);
+    return real;
+}
+
+// A fixed file under ~/.jos (modules.json, runs/...): its real path, or null when it is protected or unresolvable.
+function homePath(ctx, g, ...parts) {
+    const real = canonical(path.join(ctx.home, ...parts));
+    return real === null || g.isProtected(real) ? null : real;
+}
+
+// Opens an already checked real path without following a symlink put there since, and refuses a hard link to a
+// secret. `shown` is the path as the client wrote it (never the real path, never content).
+function openChecked(g, real, write, shown) {
+    const flags = (write ? fs.constants.O_WRONLY | fs.constants.O_CREAT : fs.constants.O_RDONLY) | O_NOFOLLOW | O_NONBLOCK;
+    let fd;
+    try { fd = fs.openSync(real, flags, 0o666); } catch (e) {
+        throw new Error(e.code === 'ENOENT' ? 'File not found: ' + shown : 'Cannot open ' + shown + ': ' + e.code);
+    }
+    try {
+        const st = fs.fstatSync(fd);
+        if (g.inodes().has(inodeKey(st))) throw new Error(DENIED);
+        return { fd, st };
+    } catch (e) {
+        fs.closeSync(fd);
+        throw e;
+    }
+}
+
+// An entry met while listing or searching: hidden when protected, or when it is a symlink that leaves the root,
+// dangles or ends in a protected place.
+function visible(ctx, g, fullPath, entry) {
+    if (g.isProtected(fullPath)) return false;
+    if (entry.isSymbolicLink()) {
+        const real = canonical(fullPath);
+        if (real === null || !within(real, ctx.root) || g.isProtected(real)) return false;
+    }
+    // A hard link to a secret is hidden too (a missing entry, gone since readdir, is harmless to show).
+    const st = fs.statSync(fullPath, { throwIfNoEntry: false });
+    return !st || !g.inodes().has(inodeKey(st));
+}
+
+// JSON of a fixed file under ~/.jos, or undefined when missing, protected, unreadable or not JSON.
+function readHomeJson(ctx, g, ...parts) {
+    const real = homePath(ctx, g, ...parts);
+    if (real === null) return undefined;
+    try {
+        const { fd } = openChecked(g, real, false, parts.join('/'));
+        try { return JSON.parse(fs.readFileSync(fd, 'utf8')); } finally { fs.closeSync(fd); }
+    } catch (e) {
+        return undefined;
+    }
+}
+
+function readModulesConfig(ctx, g) {
+    const raw = readHomeJson(ctx, g, 'modules.json');
+    return isPlainObject(raw) ? raw : { enabled: [], disabled: [] };
+}
+
+// Names of the secrets (vault.json keys and keychain.json names), upper-cased. A file that exists but cannot be
+// read or has another shape refuses the command: better no shell than a shell with a secret in its environment.
+function secretNames(ctx) {
+    const dir = path.join(ctx.home, 'secrets');
+    const sources = [
+        ['vault.json', (d) => (isPlainObject(d) ? Object.keys(d) : null)],
+        ['keychain.json', (d) => (isPlainObject(d) && Array.isArray(d.names) ? d.names.map(String) : null)],
+    ];
+    const names = new Set();
+    for (const [file, pick] of sources) {
+        let text;
+        try { text = fs.readFileSync(path.join(dir, file), 'utf8'); } catch (e) {
+            if (e.code === 'ENOENT') continue;
+            throw new Error(SHELL_REFUSED + file + ' cannot be read (' + e.code + ')');
+        }
+        let list = null;
+        try { list = pick(JSON.parse(text)); } catch (e) { /* reported below */ }
+        if (list === null) throw new Error(SHELL_REFUSED + file + ' does not have the expected shape');
+        for (const n of list) names.add(n.toUpperCase());
+    }
+    return names;
+}
+
+// The child's environment: the server's, minus every variable named like a secret (compared without case, so
+// that Windows' case-insensitive names cannot slip through). This also drops what `jos secrets exec` injected.
+function childEnv(ctx) {
+    const drop = secretNames(ctx);
+    const env = {};
+    for (const [k, v] of Object.entries(ctx.env)) if (!drop.has(k.toUpperCase())) env[k] = v;
+    return env;
+}
+
+// Glob match on one name: `*` any run, `?` one character, everything else literal. Linear backtracking only (no
+// RegExp built from client text, so no catastrophic backtracking).
+function globMatch(pattern, name) {
+    let i = 0, j = 0, star = -1, mark = 0;
+    while (j < name.length) {
+        if (i < pattern.length && (pattern[i] === '?' || pattern[i] === name[j])) { i++; j++; }
+        else if (pattern[i] === '*') { star = i++; mark = j; }
+        else if (star !== -1) { i = star + 1; j = ++mark; }
+        else return false;
+    }
+    while (pattern[i] === '*') i++;
+    return i === pattern.length;
+}
+
+// ---------------------------------------------------------------------------------------------- tools
+
+// Tool definitions for MCP
+const TOOLS = [
+    {
+        name: 'list_files',
+        description: 'List files and directories in a given path (inside the working directory)',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'Directory path to list' },
+                recursive: { type: 'boolean', description: 'List recursively (max depth 3)', default: false }
+            },
+            required: ['path']
+        }
+    },
+    {
+        name: 'read_file',
+        description: 'Read the contents of a file (inside the working directory)',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'File path to read' },
+                encoding: { type: 'string', description: 'File encoding', default: 'utf8' }
+            },
+            required: ['path']
+        }
+    },
+    {
+        name: 'write_file',
+        description: 'Write content to a file (creates or overwrites; inside the working directory, never under ~/.jos; only with jos serve --mcp --allow-write)',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'File path to write' },
+                content: { type: 'string', description: 'Content to write' }
+            },
+            required: ['path', 'content']
+        }
+    },
+    {
+        name: 'search_files',
+        description: 'Search for files whose name matches a glob pattern (inside the working directory)',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                directory: { type: 'string', description: 'Directory to search in' },
+                pattern: { type: 'string', description: 'Glob on the file name: * any run, ? one character (e.g. "*.jos")' }
+            },
+            required: ['directory', 'pattern']
+        }
+    },
+    {
+        name: 'read_markdown',
+        description: 'Read and return markdown file content with metadata',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'Markdown file path' }
+            },
+            required: ['path']
+        }
+    },
+    {
+        name: 'list_modules',
+        description: 'List available JOS modules in ~/.jos/modules',
+        inputSchema: {
+            type: 'object',
+            properties: {}
+        }
+    },
+    {
+        name: 'hot_reload',
+        description: 'Reload JOS module state from disk',
+        inputSchema: {
+            type: 'object',
+            properties: {}
+        }
+    },
+    {
+        name: SHELL_TOOL,
+        description: 'Run a program with arguments, without a shell, and return its output (only with jos serve --mcp --allow-shell)',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                command: { type: 'string', description: 'Program to run (a name looked up in PATH, or a path); no shell' },
+                args: { type: 'array', items: { type: 'string' }, description: 'Arguments, one per item (default: none)', default: [] },
+                cwd: { type: 'string', description: 'Working directory (optional, inside the working directory, not "/")' },
+                timeout: { type: 'number', description: 'Timeout in ms (default: 30000, max 600000)', default: 30000 }
+            },
+            required: ['command']
+        }
+    },
+    {
+        name: 'list_processes',
+        description: 'List running JOS shadow clones/processes',
+        inputSchema: {
+            type: 'object',
+            properties: {}
+        }
+    }
+];
+
+// Tool handlers
+const toolHandlers = {
+    async list_files({ path: dirPath, recursive = false }, ctx) {
+        const g = guard(ctx);
+        const real = checkedPath(ctx, g, dirPath, 'path');
+        let stat;
+        try { stat = fs.statSync(real); } catch (e) { throw new Error('Path not found: ' + dirPath); }
+        if (!stat.isDirectory()) throw new Error('Not a directory: ' + dirPath);
+
+        const results = [];
+        const scan = (dir, depth) => {
+            for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+                if (entry.name.startsWith('.') || entry.name === 'node_modules') continue;
+                const fullPath = path.join(dir, entry.name);
+                if (!visible(ctx, g, fullPath, entry)) continue;
+                results.push({
+                    name: entry.name,
+                    path: path.relative(ctx.root, fullPath),
+                    type: entry.isDirectory() ? 'directory' : 'file',
+                    size: entry.isFile() ? fs.statSync(fullPath).size : undefined
+                });
+                if (entry.isDirectory() && recursive && depth < 3) scan(fullPath, depth + 1);
+            }
+        };
+        scan(real, 0);
+        return { files: results, count: results.length };
+    },
+
+    async read_file({ path: filePath, encoding = 'utf8' }, ctx) {
+        if (!Buffer.isEncoding(encoding)) throw new Error('Invalid params: unknown encoding');
+        const g = guard(ctx);
+        const real = checkedPath(ctx, g, filePath, 'path');
+        const { fd, st } = openChecked(g, real, false, filePath);
+        try {
+            if (st.isDirectory()) throw new Error('Cannot read directory as file: ' + filePath);
+            if (!st.isFile()) throw new Error('Not a regular file: ' + filePath);
+            if (st.size > MAX_READ) throw new Error('File too large (max 10MB)');
+            const content = fs.readFileSync(fd, encoding);
+            return { content, path: filePath, size: st.size, modified: st.mtime.toISOString() };
+        } finally {
+            fs.closeSync(fd);
+        }
+    },
+
+    async write_file({ path: filePath, content }, ctx) {
+        if (typeof content !== 'string') throw new Error('Invalid params: content must be a string');
+        const g = guard(ctx);
+        const real = checkedPath(ctx, g, filePath, 'path', true);
+        try { fs.mkdirSync(path.dirname(real), { recursive: true }); } catch (e) {
+            throw new Error('Cannot write ' + filePath + ': ' + e.code);
+        }
+        // Opened without O_TRUNC: the inode is checked first, then the file is truncated through the same fd.
+        const { fd } = openChecked(g, real, true, filePath);
+        try {
+            fs.ftruncateSync(fd, 0);
+            fs.writeFileSync(fd, content, 'utf8');
+        } finally {
+            fs.closeSync(fd);
+        }
+        return { success: true, path: filePath, size: Buffer.byteLength(content, 'utf8') };
+    },
+
+    async search_files({ directory, pattern }, ctx) {
+        if (typeof pattern !== 'string' || pattern.length > 1024) throw new Error('Invalid params: pattern must be a string of at most 1024 characters');
+        const g = guard(ctx);
+        const real = checkedPath(ctx, g, directory, 'directory');
+        const glob = pattern.replace(/^(\*\*\/)+/, ''); // names have no "/": "**/*.jos" means "*.jos" at any depth
+        const results = [];
+        const scan = (dir, depth) => {
+            if (depth > 5) return;
+            try {
+                for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+                    if (results.length >= 100) return;
+                    if (entry.name.startsWith('.') || entry.name === 'node_modules') continue;
+                    const fullPath = path.join(dir, entry.name);
+                    if (!visible(ctx, g, fullPath, entry)) continue;
+                    if (globMatch(glob, entry.name)) {
+                        results.push({
+                            name: entry.name,
+                            path: path.relative(ctx.root, fullPath),
+                            type: entry.isDirectory() ? 'directory' : 'file'
+                        });
+                    }
+                    if (entry.isDirectory()) scan(fullPath, depth + 1);
+                }
+            } catch (e) { /* not a directory, or no permission: nothing found there */ }
+        };
+        scan(real, 0);
+        return { matches: results, count: results.length };
+    },
+
+    async read_markdown({ path: filePath }, ctx) {
+        const result = await toolHandlers.read_file({ path: filePath }, ctx);
+        return {
+            content: result.content,
+            path: filePath,
+            type: 'markdown',
+            lines: result.content.split('\n').length
+        };
+    },
+
+    async list_modules(params, ctx) {
+        const g = guard(ctx);
+        const config = readModulesConfig(ctx, g);
+        const enabledList = Array.isArray(config.enabled) ? config.enabled : null; // no list: all enabled
+        let entries = [];
+        try { entries = fs.readdirSync(homePath(ctx, g, 'modules'), { withFileTypes: true }); } catch (e) { /* no modules */ }
+        const modules = [];
+        for (const entry of entries) {
+            if (!entry.isDirectory()) continue;
+            const raw = readHomeJson(ctx, g, 'modules', entry.name, 'package.json');
+            const meta = isPlainObject(raw) ? raw : {};
+            modules.push({
+                name: entry.name,
+                version: meta.version || '1.0.0',
+                description: meta.description || '',
+                enabled: enabledList === null || enabledList.includes(entry.name)
+            });
+        }
+        return { modules, count: modules.length };
+    },
+
+    async hot_reload(params, ctx) {
+        const config = readModulesConfig(ctx, guard(ctx));
+        return {
+            success: true,
+            reloaded: true,
+            enabled: strings(config.enabled),
+            disabled: strings(config.disabled)
+        };
+    },
+
+    async run_command({ command, args = [], cwd = '.', timeout = 30000 }, ctx) {
+        const arg = (a) => typeof a === 'string' && !a.includes('\0');
+        if (!arg(command) || command === '') throw new Error('Invalid params: command must be a non-empty string');
+        if (!Array.isArray(args) || !args.every(arg)) throw new Error('Invalid params: args must be an array of strings');
+        if (typeof timeout !== 'number' || !(timeout > 0)) throw new Error('Invalid params: timeout must be a positive number of milliseconds');
+        const workDir = checkedPath(ctx, guard(ctx), cwd, 'cwd');
+        if (path.dirname(workDir) === workDir) throw new Error('Invalid params: cwd must not be the root of the file system');
+        const env = childEnv(ctx);
+        // Every command is announced where the user can see it (JSON-quoted: no terminal escapes get through).
+        ui.printer(ctx.stderr).step('jos serve: run_command ' + JSON.stringify([command, ...args]) + ' in ' + JSON.stringify(workDir));
+        const r = spawnSync(command, args, {
+            shell: false, // an argv, never a command line: no expansion, no `;`, no `$(...)`
+            cwd: workDir,
+            env,
+            timeout: Math.min(timeout, MAX_TIMEOUT),
+            maxBuffer: 1024 * 1024, // 1MB
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'pipe'] // never the protocol's stdin
+        });
+        if (r.status === 0 && !r.error) return { success: true, output: r.stdout, command, args, cwd: workDir };
+        return {
+            success: false,
+            error: r.error ? r.error.message : (r.signal ? 'Command killed by ' + r.signal : 'Command failed with exit code ' + r.status),
+            output: r.stdout || '',
+            stderr: r.stderr || '',
+            command,
+            args
+        };
+    },
+
+    async list_processes(params, ctx) {
+        const g = guard(ctx);
+        let runs = [];
+        try { runs = fs.readdirSync(homePath(ctx, g, 'runs')).reverse().slice(0, 20); } catch (e) { /* no runs */ }
+        const processes = [];
+        for (const runId of runs) {
+            const report = readHomeJson(ctx, g, 'runs', runId, 'report.json');
+            if (!isPlainObject(report)) continue;
+            const meta = isPlainObject(report.meta) ? report.meta : {};
+            let alive = false;
+            if (meta.pid) {
+                try { process.kill(meta.pid, 0); alive = true; } catch (e) { /* not running */ }
+            }
+            processes.push({
+                epochId: runId,
+                pid: meta.pid,
+                command: report.command,
+                status: alive ? 'running' : 'stopped',
+                port: report.port
+            });
+        }
+        return { processes, count: processes.length };
+    }
+};
+
+// ------------------------------------------------------------------------------------------- protocol
+
+// The context of one server: ~/.jos, the real working directory, whether run_command exists, the environment
+// a child would start from and where notices go.
+function createContext(home, opts) {
+    const o = opts || {};
+    return {
+        home: path.resolve(home),
+        root: fs.realpathSync.native(o.root || process.cwd()),
+        allowShell: o.allowShell === true,
+        allowWrite: o.allowWrite === true,
+        env: o.env || process.env,
+        stderr: o.stderr || process.stderr,
+    };
+}
+
+// A gated tool exists (listed and callable) only when its switch is on.
+const enabled = (context, name) => !hasOwn(GATED, name) || context[GATED[name]] === true;
+const toolsFor = (context) => TOOLS.filter((t) => enabled(context, t.name));
+
+// JSON-RPC 2.0 message handler. Only a request object with jsonrpc "2.0" and a string method is dispatched;
+// anything else is -32600 with id null (JSON-RPC 2.0 §5.1). A request without id is a notification: no response.
+async function handleMessage(message, context) {
+    if (!isPlainObject(message) || message.jsonrpc !== '2.0' || typeof message.method !== 'string') {
+        const id = isPlainObject(message) && hasOwn(message, 'id') && (typeof message.id === 'string' || typeof message.id === 'number' || message.id === null) ? message.id : null;
+        return { jsonrpc: '2.0', id, error: { code: -32600, message: 'Invalid Request: not a JSON-RPC 2.0 request' } };
+    }
+    const { id, method, params } = message;
+    const notification = !hasOwn(message, 'id');
+    if (params !== undefined && !isPlainObject(params) && !Array.isArray(params)) {
+        return notification ? null : { jsonrpc: '2.0', id, error: { code: -32602, message: 'Invalid params: expected an object' } };
+    }
+
+    try {
+        switch (method) {
+            case 'initialize':
+                return {
+                    jsonrpc: '2.0',
+                    id,
+                    result: {
+                        protocolVersion: PROTOCOL_VERSION,
+                        serverInfo: { name: SERVER_NAME, version: SERVER_VERSION },
+                        capabilities: {
+                            tools: { listChanged: false }
+                        }
+                    }
+                };
+
+            case 'initialized':
+            case 'notifications/initialized':
+                // Notification, no response needed
+                return null;
+
+            case 'tools/list':
+                return {
+                    jsonrpc: '2.0',
+                    id,
+                    result: { tools: toolsFor(context) }
+                };
+
+            case 'tools/call': {
+                const p = isPlainObject(params) ? params : {};
+                const name = typeof p.name === 'string' ? p.name : null;
+                // Own properties only: 'constructor', 'toString' or '__proto__' are not tools; run_command exists
+                // only with --allow-shell and write_file only with --allow-write.
+                const known = name !== null && hasOwn(toolHandlers, name) && enabled(context, name);
+
+                if (!known) {
+                    return {
+                        jsonrpc: '2.0',
+                        id,
+                        error: { code: -32601, message: `Unknown tool: ${name === null ? '(missing name)' : name}` }
+                    };
+                }
+                if (p.arguments !== undefined && !isPlainObject(p.arguments)) {
+                    return { jsonrpc: '2.0', id, error: { code: -32602, message: 'Invalid params: arguments must be an object' } };
+                }
+
+                const result = await toolHandlers[name](p.arguments || {}, context);
+                return {
+                    jsonrpc: '2.0',
+                    id,
+                    result: {
+                        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }]
+                    }
+                };
+            }
+
+            case 'ping':
+                return { jsonrpc: '2.0', id, result: {} };
+
+            default:
+                return {
+                    jsonrpc: '2.0',
+                    id,
+                    error: { code: -32601, message: `Method not found: ${method}` }
+                };
+        }
+    } catch (err) {
+        // Handlers throw Error objects whose messages never carry file content.
+        return { jsonrpc: '2.0', id, error: { code: -32000, message: err.message } };
+    }
+}
+
+// Start MCP server on stdio. opts: { allowShell, allowWrite, root, explicitRoot, env, stdin, stdout, stderr, exit };
+// streams and exit default to the process (tests pass their own). Resolves to an exit code when it refuses to start.
+async function startMCPServer(home, o = {}) {
+    const err = ui.printer(o.stderr || process.stderr);
+    let context;
+    try {
+        context = createContext(home, o);
+        if (!fs.statSync(context.root).isDirectory()) throw new Error('not a directory');
+    } catch (e) {
+        err.fail('jos serve: --root ' + JSON.stringify(o.root) + ' is not an existing directory');
+        return 64;
+    }
+    // The home directory is the parent of ~/.jos. A root that is it, or contains it ("/" included), exposes every
+    // file of the user: refused unless the user named it with --root.
+    const userHome = canonical(path.dirname(context.home));
+    if (!o.explicitRoot && userHome !== null && within(fold(userHome), fold(context.root))) {
+        err.fail('jos serve: refusing to serve ' + JSON.stringify(context.root) + ': it is "/", your home directory or contains it.');
+        err.hint('Start it in a project directory, or name the root explicitly with --root <dir>.');
+        return 2;
+    }
+    const input = o.stdin || process.stdin;
+    const output = o.stdout || process.stdout;
+    const exit = o.exit || process.exit;
+
+    // A person at a terminal gets a notice on stderr (never on stdout, the JSON-RPC channel); a client never does.
+    if (input.isTTY) guide.notice(err, context, toolsFor(context).map((t) => t.name));
+    if (guard(context).josForms.some((j) => within(j, fold(context.root)))) {
+        err.warn('jos serve: the root contains ~/.jos: ~/.jos/secrets, .master and vault.json stay denied, ' +
+            'every other file under it is readable by the MCP client (never writable)');
+    }
+    if (context.allowWrite) {
+        err.warn('jos serve: --allow-write: write_file is on; the MCP client can create and overwrite files in ' +
+            JSON.stringify(context.root) + ' (never under ~/.jos).');
+    }
+    if (context.allowShell) {
+        err.warn('jos serve: --allow-shell: run_command is on; the MCP client can run any program as you, ' +
+            'including one that reads ~/.jos/secrets. Every command is shown here. Do not give this to an untrusted agent ' +
+            'without an external sandbox.');
+    }
+    if (input.isTTY) { err.hint('Ctrl-C to exit.'); err.line(); }
+
+    // Use readline for line-based JSON-RPC
+    const rl = readline.createInterface({ input, terminal: false });
+
+    // Send response to stdout
+    const send = (response) => {
+        if (response) {
+            output.write(JSON.stringify(response) + '\n'); // the JSON-RPC channel (STYLE.md, exceptions)
+        }
+    };
+
+    // Messages are processed one at a time, in input order, so responses come out in input order too
+    // (a parse error must not overtake the answer to an earlier line: both would carry id null).
+    const processLine = async (line) => {
+        if (!line.trim()) return;
+        let message;
+        try { message = JSON.parse(line); } catch (err) {
+            send({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error: ' + err.message } });
+            return;
+        }
+        const response = await handleMessage(message, context);
+        // A well-formed request without id is a notification: no response, not even an error (JSON-RPC 2.0 §4.1).
+        if (isPlainObject(message) && message.jsonrpc === '2.0' && typeof message.method === 'string' && !hasOwn(message, 'id')) return;
+        send(response);
+    };
+    let queue = Promise.resolve();
+    rl.on('line', (line) => {
+        queue = queue.then(() => processLine(line)).catch((err) => {
+            send({ jsonrpc: '2.0', id: null, error: { code: -32603, message: 'Internal error: ' + err.message } });
+        });
+    });
+
+    rl.on('close', () => {
+        // Answer everything already read before leaving.
+        queue.then(() => exit(0));
+    });
+
+    // Keep process alive
+    input.resume();
+}
+
+module.exports = { startMCPServer, handleMessage, createContext, TOOLS, toolHandlers, globMatch };