berry-agent 0.1.0-alpha.1

package/dist/mcp/jsonrpc.js

@@ -0,0 +1,230 @@
+/**
+ * 行帧 JSON-RPC 编解码与关联表（03 §10.1 手写最小桥的协议腿——零新增依赖）。
+ *
+ * 五方法面：initialize / notifications·initialized / tools/list / tools/call /
+ * ping——id 关联表桥级数十行即覆盖，不引 @modelcontextprotocol/sdk。
+ *
+ * 行帧卫生：server stdout 单行字节上限（缺省 8MiB）——超限按载体级失败收场：
+ * 本层停攒丢弃（静默巨行不进宿主堆）+ fatal 一次上报（桥侧收口 = 封读
+ * destroy + 结清 pending + 树杀 server）。
+ *
+ * 服务器→客户端方向（transport v1 = stdio-only）：
+ * - 请求一律回 -32601（sampling/elicitation capability 拒答——本仓不承载
+ *   这些面），唯一例外 ping 照答（result null）；
+ * - 通知忽略（tools/list_changed v1 不热刷——改配置走 /reload）；
+ * - 宿主不主动 ping——crash 检测靠载体 close 事件（桥侧接线），本层只给
+ *   failAll 结清面。
+ */
+import { BaseError } from '../contracts/index.js';
+import { MCP_LINE_LIMIT_BYTES } from './types.js';
+/** JSON-RPC 层错误（服务器 error 响应折形——业务面消费 code/message） */
+export class JsonRpcError extends Error {
+    rpcCode;
+    rpcData;
+    constructor(error) {
+        super(`JSON-RPC ${error.code}: ${error.message}`);
+        this.name = 'JsonRpcError';
+        this.rpcCode = error.code;
+        this.rpcData = error.data;
+    }
+}
+/**
+ * 行劈解码器（字节面——攒段跨 chunk 拼行）。
+ *
+ * 防线两处：残段累积超帽（无换行的持续巨流）与完整单行超帽（一次到位的
+ * 巨行响应）——任一触发行帧 fatal：此后解码器恒死（不再攒、不再上报——
+ * 一次语义），fatal 后残余行不外发（pending 由连接层结清，行内容无意义）。
+ */
+export class LineDecoder {
+    limitBytes;
+    chunks = [];
+    size = 0;
+    fatal = false;
+    constructor(limitBytes = MCP_LINE_LIMIT_BYTES) {
+        this.limitBytes = limitBytes;
+    }
+    /**
+     * 喂入一段字节；返回完整行（UTF-8 解码、空行丢弃）。
+     * fatal = true 即载体级失败（本次起解码器死——后续 feed 恒空恒不报）。
+     */
+    feed(chunk) {
+        if (this.fatal)
+            return { lines: [], fatal: false };
+        // 换行只可能在本次 chunk 内新现（此前 chunk 已全扫无换行）——快路径零拷贝
+        let idx = chunk.indexOf(0x0a);
+        if (idx < 0) {
+            this.chunks.push(chunk);
+            this.size += chunk.length;
+            if (this.size > this.limitBytes) {
+                this.fatal = true;
+                this.chunks = [];
+                this.size = 0;
+                return { lines: [], fatal: true };
+            }
+            return { lines: [], fatal: false };
+        }
+        // 劈完整行（首段与历史残段拼接；后续段即完整行；尾段成新残段）
+        const rawLines = [];
+        let start = 0;
+        let first = true;
+        while (idx >= 0) {
+            const seg = chunk.subarray(start, idx);
+            if (first && this.chunks.length > 0) {
+                rawLines.push(Buffer.concat([...this.chunks, seg]));
+                this.chunks = [];
+                this.size = 0;
+            }
+            else {
+                rawLines.push(seg);
+            }
+            first = false;
+            start = idx + 1;
+            idx = chunk.indexOf(0x0a, start);
+        }
+        const rest = chunk.subarray(start);
+        if (rest.length > 0) {
+            // subarray 视图持有母本——拷贝释放（防巨母本长活）
+            this.chunks = [Buffer.from(rest)];
+            this.size = rest.length;
+        }
+        else {
+            this.chunks = [];
+            this.size = 0;
+        }
+        // 单行超帽判定（先判后转——fatal 即全弃不发半批）
+        for (const raw of rawLines) {
+            if (raw.length > this.limitBytes) {
+                this.fatal = true;
+                this.chunks = [];
+                this.size = 0;
+                return { lines: [], fatal: true };
+            }
+        }
+        const lines = [];
+        for (const raw of rawLines) {
+            if (raw.length > 0)
+                lines.push(raw.toString('utf8'));
+        }
+        return { lines, fatal: false };
+    }
+}
+/**
+ * 行帧 JSON-RPC 连接（单服务器一座——请求关联表 + 服务器方向分派）。
+ *
+ * 生命周期语义：dead 旗（载体死/fatal）后 request 即拒（快失败不悬挂）；
+ * failAll 是 pending 的总结清面（crash/close/超限三源共用）。
+ */
+export class JsonRpcConnection {
+    nextId = 1;
+    pending = new Map();
+    decoder;
+    options;
+    dead = false;
+    constructor(options) {
+        this.options = options;
+        this.decoder = new LineDecoder(options.lineLimitBytes);
+    }
+    /**
+     * 发请求（关联表登记 + 可选超时执法）。超时按拒绝结清——调用方分类语义
+     * （连接期超时 = MCP_CONNECT_FAILED；调用期超时 = 工具结果 error）。
+     */
+    request(method, params, timeoutMs) {
+        if (this.dead) {
+            return Promise.reject(new BaseError('MCP_CONNECT_FAILED', '连接已死（载体级失败/crash）——不再发请求'));
+        }
+        const id = this.nextId++;
+        const frame = { jsonrpc: '2.0', id, method };
+        if (params !== undefined)
+            frame.params = params;
+        return new Promise((resolve, reject) => {
+            let timer;
+            if (timeoutMs !== undefined && timeoutMs > 0) {
+                timer = setTimeout(() => {
+                    this.pending.delete(id);
+                    reject(new Error(`JSON-RPC 请求超时（${method}，预算 ${timeoutMs}ms）`));
+                }, timeoutMs);
+            }
+            this.pending.set(id, { resolve, reject, timer });
+            this.options.send(JSON.stringify(frame));
+        });
+    }
+    /** 发通知（无 id 不等回复——notifications/initialized 唯一消费者） */
+    notify(method, params) {
+        if (this.dead)
+            return;
+        const frame = { jsonrpc: '2.0', method };
+        if (params !== undefined)
+            frame.params = params;
+        this.options.send(JSON.stringify(frame));
+    }
+    /** stdout 字节喂入（行劈 → 逐行分派；行帧 fatal 即载体级失败收口） */
+    feed(chunk) {
+        const { lines, fatal } = this.decoder.feed(chunk);
+        if (fatal) {
+            this.die(new BaseError('MCP_CONNECT_FAILED', `server stdout 单行超 ${this.options.lineLimitBytes ?? MCP_LINE_LIMIT_BYTES} 字节帽——载体级失败`), '行帧超帽');
+            return;
+        }
+        for (const line of lines)
+            this.dispatch(line);
+    }
+    /** 载体死结清（crash/close——pending 全拒；幂等） */
+    failAll(error) {
+        this.die(error, undefined);
+    }
+    /** 内部死面：dead 封口 + pending 总清（fatal 时另报 onFatal 一次） */
+    die(error, fatalReason) {
+        if (this.dead)
+            return;
+        this.dead = true;
+        for (const entry of this.pending.values()) {
+            if (entry.timer !== undefined)
+                clearTimeout(entry.timer);
+            entry.reject(error);
+        }
+        this.pending.clear();
+        if (fatalReason !== undefined)
+            this.options.onFatal?.(fatalReason);
+    }
+    /** 单行分派（响应结清 / 服务器方向请求应答 / 通知忽略） */
+    dispatch(line) {
+        let msg;
+        try {
+            msg = JSON.parse(line);
+        }
+        catch {
+            this.options.warn?.(`server 行帧 JSON 坏形跳过：${line.slice(0, 120)}`);
+            return;
+        }
+        if (typeof msg !== 'object' || msg === null)
+            return;
+        const m = msg;
+        if (typeof m.method === 'string') {
+            if (m.id !== undefined) {
+                // 服务器→客户端请求：ping 照答；其余一律 -32601（capability 拒答）
+                const response = m.method === 'ping'
+                    ? { jsonrpc: '2.0', id: m.id, result: null }
+                    : {
+                        jsonrpc: '2.0',
+                        id: m.id,
+                        error: { code: -32601, message: `transport v1 stdio-only：拒答服务器请求 ${m.method}` },
+                    };
+                if (!this.dead)
+                    this.options.send(JSON.stringify(response));
+            }
+            // 通知（含 tools/list_changed）——v1 忽略不热刷
+            return;
+        }
+        if (typeof m.id === 'number') {
+            const entry = this.pending.get(m.id);
+            if (entry === undefined)
+                return; // 迟到/未知 id——超时已结清或非本连接帧
+            this.pending.delete(m.id);
+            if (entry.timer !== undefined)
+                clearTimeout(entry.timer);
+            if (m.error !== undefined)
+                entry.reject(new JsonRpcError(m.error));
+            else
+                entry.resolve(m.result);
+        }
+    }
+}

package/dist/mcp/service.js

@@ -0,0 +1,125 @@
+/**
+ * MCP 服务面（03 §10.1 连接语义的编排核心——装配后异步发现零阻塞）。
+ *
+ * apply(config)：同步返回零等待——每服务器后台发现（fire-and-forget 必带
+ * .catch 失败收口：MCP_CONNECT_FAILED 降 warn + ui.notify，单服务器失败不阻
+ * 同行其余、不阻宿主启动）；续段每步查 scope 活（/reload/卸行竞速护栏——
+ * 死即协议化关停且不计失败）。发现完成 → 桥入活表 → 工具面重铺（全局合计
+ * 定形态：≤20 原生注册 / >20 目录降级——每桥落地/撤销均重铺，阈值随活集
+ * 自然收敛）。
+ *
+ * crash：撤该服务器工具（重铺减源）+ ui.notify warn + 不自动重连（复位走
+ * /reload）。作用域回卷：ctx.effect LIFO——各桥 close()（stdin.end 协议化
+ * 告别 → 宽限 → killTree 树杀）异步起跑不阻塞回卷序。
+ */
+import { createLogger } from '../context/index.js';
+import { connectMcpServer } from './bridge.js';
+import { buildMcpToolDefs } from './tools.js';
+import { filterServerTools } from './tools.js';
+/** 组 MCP 服务 */
+export function createMcpService(deps) {
+    const logger = deps.logger ?? createLogger('mcp');
+    const notify = deps.notify ?? (() => undefined);
+    /** 活桥表（server → { bridge, config }——config 供过滤与重铺） */
+    const bridges = new Map();
+    /** 当前注册面注销器（重铺先全撤） */
+    let surfaceDisposers = [];
+    const isAlive = () => !deps.scope.isDisposed;
+    /** 撤当前注册面（重铺/回卷共用——幂等） */
+    function disposeSurface() {
+        for (const dispose of surfaceDisposers) {
+            try {
+                dispose();
+            }
+            catch (err) {
+                logger.warn(`MCP 工具注销失败：${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        surfaceDisposers = [];
+    }
+    /** 拼活源清单（enabled/disabled 过滤落此——复合名/目录面只见过滤后集） */
+    function liveSources() {
+        const sources = [];
+        for (const { bridge, config } of bridges.values()) {
+            sources.push({
+                server: bridge.server,
+                tools: filterServerTools(bridge.tools, config),
+                toolTimeoutMs: bridge.toolTimeoutMs,
+                call: (tool, args) => bridge.call(tool, args),
+            });
+        }
+        return sources;
+    }
+    /** 重铺工具面（全撤重建——形态随活集合计裁决；scope 死即不铺） */
+    function resurface() {
+        if (!isAlive())
+            return;
+        disposeSurface();
+        const { defs } = buildMcpToolDefs(liveSources(), (message) => logger.warn(message));
+        for (const def of defs) {
+            try {
+                surfaceDisposers.push(deps.registry.register(def));
+            }
+            catch (err) {
+                // per-def 容错：撞名（TOOL_NAME_CONFLICT）/令牌桶（TOOL_CHANGE_RATE_LIMITED）
+                // 等注册面拒——单件降级 warn 不炸全行
+                logger.warn(`MCP 工具注册失败（${def.name}）：${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    /** 单服务器后台发现（fire-and-forget 调用方必带 .catch） */
+    async function discover(server, config) {
+        const bridge = await connectMcpServer(server, config, {
+            spawn: deps.spawn,
+            logger,
+            closeGraceMs: deps.closeGraceMs,
+            clientVersion: deps.clientVersion,
+        });
+        // 续段 scope 活查（异步边界护栏——/reload/卸行竞速）：死即协议化关停，
+        // 不入活表不计失败（安静退场非降级语义）
+        if (!isAlive()) {
+            await bridge.close();
+            return;
+        }
+        bridges.set(server, { bridge, config });
+        bridge.onDown((reason) => {
+            // 运行期 crash：撤工具 + ui.notify warn + 不自动重连（复位走 /reload）
+            if (bridges.get(server)?.bridge !== bridge)
+                return; // 旧桥迟到事件（重 apply 后）
+            bridges.delete(server);
+            notify(`MCP 服务器 ${server} 已断开（${reason}）——其工具已撤，复位走 /reload`);
+            resurface();
+        });
+        resurface();
+    }
+    /** 撤全部桥（重复 apply / 回卷共用——LIFO 关停异步起跑） */
+    function shutdownAll() {
+        const entries = [...bridges.values()].reverse(); // LIFO——后连先关
+        bridges.clear();
+        disposeSurface();
+        for (const { bridge } of entries)
+            void bridge.close();
+    }
+    // 作用域回卷登记（LIFO 尾位——回卷即全撤：stdin.end → 宽限 → killTree）
+    deps.scope.effect(() => () => shutdownAll());
+    const service = {
+        apply(config) {
+            shutdownAll(); // config 整值替换语义——旧桥全撤再发现（§5.3）
+            for (const [server, serverConfig] of Object.entries(config)) {
+                void discover(server, serverConfig).catch((err) => {
+                    // 失败收口必带（fire-and-forget 纪律）：降 warn + ui.notify 不炸装配
+                    const detail = err instanceof Error ? err.message : String(err);
+                    logger.warn(`MCP 服务器连接失败（${server}）：${detail}`);
+                    notify(`MCP 服务器 ${server} 连接失败：${detail}`);
+                });
+            }
+        },
+        liveServers() {
+            return [...bridges.entries()].map(([server, { bridge, config }]) => ({
+                server,
+                toolCount: filterServerTools(bridge.tools, config).length,
+            }));
+        },
+    };
+    return service;
+}

package/dist/mcp/tools.js

@@ -0,0 +1,145 @@
+import { MCP_NATIVE_TOOL_LIMIT } from './types.js';
+/** 目录工具名（降级形态单件名——命名域顶层 'mcp'） */
+export const MCP_DIRECTORY_TOOL_NAME = 'mcp';
+/** 组复合名（`<server>__<tool>`——服务器键无下划线，首 `__` 即分界） */
+export function mcpToolKey(server, tool) {
+    return `${server}__${tool}`;
+}
+/** 劈复合名（首 `__` 分界；无分界/空段 = 非法键返 null） */
+export function splitMcpToolKey(key) {
+    const idx = key.indexOf('__');
+    if (idx <= 0 || idx === key.length - 2)
+        return null;
+    return { server: key.slice(0, idx), tool: key.slice(idx + 2) };
+}
+/**
+ * enabled/disabled 双表过滤（enabled 在场 = 白名单收窄；disabled 恒排除——
+ * 双表合用先白后黑）。过滤语义在服务器侧原名面（复合名只在暴露面）。
+ */
+export function filterServerTools(tools, config) {
+    let out = tools;
+    if (config.enabled_tools !== undefined) {
+        const allow = new Set(config.enabled_tools);
+        out = out.filter((t) => allow.has(t.name));
+    }
+    if (config.disabled_tools !== undefined) {
+        const deny = new Set(config.disabled_tools);
+        out = out.filter((t) => !deny.has(t.name));
+    }
+    return out;
+}
+/**
+ * 建工具面（形态裁决 + 定义产出）。非 object 根 inputSchema 的工具跳过 +
+ * warn（直喂纪律下坏形不入注册面——注册表 TOOL_SCHEMA_INVALID 会炸全行，
+ * 诚实降级单件跳过）。
+ */
+export function buildMcpToolDefs(sources, warn = () => undefined) {
+    // 逐源过滤 + 复合名配对（server 键词法已保证无 `__`——无歧义）
+    const entries = [];
+    for (const source of sources) {
+        for (const tool of source.tools) {
+            entries.push({ source, tool });
+        }
+    }
+    if (entries.length > MCP_NATIVE_TOOL_LIMIT) {
+        return { defs: [buildDirectoryDef(sources)], directory: true };
+    }
+    const defs = [];
+    for (const { source, tool } of entries) {
+        if (!isRootObjectSchema(tool.inputSchema)) {
+            warn(`MCP 工具 schema 根非 object 跳过：${mcpToolKey(source.server, tool.name)}`);
+            continue;
+        }
+        const originalName = tool.name;
+        defs.push({
+            name: mcpToolKey(source.server, originalName),
+            description: tool.description ?? `MCP 工具（服务器 ${source.server}）`,
+            parameters: tool.inputSchema,
+            timeoutMs: source.toolTimeoutMs,
+            execute: (args) => source.call(originalName, args), // 落桥换回服务器侧原名
+        });
+    }
+    return { defs, directory: false };
+}
+/** 目录工具（降级形态——schema 恒定三动作） */
+function buildDirectoryDef(sources) {
+    // 管道帽 = 活服务器逐台预算最大值（缺省服务器不被他台大预算连带抬升——
+    // 各台缺省一致时即缺省值；call 落桥后逐台执法不受此帽语义干扰）
+    const pipelineTimeoutMs = sources.reduce((max, s) => Math.max(max, s.toolTimeoutMs), 0);
+    return {
+        name: MCP_DIRECTORY_TOOL_NAME,
+        description: 'MCP 服务器工具目录（多服务器工具合计超 20 件的降级形态）：action=search 列出 / describe 详述 / call 调用；tool 参数为寻址键 <server>__<tool>',
+        parameters: {
+            type: 'object',
+            properties: {
+                action: { type: 'string', enum: ['search', 'describe', 'call'], description: '目录动作' },
+                tool: { type: 'string', description: '目录寻址键 <server>__<tool>（describe/call 必填）' },
+                query: { type: 'string', description: 'search 的过滤词（子串匹配，可选）' },
+                arguments: { type: 'object', description: 'call 动作的工具参数（可选）' },
+            },
+            required: ['action'],
+        },
+        timeoutMs: pipelineTimeoutMs,
+        execute: async (args) => directoryExecute(sources, args),
+    };
+}
+/** 目录三动作路由（search/describe/call——未知键诚实 isError） */
+async function directoryExecute(sources, args) {
+    const action = args.action;
+    if (action === 'search') {
+        const query = typeof args.query === 'string' ? args.query.toLowerCase() : '';
+        const lines = [];
+        for (const source of sources) {
+            for (const tool of source.tools) {
+                const key = mcpToolKey(source.server, tool.name);
+                const hay = `${key} ${tool.description ?? ''}`.toLowerCase();
+                if (query === '' || hay.includes(query)) {
+                    lines.push(`${key} — ${tool.description ?? '（无描述）'}`);
+                }
+            }
+        }
+        return { content: [{ type: 'text', text: lines.length > 0 ? lines.join('\n') : '（无匹配 MCP 工具）' }] };
+    }
+    if (action === 'describe' || action === 'call') {
+        const key = typeof args.tool === 'string' ? args.tool : '';
+        const split = splitMcpToolKey(key);
+        const source = split !== null ? sources.find((s) => s.server === split.server) : undefined;
+        const tool = source !== undefined && split !== null ? source.tools.find((t) => t.name === split.tool) : undefined;
+        if (source === undefined || tool === undefined || split === null) {
+            return {
+                content: [
+                    { type: 'text', text: `未知 MCP 工具键：${key}（search 动作可列当前可用键——服务器 crash 后工具即撤）` },
+                ],
+                isError: true,
+            };
+        }
+        if (action === 'describe') {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            server: source.server,
+                            name: tool.name,
+                            description: tool.description ?? null,
+                            inputSchema: tool.inputSchema,
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        const callArgs = typeof args.arguments === 'object' && args.arguments !== null && !Array.isArray(args.arguments)
+            ? args.arguments
+            : {};
+        return source.call(tool.name, callArgs); // 落桥换回服务器侧原名——逐台执法
+    }
+    return {
+        content: [{ type: 'text', text: `未知目录动作：${JSON.stringify(action)}（search/describe/call 三选一）` }],
+        isError: true,
+    };
+}
+/** schema 根 object 判（直喂注册面的前置校验——非 object 根注册表会拒） */
+function isRootObjectSchema(schema) {
+    const t = schema.type;
+    return t === 'object';
+}

package/dist/mcp/types.js

@@ -0,0 +1,108 @@
+/**
+ * core:mcp 类型面（03 §10.1——stdio 行帧 JSON-RPC 手写最小桥；批 17a-2）。
+ *
+ * 词面独立律（02 §4.1 席 deps = contracts + context）：本件与 exec/tools 零
+ * DAG 边——spawn 与工具注册全经**窄面注入**消费（issue 件 IssueWorktreeFace
+ * 先例同律）：
+ * - `McpSpawnFace` 与 exec SpawnPipeline.spawnInteractive 结构兼容（组合根
+ *   直接传管道真身；兼容性互证测试在 compat.test.ts）；
+ * - `McpRegisterToolsFace` 与 tools ToolRegistry.register 子面结构兼容
+ *   （返回注销器 = 撤工具面）；
+ * - `McpScopeFace` 与 context Scope 的 effect/isDisposed 子面结构兼容
+ *   （ctx.effect 回卷 + 续段 scope 活查）。
+ *
+ * context 席边为真消费（createLogger——装载态 ui.notify 接线随装配批）。
+ */
+import { BaseError } from '../contracts/index.js';
+/* ---------------- 常量（缺省值单源——03 §10.1 字段集落码定形注） ---------------- */
+/** 服务器键词法（`[A-Za-z0-9-]+`——`__` 与空白禁入；复合名 `<server>__<tool>` 的无歧义分界前提） */
+export const MCP_SERVER_NAME_RE = /^[A-Za-z0-9-]+$/;
+/** initialize 握手预算缺省秒数（spawn+握手同罩——只罩连接建立，不罩单次调用） */
+export const MCP_STARTUP_TIMEOUT_SEC_DEFAULT = 10;
+/** 单次工具调用预算缺省秒数（tools/call 逐台执法） */
+export const MCP_TOOL_TIMEOUT_SEC_DEFAULT = 60;
+/** server stdout 单行字节上限（行帧卫生——超限按载体级失败收场，静默巨行不进宿主堆） */
+export const MCP_LINE_LIMIT_BYTES = 8 * 1024 * 1024;
+/** 注册面爆炸防线阈值（过滤后全局合计 >20 → 全部降级为单件 mcp 目录工具） */
+export const MCP_NATIVE_TOOL_LIMIT = 20;
+/** 协议化关停宽限缺省（stdin.end 告别 → 宽限等退 → killTree 树杀兜底） */
+export const MCP_CLOSE_GRACE_MS = 3_000;
+/** 客户端握手 protocolVersion（已知集最基底值——最广服务器支持面；服务器回显异值不拒） */
+export const MCP_PROTOCOL_VERSION = '2024-11-05';
+/**
+ * 归一 config.servers（坏形响亮拒 MCP_CONFIG_INVALID——/reload 时刻可见）。
+ * 非对象/null/undefined → 空配置（缺省 servers 空 = 行惰性无害零 spawn）。
+ */
+export function normalizeMcpConfig(raw) {
+    if (raw === undefined || raw === null)
+        return {};
+    if (typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new BaseError('MCP_CONFIG_INVALID', 'config.servers 须为对象（键 = 服务器名）');
+    }
+    const out = {};
+    for (const [name, value] of Object.entries(raw)) {
+        out[name] = normalizeServerEntry(name, value);
+    }
+    return out;
+}
+/** 单服务器条目归一（字段集逐一类型校验——词法/绝对路径/正数域） */
+function normalizeServerEntry(name, value) {
+    if (!MCP_SERVER_NAME_RE.test(name)) {
+        throw new BaseError('MCP_CONFIG_INVALID', `服务器键词法违例：${JSON.stringify(name)}（须匹配 [A-Za-z0-9-]+——__ 与空白禁入）`);
+    }
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new BaseError('MCP_CONFIG_INVALID', `servers.${name} 须为对象`);
+    }
+    const v = value;
+    const command = v.command;
+    if (typeof command !== 'string' || command === '' || !command.startsWith('/')) {
+        throw new BaseError('MCP_CONFIG_INVALID', `servers.${name}.command 须为绝对路径（v1 只收绝对路径）：${JSON.stringify(command)}`);
+    }
+    const args = strArray(v.args, `servers.${name}.args`);
+    const env = strRecord(v.env, `servers.${name}.env`);
+    const enabled = strArray(v.enabled_tools, `servers.${name}.enabled_tools`);
+    const disabled = strArray(v.disabled_tools, `servers.${name}.disabled_tools`);
+    const startup = positiveNumber(v.startup_timeout_sec, `servers.${name}.startup_timeout_sec`);
+    const toolTimeout = positiveNumber(v.tool_timeout_sec, `servers.${name}.tool_timeout_sec`);
+    return {
+        command,
+        ...(args !== undefined ? { args } : {}),
+        ...(env !== undefined ? { env } : {}),
+        ...(enabled !== undefined ? { enabled_tools: enabled } : {}),
+        ...(disabled !== undefined ? { disabled_tools: disabled } : {}),
+        ...(startup !== undefined ? { startup_timeout_sec: startup } : {}),
+        ...(toolTimeout !== undefined ? { tool_timeout_sec: toolTimeout } : {}),
+    };
+}
+/** 字符串数组字段校验（undefined 放行——可选字段缺席合法） */
+function strArray(value, label) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value) || value.some((e) => typeof e !== 'string')) {
+        throw new BaseError('MCP_CONFIG_INVALID', `${label} 须为字符串数组`);
+    }
+    return value;
+}
+/** 字符串记录字段校验（env 显式注入面） */
+function strRecord(value, label) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new BaseError('MCP_CONFIG_INVALID', `${label} 须为 string→string 对象`);
+    }
+    for (const [k, val] of Object.entries(value)) {
+        if (typeof val !== 'string') {
+            throw new BaseError('MCP_CONFIG_INVALID', `${label}.${k} 须为 string`);
+        }
+    }
+    return value;
+}
+/** 正数域字段校验（超时秒——0/负/非数拒） */
+function positiveNumber(value, label) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
+        throw new BaseError('MCP_CONFIG_INVALID', `${label} 须为正数（秒）`);
+    }
+    return value;
+}