@jadchene/mcp-gateway-service 0.4.4 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -150,23 +150,27 @@ The gateway exposes six public tools:
150
150
 
151
151
  | Tool | Purpose |
152
152
  | --- | --- |
153
- | `gateway_list_services` | List all downstream MCP services managed by the gateway, including each `serviceId`, description, and availability. |
154
- | `gateway_get_service` | Return one service summary, runtime state, recent errors, and cached metadata. Use this for diagnostics. |
155
- | `gateway_list_tools` | List tools exposed by one downstream service. Optional `toolName` filters by one or more name fragments; `includeSchema: true` includes each matching tool's input and output schemas. |
156
- | `gateway_get_tool_schema` | Return input and output schemas for one or more exact tool names, keyed by tool name. |
157
- | `gateway_manage_service` | Reconnect a service or persistently enable/disable it in the config file. |
158
- | `gateway_call_tool` | Call one downstream tool through the gateway and return the downstream MCP result. |
153
+ | `gateway_list_services` | List downstream services with each logical `serviceId`, description, and current availability. |
154
+ | `gateway_get_service` | Return one service's identity, availability, recent error and connection time, protocol version, and server information. Use this for diagnostics. |
155
+ | `gateway_list_tools` | Search tool names or descriptions by case-insensitive literal substrings. Optional unique non-empty `toolName` and `desc` arrays use OR; `includeSchema: true` includes schemas. |
156
+ | `gateway_get_tool_schema` | Return schemas for unique exact, case-sensitive tool names. Results are keyed by name, and any unknown name fails the whole request. |
157
+ | `gateway_manage_service` | Reconnect without changing config, or persistently enable/disable a service in the config and reload the registry. |
158
+ | `gateway_call_tool` | Call one exact downstream tool and forward its result unchanged. The downstream tool may have read or write side effects. |
159
159
 
160
160
  Default token-efficient workflow:
161
161
 
162
162
  1. Call `gateway_list_services` once.
163
- 2. Call `gateway_list_tools(serviceId)` only when a service is needed. Use `toolName` to filter large tool lists by name.
164
- 3. When all filtered matches need schemas, pass `includeSchema: true`; when exact tool names are already known, call `gateway_get_tool_schema` with one name or a name array.
163
+ 2. Call `gateway_list_tools(serviceId)` only when a service is needed. Use a `toolName` array for name keywords and a `desc` array for description keywords.
164
+ 3. When all filtered matches need schemas, pass `includeSchema: true`; when exact tool names are already known, call `gateway_get_tool_schema` with a non-empty name array.
165
165
  4. Call `gateway_call_tool` to execute the downstream tool.
166
166
  5. Use `gateway_get_service` only for diagnostics.
167
167
  6. Use `gateway_manage_service` only to reconnect, enable, or disable a service.
168
168
 
169
- `gateway_get_tool_schema` accepts `toolName` as a string or non-empty string array and returns a `schemas` object keyed by each requested tool name.
169
+ `gateway_get_tool_schema.toolName` is a required unique non-empty string array and returns a `schemas` object keyed by each requested exact tool name. Use a one-element array when requesting one schema.
170
+
171
+ `gateway_list_tools.toolName` and `gateway_list_tools.desc` are optional unique non-empty string arrays. Matching is case-insensitive and uses literal substrings. When both are present, a tool is returned when either its name or description matches any supplied keyword. Description matching can also hit negative guidance such as "when not to use", so inspect the returned descriptions before selecting a tool.
172
+
173
+ All gateway tools with stable structured content expose an `outputSchema`. `gateway_call_tool` intentionally omits a fixed output schema because it forwards arbitrary downstream results. Its `arguments` object is always required; pass `{}` for a downstream tool with no arguments.
170
174
 
171
175
  `gateway_manage_service` actions:
172
176
 
package/README_zh.md CHANGED
@@ -150,23 +150,27 @@ HTTP endpoint 使用同一路径处理 `GET` 和 `POST`:
150
150
 
151
151
  | 工具 | 用途 |
152
152
  | --- | --- |
153
- | `gateway_list_services` | 列出网关管理的所有下游 MCP 服务,包括 `serviceId`、描述和可用状态。 |
154
- | `gateway_get_service` | 返回单个服务的摘要、运行状态、最近错误和缓存元数据。主要用于诊断。 |
155
- | `gateway_list_tools` | 列出某个下游服务暴露的工具。可用 `toolName` 按一个或多个名称片段过滤;传入 `includeSchema: true` 时返回每个匹配工具的输入和输出 schema。 |
156
- | `gateway_get_tool_schema` | 按一个或多个准确工具名返回输入和输出 schema,并以工具名作为结果 key。 |
157
- | `gateway_manage_service` | 重连服务,或把启用/禁用状态持久化写入配置文件。 |
158
- | `gateway_call_tool` | 通过网关调用一个下游工具,并返回下游 MCP 结果。 |
153
+ | `gateway_list_services` | 列出下游服务及其逻辑 `serviceId`、描述和当前可用状态。 |
154
+ | `gateway_get_service` | 返回服务标识、可用状态、最近错误和连接时间、协议版本及服务端信息,主要用于诊断。 |
155
+ | `gateway_list_tools` | 按不区分大小写的字面子串搜索工具名称或描述。可选的唯一非空 `toolName` 和 `desc` 数组使用 OR;`includeSchema: true` 会附带 schema。 |
156
+ | `gateway_get_tool_schema` | 按唯一、准确、区分大小写的工具名返回 schema,并以名称为 key;任一名称未知时整批失败。 |
157
+ | `gateway_manage_service` | 不修改配置地重连服务,或持久化启用/禁用配置并重载注册表。 |
158
+ | `gateway_call_tool` | 调用一个准确的下游工具并原样转发结果;下游工具可能包含读写副作用。 |
159
159
 
160
160
  默认的节省 token 流程:
161
161
 
162
162
  1. 调用一次 `gateway_list_services`。
163
- 2. 真正需要某个服务时,再调用 `gateway_list_tools(serviceId)`。工具很多时可用 `toolName` 按名称过滤。
164
- 3. 所有筛选结果都需要 schema 时,传入 `includeSchema: true`;已知准确工具名时,调用 `gateway_get_tool_schema` 并传入单个名称或名称数组。
163
+ 2. 真正需要某个服务时,再调用 `gateway_list_tools(serviceId)`。用 `toolName` 数组按名称关键词筛选,或用 `desc` 数组按描述关键词筛选。
164
+ 3. 所有筛选结果都需要 schema 时,传入 `includeSchema: true`;已知准确工具名时,调用 `gateway_get_tool_schema` 并传入非空名称数组。
165
165
  4. 调用 `gateway_call_tool` 执行下游工具。
166
166
  5. 只有诊断时才使用 `gateway_get_service`。
167
167
  6. 只有需要重连、启用或禁用服务时才使用 `gateway_manage_service`。
168
168
 
169
- `gateway_get_tool_schema` 的 `toolName` 接受字符串或非空字符串数组,返回的 `schemas` 对象以每个请求的工具名为 key。
169
+ `gateway_get_tool_schema.toolName` 必须是唯一非空字符串数组,返回的 `schemas` 对象以每个准确工具名为 key。只查询一个 schema 时使用单元素数组。
170
+
171
+ `gateway_list_tools.toolName` 和 `gateway_list_tools.desc` 都是可选的唯一非空字符串数组,按字面子串进行不区分大小写的匹配。同时传入时,只要工具名称或描述匹配任一关键词就会返回。描述匹配也可能命中 “when not to use” 等负向说明,因此选择工具前应检查完整描述。
172
+
173
+ 所有具有稳定结构化结果的网关工具都声明了 `outputSchema`。`gateway_call_tool` 会转发任意下游结果,因此不声明固定输出 schema;其 `arguments` 对象始终必填,下游工具无参数时传 `{}`。
170
174
 
171
175
  `gateway_manage_service` 动作:
172
176
 
@@ -122,10 +122,11 @@ export class McpGatewayEngine {
122
122
  */
123
123
  listTools(args) {
124
124
  const serviceId = requireString(args.serviceId, "The 'serviceId' argument must be a string.");
125
- const toolName = optionalStringArray(args.toolName, "The 'toolName' argument must be a string or string array when provided.");
125
+ const toolName = optionalUniqueNonEmptyStringArray(args.toolName, "The 'toolName' argument must be a unique non-empty string array when provided.");
126
+ const desc = optionalUniqueNonEmptyStringArray(args.desc, "The 'desc' argument must be a unique non-empty string array when provided.");
126
127
  const includeSchema = optionalBoolean(args.includeSchema, "The 'includeSchema' argument must be a boolean when provided.") ?? false;
127
128
  return successContent({
128
- tools: this.registry.listTools(serviceId, toolName).map((tool) => {
129
+ tools: this.registry.listTools(serviceId, toolName, desc).map((tool) => {
129
130
  const summary = {
130
131
  name: tool.name,
131
132
  description: tool.description ?? null
@@ -143,7 +144,7 @@ export class McpGatewayEngine {
143
144
  */
144
145
  getToolSchema(args) {
145
146
  const serviceId = requireString(args.serviceId, "The 'serviceId' argument must be a string.");
146
- const toolNames = requireStringArray(args.toolName, "The 'toolName' argument must be a non-empty string or non-empty string array.");
147
+ const toolNames = requireUniqueNonEmptyStringArray(args.toolName, "The 'toolName' argument must be a unique non-empty string array.");
147
148
  const schemas = Object.fromEntries(toolNames.map((toolName) => {
148
149
  const tool = this.registry.getTool(serviceId, toolName);
149
150
  if (!tool) {
@@ -162,7 +163,7 @@ export class McpGatewayEngine {
162
163
  async callDownstreamTool(args) {
163
164
  const serviceId = requireString(args.serviceId, "The 'serviceId' argument must be a string.");
164
165
  const toolName = requireString(args.toolName, "The 'toolName' argument must be a string.");
165
- const toolArgs = toObject(args.arguments ?? {}, "The 'arguments' field must be an object.");
166
+ const toolArgs = toObject(args.arguments, "The 'arguments' field must be an object.");
166
167
  const call = await this.registry.callTool(serviceId, toolName, toolArgs);
167
168
  return call.result;
168
169
  }
@@ -202,92 +203,71 @@ export class McpGatewayEngine {
202
203
  * Builds the fixed gateway tool definitions exposed to all MCP clients.
203
204
  */
204
205
  export function buildGatewayTools() {
206
+ const outputSchemas = buildGatewayOutputSchemas();
205
207
  return [
206
208
  {
207
209
  name: "gateway_list_services",
208
- description: "Lists all MCP services currently managed by the gateway.",
210
+ description: "Lists downstream MCP services with their logical identifiers, descriptions, and current availability.",
209
211
  inputSchema: {
210
212
  type: "object",
211
213
  properties: {},
212
214
  additionalProperties: false
213
- }
215
+ },
216
+ outputSchema: outputSchemas.listServices
214
217
  },
215
218
  {
216
219
  name: "gateway_get_service",
217
- description: "Returns one service summary, runtime state, and metadata cache details.",
220
+ description: "Returns one downstream service's configured identity, availability, recent error and connection time, protocol version, and server information.",
218
221
  inputSchema: objectSchema(["serviceId"], {
219
- serviceId: stringSchema("Logical service identifier.")
220
- })
222
+ serviceId: stringSchema("Logical downstream service identifier returned by gateway_list_services.")
223
+ }),
224
+ outputSchema: outputSchemas.getService
221
225
  },
222
226
  {
223
227
  name: "gateway_list_tools",
224
- description: "Lists tools exposed by one downstream service, optionally filtered by name keywords and including their schemas.",
228
+ description: "Lists downstream tools by case-insensitive name or description substring filters and optionally includes each matching schema.",
225
229
  inputSchema: objectSchema(["serviceId"], {
226
- serviceId: stringSchema("Logical service identifier."),
227
- toolName: {
228
- anyOf: [
229
- stringSchema("Optional keyword matched against downstream tool names."),
230
- {
231
- type: "array",
232
- description: "Optional keywords matched against downstream tool names. A tool is returned when any keyword matches.",
233
- items: {
234
- type: "string"
235
- }
236
- }
237
- ]
238
- },
230
+ serviceId: stringSchema("Logical downstream service identifier returned by gateway_list_services."),
231
+ toolName: uniqueNonEmptyStringArraySchema("Optional unique name substrings. Matching is case-insensitive; any name or description keyword may match."),
232
+ desc: uniqueNonEmptyStringArraySchema("Optional unique literal description substrings. Matching is case-insensitive and may hit negative guidance, so inspect candidate descriptions. Name and description filters use OR."),
239
233
  includeSchema: {
240
234
  type: "boolean",
241
235
  description: "Includes inputSchema and outputSchema in every returned tool when true. Defaults to false."
242
236
  }
243
- })
237
+ }),
238
+ outputSchema: outputSchemas.listTools
244
239
  },
245
240
  {
246
241
  name: "gateway_get_tool_schema",
247
- description: "Returns input and output schemas for one or more downstream tools, keyed by tool name.",
242
+ description: "Returns schemas for exact, case-sensitive downstream tool names, keyed by name; the whole request fails when any name is unknown.",
248
243
  inputSchema: objectSchema(["serviceId", "toolName"], {
249
- serviceId: stringSchema("Logical service identifier."),
250
- toolName: {
251
- anyOf: [
252
- {
253
- type: "string",
254
- description: "Downstream tool name.",
255
- minLength: 1
256
- },
257
- {
258
- type: "array",
259
- description: "Downstream tool names whose schemas should be returned.",
260
- minItems: 1,
261
- items: {
262
- type: "string",
263
- minLength: 1
264
- }
265
- }
266
- ]
267
- }
268
- })
244
+ serviceId: stringSchema("Logical downstream service identifier returned by gateway_list_services."),
245
+ toolName: uniqueNonEmptyStringArraySchema("Unique exact, case-sensitive downstream tool names returned by gateway_list_tools.")
246
+ }),
247
+ outputSchema: outputSchemas.getToolSchema
269
248
  },
270
249
  {
271
250
  name: "gateway_manage_service",
272
- description: "Reconnects one service or updates its enabled state with a compact action.",
251
+ description: "Reconnects a downstream service without changing config, or persistently enables or disables it in the gateway config and reloads the registry.",
273
252
  inputSchema: objectSchema(["serviceId", "action"], {
274
- serviceId: stringSchema("Logical service identifier."),
253
+ serviceId: stringSchema("Logical downstream service identifier returned by gateway_list_services."),
275
254
  action: {
276
255
  type: "string",
277
- description: "Management action applied to the service.",
256
+ description: "reconnect refreshes the connection and metadata without changing config; enable and disable persist the enable flag and reload the registry.",
278
257
  enum: ["reconnect", "enable", "disable"]
279
258
  }
280
- })
259
+ }),
260
+ outputSchema: outputSchemas.manageService
281
261
  },
282
262
  {
283
263
  name: "gateway_call_tool",
284
- description: "Calls one downstream tool through the gateway service pool.",
264
+ description: "Calls one exact downstream tool and forwards its result unchanged. The downstream tool may have read or write side effects; inspect its schema and service rules first.",
285
265
  inputSchema: objectSchema(["serviceId", "toolName", "arguments"], {
286
- serviceId: stringSchema("Logical service identifier."),
287
- toolName: stringSchema("Downstream tool name."),
266
+ serviceId: stringSchema("Logical downstream service identifier returned by gateway_list_services."),
267
+ toolName: stringSchema("Exact, case-sensitive downstream tool name returned by gateway_list_tools."),
288
268
  arguments: {
289
269
  type: "object",
290
- description: "Arguments passed to the downstream tool."
270
+ description: "Required arguments object built from the downstream inputSchema. Pass an empty object when the tool has no arguments."
291
271
  }
292
272
  })
293
273
  }
@@ -328,13 +308,108 @@ function objectSchema(required, properties) {
328
308
  additionalProperties: false
329
309
  };
330
310
  }
311
+ /**
312
+ * Builds output schemas for gateway tools with stable structured content.
313
+ */
314
+ function buildGatewayOutputSchemas() {
315
+ const nullableString = nullableSchema({ type: "string" });
316
+ const nullableObject = nullableSchema({ type: "object" });
317
+ const nullableToolSchema = nullableSchema({ type: "object" });
318
+ return {
319
+ listServices: objectSchema(["services"], {
320
+ services: {
321
+ type: "array",
322
+ items: objectSchema(["serviceId", "description", "available"], {
323
+ serviceId: { type: "string" },
324
+ description: nullableString,
325
+ available: { type: "boolean" }
326
+ })
327
+ }
328
+ }),
329
+ getService: objectSchema([
330
+ "serviceId",
331
+ "name",
332
+ "description",
333
+ "available",
334
+ "lastError",
335
+ "lastConnectedAt",
336
+ "protocolVersion",
337
+ "serverInfo"
338
+ ], {
339
+ serviceId: { type: "string" },
340
+ name: { type: "string" },
341
+ description: nullableString,
342
+ available: { type: "boolean" },
343
+ lastError: nullableString,
344
+ lastConnectedAt: nullableString,
345
+ protocolVersion: nullableString,
346
+ serverInfo: nullableObject
347
+ }),
348
+ listTools: objectSchema(["tools"], {
349
+ tools: {
350
+ type: "array",
351
+ items: objectSchema(["name", "description"], {
352
+ name: { type: "string" },
353
+ description: nullableString,
354
+ inputSchema: nullableToolSchema,
355
+ outputSchema: nullableToolSchema
356
+ })
357
+ }
358
+ }),
359
+ getToolSchema: objectSchema(["schemas"], {
360
+ schemas: {
361
+ type: "object",
362
+ minProperties: 1,
363
+ additionalProperties: objectSchema(["inputSchema", "outputSchema"], {
364
+ inputSchema: nullableToolSchema,
365
+ outputSchema: nullableToolSchema
366
+ })
367
+ }
368
+ }),
369
+ manageService: objectSchema(["serviceId", "action", "enabled", "available"], {
370
+ serviceId: { type: "string" },
371
+ action: {
372
+ type: "string",
373
+ enum: ["reconnect", "enable", "disable"]
374
+ },
375
+ enabled: { type: "boolean" },
376
+ available: { type: "boolean" }
377
+ })
378
+ };
379
+ }
380
+ /**
381
+ * Builds a schema that accepts the supplied shape or null.
382
+ */
383
+ function nullableSchema(schema) {
384
+ return {
385
+ anyOf: [schema, { type: "null" }]
386
+ };
387
+ }
331
388
  /**
332
389
  * Builds a simple JSON schema string descriptor.
333
390
  */
334
391
  function stringSchema(description) {
335
392
  return {
336
393
  type: "string",
337
- description
394
+ description,
395
+ minLength: 1,
396
+ pattern: "\\S"
397
+ };
398
+ }
399
+ /**
400
+ * Builds a non-empty unique string array descriptor.
401
+ */
402
+ function uniqueNonEmptyStringArraySchema(description) {
403
+ return {
404
+ type: "array",
405
+ description,
406
+ minItems: 1,
407
+ uniqueItems: true,
408
+ items: {
409
+ type: "string",
410
+ minLength: 1,
411
+ pattern: "\\S"
412
+ }
338
413
  };
339
414
  }
340
415
  /**
@@ -356,36 +431,29 @@ function requireString(input, message) {
356
431
  return input;
357
432
  }
358
433
  /**
359
- * Returns optional string keywords, treating blank strings as absent.
434
+ * Returns an optional unique non-empty array of non-empty strings.
360
435
  */
361
- function optionalStringArray(input, message) {
436
+ function optionalUniqueNonEmptyStringArray(input, message) {
362
437
  if (input === undefined || input === null) {
363
438
  return undefined;
364
439
  }
365
- if (typeof input !== "string") {
366
- if (!Array.isArray(input) || input.some((value) => typeof value !== "string")) {
367
- throw new Error(message);
368
- }
369
- const values = input.map((value) => value.trim()).filter((value) => value !== "");
370
- return values.length === 0 ? undefined : values;
440
+ if (!Array.isArray(input)
441
+ || input.length === 0
442
+ || input.some((value) => typeof value !== "string" || value.trim() === "")
443
+ || new Set(input).size !== input.length) {
444
+ throw new Error(message);
371
445
  }
372
- const trimmed = input.trim();
373
- return trimmed === "" ? undefined : trimmed;
446
+ return input;
374
447
  }
375
448
  /**
376
- * Returns one or more required non-empty strings with duplicates removed.
449
+ * Returns a required unique non-empty string array.
377
450
  */
378
- function requireStringArray(input, message) {
379
- if (typeof input === "string") {
380
- if (input.trim() === "") {
381
- throw new Error(message);
382
- }
383
- return [input];
384
- }
385
- if (!Array.isArray(input) || input.length === 0 || input.some((value) => typeof value !== "string" || value.trim() === "")) {
451
+ function requireUniqueNonEmptyStringArray(input, message) {
452
+ const values = optionalUniqueNonEmptyStringArray(input, message);
453
+ if (!values) {
386
454
  throw new Error(message);
387
455
  }
388
- return [...new Set(input)];
456
+ return values;
389
457
  }
390
458
  /**
391
459
  * Returns an optional boolean without coercing other input types.
@@ -110,17 +110,20 @@ export class ServiceRegistry {
110
110
  return this.snapshots.get(serviceId) ?? null;
111
111
  }
112
112
  /**
113
- * Lists tools for one logical service, optionally filtering by one or more tool name keywords.
113
+ * Lists tools for one logical service, optionally matching name or description keywords.
114
114
  */
115
- listTools(serviceId, toolName) {
115
+ listTools(serviceId, toolName, desc) {
116
116
  const tools = this.requireService(serviceId).metadata.tools;
117
- const keywords = normalizeToolNameKeywords(toolName);
118
- if (keywords.length === 0) {
117
+ const nameKeywords = normalizeKeywords(toolName);
118
+ const descriptionKeywords = normalizeKeywords(desc);
119
+ if (nameKeywords.length === 0 && descriptionKeywords.length === 0) {
119
120
  return tools;
120
121
  }
121
122
  return tools.filter((tool) => {
122
123
  const normalizedName = tool.name.toLowerCase();
123
- return keywords.some((keyword) => normalizedName.includes(keyword));
124
+ const normalizedDescription = tool.description?.toLowerCase() ?? "";
125
+ return nameKeywords.some((keyword) => normalizedName.includes(keyword))
126
+ || descriptionKeywords.some((keyword) => normalizedDescription.includes(keyword));
124
127
  });
125
128
  }
126
129
  /**
@@ -158,7 +161,7 @@ export class ServiceRegistry {
158
161
  }
159
162
  }
160
163
  /**
161
- * Manages one service runtime or persisted enable flag through a compact action interface.
164
+ * Reconnects one service or persists its enabled state through the config file.
162
165
  */
163
166
  async manageService(serviceId, action) {
164
167
  switch (action) {
@@ -362,14 +365,13 @@ function createClient(service, logger) {
362
365
  }
363
366
  }
364
367
  /**
365
- * Normalizes optional tool name keywords for case-insensitive filtering.
368
+ * Normalizes optional keywords for case-insensitive filtering.
366
369
  */
367
- function normalizeToolNameKeywords(toolName) {
368
- if (!toolName) {
370
+ function normalizeKeywords(input) {
371
+ if (!input) {
369
372
  return [];
370
373
  }
371
- const values = Array.isArray(toolName) ? toolName : [toolName];
372
- return values
374
+ return input
373
375
  .map((value) => value.trim().toLowerCase())
374
376
  .filter((value) => value !== "");
375
377
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@jadchene/mcp-gateway-service",
3
- "version": "0.4.4",
3
+ "version": "0.5.0",
4
4
  "description": "A token-efficient MCP gateway that provides one unified entry point for multiple downstream MCP services.",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: mcp-gateway
3
- description: Use the MCP gateway for token-efficient discovery of downstream services and tools, filtered schema inclusion through gateway_list_tools(includeSchema), exact-name batch schema retrieval through gateway_get_tool_schema, and forwarded tool calls. Use when routing work through the gateway, reducing repeated schema calls, or diagnosing a managed service.
3
+ description: Use the MCP gateway for token-efficient discovery of downstream services and tools, name or description keyword search through gateway_list_tools, filtered schema inclusion, exact-name batch schema retrieval, and forwarded tool calls. Use when routing work through the gateway, broadening tool discovery, reducing repeated schema calls, or diagnosing a managed service.
4
4
  ---
5
5
 
6
6
  # MCP Gateway
@@ -18,10 +18,10 @@ Operate downstream MCP services through the gateway's fixed, token-efficient dis
18
18
  ## Required Workflow
19
19
 
20
20
  1. Call `gateway_list_services` once to find the right downstream service.
21
- 2. Call `gateway_list_tools(serviceId)` only for the selected service and use optional `toolName` keywords to narrow the result.
21
+ 2. Call `gateway_list_tools(serviceId)` only for the selected service. Use optional unique non-empty `toolName` and `desc` string arrays for case-insensitive literal substring matching. Description matches may come from negative guidance, so inspect the returned descriptions before selecting.
22
22
  3. Pass `includeSchema: true` when every filtered match needs its schema, such as when comparing argument contracts or preparing to call multiple matches.
23
- 4. If selected schemas were not returned by the list call, call `gateway_get_tool_schema(serviceId, toolName)` with one exact name or an array of exact names before first use or whenever arguments remain uncertain.
24
- 5. Call `gateway_call_tool(serviceId, toolName, arguments)` for execution.
23
+ 4. If selected schemas were not returned by the list call, call `gateway_get_tool_schema(serviceId, toolName)` with a unique non-empty array of exact, case-sensitive names before first use or whenever arguments remain uncertain. The whole request fails if any name is unknown; use a one-element array for one tool.
24
+ 5. Call `gateway_call_tool(serviceId, toolName, arguments)` for execution. Always pass an explicit arguments object, using `{}` for no-argument tools, and treat downstream side effects according to the matched service rules.
25
25
  6. Re-discover only when a call fails, service availability changes, or the task clearly requires fresh metadata.
26
26
 
27
27
  ## Diagnostic Exception
@@ -46,15 +46,18 @@ Operate downstream MCP services through the gateway's fixed, token-efficient dis
46
46
  ## Response Shape Expectations
47
47
 
48
48
  - `gateway_list_services` returns compact service entries with `serviceId`, `description`, and `available`.
49
- - `gateway_list_tools` returns compact tool entries with `name` and `description`, supports optional substring filtering by `toolName` as a string or string array, and includes `inputSchema` and `outputSchema` in every matching entry when `includeSchema` is true.
49
+ - `gateway_list_tools` returns compact tool entries with `name` and `description`. Optional `toolName` and `desc` must be unique non-empty string arrays; they match literal name and description substrings respectively, case-insensitively.
50
+ - When both `toolName` and `desc` are present, return the union: a tool matches when its name or description contains any supplied keyword.
51
+ - `gateway_list_tools` includes `inputSchema` and `outputSchema` in every matching entry when `includeSchema` is true.
50
52
  - `includeSchema` is optional and defaults to `false`. Keep it false for name-only discovery or broad unfiltered inventories.
51
- - `gateway_get_tool_schema` accepts `toolName` as a string or non-empty string array and returns `schemas`, keyed by requested tool name; each value contains `inputSchema` and `outputSchema`.
52
- - `gateway_call_tool` forwards the downstream MCP result directly with minimal or no gateway wrapping.
53
+ - `gateway_get_tool_schema` requires unique exact, case-sensitive names in `toolName` and returns `schemas`, keyed by requested tool name; each value contains `inputSchema` and `outputSchema`.
54
+ - Stable gateway-owned structured results expose `outputSchema`; `gateway_call_tool` omits a fixed output schema and forwards the downstream result unchanged.
53
55
 
54
56
  ## Token-Efficient Strategy
55
57
 
56
58
  - Start with the smallest discovery call that can answer the current question.
57
59
  - Avoid listing tools for multiple services when the target domain is already obvious.
60
+ - Use `desc` when task language is more likely to appear in tool descriptions than tool names. Combine it with `toolName` to broaden discovery without requesting the full inventory.
58
61
  - Combine `toolName` filtering with `includeSchema: true` when multiple likely matches all need schema inspection; this replaces one list call plus repeated schema calls with one request.
59
62
  - Keep `includeSchema` false when only names and descriptions are needed, or when an unfiltered service exposes many tools.
60
63
  - When exact selected tool names are known and their schemas were omitted from discovery, fetch one or several in a single `gateway_get_tool_schema` call.
@@ -65,8 +68,9 @@ Operate downstream MCP services through the gateway's fixed, token-efficient dis
65
68
  - Need a service for one task domain:
66
69
  - `gateway_list_services`
67
70
  - choose the most relevant `serviceId`
68
- - `gateway_list_tools({ serviceId: "selected-service", toolName: "optional-keyword" })`
71
+ - `gateway_list_tools({ serviceId: "selected-service", toolName: ["optional-keyword"] })`
69
72
  - `gateway_list_tools({ serviceId: "selected-service", toolName: ["keyword-a", "keyword-b"] })`
73
+ - `gateway_list_tools({ serviceId: "selected-service", toolName: ["name-keyword"], desc: ["description phrase"] })`
70
74
  - add `includeSchema: true` to either list call when every match needs schema inspection
71
75
  - otherwise call `gateway_get_tool_schema` after selecting exact tool names
72
76
  - `gateway_call_tool({ serviceId: "selected-service", toolName: "selected-tool", arguments: {...} })`
@@ -76,7 +80,7 @@ Operate downstream MCP services through the gateway's fixed, token-efficient dis
76
80
  - compare or reuse the returned `inputSchema` and `outputSchema` without separate schema calls
77
81
 
78
82
  - Need schemas for exact selected tools whose schemas were not included in discovery:
79
- - `gateway_get_tool_schema({ serviceId: "selected-service", toolName: "selected-tool" })`
83
+ - `gateway_get_tool_schema({ serviceId: "selected-service", toolName: ["selected-tool"] })`
80
84
  - or `gateway_get_tool_schema({ serviceId: "selected-service", toolName: ["selected-tool-a", "selected-tool-b"] })`
81
85
  - read each result from `schemas[toolName]`
82
86
  - build arguments strictly from `inputSchema`
@@ -87,6 +91,7 @@ Operate downstream MCP services through the gateway's fixed, token-efficient dis
87
91
  - **Never** flatten all downstream tools into your own notes unless the task explicitly needs a full inventory.
88
92
  - **Never** invent arguments for a tool when the schema can be queried cheaply.
89
93
  - **Never** proceed without a schema from `gateway_list_tools(..., includeSchema: true)` or `gateway_get_tool_schema` when argument names or fields are unclear.
94
+ - **Never** omit `gateway_call_tool.arguments`; pass `{}` when the downstream input schema has no properties.
90
95
  - **Never** assume a service is available without checking recent gateway discovery results when availability matters.
91
96
 
92
97
  ## Practical Guidance