@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 +13 -9
- package/README_zh.md +13 -9
- package/dist/gateway-engine.js +142 -74
- package/dist/service-registry.js +13 -11
- package/package.json +1 -1
- package/skills/mcp-gateway/SKILL.md +14 -9
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
|
|
154
|
-
| `gateway_get_service` | Return one service
|
|
155
|
-
| `gateway_list_tools` |
|
|
156
|
-
| `gateway_get_tool_schema` | Return
|
|
157
|
-
| `gateway_manage_service` | Reconnect
|
|
158
|
-
| `gateway_call_tool` | Call one downstream tool
|
|
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`
|
|
164
|
-
3. When all filtered matches need schemas, pass `includeSchema: true`; when exact tool names are already known, call `gateway_get_tool_schema` with
|
|
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
|
|
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` |
|
|
154
|
-
| `gateway_get_service` |
|
|
155
|
-
| `gateway_list_tools` |
|
|
156
|
-
| `gateway_get_tool_schema` |
|
|
157
|
-
| `gateway_manage_service` |
|
|
158
|
-
| `gateway_call_tool` |
|
|
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)
|
|
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
|
|
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
|
|
package/dist/gateway-engine.js
CHANGED
|
@@ -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 =
|
|
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 =
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
|
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: "
|
|
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
|
|
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("
|
|
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: "
|
|
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
|
|
434
|
+
* Returns an optional unique non-empty array of non-empty strings.
|
|
360
435
|
*/
|
|
361
|
-
function
|
|
436
|
+
function optionalUniqueNonEmptyStringArray(input, message) {
|
|
362
437
|
if (input === undefined || input === null) {
|
|
363
438
|
return undefined;
|
|
364
439
|
}
|
|
365
|
-
if (
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
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
|
-
|
|
373
|
-
return trimmed === "" ? undefined : trimmed;
|
|
446
|
+
return input;
|
|
374
447
|
}
|
|
375
448
|
/**
|
|
376
|
-
* Returns
|
|
449
|
+
* Returns a required unique non-empty string array.
|
|
377
450
|
*/
|
|
378
|
-
function
|
|
379
|
-
|
|
380
|
-
|
|
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
|
|
456
|
+
return values;
|
|
389
457
|
}
|
|
390
458
|
/**
|
|
391
459
|
* Returns an optional boolean without coercing other input types.
|
package/dist/service-registry.js
CHANGED
|
@@ -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
|
|
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
|
|
118
|
-
|
|
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
|
-
|
|
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
|
-
*
|
|
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
|
|
368
|
+
* Normalizes optional keywords for case-insensitive filtering.
|
|
366
369
|
*/
|
|
367
|
-
function
|
|
368
|
-
if (!
|
|
370
|
+
function normalizeKeywords(input) {
|
|
371
|
+
if (!input) {
|
|
369
372
|
return [];
|
|
370
373
|
}
|
|
371
|
-
|
|
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: mcp-gateway
|
|
3
|
-
description: Use the MCP gateway for token-efficient discovery of downstream services and tools,
|
|
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
|
|
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
|
|
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
|
|
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`
|
|
52
|
-
- `gateway_call_tool`
|
|
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
|