@evomap/evolver-mcp 2.0.0-beta.0

package/dist/proxyClient.d.ts

@@ -0,0 +1,72 @@
+export interface ProxyFetch {
+    (url: string, init: {
+        method: string;
+        headers: Record<string, string>;
+        body?: string;
+        signal?: AbortSignal;
+    }): Promise<{
+        ok: boolean;
+        status: number;
+        json(): Promise<unknown>;
+    }>;
+}
+export interface EvolverProxyClientOptions {
+    baseUrl: string;
+    token: string;
+    fetchFn?: ProxyFetch;
+    reloadSettings?: () => EvolverProxyClientOptions | undefined;
+}
+export interface ProxySearchArgs {
+    text?: string;
+    signalsAny?: string[];
+    kind?: string;
+    category?: string;
+    gene?: string;
+    limit?: number;
+}
+export interface ProxyFetchArgs {
+    assetId?: string;
+    assetIds?: string[];
+}
+export interface ProxyAssetBundle {
+    assets: unknown[];
+}
+export interface ProxyReuseResultArgs {
+    assetId: string;
+    outcome: 'success' | 'failed' | 'mismatched' | 'stale' | 'unsafe';
+    taskId?: string;
+    traceId?: string;
+    /** Deprecated compatibility field. Scalar self-reported savings are not forwarded as audited ROI. */
+    tokensSaved?: number;
+    timeSavedSeconds?: number;
+    reason?: string;
+}
+export declare class EvolverProxyClient {
+    private baseUrl;
+    private token;
+    private readonly fetchFn;
+    private readonly reloadSettings;
+    constructor(opts: EvolverProxyClientOptions);
+    status(opts?: {
+        signal?: AbortSignal;
+    }): Promise<unknown>;
+    search(args: ProxySearchArgs): Promise<unknown>;
+    fetchAsset(args: ProxyFetchArgs): Promise<unknown>;
+    submitAsset(asset: unknown): Promise<unknown>;
+    /** Pre-publish dry-run: the hub runs its quality + content-safety gate but stores nothing and charges no credits. */
+    validateAsset(asset: unknown): Promise<unknown>;
+    validateAssetBundle(bundle: ProxyAssetBundle): Promise<unknown>;
+    distillConversation(input: unknown): Promise<unknown>;
+    recordReuseResult(args: ProxyReuseResultArgs): Promise<unknown>;
+    call(method: string, path: string, body?: unknown, opts?: {
+        signal?: AbortSignal;
+    }): Promise<unknown>;
+    private callOnce;
+    private reloadFromSettings;
+    private proxyError;
+}
+export declare function proxyClientFromEnv(env?: Record<string, string | undefined>): EvolverProxyClient | undefined;
+export declare function reachableProxyClientFromEnv(env?: Record<string, string | undefined>, opts?: {
+    fetchFn?: ProxyFetch;
+    timeoutMs?: number;
+}): Promise<EvolverProxyClient | undefined>;

package/dist/proxyClient.js

@@ -0,0 +1,193 @@
+import { lstatSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+export class EvolverProxyClient {
+    baseUrl;
+    token;
+    fetchFn;
+    reloadSettings;
+    constructor(opts) {
+        this.baseUrl = opts.baseUrl.replace(/\/+$/, '');
+        this.token = opts.token;
+        this.fetchFn = opts.fetchFn ?? globalFetch;
+        this.reloadSettings = opts.reloadSettings;
+    }
+    status(opts = {}) {
+        return this.call('GET', '/proxy/status', undefined, opts);
+    }
+    search(args) {
+        return this.call('POST', '/asset/search', {
+            ...(args.text ? { text: args.text } : {}),
+            ...(args.signalsAny && args.signalsAny.length > 0 ? { signals: args.signalsAny } : {}),
+            ...(args.kind ? { kind: args.kind } : {}),
+            ...(args.category ? { category: args.category } : {}),
+            ...(args.gene ? { gene: args.gene } : {}),
+            ...(args.limit !== undefined ? { limit: args.limit } : {}),
+        });
+    }
+    fetchAsset(args) {
+        return this.call('POST', '/asset/fetch', {
+            ...(args.assetId ? { asset_id: args.assetId } : {}),
+            ...(args.assetIds ? { asset_ids: args.assetIds } : {}),
+        });
+    }
+    submitAsset(asset) {
+        return this.call('POST', '/asset/submit', { assets: [asset] });
+    }
+    /** Pre-publish dry-run: the hub runs its quality + content-safety gate but stores nothing and charges no credits. */
+    validateAsset(asset) {
+        return this.validateAssetBundle({ assets: [asset] });
+    }
+    validateAssetBundle(bundle) {
+        return this.call('POST', '/asset/validate', bundle);
+    }
+    distillConversation(input) {
+        return this.call('POST', '/conversation/distill', input);
+    }
+    recordReuseResult(args) {
+        return this.call('POST', '/asset/reuse-result', {
+            asset_id: args.assetId,
+            outcome: args.outcome,
+            ...(args.taskId ? { task_id: args.taskId } : {}),
+            ...(args.traceId ? { trace_id: args.traceId } : {}),
+            ...(args.timeSavedSeconds !== undefined ? { time_saved_seconds: args.timeSavedSeconds } : {}),
+            ...(args.reason ? { reason: args.reason } : {}),
+        });
+    }
+    async call(method, path, body, opts = {}) {
+        try {
+            const result = await this.callOnce(method, path, body, opts);
+            if (result.ok)
+                return result.parsed;
+            if (result.status === 401 && this.reloadFromSettings()) {
+                const retry = await this.callOnce(method, path, body, opts);
+                if (retry.ok)
+                    return retry.parsed;
+                throw this.proxyError(retry, path);
+            }
+            throw this.proxyError(result, path);
+        }
+        catch (err) {
+            if (this.reloadFromSettings()) {
+                const retry = await this.callOnce(method, path, body, opts);
+                if (retry.ok)
+                    return retry.parsed;
+                throw this.proxyError(retry, path);
+            }
+            throw err;
+        }
+    }
+    async callOnce(method, path, body, opts) {
+        const res = await this.fetchFn(`${this.baseUrl}${path}`, {
+            method,
+            headers: {
+                authorization: `Bearer ${this.token}`,
+                'content-type': 'application/json',
+            },
+            ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+            ...(opts.signal ? { signal: opts.signal } : {}),
+        });
+        return { ok: res.ok, status: res.status, parsed: await res.json() };
+    }
+    reloadFromSettings() {
+        const next = this.reloadSettings?.();
+        if (!next)
+            return false;
+        const nextBaseUrl = next.baseUrl.replace(/\/+$/, '');
+        if (nextBaseUrl === this.baseUrl && next.token === this.token)
+            return false;
+        this.baseUrl = nextBaseUrl;
+        this.token = next.token;
+        return true;
+    }
+    proxyError(result, path) {
+        const message = result.parsed && typeof result.parsed === 'object' && !Array.isArray(result.parsed) && typeof result.parsed.error === 'string'
+            ? result.parsed.error
+            : `evolver proxy ${result.status} ${path}`;
+        return new Error(message);
+    }
+}
+export function proxyClientFromEnv(env = process.env) {
+    const token = env['EVOLVER_IPC_TOKEN']?.trim();
+    if (!token)
+        return proxyClientFromSettings(env, env === process.env);
+    const explicitUrl = env['EVOLVER_PROXY_URL']?.trim();
+    const port = env['EVOLVER_IPC_PORT']?.trim() || env['EVOMAP_PROXY_PORT']?.trim() || '19820';
+    return new EvolverProxyClient({ baseUrl: explicitUrl || `http://127.0.0.1:${port}`, token });
+}
+export async function reachableProxyClientFromEnv(env = process.env, opts = {}) {
+    const token = env['EVOLVER_IPC_TOKEN']?.trim();
+    if (token) {
+        const explicitUrl = env['EVOLVER_PROXY_URL']?.trim();
+        const port = env['EVOLVER_IPC_PORT']?.trim() || env['EVOMAP_PROXY_PORT']?.trim() || '19820';
+        return new EvolverProxyClient({ baseUrl: explicitUrl || `http://127.0.0.1:${port}`, token, ...(opts.fetchFn ? { fetchFn: opts.fetchFn } : {}) });
+    }
+    const client = proxyClientFromSettings(env, env === process.env, opts.fetchFn);
+    if (!client)
+        return undefined;
+    return await proxyClientReachable(client, opts.timeoutMs ?? 250) ? client : undefined;
+}
+function proxyClientFromSettings(env, allowDefaultHome, fetchFn) {
+    const settings = readProxySettings(env, allowDefaultHome);
+    return settings ? new EvolverProxyClient({
+        ...settings,
+        ...(fetchFn ? { fetchFn } : {}),
+        reloadSettings: () => readProxySettings(env, allowDefaultHome),
+    }) : undefined;
+}
+function readProxySettings(env, allowDefaultHome) {
+    const homeDir = env['HOME']?.trim() || (allowDefaultHome ? homedir() : '');
+    if (!homeDir)
+        return undefined;
+    const settingsPath = join(homeDir, '.evolver', 'settings.json');
+    try {
+        if (!lstatSync(settingsPath).isFile())
+            return undefined;
+        const parsed = JSON.parse(readFileSync(settingsPath, 'utf8'));
+        const proxy = recordValue(recordValue(parsed)['proxy']);
+        const baseUrl = typeof proxy['url'] === 'string' ? proxy['url'].trim() : '';
+        const token = typeof proxy['token'] === 'string' ? proxy['token'].trim() : '';
+        if (!baseUrl || !token || !isLoopbackHttpUrl(baseUrl))
+            return undefined;
+        return { baseUrl, token };
+    }
+    catch {
+        return undefined;
+    }
+}
+function isLoopbackHttpUrl(raw) {
+    try {
+        const url = new URL(raw);
+        if (url.protocol !== 'http:' && url.protocol !== 'https:')
+            return false;
+        const hostname = url.hostname.toLowerCase();
+        return hostname === '127.0.0.1'
+            || hostname === 'localhost'
+            || hostname === '[::1]'
+            || hostname === '::1';
+    }
+    catch {
+        return false;
+    }
+}
+function recordValue(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+async function proxyClientReachable(client, timeoutMs) {
+    const controller = new AbortController();
+    const timer = timeoutMs > 0 ? setTimeout(() => controller.abort(), timeoutMs) : undefined;
+    try {
+        await client.status({ signal: controller.signal });
+        return true;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+async function globalFetch(url, init) {
+    return fetch(url, init);
+}

package/dist/server.d.ts

@@ -0,0 +1,31 @@
+import type { McpTool } from './tools.js';
+export interface ToolListEntry {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+}
+export interface ToolCallResult {
+    ok: boolean;
+    result?: unknown;
+    error?: string;
+}
+export declare class UnknownToolError extends Error {
+    readonly name: string;
+    constructor(name: string);
+}
+/**
+ * Evolver MCP server 核心(M5-1). 与传输无关(stdio 适配器薄薄一层包它),
+ * 便于直接单测; listTools 给 agent 自然发现, callTool 分派 + 隔离错误.
+ */
+export declare class EvolverMcpServer {
+    private readonly tools;
+    /** Server-level onboarding text (#mcp-onboarding). A transport surfaces it as the MCP `initialize.instructions`
+     *  field so any connecting client hands the evolver mechanism to its model. Empty string when not provided. */
+    readonly instructions: string;
+    constructor(tools: readonly McpTool[], opts?: {
+        instructions?: string;
+    });
+    listTools(): ToolListEntry[];
+    callTool(name: string, args?: Record<string, unknown>): Promise<ToolCallResult>;
+    has(name: string): boolean;
+}

package/dist/server.js

@@ -0,0 +1,38 @@
+export class UnknownToolError extends Error {
+    name;
+    constructor(name) {
+        super(`未知 MCP 工具: ${name}`);
+        this.name = name;
+        this.name = 'UnknownToolError';
+    }
+}
+/**
+ * Evolver MCP server 核心(M5-1). 与传输无关(stdio 适配器薄薄一层包它),
+ * 便于直接单测; listTools 给 agent 自然发现, callTool 分派 + 隔离错误.
+ */
+export class EvolverMcpServer {
+    tools = new Map();
+    /** Server-level onboarding text (#mcp-onboarding). A transport surfaces it as the MCP `initialize.instructions`
+     *  field so any connecting client hands the evolver mechanism to its model. Empty string when not provided. */
+    instructions;
+    constructor(tools, opts = {}) {
+        for (const t of tools)
+            this.tools.set(t.name, t);
+        this.instructions = opts.instructions ?? '';
+    }
+    listTools() {
+        return [...this.tools.values()].map((t) => ({ name: t.name, description: t.description, inputSchema: t.inputSchema }));
+    }
+    async callTool(name, args = {}) {
+        const tool = this.tools.get(name);
+        if (!tool)
+            throw new UnknownToolError(name);
+        try {
+            return { ok: true, result: await tool.handler(args) };
+        }
+        catch (e) {
+            return { ok: false, error: e instanceof Error ? e.message : String(e) };
+        }
+    }
+    has(name) { return this.tools.has(name); }
+}

package/dist/serviceGuidance.d.ts

@@ -0,0 +1,15 @@
+import type { McpServerCmd } from './injection.js';
+export type ServiceTarget = 'launchd' | 'systemd' | 'windows' | 'compose' | 'k8s';
+export declare const SERVICE_TARGETS: readonly ServiceTarget[];
+export interface ServiceGuidanceContext {
+    /** Path to the credential store the service should reference via EVOLVER_ENV_FILE. Falls back to the exec env's
+     *  pointer, else a placeholder. NEVER a secret value — only the pointer path. */
+    envFile?: string;
+    /** The long-running evolver command the service runs (illustrative — operator may swap for autoexec/proxy/etc). */
+    exec: McpServerCmd;
+}
+/**
+ * Render a service template for `target`. Print-only; the operator edits + installs it. Each template wires the
+ * credential store via the EVOLVER_ENV_FILE pointer (never inlines a secret) and runs the given evolver command.
+ */
+export declare function renderServiceGuidance(target: ServiceTarget, ctx: ServiceGuidanceContext): string;

package/dist/serviceGuidance.js

@@ -0,0 +1,170 @@
+export const SERVICE_TARGETS = ['launchd', 'systemd', 'windows', 'compose', 'k8s'];
+const ENV_FILE_KEY = 'EVOLVER_ENV_FILE';
+const execParts = (exec) => [exec.command, ...(exec.args ?? [])];
+const cmdLine = (exec) => execParts(exec).map(quotePosix).join(' ');
+const envPathOf = (ctx) => ctx.envFile ?? ctx.exec.env?.[ENV_FILE_KEY] ?? '<path-to-evolver.env>';
+/**
+ * Render a service template for `target`. Print-only; the operator edits + installs it. Each template wires the
+ * credential store via the EVOLVER_ENV_FILE pointer (never inlines a secret) and runs the given evolver command.
+ */
+export function renderServiceGuidance(target, ctx) {
+    const cmd = cmdLine(ctx.exec);
+    const ef = envPathOf(ctx);
+    switch (target) {
+        case 'systemd':
+            return [
+                '# Linux systemd user unit — ~/.config/systemd/user/evolver-proxy.service',
+                '[Unit]',
+                'Description=EvoMap Evolver Proxy Daemon',
+                'After=network-online.target',
+                'Wants=network-online.target',
+                'StartLimitBurst=5',
+                'StartLimitIntervalSec=120s',
+                '',
+                '[Service]',
+                'Type=simple',
+                `Environment="${ENV_FILE_KEY}=${escapeSystemdEnvValue(ef)}"`,
+                `ExecStart=${execParts(ctx.exec).map(quoteSystemdArg).join(' ')}`,
+                'Restart=on-failure',
+                'RestartSec=5s',
+                'RestartPreventExitStatus=0',
+                'RestartForceExitStatus=78',
+                'TimeoutStopSec=30s',
+                'StandardOutput=journal',
+                'StandardError=journal',
+                'SyslogIdentifier=evolver-proxy',
+                'NoNewPrivileges=true',
+                'PrivateTmp=true',
+                '',
+                '[Install]',
+                'WantedBy=default.target',
+                '',
+                '# then: systemctl --user daemon-reload && systemctl --user enable --now evolver-proxy',
+                `# ${ENV_FILE_KEY} is a pointer to the credential store; never inline secret values in this unit.`,
+            ].join('\n');
+        case 'launchd':
+            return [
+                '<!-- macOS launchd — ~/Library/LaunchAgents/com.evomap.evolver-proxy.plist -->',
+                '<?xml version="1.0" encoding="UTF-8"?>',
+                '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
+                '<plist version="1.0">',
+                '<dict>',
+                '  <key>Label</key>',
+                '  <string>com.evomap.evolver-proxy</string>',
+                '  <key>EnvironmentVariables</key>',
+                '  <dict>',
+                `    <key>${ENV_FILE_KEY}</key>`,
+                `    <string>${escapeXml(ef)}</string>`,
+                '    <key>PATH</key>',
+                '    <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>',
+                '  </dict>',
+                '  <key>ProgramArguments</key>',
+                '  <array>',
+                ...execParts(ctx.exec).map((a) => `    <string>${escapeXml(a)}</string>`),
+                '  </array>',
+                '  <key>RunAtLoad</key>',
+                '  <true/>',
+                '  <key>KeepAlive</key>',
+                '  <dict>',
+                '    <key>SuccessfulExit</key>',
+                '    <false/>',
+                '  </dict>',
+                '  <key>ThrottleInterval</key>',
+                '  <integer>5</integer>',
+                '  <key>ProcessType</key>',
+                '  <string>Standard</string>',
+                '</dict>',
+                '</plist>',
+                '',
+                '# then: launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.evomap.evolver-proxy.plist',
+                `# (the pointer ${ENV_FILE_KEY}=${ef} references the credential store; never inline secrets)`,
+            ].join('\n');
+        case 'windows':
+            return [
+                '# Windows Task Scheduler — hidden wscript.exe launcher; do not use a foreground command wrapper',
+                '$launcher = "$env:LOCALAPPDATA\\EvoMap\\evolver-proxy-task-launcher.vbs"',
+                '$dir = Split-Path -Parent $launcher',
+                'if (-not (Test-Path $dir)) { New-Item -ItemType Directory -Path $dir | Out-Null }',
+                '$body = @\'',
+                "' AUTO-GENERATED; wscript.exe runs without a visible console window.",
+                'Dim WshShell, env, cmd, rc',
+                'Set WshShell = CreateObject("WScript.Shell")',
+                'Set env = WshShell.Environment("PROCESS")',
+                `env("${ENV_FILE_KEY}") = ${vbsString(ef)}`,
+                `cmd = ${vbsString(windowsCommandLine(ctx.exec))}`,
+                'rc = WshShell.Run(cmd, 0, True)',
+                'WScript.Quit rc',
+                "'@",
+                'Set-Content -Path $launcher -Value $body -Encoding Unicode',
+                'schtasks /Create /TN EvoMapEvolverProxyDaemon /TR "wscript.exe ""%LOCALAPPDATA%\\EvoMap\\evolver-proxy-task-launcher.vbs""" /SC ONLOGON /RL LIMITED /F',
+                `# The VBS sets only the ${ENV_FILE_KEY} pointer; the credential store stays out of the task definition.`,
+            ].join('\n');
+        case 'compose':
+            return [
+                '# docker compose — mount the credential store as a file and point EVOLVER_ENV_FILE at it (do NOT bake secrets into the image/env)',
+                'services:',
+                '  evolver:',
+                '    image: <your-evolver-image>',
+                `    command: ${cmd}`,
+                '    environment:',
+                `      ${ENV_FILE_KEY}: /run/secrets/evolver_env   # pointer to the mounted store`,
+                '    secrets:',
+                '      - evolver_env',
+                '    restart: on-failure',
+                'secrets:',
+                '  evolver_env:',
+                `    file: ${ef}   # the real credential store, mounted at /run/secrets/evolver_env`,
+            ].join('\n');
+        case 'k8s':
+            return [
+                '# Kubernetes — keep creds in a Secret, mount it as a file, point EVOLVER_ENV_FILE at the mount (never inline in env)',
+                'apiVersion: apps/v1',
+                'kind: Deployment',
+                'metadata: { name: evolver }',
+                'spec:',
+                '  replicas: 1',
+                '  selector: { matchLabels: { app: evolver } }',
+                '  template:',
+                '    metadata: { labels: { app: evolver } }',
+                '    spec:',
+                '      containers:',
+                '        - name: evolver',
+                '          image: <your-evolver-image>',
+                `          command: [${[ctx.exec.command, ...(ctx.exec.args ?? [])].map((a) => `"${a}"`).join(', ')}]`,
+                `          env: [{ name: ${ENV_FILE_KEY}, value: /etc/evolver/evolver.env }]   # pointer to the mounted secret`,
+                '          volumeMounts: [{ name: evolver-env, mountPath: /etc/evolver, readOnly: true }]',
+                '      volumes:',
+                `        - name: evolver-env`,
+                `          secret: { secretName: evolver-env }   # create from your store: kubectl create secret generic evolver-env --from-file=evolver.env=${ef}`,
+            ].join('\n');
+        default: {
+            const _exhaustive = target;
+            throw new Error(`unknown service target: ${String(_exhaustive)}`);
+        }
+    }
+}
+function quotePosix(value) {
+    return /^[A-Za-z0-9_/:.@%+=,-]+$/.test(value) ? value : `'${value.replaceAll("'", "'\\''")}'`;
+}
+function quoteSystemdArg(value) {
+    return /^[A-Za-z0-9_/:.@%+=,-]+$/.test(value)
+        ? value
+        : `"${value.replaceAll('\\', '\\\\').replaceAll('"', '\\"').replaceAll('$', '\\$')}"`;
+}
+function escapeSystemdEnvValue(value) {
+    return value.replaceAll('\\', '\\\\').replaceAll('"', '\\"').replaceAll('$', '\\$');
+}
+function escapeXml(value) {
+    return value
+        .replaceAll('&', '&amp;')
+        .replaceAll('<', '&lt;')
+        .replaceAll('>', '&gt;')
+        .replaceAll('"', '&quot;')
+        .replaceAll("'", '&apos;');
+}
+function windowsCommandLine(exec) {
+    return execParts(exec).map((part) => `"${part.replaceAll('"', '""')}"`).join(' ');
+}
+function vbsString(value) {
+    return `"${value.replaceAll('"', '""')}"`;
+}

package/dist/stdio.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/stdio.js

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+import { createInterface } from 'node:readline';
+import { randomUUID } from 'node:crypto';
+import { mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { assetstore, events, mailbox } from '@evomap/evolver-core';
+import { buildEvolverTools } from './tools.js';
+import { buildEvolverPrimer } from './primer.js';
+import { EvolverMcpServer, UnknownToolError } from './server.js';
+import { reachableProxyClientFromEnv } from './proxyClient.js';
+import { loadEnvFileFromEnv } from './envFile.js';
+const envFile = loadEnvFileFromEnv(process.env);
+if (envFile.error) {
+    process.stderr.write(`[evolver-mcp] failed to load EVOLVER_ENV_FILE: ${envFile.error}\n`);
+}
+const store = new assetstore.LocalJsonlProvider(events.assetsDir());
+const mailboxPath = process.env['EVOLVER_MCP_MAILBOX'] ?? join(events.evomapHome(), 'mailbox', 'mcp.db');
+mkdirSync(dirname(mailboxPath), { recursive: true });
+const box = new mailbox.MailboxStore({ path: mailboxPath });
+const proxy = await reachableProxyClientFromEnv(process.env);
+// Reuse-feedback wiring (#268): a root_events writer + a per-connection correlation id so a SUCCESS reuse_result
+// from THIS MCP agent credits the local experience loop (one stdio process ~ one MCP session).
+const ingestor = new events.Ingestor({ path: events.rootEventsPath() });
+const connId = `mcp-${randomUUID()}`;
+const server = new EvolverMcpServer(buildEvolverTools({ store, mailbox: box, ingestor, cycleId: connId, ...(proxy ? { proxy } : {}) }), { instructions: buildEvolverPrimer({ proxy: !!proxy }) });
+function send(message) {
+    process.stdout.write(`${JSON.stringify(message)}\n`);
+}
+function ok(id, result) {
+    send({ jsonrpc: '2.0', id, result });
+}
+function fail(id, code, message) {
+    send({ jsonrpc: '2.0', id, error: { code, message } });
+}
+function asRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+async function handle(req) {
+    const id = req.id ?? null;
+    const method = req.method;
+    if (!method)
+        return fail(id, -32600, 'missing method');
+    if (method === 'initialize') {
+        const params = asRecord(req.params);
+        ok(id, {
+            protocolVersion: typeof params['protocolVersion'] === 'string' ? params['protocolVersion'] : '2024-11-05',
+            capabilities: { tools: {} },
+            serverInfo: { name: 'evolver-mcp', version: '0.0.0' },
+            // Quiet mechanism primer (#mcp-onboarding): keep tool workflow available without encouraging user-visible
+            // narration of routine Evolver checks.
+            ...(server.instructions ? { instructions: server.instructions } : {}),
+        });
+        return;
+    }
+    if (method === 'notifications/initialized')
+        return;
+    if (method === 'ping')
+        return ok(id, {});
+    if (method === 'tools/list')
+        return ok(id, { tools: server.listTools() });
+    if (method === 'tools/call') {
+        const params = asRecord(req.params);
+        const name = typeof params['name'] === 'string' ? params['name'] : '';
+        const args = asRecord(params['arguments']);
+        try {
+            const r = await server.callTool(name, args);
+            ok(id, {
+                content: [{ type: 'text', text: r.ok ? JSON.stringify(r.result, null, 2) : (r.error ?? 'tool failed') }],
+                isError: !r.ok,
+            });
+        }
+        catch (err) {
+            const message = err instanceof UnknownToolError ? err.message : (err instanceof Error ? err.message : String(err));
+            fail(id, err instanceof UnknownToolError ? -32601 : -32603, message);
+        }
+        return;
+    }
+    fail(id, -32601, `unknown method: ${method}`);
+}
+const rl = createInterface({ input: process.stdin, crlfDelay: Infinity });
+let requestQueue = Promise.resolve();
+async function processLine(line) {
+    const raw = line.trim();
+    if (!raw)
+        return;
+    let req;
+    try {
+        req = JSON.parse(raw);
+    }
+    catch (err) {
+        fail(null, -32700, err instanceof Error ? err.message : String(err));
+        return;
+    }
+    try {
+        await handle(req);
+    }
+    catch (err) {
+        fail(req.id ?? null, -32603, err instanceof Error ? err.message : String(err));
+    }
+}
+rl.on('line', (line) => {
+    const next = requestQueue.then(() => processLine(line), () => processLine(line));
+    requestQueue = next.catch(() => undefined);
+});
+rl.on('close', () => { void requestQueue.finally(() => { box.close(); process.exit(0); }); });
+process.on('SIGINT', () => { box.close(); process.exit(0); });
+process.on('SIGTERM', () => { box.close(); process.exit(0); });

package/dist/tools.d.ts

@@ -0,0 +1,39 @@
+import { assetstore, mailbox as mb } from '@evomap/evolver-core';
+import type { EvolverProxyClient } from './proxyClient.js';
+/** Minimal root_events writer the reuse-feedback path needs (#268). Structural so the stdio server can pass the
+ *  real `events.Ingestor` and tests can pass a fake — tools.ts stays decoupled from the concrete class. */
+export interface ReuseHitIngestor {
+    ingest(raw: {
+        type: string;
+        human: {
+            title: string;
+            detail?: string;
+        };
+        payload?: Record<string, unknown>;
+    }): Promise<unknown>;
+}
+/** MCP 工具(自带描述, agent runtime 在 tool list 自然发现, 按需调用 — 优于扔大 skill/--help). */
+export interface McpTool {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    handler: (args: Record<string, unknown>) => Promise<unknown>;
+}
+export interface EvolverToolDeps {
+    store: assetstore.AssetStoreProvider;
+    mailbox?: mb.MailboxStore;
+    proxy?: EvolverProxyClient;
+    now?: () => number;
+    /** Root_events writer for the MCP reuse-feedback loop (#268). When wired, a SUCCESS reuse-result emits a local
+     *  `value.reuse_hit` so the local ledger credits reuse driven by an MCP agent (not just the hook/daemon path).
+     *  Absent → no local emission (the tool still works, just no local feedback). */
+    ingestor?: ReuseHitIngestor;
+    /** Server-minted correlation id for this MCP connection (#268). Used as the reuse_hit `cycleId` audit anchor and,
+     *  with the agent's optional taskId, as the idempotency key. One stdio process ~ one MCP session. */
+    cycleId?: string;
+}
+/**
+ * Evolver MCP 工具集(M5-2). asset.search/fetch/publish + gep.build + mailbox.*.
+ * schema 单一来源走 gep-sdk(经 evolver-core 重导出), 不重复实现.
+ */
+export declare function buildEvolverTools(deps: EvolverToolDeps): McpTool[];