@ai-setting/roy-agent-cli 1.3.14 → 1.3.16

package/dist/core/src/env/mcp/scanner.test.js

@@ -0,0 +1,115 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "fs/promises";
+import path from "path";
+import os from "os";
+import { McpScanner } from "./scanner.js";
+/**
+ * TDD RED: 测试 McpScanner
+ */
+describe("McpScanner", () => {
+    const tempDir = path.join(os.tmpdir(), "mcp-scanner-test-" + Date.now());
+    beforeEach(async () => {
+        await fs.mkdir(tempDir, { recursive: true });
+    });
+    afterEach(async () => {
+        await fs.rm(tempDir, { recursive: true, force: true });
+    });
+    describe("scan", () => {
+        it("should return empty map when path does not exist", async () => {
+            const scanner = new McpScanner([
+                { type: "user", path: "/non/existent/path" },
+            ]);
+            const servers = await scanner.scan();
+            expect(servers.size).toBe(0);
+        });
+        it("should discover servers from directory", async () => {
+            // 创建测试目录结构
+            await fs.mkdir(path.join(tempDir, "test-mcp"));
+            await fs.writeFile(path.join(tempDir, "test-mcp", "server.ts"), "console.log('hello')");
+            const scanner = new McpScanner([
+                { type: "user", path: tempDir },
+            ]);
+            const servers = await scanner.scan();
+            expect(servers.size).toBe(1);
+            expect(servers.has("test-mcp")).toBe(true);
+        });
+        it("should find entryPath for discovered server", async () => {
+            await fs.mkdir(path.join(tempDir, "my-server"));
+            await fs.writeFile(path.join(tempDir, "my-server", "server.ts"), "export default {}");
+            const scanner = new McpScanner([
+                { type: "user", path: tempDir },
+            ]);
+            const servers = await scanner.scan();
+            const server = servers.get("my-server");
+            expect(server?.entryPath).toContain("server.ts");
+        });
+        it("should skip non-directory entries", async () => {
+            await fs.writeFile(path.join(tempDir, "not-a-server.txt"), "content");
+            const scanner = new McpScanner([
+                { type: "user", path: tempDir },
+            ]);
+            const servers = await scanner.scan();
+            expect(servers.size).toBe(0);
+        });
+        it("should find index.ts as entry point", async () => {
+            await fs.mkdir(path.join(tempDir, "index-server"));
+            await fs.writeFile(path.join(tempDir, "index-server", "index.ts"), "export default {}");
+            const scanner = new McpScanner([
+                { type: "user", path: tempDir },
+            ]);
+            const servers = await scanner.scan();
+            const server = servers.get("index-server");
+            expect(server?.entryPath).toContain("index.ts");
+        });
+        it("should load config.jsonc if exists", async () => {
+            await fs.mkdir(path.join(tempDir, "config-server"));
+            await fs.writeFile(path.join(tempDir, "config-server", "server.ts"), "export default {}");
+            await fs.writeFile(path.join(tempDir, "config-server", "config.jsonc"), JSON.stringify({ enabled: true, timeout: 60000 }));
+            const scanner = new McpScanner([
+                { type: "user", path: tempDir },
+            ]);
+            const servers = await scanner.scan();
+            const server = servers.get("config-server");
+            expect(server?.configPath).toContain("config.jsonc");
+            expect(server?.directoryConfig?.enabled).toBe(true);
+        });
+        it("should support multiple paths", async () => {
+            const tempDir2 = path.join(os.tmpdir(), "mcp-scanner-test2-" + Date.now());
+            await fs.mkdir(tempDir2, { recursive: true });
+            await fs.mkdir(path.join(tempDir, "server1"));
+            await fs.writeFile(path.join(tempDir, "server1", "server.ts"), "export default {}");
+            await fs.mkdir(path.join(tempDir2, "server2"));
+            await fs.writeFile(path.join(tempDir2, "server2", "server.ts"), "export default {}");
+            const scanner = new McpScanner([
+                { type: "user", path: tempDir },
+                { type: "custom", path: tempDir2 },
+            ]);
+            const servers = await scanner.scan();
+            expect(servers.size).toBe(2);
+            expect(servers.has("server1")).toBe(true);
+            expect(servers.has("server2")).toBe(true);
+            await fs.rm(tempDir2, { recursive: true, force: true });
+        });
+    });
+    describe("getServers", () => {
+        it("should return scanned servers", async () => {
+            await fs.mkdir(path.join(tempDir, "cached-server"));
+            await fs.writeFile(path.join(tempDir, "cached-server", "server.ts"), "export default {}");
+            const scanner = new McpScanner([
+                { type: "user", path: tempDir },
+            ]);
+            await scanner.scan();
+            const servers = scanner.getServers();
+            expect(servers.size).toBe(1);
+            expect(servers.has("cached-server")).toBe(true);
+        });
+        it("should return empty map before scan", () => {
+            const scanner = new McpScanner([
+                { type: "user", path: tempDir },
+            ]);
+            const servers = scanner.getServers();
+            expect(servers.size).toBe(0);
+        });
+    });
+});
+//# sourceMappingURL=scanner.test.js.map

package/dist/core/src/env/mcp/tool/adapter.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @fileoverview MCP Tool 适配器
+ *
+ * 将 MCP 工具转换为 Environment Tool
+ * 完整保留参数描述等信息，供 LLM 正确调用
+ */
+import { z } from "zod";
+import type { Tool as McpTool } from "@modelcontextprotocol/sdk/types.js";
+import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import type { ToolInfo } from "../../tool/types";
+/**
+ * 将 MCP 工具转换为 Environment Tool
+ *
+ * 命名策略: mcp_{serverName}_{toolName}
+ */
+export declare function adaptMcpTool(mcpTool: McpTool, mcpClient: Client, serverName: string): ToolInfo;
+/**
+ * 转换 MCP inputSchema 为 Zod schema
+ *
+ * 关键：保留参数描述，让 LLM 知道每个参数的用途
+ */
+export declare function convertInputSchemaToZod(inputSchema: McpTool["inputSchema"]): z.ZodType<unknown>;
+/**
+ * 创建 MCP 工具描述
+ */
+export declare function createMcpToolsDescription(tools: ToolInfo[]): string;
+/**
+ * 获取工具的完整参数描述（供 LLM 使用）
+ *
+ * 从 Zod schema 中提取参数描述
+ */
+export declare function getToolParamDescriptions(tool: ToolInfo): Record<string, string>;
+//# sourceMappingURL=adapter.d.ts.map

package/dist/core/src/env/mcp/tool/adapter.js

@@ -0,0 +1,413 @@
+/**
+ * @fileoverview MCP Tool 适配器
+ *
+ * 将 MCP 工具转换为 Environment Tool
+ * 完整保留参数描述等信息，供 LLM 正确调用
+ */
+import { z } from "zod";
+import { createLogger } from "../../log-trace/logger.js";
+const logger = createLogger("mcp-adapter");
+/**
+ * 将 MCP 工具转换为 Environment Tool
+ *
+ * 命名策略: mcp_{serverName}_{toolName}
+ */
+export function adaptMcpTool(mcpTool, mcpClient, serverName) {
+    const toolName = `mcp_${serverName}_${mcpTool.name}`;
+    const description = `MCP tool [${serverName}/${mcpTool.name}]: ${mcpTool.description ?? ""}`;
+    // 转换参数 schema（包含描述信息）
+    const paramsSchema = convertInputSchemaToZod(mcpTool.inputSchema);
+    return {
+        name: toolName,
+        description,
+        parameters: paramsSchema,
+        execute: async (args, _ctx) => {
+            try {
+                const result = await mcpClient.callTool({
+                    name: mcpTool.name,
+                    arguments: args ?? {},
+                });
+                // 转换结果
+                return convertMcpCallResult(result);
+            }
+            catch (error) {
+                logger.error(`[McpAdapter] Tool call failed: ${toolName}`, {
+                    error: error instanceof Error ? error.message : String(error),
+                });
+                return {
+                    success: false,
+                    output: "",
+                    error: error instanceof Error ? error.message : String(error),
+                };
+            }
+        },
+        metadata: {
+            category: "mcp",
+            tags: ["mcp", serverName],
+            // 保留原始 MCP 工具信息，供 LLM 使用
+            mcpTool: {
+                originalName: mcpTool.name,
+                originalDescription: mcpTool.description || "",
+                inputSchema: mcpTool.inputSchema,
+            },
+        },
+    };
+}
+/**
+ * 转换 MCP inputSchema 为 Zod schema
+ *
+ * 关键：保留参数描述，让 LLM 知道每个参数的用途
+ */
+export function convertInputSchemaToZod(inputSchema) {
+    if (!inputSchema) {
+        return z.unknown();
+    }
+    const schema = inputSchema;
+    const properties = schema.properties ?? {};
+    const required = schema.required ?? [];
+    // 检查是否有 anyOf/oneOf - 表示联合类型
+    if (schema.anyOf || schema.oneOf) {
+        const unions = schema.anyOf || schema.oneOf || [];
+        const zodUnions = unions.map((s) => jsonSchemaToZod(s, false)).filter((t) => t);
+        if (zodUnions.length > 0) {
+            // 使用 any 避免复杂的类型问题
+            return z.union(zodUnions);
+        }
+    }
+    // 处理 anyOf/oneOf 作为联合类型
+    if (schema.allOf) {
+        // allOf 表示组合多个 schema
+        const schemas = [];
+        for (const subSchema of schema.allOf) {
+            const sub = jsonSchemaToZod(subSchema, false);
+            schemas.push(sub);
+        }
+        if (schemas.length === 1) {
+            return schemas[0];
+        }
+        // 使用 intersect 替代 merge
+        let combined = schemas[0];
+        for (let i = 1; i < schemas.length; i++) {
+            combined = z.intersection(combined, schemas[i]);
+        }
+        return combined;
+    }
+    // 构建对象 schema
+    const zodFields = {};
+    const fieldDescriptions = {};
+    for (const [key, prop] of Object.entries(properties)) {
+        const isRequired = required.includes(key);
+        const fieldResult = jsonSchemaToZod(prop, !isRequired);
+        // 保留参数描述
+        const propSchema = prop;
+        if (propSchema.description) {
+            fieldDescriptions[key] = propSchema.description;
+        }
+        // 如果不是 required，添加 optional
+        if (!isRequired) {
+            zodFields[key] = fieldResult.optional();
+        }
+        else {
+            zodFields[key] = fieldResult;
+        }
+    }
+    // 使用 describe 构建 schema
+    if (Object.keys(zodFields).length === 0) {
+        return schema.description ? z.unknown().describe(schema.description) : z.unknown();
+    }
+    // 构建带描述的 Zod schema
+    const result = z.object(zodFields);
+    // 添加 schema 级别的描述
+    if (schema.description) {
+        return result.describe(schema.description);
+    }
+    return result;
+}
+/**
+ * JSON Schema 属性转 Zod 类型
+ *
+ * 保留描述信息
+ */
+function jsonSchemaToZod(prop, isOptional) {
+    const description = prop.description;
+    let baseType;
+    // 处理 nullable
+    if (prop.nullable === true) {
+        const innerType = jsonSchemaToZod({ ...prop, nullable: undefined }, isOptional);
+        baseType = z.union([innerType, z.null()]);
+        if (description) {
+            return baseType.describe(description);
+        }
+        return baseType;
+    }
+    // 处理 anyOf/oneOf
+    if (prop.anyOf || prop.oneOf) {
+        const unions = prop.anyOf || prop.oneOf || [];
+        const zodUnions = unions
+            .map((s) => jsonSchemaToZod(s, false))
+            .filter((t) => t);
+        if (zodUnions.length > 0) {
+            baseType = z.union(zodUnions);
+            if (description) {
+                return baseType.describe(description);
+            }
+            return baseType;
+        }
+    }
+    // 处理 allOf
+    if (prop.allOf) {
+        const schemas = [];
+        for (const subSchema of prop.allOf) {
+            const sub = jsonSchemaToZod(subSchema, false);
+            schemas.push(sub);
+        }
+        if (schemas.length === 1) {
+            baseType = schemas[0];
+        }
+        else {
+            // 使用 intersect 组合
+            baseType = z.intersection(schemas[0], schemas[1]);
+            for (let i = 2; i < schemas.length; i++) {
+                baseType = z.intersection(baseType, schemas[i]);
+            }
+        }
+        if (description) {
+            return baseType.describe(description);
+        }
+        return baseType;
+    }
+    // 获取类型（支持 type 或 types）
+    const types = prop.types || (prop.type ? [prop.type] : []);
+    // 处理多个类型
+    if (types.length > 1) {
+        const zodTypes = types
+            .map((t) => getZodTypeForBasicType(t, prop))
+            .filter((t) => t);
+        if (zodTypes.length > 0) {
+            baseType = z.union(zodTypes);
+            if (description) {
+                return baseType.describe(description);
+            }
+            return baseType;
+        }
+    }
+    // 单类型处理
+    const type = types[0];
+    if (!type) {
+        // 没有类型但有 enum
+        if (prop.enum) {
+            // handleEnum 内部会处理描述
+            return handleEnum(prop, description);
+        }
+        // 没有类型也没有 enum，返回 unknown
+        baseType = z.unknown();
+        if (description) {
+            return baseType.describe(description);
+        }
+        return baseType;
+    }
+    baseType = getZodTypeForBasicType(type, prop);
+    // 添加描述（但保留 handleEnum 已经添加的有效值描述）
+    if (description) {
+        // 检查 schema 是否有描述（来自 handleEnum）
+        const schemaDescription = baseType._def?.description;
+        if (schemaDescription) {
+            // 如果 schema 已有描述，说明是 enum，追加而不是覆盖
+            return baseType.describe(`${schemaDescription}. ${description}`);
+        }
+        return baseType.describe(description);
+    }
+    return baseType;
+}
+/**
+ * 根据基本类型获取 Zod 类型
+ * 注意：不处理描述，描述由调用方统一处理
+ */
+function getZodTypeForBasicType(type, prop) {
+    switch (type) {
+        case "string": {
+            // 优先处理 enum - 使用 handleEnum 来确保添加有效值描述
+            if (prop.enum && prop.enum.length > 0 && prop.enum.every((v) => typeof v === "string")) {
+                // handleEnum 会自动添加有效值列表到描述
+                return handleEnum(prop, prop.description);
+            }
+            let schema = z.string();
+            // 处理 minLength
+            if (typeof prop.minLength === "number") {
+                schema = schema.min(prop.minLength);
+            }
+            // 处理 maxLength
+            if (typeof prop.maxLength === "number") {
+                schema = schema.max(prop.maxLength);
+            }
+            // 处理 pattern (正则)
+            if (prop.pattern) {
+                try {
+                    schema = schema.regex(new RegExp(prop.pattern));
+                }
+                catch {
+                    // 无效的正则，忽略
+                }
+            }
+            // 处理 format - 添加到 schema 描述
+            if (prop.format) {
+                schema = schema.describe(`Format: ${prop.format}`);
+            }
+            // 处理 default
+            if (prop.default !== undefined) {
+                schema = schema.default(prop.default);
+            }
+            return schema;
+        }
+        case "number":
+        case "integer": {
+            let schema = type === "integer" ? z.number().int() : z.number();
+            // 处理 minimum
+            if (typeof prop.minimum === "number") {
+                schema = schema.min(prop.minimum);
+            }
+            // 处理 maximum
+            if (typeof prop.maximum === "number") {
+                schema = schema.max(prop.maximum);
+            }
+            // 处理 default
+            if (prop.default !== undefined) {
+                schema = schema.default(prop.default);
+            }
+            return schema;
+        }
+        case "boolean": {
+            let schema = z.boolean();
+            if (prop.default !== undefined) {
+                schema = schema.default(prop.default);
+            }
+            return schema;
+        }
+        case "array": {
+            let itemSchema = z.unknown();
+            if (prop.items) {
+                itemSchema = jsonSchemaToZod(prop.items, false);
+            }
+            let schema = z.array(itemSchema);
+            // 处理 additionalProperties 作为数组成员类型
+            if (prop.additionalProperties && typeof prop.additionalProperties !== "boolean") {
+                const additionalItems = jsonSchemaToZod(prop.additionalProperties, false);
+                // 混合数组
+                schema = z.array(z.union([itemSchema, additionalItems]));
+            }
+            return schema;
+        }
+        case "object": {
+            if (prop.properties) {
+                const fields = {};
+                const required = prop.required ?? [];
+                for (const [key, value] of Object.entries(prop.properties)) {
+                    const isRequired = required.includes(key);
+                    fields[key] = isRequired
+                        ? jsonSchemaToZod(value, false)
+                        : jsonSchemaToZod(value, true).optional();
+                }
+                return z.object(fields);
+            }
+            // 没有 properties，检查 additionalProperties
+            if (prop.additionalProperties) {
+                if (typeof prop.additionalProperties === "boolean") {
+                    return z.record(z.string(), z.unknown());
+                }
+                return z.record(z.string(), jsonSchemaToZod(prop.additionalProperties, false));
+            }
+            return z.record(z.string(), z.unknown());
+        }
+        case "null":
+            return z.null();
+        case "null | string":
+        case "string | null":
+            return z.union([z.string(), z.null()]);
+        case "null | number":
+        case "number | null":
+            return z.union([z.number(), z.null()]);
+        default:
+            // 处理 enum
+            if (prop.enum) {
+                return handleEnum(prop);
+            }
+            return z.unknown();
+    }
+}
+/**
+ * 处理 enum 类型
+ *
+ * 关键改进：自动在描述中添加有效值列表，帮助 LLM 正确理解参数值
+ * 例如：enum: ["24h", "week", "month"] -> 描述变为 "Valid values: 24h, week, month"
+ */
+function handleEnum(prop, existingDescription) {
+    if (!prop.enum || prop.enum.length === 0) {
+        return z.unknown();
+    }
+    // 检查是否是字符串枚举
+    const stringValues = prop.enum.filter((v) => typeof v === "string");
+    if (stringValues.length === 0) {
+        return z.any();
+    }
+    let schema;
+    if (stringValues.length === 1) {
+        schema = z.literal(stringValues[0]);
+    }
+    else {
+        schema = z.enum([stringValues[0], ...stringValues.slice(1)]);
+    }
+    // 构建有效值描述
+    const valuesList = stringValues.map((v) => `"${v}"`).join(", ");
+    const valuesDescription = `Valid values: ${valuesList}`;
+    // 组合描述：如果有原始描述，追加有效值；如果没有，直接使用有效值
+    if (existingDescription) {
+        return schema.describe(`${existingDescription}. ${valuesDescription}`);
+    }
+    return schema.describe(valuesDescription);
+}
+/**
+ * 转换 MCP 调用结果为 ToolResult
+ */
+function convertMcpCallResult(result) {
+    const content = result.content;
+    const textContent = content
+        ?.filter((c) => c.type === "text")
+        ?.map((c) => c.text)
+        ?.join("") ?? "";
+    return {
+        success: !result.isError,
+        output: textContent,
+        error: result.isError ? textContent : undefined,
+    };
+}
+/**
+ * 创建 MCP 工具描述
+ */
+export function createMcpToolsDescription(tools) {
+    if (tools.length === 0) {
+        return "  No MCP tools currently available.";
+    }
+    return tools
+        .map((t) => `  - ${t.name}: ${t.description}`)
+        .join("\n");
+}
+/**
+ * 获取工具的完整参数描述（供 LLM 使用）
+ *
+ * 从 Zod schema 中提取参数描述
+ */
+export function getToolParamDescriptions(tool) {
+    const descriptions = {};
+    // 从 metadata 中获取原始 schema
+    const mcpMeta = tool.metadata?.mcpTool;
+    if (mcpMeta?.inputSchema?.properties) {
+        for (const [key, prop] of Object.entries(mcpMeta.inputSchema.properties)) {
+            const propSchema = prop;
+            if (propSchema.description) {
+                descriptions[key] = propSchema.description;
+            }
+        }
+    }
+    return descriptions;
+}
+//# sourceMappingURL=adapter.js.map

package/dist/core/src/env/mcp/tool/adapter.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=adapter.test.d.ts.map