@event4u/agent-config 6.1.0 → 7.0.0

package/src/scripts/mcp_render.ts

@@ -0,0 +1,346 @@
+#!/usr/bin/env node
+/**
+ * MCP config renderer — one `mcp.json` → per-tool output files.
+ *
+ * TypeScript twin of `mcp_render.py` (Phase 8 / Wave 8g).
+ *
+ * Reads `mcp.json` at repo root (`{ "servers": { <name>: { command, args,
+ * env, cwd } } }`), substitutes `${env:VAR}` placeholders from the
+ * environment, and writes each target tool's concrete config format.
+ *
+ * Targets:
+ *     .cursor/mcp.json                                       (in-project)
+ *     .windsurf/mcp.json                                     (in-project)
+ *     ~/.config/claude-desktop/claude_desktop_config.json    (user, opt-in)
+ *
+ * All targets use the same `mcpServers` top-level key. The source file uses
+ * `servers` to keep our internal schema stable if a downstream format ever
+ * diverges.
+ *
+ * Failure mode: unresolved `${env:VAR}` placeholders are collected first,
+ * then reported together and a non-zero exit is raised. No target file is
+ * written when any placeholder is missing.
+ *
+ * See docs/mcp.md for schema, usage, and worked examples.
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const _HERE = fileURLToPath(import.meta.url);
+
+const ENV_PLACEHOLDER = /\$\{env:([^}]+)\}/g;
+
+// Project root defaults to the current working directory so the renderer
+// works both for package maintainers (running from the package root via
+// Taskfile) and for consumer projects (running via `./agent-config
+// mcp:render` from their own repo root). Override with --project-root.
+export function default_project_root(): string {
+    return fs.realpathSync(process.cwd());
+}
+
+export function in_project_targets(projectRoot: string): Record<string, string> {
+    return {
+        cursor: path.join(projectRoot, '.cursor', 'mcp.json'),
+        windsurf: path.join(projectRoot, '.windsurf', 'mcp.json'),
+    };
+}
+
+// Mutable so tests can override (mirrors monkeypatch.setattr on the module
+// constant in the Python test suite).
+export const _claudeDesktop = {
+    target: path.join(os.homedir(), '.config', 'claude-desktop', 'claude_desktop_config.json'),
+};
+
+/** Raised on a JSON / schema problem to mirror Python's `SystemExit(msg)`. */
+export class RenderExit extends Error {}
+
+/**
+ * Recursively substitute `${env:VAR}` in strings.
+ *
+ * Missing variables are appended to `missing` as `[var_name, json_path]`
+ * instead of raising, so a single run surfaces *all* gaps at once.
+ */
+export function substitute(
+    value: unknown,
+    jsonPath: string,
+    missing: Array<[string, string]>,
+): unknown {
+    if (typeof value === 'string') {
+        return value.replace(ENV_PLACEHOLDER, (match, name: string) => {
+            const envValue = process.env[name];
+            if (envValue === undefined) {
+                missing.push([name, jsonPath]);
+                return match;
+            }
+            return envValue;
+        });
+    }
+    if (Array.isArray(value)) {
+        return value.map((v, i) => substitute(v, `${jsonPath}[${i}]`, missing));
+    }
+    if (value !== null && typeof value === 'object') {
+        const out: Record<string, unknown> = {};
+        for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+            out[k] = substitute(v, `${jsonPath}.${k}`, missing);
+        }
+        return out;
+    }
+    return value;
+}
+
+export function load_source(source: string): Record<string, unknown> {
+    if (!fs.existsSync(source)) {
+        throw new RenderExit(`❌  Source file not found: ${source}`);
+    }
+    let data: unknown;
+    try {
+        data = JSON.parse(fs.readFileSync(source, 'utf-8'));
+    } catch (exc) {
+        const msg = exc instanceof Error ? exc.message : String(exc);
+        throw new RenderExit(`❌  Invalid JSON in ${source}: ${msg}`);
+    }
+    if (
+        data === null ||
+        typeof data !== 'object' ||
+        Array.isArray(data) ||
+        !('servers' in (data as Record<string, unknown>)) ||
+        (data as Record<string, unknown>)['servers'] === null ||
+        typeof (data as Record<string, unknown>)['servers'] !== 'object' ||
+        Array.isArray((data as Record<string, unknown>)['servers'])
+    ) {
+        throw new RenderExit(`❌  ${source} must contain a top-level 'servers' object.`);
+    }
+    return data as Record<string, unknown>;
+}
+
+/** Return [rendered, missing]. Caller decides what to do on missing. */
+export function render(
+    data: Record<string, unknown>,
+): [Record<string, unknown>, Array<[string, string]>] {
+    const missing: Array<[string, string]> = [];
+    const resolvedServers = substitute(data['servers'], 'servers', missing);
+    return [{ mcpServers: resolvedServers }, missing];
+}
+
+export function format_missing_report(missing: Array<[string, string]>): string {
+    const grouped = new Map<string, string[]>();
+    for (const [name, p] of missing) {
+        if (!grouped.has(name)) {
+            grouped.set(name, []);
+        }
+        grouped.get(name)!.push(p);
+    }
+    const lines: string[] = [
+        `❌  Unresolved \${env:VAR} placeholders (${grouped.size} variable(s)):`,
+    ];
+    for (const name of [...grouped.keys()].sort()) {
+        lines.push(`  - ${name}  used at:`);
+        for (const p of grouped.get(name)!) {
+            lines.push(`      ${p}`);
+        }
+    }
+    lines.push('\nSet the variable(s) in your environment and re-run.');
+    return lines.join('\n');
+}
+
+/**
+ * Mirror `json.dumps(content, indent=2, sort_keys=True)` for JSON-shaped
+ * values. ensure_ascii defaults to True.
+ */
+function _pyJsonDumpsSorted(obj: unknown): string {
+    return _dumpValue(obj, 0);
+}
+
+function _dumpValue(value: unknown, depth: number): string {
+    const pad = '  '.repeat(depth);
+    const padInner = '  '.repeat(depth + 1);
+    if (value === null || value === undefined) return 'null';
+    if (typeof value === 'number') return String(value);
+    if (typeof value === 'boolean') return value ? 'true' : 'false';
+    if (typeof value === 'string') return _dumpString(value);
+    if (Array.isArray(value)) {
+        if (value.length === 0) return '[]';
+        const items = value.map((v) => padInner + _dumpValue(v, depth + 1));
+        return '[\n' + items.join(',\n') + '\n' + pad + ']';
+    }
+    const entries = Object.entries(value as Record<string, unknown>).sort((a, b) =>
+        a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0,
+    );
+    if (entries.length === 0) return '{}';
+    const items = entries.map(
+        ([k, v]) => padInner + _dumpString(k) + ': ' + _dumpValue(v, depth + 1),
+    );
+    return '{\n' + items.join(',\n') + '\n' + pad + '}';
+}
+
+function _dumpString(s: string): string {
+    let out = '"';
+    for (const ch of s) {
+        const code = ch.codePointAt(0) as number;
+        if (ch === '"') out += '\\"';
+        else if (ch === '\\') out += '\\\\';
+        else if (ch === '\n') out += '\\n';
+        else if (ch === '\r') out += '\\r';
+        else if (ch === '\t') out += '\\t';
+        else if (ch === '\b') out += '\\b';
+        else if (ch === '\f') out += '\\f';
+        else if (code < 0x20) out += '\\u' + code.toString(16).padStart(4, '0');
+        else if (code < 0x7f) out += ch;
+        else if (code <= 0xffff) out += '\\u' + code.toString(16).padStart(4, '0');
+        else {
+            const v = code - 0x10000;
+            const hi = 0xd800 + (v >> 10);
+            const lo = 0xdc00 + (v & 0x3ff);
+            out += '\\u' + hi.toString(16).padStart(4, '0');
+            out += '\\u' + lo.toString(16).padStart(4, '0');
+        }
+    }
+    return out + '"';
+}
+
+export function write_target(p: string, content: Record<string, unknown>): void {
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    const serialized = _pyJsonDumpsSorted(content) + '\n';
+    fs.writeFileSync(p, serialized, 'utf-8');
+}
+
+export function collect_targets(
+    projectRoot: string,
+    includeClaudeDesktop: boolean,
+): Record<string, string> {
+    const targets: Record<string, string> = { ...in_project_targets(projectRoot) };
+    if (includeClaudeDesktop) {
+        targets['claude-desktop'] = _claudeDesktop.target;
+    }
+    return targets;
+}
+
+interface ParsedArgs {
+    source: string | null;
+    projectRoot: string | null;
+    claudeDesktop: boolean;
+    check: boolean;
+}
+
+export function resolve_source(args: ParsedArgs, projectRoot: string): string {
+    return args.source ? args.source : path.join(projectRoot, 'mcp.json');
+}
+
+/** Python `f"{name:16}"` — left-justify, pad to width 16. */
+function _ljust(s: string, width: number): string {
+    return s.length >= width ? s : s + ' '.repeat(width - s.length);
+}
+
+function cmd_render(args: ParsedArgs): number {
+    const projectRoot = args.projectRoot ? fs.realpathSync(args.projectRoot) : default_project_root();
+    const data = load_source(resolve_source(args, projectRoot));
+    const [rendered, missing] = render(data);
+    if (missing.length > 0) {
+        process.stderr.write(format_missing_report(missing) + '\n');
+        return 1;
+    }
+    const targets = collect_targets(projectRoot, args.claudeDesktop);
+    for (const [name, p] of Object.entries(targets)) {
+        write_target(p, rendered);
+        process.stdout.write(`✅  ${_ljust(name, 16)} → ${p}\n`);
+    }
+    return 0;
+}
+
+function cmd_check(args: ParsedArgs): number {
+    const projectRoot = args.projectRoot ? fs.realpathSync(args.projectRoot) : default_project_root();
+    const data = load_source(resolve_source(args, projectRoot));
+    const [rendered, missing] = render(data);
+    if (missing.length > 0) {
+        process.stderr.write(format_missing_report(missing) + '\n');
+        return 1;
+    }
+    const serialized = _pyJsonDumpsSorted(rendered) + '\n';
+    const targets = collect_targets(projectRoot, args.claudeDesktop);
+    const diffs: Array<[string, string]> = [];
+    for (const [name, p] of Object.entries(targets)) {
+        const actual = fs.existsSync(p) ? fs.readFileSync(p, 'utf-8') : '';
+        if (actual !== serialized) {
+            diffs.push([name, p]);
+        }
+    }
+    if (diffs.length > 0) {
+        process.stderr.write('❌  Targets out of date (run `./agent-config mcp:render`):\n');
+        for (const [name, p] of diffs) {
+            process.stderr.write(`  - ${name}: ${p}\n`);
+        }
+        return 1;
+    }
+    process.stdout.write('✅  All MCP targets match source.\n');
+    return 0;
+}
+
+class ArgError extends Error {}
+
+function _parseArgs(argv: string[]): ParsedArgs {
+    let source: string | null = null;
+    let projectRoot: string | null = null;
+    let claudeDesktop = false;
+    let check = false;
+    let i = 0;
+    while (i < argv.length) {
+        const a = argv[i] as string;
+        if (a === '--source') {
+            source = argv[i + 1] ?? null;
+            if (source === null) throw new ArgError('argument --source: expected one argument');
+            i += 2;
+        } else if (a.startsWith('--source=')) {
+            source = a.slice('--source='.length);
+            i += 1;
+        } else if (a === '--project-root') {
+            projectRoot = argv[i + 1] ?? null;
+            if (projectRoot === null) {
+                throw new ArgError('argument --project-root: expected one argument');
+            }
+            i += 2;
+        } else if (a.startsWith('--project-root=')) {
+            projectRoot = a.slice('--project-root='.length);
+            i += 1;
+        } else if (a === '--claude-desktop') {
+            claudeDesktop = true;
+            i += 1;
+        } else if (a === '--check') {
+            check = true;
+            i += 1;
+        } else {
+            throw new ArgError(`unrecognized arguments: ${a}`);
+        }
+    }
+    return { source, projectRoot, claudeDesktop, check };
+}
+
+export function main(argv: string[] | null = null): number {
+    let args: ParsedArgs;
+    try {
+        args = _parseArgs(argv ?? process.argv.slice(2));
+    } catch (e) {
+        if (e instanceof ArgError) {
+            process.stderr.write(`mcp_render: ${e.message}\n`);
+            return 2;
+        }
+        throw e;
+    }
+    try {
+        return args.check ? cmd_check(args) : cmd_render(args);
+    } catch (e) {
+        if (e instanceof RenderExit) {
+            process.stderr.write(e.message + '\n');
+            return 1;
+        }
+        throw e;
+    }
+}
+
+const _isCliEntry =
+    process.argv[1] !== undefined &&
+    import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
+if (_isCliEntry || process.argv[1] === _HERE) {
+    process.exitCode = main();
+}

package/src/scripts/mcp_server/__main__.ts

@@ -0,0 +1,28 @@
+// Entrypoint — TS twin of `scripts/mcp_server/__main__.py`
+// (`python -m scripts.mcp_server`).
+//
+// Required by Claude Desktop / Zed / Continue stdio-server config on the
+// Python side; the .py stays the runtime entry until a later phase (glama
+// still launches `python -m scripts.mcp_server`). This twin coexists and
+// forwards to `server.main()`; keep this file flat so crash stack traces
+// point at server.ts, not the bootstrap.
+//
+// `node __main__.js` (or importing this module as the package main) runs
+// the server, mirroring the Python `if __name__ == "__main__": main()`
+// guard via the standard-module-entry check.
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { main } from './server.js';
+
+// Mirror `if __name__ == "__main__"`: run only when invoked directly,
+// not when imported. Compare the resolved module path to argv[1].
+const _selfPath = fileURLToPath(import.meta.url);
+const _invokedDirectly =
+    process.argv[1] !== undefined && path.resolve(process.argv[1]) === path.resolve(_selfPath);
+
+if (_invokedDirectly) {
+    main();
+}
+
+export { main };

package/src/scripts/mcp_server/catalog.ts

@@ -0,0 +1,154 @@
+// Consumer tool catalog — source of truth for Phase 1 discovery stubs.
+//
+// Loaded once at module import from `consumer_tool_catalog.json`. Both
+// the stdio server (`tools.py`) and the cloud pack
+// (`scripts/pack_mcp_content.py`) read from this file so the manifest
+// returned by `tools/list` on either transport is byte-identical apart
+// from per-tool `implemented_on` metadata.
+//
+// Side-effect classification (`ro` / `fs-write` / `shell`) and the
+// `not_implemented` envelope contract live in
+// `docs/contracts/mcp-tool-stub-envelope.md`.
+//
+// TS twin of catalog.py (py2ts Phase 8). Mirrors the full public surface:
+//   - NOT_IMPLEMENTED_CODE, CatalogEntry, load_catalog, load_raw,
+//     install_hint, not_implemented_envelope.
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const _CATALOG_FILE = path.join(
+    path.dirname(fileURLToPath(import.meta.url)),
+    'consumer_tool_catalog.json',
+);
+
+// Stable error code surfaced in the `not_implemented` envelope. The
+// Worker mirrors this string verbatim — keep them in sync via the
+// envelope contract.
+export const NOT_IMPLEMENTED_CODE = 'not_implemented';
+
+/**
+ * One row in `consumer_tool_catalog.json`.
+ *
+ * `implemented_on` lists transports where a real handler is wired
+ * (`stdio` / `worker`); missing transports return the
+ * `not_implemented` envelope.
+ *
+ * Mirrors the Python frozen dataclass `CatalogEntry` (field order
+ * preserved). `implemented_on` is a tuple in Python; a readonly array
+ * here, populated in file order.
+ */
+export interface CatalogEntry {
+    readonly name: string;
+    readonly description: string;
+    readonly side_effect: string;
+    readonly implemented_on: readonly string[];
+    readonly input_schema: Record<string, unknown>;
+}
+
+/** Refuse to boot on a malformed catalog. Boot-time errors only. */
+function _validate(raw: Record<string, unknown>): void {
+    if (raw.schema_version !== 1) {
+        throw new Error(
+            `catalog: unsupported schema_version=` +
+                `${_pyRepr(raw.schema_version)}; expected 1`,
+        );
+    }
+    const tools = raw.tools;
+    if (!Array.isArray(tools) || tools.length === 0) {
+        throw new Error("catalog: 'tools' must be a non-empty list");
+    }
+    const seen = new Set<string>();
+    for (const entry of tools) {
+        if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) {
+            throw new Error('catalog: every tool entry must be an object');
+        }
+        const e = entry as Record<string, unknown>;
+        for (const field of ['name', 'description', 'side_effect', 'input_schema']) {
+            if (!(field in e)) {
+                throw new Error(`catalog: tool missing '${field}'`);
+            }
+        }
+        if (
+            e.side_effect !== 'ro' &&
+            e.side_effect !== 'fs-write' &&
+            e.side_effect !== 'shell'
+        ) {
+            throw new Error(
+                `catalog: tool ${_pyRepr(e.name)} has invalid side_effect ` +
+                    `${_pyRepr(e.side_effect)} (expected ro / fs-write / shell)`,
+            );
+        }
+        const name = e.name as string;
+        if (seen.has(name)) {
+            throw new Error(`catalog: duplicate tool name ${_pyRepr(name)}`);
+        }
+        seen.add(name);
+    }
+}
+
+/** Mirror Python `repr()` for the small set of values that reach error text. */
+function _pyRepr(value: unknown): string {
+    if (typeof value === 'string') {
+        return `'${value}'`;
+    }
+    if (value === null || value === undefined) {
+        return 'None';
+    }
+    return String(value);
+}
+
+/** Parse and validate the catalog. Returns entries in file order. */
+export function load_catalog(targetPath?: string): CatalogEntry[] {
+    const target = targetPath ?? _CATALOG_FILE;
+    const raw = JSON.parse(fs.readFileSync(target, 'utf-8')) as Record<string, unknown>;
+    _validate(raw);
+    const tools = raw.tools as Record<string, unknown>[];
+    return tools.map((t) => ({
+        name: t.name as string,
+        description: t.description as string,
+        side_effect: t.side_effect as string,
+        implemented_on: [...((t.implemented_on as unknown[] | null | undefined) ?? [])].map(
+            (v) => v as string,
+        ),
+        input_schema: t.input_schema as Record<string, unknown>,
+    }));
+}
+
+/** Return the raw parsed JSON. Used by the cloud packer. */
+export function load_raw(targetPath?: string): Record<string, unknown> {
+    const target = targetPath ?? _CATALOG_FILE;
+    const raw = JSON.parse(fs.readFileSync(target, 'utf-8')) as Record<string, unknown>;
+    _validate(raw);
+    return raw;
+}
+
+/** Stable install-hint surfaced in the envelope. */
+export function install_hint(raw?: Record<string, unknown>): string {
+    const data = raw !== undefined ? raw : load_raw();
+    return String(data.install_hint_stdio ?? '');
+}
+
+/**
+ * Wire-shape error envelope used when a stub is invoked.
+ *
+ * Mirrored verbatim by the Cloud Worker (`internal/workers/mcp/src/stubs.ts`).
+ */
+export function not_implemented_envelope(
+    tool_name: string,
+    options: { transport: string; install_hint_value: string },
+): Record<string, unknown> {
+    const { transport, install_hint_value } = options;
+    return {
+        code: NOT_IMPLEMENTED_CODE,
+        tool: tool_name,
+        transport,
+        install_hint: install_hint_value,
+        alternative: 'stdio',
+        message:
+            `Tool '${tool_name}' is in the discovery catalog but not ` +
+            `implemented on the ${transport} transport. See the install ` +
+            'hint to wire it up locally, or check ' +
+            'docs/contracts/mcp-tool-stub-envelope.md.',
+    };
+}

package/src/scripts/mcp_server/index.ts

@@ -0,0 +1,24 @@
+// MCP server for agent-config — Phase 1 MVP.
+//
+// mcp_scope: full — local stdio access can be extended to tool execution
+// under the Phase 7 wake-up triggers in `docs/contracts/mcp-cloud-scope.md`.
+// The hosted Worker (`internal/workers/mcp/`) is `mcp_scope: lite` and is
+// intentionally narrower.
+//
+// Exposes a hand-picked subset of `dist/agent-src/skills/` as MCP `prompts`
+// over stdio. Read-only and instructional per the A0 execution-safety
+// boundary in `agents/roadmaps/road-to-mcp-server.md`. No `tools`
+// primitive, no engine spawn, no shell execution.
+//
+// Stability: experimental. Contract: `docs/contracts/mcp-phase-1-scope.md`.
+// Promotion to beta gated on `docs/contracts/mcp-beta-criteria.md`.
+//
+// TS twin of __init__.py (py2ts Phase 8). The Python package barrel exposes
+// exactly two module-level names: `__version__` and `SERVER_NAME`. Mirrored
+// here as `__version__` (Python wire-surface SemVer name preserved) and
+// SERVER_NAME.
+
+// Wire-surface SemVer. Hand-bumped when the MCP-side surface changes.
+ 
+export const __version__ = '0.1.0';
+export const SERVER_NAME = 'agent-config';

package/src/scripts/mcp_server/metadata.ts

@@ -0,0 +1,83 @@
+// Phase-6 F1 — server identity metadata.
+//
+// Three values surfaced at boot via stderr (`run_stdio` boot log):
+//
+// - **server version** — wire-surface SemVer in `__init__.py::__version__`.
+//   Hand-bumped when the MCP-side surface (prompts/resources/tools shape,
+//   protocol semantics) changes.
+// - **package version** — read from `package.json::version` at boot.
+//   Build-ID semantics; bumps with every release of the agent-config bundle.
+// - **skill-set signature** — SHA-256 hex (first 12 chars) over the joined
+//   `PromptCache._signature` + `ResourceCache._signature` tuples
+//   (`(uri, mtime)` pairs, already sorted). Content fingerprint, not a
+//   version — auto-derived, never hand-edited.
+//
+// Wire-surface caveat: the MCP SDK constructs `serverInfo.Implementation`
+// internally with a fixed field set (`name`, `version`, `websiteUrl`,
+// `icons`), so the package version and skill-set signature cannot be
+// attached to `serverInfo._meta` without subclassing the session.
+// Stderr is the canonical surface in Phase 6; a wire-surface lift can
+// follow once the SDK supports it.
+//
+// TS twin of metadata.py (py2ts Phase 8). Mirrors the full public surface:
+//   - Signature type, read_package_version, compute_skill_set_signature,
+//     boot_log_line.
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+// `(uri, mtime)` pairs. Mirrors Python `Sequence[tuple[str, float]]`.
+export type Signature = ReadonlyArray<readonly [string, number]>;
+
+/** Return `package.json::version`, or `"unknown"` if unreadable. */
+export function read_package_version(root: string): string {
+    const p = path.join(root, 'package.json');
+    let data: Record<string, unknown>;
+    try {
+        data = JSON.parse(fs.readFileSync(p, 'utf-8')) as Record<string, unknown>;
+    } catch {
+        return 'unknown';
+    }
+    const version = data.version;
+    if (typeof version !== 'string' || !version) {
+        return 'unknown';
+    }
+    return version;
+}
+
+/**
+ * SHA-256 hex (12 chars) over the concatenated `(uri, mtime)` tuples.
+ *
+ * Deterministic across processes for identical inputs. Changes when
+ * any tracked file's path-set or mtime changes. Inputs are taken as-is
+ * (callers pass already-sorted cache signatures); the hash is taken
+ * over the joined repr to keep the framing unambiguous.
+ */
+export function compute_skill_set_signature(...signatures: Signature[]): string {
+    const hasher = crypto.createHash('sha256');
+    for (const sig of signatures) {
+        for (const [uri, mtime] of sig) {
+            hasher.update(Buffer.from(uri, 'utf-8'));
+            hasher.update(Buffer.from([0x00]));
+            // Python: f"{mtime:.6f}".encode("ascii") — fixed 6 decimals.
+            hasher.update(Buffer.from(mtime.toFixed(6), 'ascii'));
+            hasher.update(Buffer.from([0x1e])); // record separator
+        }
+        hasher.update(Buffer.from([0x1d])); // group separator between caches
+    }
+    return hasher.digest('hex').slice(0, 12);
+}
+
+/** Single stderr line surfacing all three identity values at boot. */
+export function boot_log_line(options: {
+    server_version: string;
+    package_version: string;
+    skill_set_signature: string;
+}): string {
+    const { server_version, package_version, skill_set_signature } = options;
+    return (
+        `mcp-server: identity serverVersion=${server_version} ` +
+        `packageVersion=${package_version} ` +
+        `skillSetSignature=${skill_set_signature}`
+    );
+}