Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

fix(pi): cindy_mcp_call_tool 把通用 call_tool 信封写进 schema 并对平铺形态自纠错 (#6084)

Yunjin Zhang261eda8d9fa9
diff --git a/packages/maker-core/src/agents/pi/__tests__/cindyBridgeSource.test.ts b/packages/maker-core/src/agents/pi/__tests__/cindyBridgeSource.test.ts
index 8d433b1655..095f475a61 100644
--- a/packages/maker-core/src/agents/pi/__tests__/cindyBridgeSource.test.ts
+++ b/packages/maker-core/src/agents/pi/__tests__/cindyBridgeSource.test.ts
@@ -2473,7 +2473,8 @@ it('lets cindy_mcp_call_tool omit args and forwards an empty object for no-param
const gateway = new context.Gateway();
gateway.add('cindy_memory', client, [
{ name: 'list_tools', inputSchema: { type: 'object' } },
- { name: 'call_tool', inputSchema: { type: 'object' } },
+ // 真实 cindy server 的 call_tool schema 形状指纹: name:string + args:object + required 含 name。
+ { name: 'call_tool', inputSchema: { type: 'object', properties: { name: { type: 'string' }, args: { type: 'object' } }, required: ['name'] } },
]);
const ordinary: any[] = [];
gateway.register({ registerTool: (tool: unknown) => ordinary.push(tool) });
@@ -2483,15 +2484,166 @@ it('lets cindy_mcp_call_tool omit args and forwards an empty object for no-param
expect(callTool.parameters.required).toEqual(['server', 'tool']);
expect(callTool.parameters.required).not.toContain('args');
// 披露门: 先按 schema 检视一次再调用 (与生产路径同序)。
- await gateway.listResult({ server: 'cindy_memory', tool: 'call_tool' });
- await gateway.executeCall({ server: 'cindy_memory', tool: 'call_tool' });
+ // 目标选 list_tools 而不是 call_tool: 后者的参数必填 name, 「完全省略 args」对它本来就
+ // 是非法调用, 用它当夹具会把「省略即转发 {}」与「信封缺 name」两件事混在一起。
+ await gateway.listResult({ server: 'cindy_memory', tool: 'list_tools' });
+ await gateway.executeCall({ server: 'cindy_memory', tool: 'list_tools' });
expect(requests).toHaveLength(1);
expect(requests[0].method).toBe('tools/call');
- expect(requests[0].params).toEqual({ name: 'call_tool', arguments: {} });
- // 对照: 显式传 args 时仍原样转发 (既有行为不变)。
+ expect(requests[0].params).toEqual({ name: 'list_tools', arguments: {} });
+ // 对照: 显式传 args 时仍原样转发 (既有行为不变), 含通用 call_tool 的 {name, args} 信封。
+ await gateway.listResult({ server: 'cindy_memory', tool: 'call_tool' });
await gateway.executeCall({ server: 'cindy_memory', tool: 'call_tool', args: { name: 'memory_list', args: {} } });
expect(requests[1].params).toEqual({
name: 'call_tool',
arguments: { name: 'memory_list', args: {} },
});
+ // 2026-10-15 回归: args 就是「所选工具自己的参数」, 直调形态合法, schema 不得收窄;
+ // 同时必须把通用 call_tool 的信封 {name, args} 作为提示属性挂在 args 上 —— 此前 args 是
+ // 无声明字段的自由袋子, 模型看不到信封就把内层字段平铺进来并丢掉 name。
+ const argsSchema = callTool.parameters.properties.args;
+ expect(argsSchema.additionalProperties).toBe(true);
+ expect(argsSchema.properties).toHaveProperty('name');
+ expect(argsSchema.properties).toHaveProperty('args');
+ expect(argsSchema.properties.name.type).toBeUndefined();
+ expect(argsSchema.properties.args.type).toBeUndefined();
+});
+
+it('tells the model the call_tool envelope instead of forwarding a flattened envelope', async () => {
+ const source = CINDY_BRIDGE_EXTENSION_SOURCE;
+ const compiled = ts.transpileModule(
+ source.slice(source.indexOf('const CINDY_MCP_LIST_TOOLS'), source.indexOf('async function connectServer'))
+ + '\n(globalThis as any).Gateway = CindyMcpGateway;',
+ { compilerOptions: { module: ts.ModuleKind.None, target: ts.ScriptTarget.ES2022 } },
+ ).outputText;
+ const context: Record<string, any> = {
+ recordInput: (value: unknown) => value && typeof value === 'object' ? value : {},
+ mcpContentToPi: (content: unknown) => content,
+ };
+ runInNewContext(compiled, context);
+ const requests: Array<{ method: string; params: any }> = [];
+ const client = { request: async (method: string, params: unknown) => {
+ requests.push({ method, params });
+ return { content: [{ type: 'text', text: 'ok' }] };
+ } };
+ const gateway = new context.Gateway();
+ gateway.add('cindy_memory', client, [
+ { name: 'list_tools', inputSchema: { type: 'object' } },
+ // 真实 cindy server 的 call_tool schema 形状指纹: name:string + args:object + required 含 name。
+ { name: 'call_tool', inputSchema: { type: 'object', properties: { name: { type: 'string' }, args: { type: 'object' } }, required: ['name'] } },
+ ]);
+ gateway.register({ registerTool: () => undefined });
+ await gateway.listResult({ server: 'cindy_memory', tool: 'call_tool' });
+ // 模型把内层参数平铺进 args、丢掉 name: 不触达 MCP, 一次说清正确形态。
+ await expect(gateway.executeCall({
+ server: 'cindy_memory',
+ tool: 'call_tool',
+ args: { filename: 'project_x.md' },
+ })).rejects.toThrow(/envelope \{"name": <tool>, "args"/);
+ expect(requests).toHaveLength(0);
+ // 直调形态不受影响: 所选工具不是 call_tool 时, args 仍原样转发 (含参数名恰好叫 args/name)。
+ gateway.add('cindy_workspace', client, [{ name: 'status', inputSchema: { type: 'object' } }]);
+ await gateway.listResult({ server: 'cindy_workspace', tool: 'status' });
+ await gateway.executeCall({ server: 'cindy_workspace', tool: 'status', args: { args: ['x'], name: 'y' } });
+ expect(requests[0].params).toEqual({ name: 'status', arguments: { args: ['x'], name: 'y' } });
+});
+
+it('does not apply the Cindy envelope rule to a third-party tool also named call_tool', async () => {
+ const source = CINDY_BRIDGE_EXTENSION_SOURCE;
+ const compiled = ts.transpileModule(
+ source.slice(source.indexOf('const CINDY_MCP_LIST_TOOLS'), source.indexOf('async function connectServer'))
+ + '\n(globalThis as any).Gateway = CindyMcpGateway;',
+ { compilerOptions: { module: ts.ModuleKind.None, target: ts.ScriptTarget.ES2022 } },
+ ).outputText;
+ const context: Record<string, any> = {
+ recordInput: (value: unknown) => value && typeof value === 'object' ? value : {},
+ mcpContentToPi: (content: unknown) => content,
+ };
+ runInNewContext(compiled, context);
+ const requests: Array<{ method: string; params: any }> = [];
+ const client = { request: async (method: string, params: unknown) => {
+ requests.push({ method, params });
+ return { content: [{ type: 'text', text: 'ok' }] };
+ } };
+ const gateway = new context.Gateway();
+ // 用户自接的第三方 MCP: 工具同样叫 call_tool, 但信封是 {tool_name, arguments}。
+ gateway.add('third_party', client, [{
+ name: 'call_tool',
+ inputSchema: {
+ type: 'object',
+ properties: {
+ tool_name: { type: 'string' },
+ arguments: { type: 'object', additionalProperties: true },
+ },
+ required: ['tool_name'],
+ },
+ }]);
+ gateway.register({ registerTool: () => undefined });
+ await gateway.listResult({ server: 'third_party', tool: 'call_tool' });
+ // 模型完全照检视到的 schema 调用: 必须放行到服务端, 不能被 Cindy 的信封规则连坐。
+ await gateway.executeCall({
+ server: 'third_party',
+ tool: 'call_tool',
+ args: { tool_name: 'inner', arguments: { a: 1 } },
+ });
+ expect(requests[0].params).toEqual({
+ name: 'call_tool',
+ arguments: { tool_name: 'inner', arguments: { a: 1 } },
+ });
+ // 同一 server 里, schema 形状指纹齐全 (name+args+required) 的工具仍走信封自纠错
+ // (判据是形状不是名字)。
+ gateway.add('mixed', client, [{
+ name: 'call_tool',
+ inputSchema: {
+ type: 'object',
+ properties: { name: { type: 'string' }, args: { type: 'object' } },
+ required: ['name'],
+ },
+ }]);
+ await gateway.listResult({ server: 'mixed', tool: 'call_tool' });
+ await expect(gateway.executeCall({ server: 'mixed', tool: 'call_tool', args: { filename: 'x.md' } }))
+ .rejects.toThrow(/envelope \{"name": <tool>, "args"/);
+ expect(requests).toHaveLength(1);
+});
+
+it('leaves a direct tool alone when its required name is not the Cindy envelope', async () => {
+ const source = CINDY_BRIDGE_EXTENSION_SOURCE;
+ const compiled = ts.transpileModule(
+ source.slice(source.indexOf('const CINDY_MCP_LIST_TOOLS'), source.indexOf('async function connectServer'))
+ + '\n(globalThis as any).Gateway = CindyMcpGateway;',
+ { compilerOptions: { module: ts.ModuleKind.None, target: ts.ScriptTarget.ES2022 } },
+ ).outputText;
+ const context: Record<string, any> = {
+ recordInput: (value: unknown) => value && typeof value === 'object' ? value : {},
+ mcpContentToPi: (content: unknown) => content,
+ };
+ runInNewContext(compiled, context);
+ const requests: Array<{ method: string; params: any }> = [];
+ const client = { request: async (method: string, params: unknown) => {
+ requests.push({ method, params });
+ // 服务端按真实 schema 报缺 content —— 这才是模型该看到的修正信息。
+ throw Object.assign(new Error('MCP error -32602: missing content'), { invalidParams: true });
+ } };
+ const gateway = new context.Gateway();
+ // 第三方直调工具: name 是文件名, content 是正文, 没有 args 信封。
+ gateway.add('files', client, [{
+ name: 'write_file',
+ inputSchema: {
+ type: 'object',
+ properties: { name: { type: 'string' }, content: { type: 'string' } },
+ required: ['name', 'content'],
+ },
+ }]);
+ gateway.register({ registerTool: () => undefined });
+ await gateway.listResult({ server: 'files', tool: 'write_file' });
+ // 缺 name 时必须原样走到服务端, 由服务端报它真实的参数要求 (缺 name 与缺 content);
+ // 桥不得把它引向「把 name 当工具名、其余塞进 args」的错误形状。
+ // 关键: 参数里**不能带 name** —— 带了它新旧判据都不会进信封分支, 撤掉修复这测试照样绿,
+ // 就盖不住「普通工具又收到信封提示」这个回归。
+ // 错误正文过 safeMcpFailure 脱敏 (不外泄上游 body), 所以断言错误来自服务端那条路径,
+ // 关键证据是下面两条: 请求确实发出了, 且 arguments 逐字未被桥改写。
+ await expect(gateway.executeCall({ server: 'files', tool: 'write_file', args: { content: 'text' } }))
+ .rejects.toThrow(/write_file failed/);
+ expect(requests).toHaveLength(1);
+ expect(requests[0].params).toEqual({ name: 'write_file', arguments: { content: 'text' } });
});
diff --git a/packages/maker-core/src/agents/pi/cindy-bridge-source.ts b/packages/maker-core/src/agents/pi/cindy-bridge-source.ts
index 5e3e92159c..d5703c032b 100644
--- a/packages/maker-core/src/agents/pi/cindy-bridge-source.ts
+++ b/packages/maker-core/src/agents/pi/cindy-bridge-source.ts
@@ -3036,6 +3036,28 @@ class CindyMcpGateway {
return this.disclosedSchemas.has(mcpGatewayKey(call.tool.serverName, call.tool.name));
}
+ /**
+ * 该工具是否采用 Cindy 通用 call_tool 的 {name, args} 信封。
+ *
+ * 判据必须用**形状指纹**而不是名字或单个字段:Pi 也接入用户自接的第三方 MCP,它们可能
+ * 同样叫 call_tool(但信封是 {tool_name, arguments}),也可能有个叫 name 的必填字符串
+ * 参数却是文件名(配 content 直传)。所以要求三个信号同时成立 —— properties.name 是
+ * string、properties.args 是 object、且 required 含 name —— 才认定是 Cindy 的信封。
+ * 少一个都不套用这条自纠错说明,让调用按检视到的 schema 原样走到服务端,由服务端报它
+ * 真实的参数要求:普通工具缺字段时不能被引向错误的嵌套形状。
+ */
+ private requiresNameEnvelope(tool: ConnectedMcpTool): boolean {
+ const schema = tool.inputSchema as {
+ required?: unknown;
+ properties?: Record<string, { type?: unknown } | undefined>;
+ } | null;
+ const properties = schema?.properties;
+ return Array.isArray(schema?.required)
+ && schema.required.includes('name')
+ && properties?.name?.type === 'string'
+ && properties?.args?.type === 'object';
+ }
+
list(serverName?: string): Array<{ server: string; name: string; description: string }> {
return [...this.tools.values()]
.filter((tool) => !this.botMemoryFacadeEnabled || tool.serverName !== 'cindy_memory')
@@ -3181,6 +3203,20 @@ class CindyMcpGateway {
}> {
const resolved = this.resolveCall(params);
if (!resolved) throw new Error(this.unknownCallMessage(params));
+ if (this.requiresNameEnvelope(resolved.tool) && typeof recordInput(resolved.args).name !== 'string') {
+ // 该工具的 schema 自己声明了必填的字符串 name(即 Cindy 通用 call_tool 的 {name, args}
+ // 信封), 而模型没给 —— 多半是把内层字段平铺进来了。工具名无法猜, 但正确形态可以一次
+ // 说清, 让模型自纠错, 也省掉一轮往返。判定只看 schema 而不是工具名: 用户自接的第三方
+ // MCP 里可能也有叫 call_tool 的工具, 信封形状不同, 不能按名字连坐。
+ const keys = Object.keys(recordInput(resolved.args));
+ throw new Error(
+ resolved.tool.serverName + '/' + resolved.tool.name +
+ ' expects the envelope {"name": <tool>, "args": {<its parameters>}}; ' +
+ (keys.length > 0
+ ? 'you passed ' + JSON.stringify(keys) + ' directly — put the selected tool name in args.name.'
+ : 'args.name is required.'),
+ );
+ }
if (!this.isSchemaDisclosed(resolved)) {
throw new Error(
'Inspect this tool before execution by calling cindy_mcp_list_tools with ' +
@@ -3512,16 +3548,27 @@ class CindyMcpGateway {
label: 'Call a Cindy MCP tool',
description:
'Invoke a tool after inspecting its exact input schema with cindy_mcp_list_tools. Pass the exact server and ' +
- 'tool names plus args as an object; omit args for tools that take no parameters. ' +
- 'If the server rejects the arguments, the error repeats that schema.',
+ 'tool names, then args exactly as that tool\'s inspected schema. When the selected tool is itself a generic ' +
+ 'call_tool, its arguments are the envelope {"name": <tool>, "args": {<its parameters>}}; omit the inner args ' +
+ 'for tools that take no parameters. If the server rejects the arguments, the error repeats that schema.',
parameters: {
type: 'object',
properties: {
server: { type: 'string', description: 'Exact server name from cindy_mcp_list_tools.' },
tool: { type: 'string', description: 'Exact tool name from cindy_mcp_list_tools.' },
+ // args 就是「所选工具自己的参数」, 形状随工具而变, 所以 additionalProperties 保持 true
+ // (直调形态合法)。但通用 call_tool 的信封 {name, args} 在此之前对模型完全不可见 ——
+ // 模型看不到 name/args, 就把内层字段直接塞进 args 并丢掉 name (2026-10-15 实测
+ // MiniMax-M3.1 / deepseek-v4.1-flash / step-5 三会话均复现), 服务端只报 expected
+ // string/name。故把信封形状作为**无类型约束**的提示属性挂出来: 声明结构给模型看,
+ // 不约束任何值, 避免误伤参数名恰好叫 args 或 name 的直调工具。
args: {
type: 'object',
description: 'Arguments for the selected tool as a JSON object; omit when the selected tool takes none.',
+ properties: {
+ name: { description: 'Generic call_tool envelope only: the target tool name.' },
+ args: { description: 'Generic call_tool envelope only: the target tool parameters.' },
+ },
additionalProperties: true,
},
},