@jadchene/mcp-gateway-service 0.4.3 → 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 +246 -300
- package/README_zh.md +251 -307
- package/config.example.json +1 -1
- package/dist/gateway-engine.js +185 -58
- package/dist/service-registry.js +13 -11
- package/package.json +1 -1
- package/skills/mcp-gateway/SKILL.md +36 -18
package/dist/gateway-engine.js
CHANGED
|
@@ -122,28 +122,40 @@ 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.");
|
|
127
|
+
const includeSchema = optionalBoolean(args.includeSchema, "The 'includeSchema' argument must be a boolean when provided.") ?? false;
|
|
126
128
|
return successContent({
|
|
127
|
-
tools: this.registry.listTools(serviceId, toolName).map((tool) =>
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
129
|
+
tools: this.registry.listTools(serviceId, toolName, desc).map((tool) => {
|
|
130
|
+
const summary = {
|
|
131
|
+
name: tool.name,
|
|
132
|
+
description: tool.description ?? null
|
|
133
|
+
};
|
|
134
|
+
if (includeSchema) {
|
|
135
|
+
summary.inputSchema = tool.inputSchema ?? null;
|
|
136
|
+
summary.outputSchema = tool.outputSchema ?? null;
|
|
137
|
+
}
|
|
138
|
+
return summary;
|
|
139
|
+
})
|
|
131
140
|
});
|
|
132
141
|
}
|
|
133
142
|
/**
|
|
134
|
-
* Returns input and output schemas
|
|
143
|
+
* Returns input and output schemas keyed by downstream tool name.
|
|
135
144
|
*/
|
|
136
145
|
getToolSchema(args) {
|
|
137
146
|
const serviceId = requireString(args.serviceId, "The 'serviceId' argument must be a string.");
|
|
138
|
-
const
|
|
139
|
-
const
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
+
const toolNames = requireUniqueNonEmptyStringArray(args.toolName, "The 'toolName' argument must be a unique non-empty string array.");
|
|
148
|
+
const schemas = Object.fromEntries(toolNames.map((toolName) => {
|
|
149
|
+
const tool = this.registry.getTool(serviceId, toolName);
|
|
150
|
+
if (!tool) {
|
|
151
|
+
throw new Error(`Unknown tool '${toolName}' in service '${serviceId}'.`);
|
|
152
|
+
}
|
|
153
|
+
return [toolName, {
|
|
154
|
+
inputSchema: tool.inputSchema ?? null,
|
|
155
|
+
outputSchema: tool.outputSchema ?? null
|
|
156
|
+
}];
|
|
157
|
+
}));
|
|
158
|
+
return successContent({ schemas });
|
|
147
159
|
}
|
|
148
160
|
/**
|
|
149
161
|
* Routes one downstream tool call through the service registry.
|
|
@@ -151,7 +163,7 @@ export class McpGatewayEngine {
|
|
|
151
163
|
async callDownstreamTool(args) {
|
|
152
164
|
const serviceId = requireString(args.serviceId, "The 'serviceId' argument must be a string.");
|
|
153
165
|
const toolName = requireString(args.toolName, "The 'toolName' argument must be a string.");
|
|
154
|
-
const toolArgs = toObject(args.arguments
|
|
166
|
+
const toolArgs = toObject(args.arguments, "The 'arguments' field must be an object.");
|
|
155
167
|
const call = await this.registry.callTool(serviceId, toolName, toolArgs);
|
|
156
168
|
return call.result;
|
|
157
169
|
}
|
|
@@ -191,71 +203,71 @@ export class McpGatewayEngine {
|
|
|
191
203
|
* Builds the fixed gateway tool definitions exposed to all MCP clients.
|
|
192
204
|
*/
|
|
193
205
|
export function buildGatewayTools() {
|
|
206
|
+
const outputSchemas = buildGatewayOutputSchemas();
|
|
194
207
|
return [
|
|
195
208
|
{
|
|
196
209
|
name: "gateway_list_services",
|
|
197
|
-
description: "Lists
|
|
210
|
+
description: "Lists downstream MCP services with their logical identifiers, descriptions, and current availability.",
|
|
198
211
|
inputSchema: {
|
|
199
212
|
type: "object",
|
|
200
213
|
properties: {},
|
|
201
214
|
additionalProperties: false
|
|
202
|
-
}
|
|
215
|
+
},
|
|
216
|
+
outputSchema: outputSchemas.listServices
|
|
203
217
|
},
|
|
204
218
|
{
|
|
205
219
|
name: "gateway_get_service",
|
|
206
|
-
description: "Returns one service
|
|
220
|
+
description: "Returns one downstream service's configured identity, availability, recent error and connection time, protocol version, and server information.",
|
|
207
221
|
inputSchema: objectSchema(["serviceId"], {
|
|
208
|
-
serviceId: stringSchema("Logical service identifier.")
|
|
209
|
-
})
|
|
222
|
+
serviceId: stringSchema("Logical downstream service identifier returned by gateway_list_services.")
|
|
223
|
+
}),
|
|
224
|
+
outputSchema: outputSchemas.getService
|
|
210
225
|
},
|
|
211
226
|
{
|
|
212
227
|
name: "gateway_list_tools",
|
|
213
|
-
description: "Lists tools
|
|
228
|
+
description: "Lists downstream tools by case-insensitive name or description substring filters and optionally includes each matching schema.",
|
|
214
229
|
inputSchema: objectSchema(["serviceId"], {
|
|
215
|
-
serviceId: stringSchema("Logical service identifier."),
|
|
216
|
-
toolName:
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
description: "Optional keywords matched against downstream tool names. A tool is returned when any keyword matches.",
|
|
222
|
-
items: {
|
|
223
|
-
type: "string"
|
|
224
|
-
}
|
|
225
|
-
}
|
|
226
|
-
]
|
|
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."),
|
|
233
|
+
includeSchema: {
|
|
234
|
+
type: "boolean",
|
|
235
|
+
description: "Includes inputSchema and outputSchema in every returned tool when true. Defaults to false."
|
|
227
236
|
}
|
|
228
|
-
})
|
|
237
|
+
}),
|
|
238
|
+
outputSchema: outputSchemas.listTools
|
|
229
239
|
},
|
|
230
240
|
{
|
|
231
241
|
name: "gateway_get_tool_schema",
|
|
232
|
-
description: "Returns the
|
|
242
|
+
description: "Returns schemas for exact, case-sensitive downstream tool names, keyed by name; the whole request fails when any name is unknown.",
|
|
233
243
|
inputSchema: objectSchema(["serviceId", "toolName"], {
|
|
234
|
-
serviceId: stringSchema("Logical service identifier."),
|
|
235
|
-
toolName:
|
|
236
|
-
})
|
|
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
|
|
237
248
|
},
|
|
238
249
|
{
|
|
239
250
|
name: "gateway_manage_service",
|
|
240
|
-
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.",
|
|
241
252
|
inputSchema: objectSchema(["serviceId", "action"], {
|
|
242
|
-
serviceId: stringSchema("Logical service identifier."),
|
|
253
|
+
serviceId: stringSchema("Logical downstream service identifier returned by gateway_list_services."),
|
|
243
254
|
action: {
|
|
244
255
|
type: "string",
|
|
245
|
-
description: "
|
|
256
|
+
description: "reconnect refreshes the connection and metadata without changing config; enable and disable persist the enable flag and reload the registry.",
|
|
246
257
|
enum: ["reconnect", "enable", "disable"]
|
|
247
258
|
}
|
|
248
|
-
})
|
|
259
|
+
}),
|
|
260
|
+
outputSchema: outputSchemas.manageService
|
|
249
261
|
},
|
|
250
262
|
{
|
|
251
263
|
name: "gateway_call_tool",
|
|
252
|
-
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.",
|
|
253
265
|
inputSchema: objectSchema(["serviceId", "toolName", "arguments"], {
|
|
254
|
-
serviceId: stringSchema("Logical service identifier."),
|
|
255
|
-
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."),
|
|
256
268
|
arguments: {
|
|
257
269
|
type: "object",
|
|
258
|
-
description: "
|
|
270
|
+
description: "Required arguments object built from the downstream inputSchema. Pass an empty object when the tool has no arguments."
|
|
259
271
|
}
|
|
260
272
|
})
|
|
261
273
|
}
|
|
@@ -296,13 +308,108 @@ function objectSchema(required, properties) {
|
|
|
296
308
|
additionalProperties: false
|
|
297
309
|
};
|
|
298
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
|
+
}
|
|
299
388
|
/**
|
|
300
389
|
* Builds a simple JSON schema string descriptor.
|
|
301
390
|
*/
|
|
302
391
|
function stringSchema(description) {
|
|
303
392
|
return {
|
|
304
393
|
type: "string",
|
|
305
|
-
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
|
+
}
|
|
306
413
|
};
|
|
307
414
|
}
|
|
308
415
|
/**
|
|
@@ -324,21 +431,41 @@ function requireString(input, message) {
|
|
|
324
431
|
return input;
|
|
325
432
|
}
|
|
326
433
|
/**
|
|
327
|
-
* Returns optional
|
|
434
|
+
* Returns an optional unique non-empty array of non-empty strings.
|
|
328
435
|
*/
|
|
329
|
-
function
|
|
436
|
+
function optionalUniqueNonEmptyStringArray(input, message) {
|
|
330
437
|
if (input === undefined || input === null) {
|
|
331
438
|
return undefined;
|
|
332
439
|
}
|
|
333
|
-
if (
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
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);
|
|
339
445
|
}
|
|
340
|
-
|
|
341
|
-
|
|
446
|
+
return input;
|
|
447
|
+
}
|
|
448
|
+
/**
|
|
449
|
+
* Returns a required unique non-empty string array.
|
|
450
|
+
*/
|
|
451
|
+
function requireUniqueNonEmptyStringArray(input, message) {
|
|
452
|
+
const values = optionalUniqueNonEmptyStringArray(input, message);
|
|
453
|
+
if (!values) {
|
|
454
|
+
throw new Error(message);
|
|
455
|
+
}
|
|
456
|
+
return values;
|
|
457
|
+
}
|
|
458
|
+
/**
|
|
459
|
+
* Returns an optional boolean without coercing other input types.
|
|
460
|
+
*/
|
|
461
|
+
function optionalBoolean(input, message) {
|
|
462
|
+
if (input === undefined || input === null) {
|
|
463
|
+
return undefined;
|
|
464
|
+
}
|
|
465
|
+
if (typeof input !== "boolean") {
|
|
466
|
+
throw new Error(message);
|
|
467
|
+
}
|
|
468
|
+
return input;
|
|
342
469
|
}
|
|
343
470
|
/**
|
|
344
471
|
* Ensures the service management action is supported.
|
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
|
|
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
|
|
@@ -10,7 +10,7 @@ Operate downstream MCP services through the gateway's fixed, token-efficient dis
|
|
|
10
10
|
## Core Mandates
|
|
11
11
|
|
|
12
12
|
- **Discovery First**: Never guess a `serviceId` or downstream `toolName`. Discover them through the gateway.
|
|
13
|
-
- **Token Efficiency**:
|
|
13
|
+
- **Token Efficiency**: Keep tool discovery narrow. Use `includeSchema: true` only when schemas are needed for all filtered matches, and reuse schemas returned by the list call.
|
|
14
14
|
- **Schema Before Unclear Arguments**: If the tool arguments are not fully certain, fetch the schema before calling the tool. Do not guess argument names, shapes, or confirmation fields.
|
|
15
15
|
- **Cache Mentally Per Session**: Reuse known service lists, tool lists, and schemas within the current session instead of asking again without reason.
|
|
16
16
|
- **Compression Recovery Gate**: After any context compression event, re-read `AGENTS.md` and this `SKILL.md` before continuing.
|
|
@@ -18,16 +18,17 @@ 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
|
|
22
|
-
3.
|
|
23
|
-
4.
|
|
24
|
-
5.
|
|
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
|
+
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 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
|
+
6. Re-discover only when a call fails, service availability changes, or the task clearly requires fresh metadata.
|
|
25
26
|
|
|
26
27
|
## Diagnostic Exception
|
|
27
28
|
|
|
28
29
|
- Treat `gateway_get_service` as a diagnostic tool, not part of the default workflow.
|
|
29
30
|
- Use it only when the user explicitly asks to inspect service health, connection state, protocol details, or recent service errors.
|
|
30
|
-
- Do not call it during normal
|
|
31
|
+
- Do not call it during normal routing when service discovery, filtered tool discovery, and execution are sufficient.
|
|
31
32
|
- Treat `gateway_manage_service` as an explicit service-control tool, not part of the default workflow.
|
|
32
33
|
- Use `gateway_manage_service({ serviceId, action: "reconnect" })` only when the user explicitly wants to retry starting a failed service after its dependency becomes ready.
|
|
33
34
|
- Use `gateway_manage_service({ serviceId, action: "enable" | "disable" })` only when the user explicitly wants to persistently change that service's enabled state in the config file.
|
|
@@ -35,7 +36,9 @@ Operate downstream MCP services through the gateway's fixed, token-efficient dis
|
|
|
35
36
|
## Strict Argument Rule
|
|
36
37
|
|
|
37
38
|
- Treat every `serviceId` argument accepted by `gateway_*` tools as a downstream service identifier returned by `gateway_list_services`. Never pass `gateway`, a gateway-owned tool name, or any inferred self-reference as `serviceId`.
|
|
38
|
-
- If a tool has any non-trivial arguments, optional flags, confirmation fields, enum values, or write-safety fields,
|
|
39
|
+
- If a tool has any non-trivial arguments, optional flags, confirmation fields, enum values, or write-safety fields, obtain its schema through `gateway_list_tools(..., includeSchema: true)` or `gateway_get_tool_schema` before execution unless the exact argument contract is already confirmed in the current session.
|
|
40
|
+
- Treat a schema returned by `gateway_list_tools(includeSchema: true)` as authoritative for that tool. Do not immediately repeat the same lookup with `gateway_get_tool_schema`.
|
|
41
|
+
- When exact names for several selected tools are already known, pass them in one `gateway_get_tool_schema` array instead of making one call per tool.
|
|
39
42
|
- Apply gateway discovery, schema, management, and routing tools only to downstream services and downstream tools. Do not use them to inspect or call gateway-owned tools such as `gateway_list_tools` or `gateway_call_tool`; gateway-owned tool schemas come from the MCP client's current gateway tool definitions.
|
|
40
43
|
- Do not rely on tool descriptions alone when the argument shape could affect correctness or safety.
|
|
41
44
|
- This is especially important for write tools, confirmation-based tools, and tools with nested argument objects.
|
|
@@ -43,29 +46,43 @@ Operate downstream MCP services through the gateway's fixed, token-efficient dis
|
|
|
43
46
|
## Response Shape Expectations
|
|
44
47
|
|
|
45
48
|
- `gateway_list_services` returns compact service entries with `serviceId`, `description`, and `available`.
|
|
46
|
-
- `gateway_list_tools` returns compact tool entries with `name` and `description
|
|
47
|
-
- `
|
|
48
|
-
- `
|
|
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.
|
|
52
|
+
- `includeSchema` is optional and defaults to `false`. Keep it false for name-only discovery or broad unfiltered inventories.
|
|
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.
|
|
49
55
|
|
|
50
56
|
## Token-Efficient Strategy
|
|
51
57
|
|
|
52
58
|
- Start with the smallest discovery call that can answer the current question.
|
|
53
59
|
- Avoid listing tools for multiple services when the target domain is already obvious.
|
|
54
|
-
-
|
|
55
|
-
-
|
|
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.
|
|
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.
|
|
62
|
+
- Keep `includeSchema` false when only names and descriptions are needed, or when an unfiltered service exposes many tools.
|
|
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.
|
|
64
|
+
- Never fetch a tool schema again in the same session when the list response already supplied it, unless metadata may have changed.
|
|
56
65
|
|
|
57
66
|
## Common Patterns
|
|
58
67
|
|
|
59
68
|
- Need a service for one task domain:
|
|
60
69
|
- `gateway_list_services`
|
|
61
70
|
- choose the most relevant `serviceId`
|
|
62
|
-
- `gateway_list_tools({ serviceId: "selected-service", toolName: "optional-keyword" })`
|
|
71
|
+
- `gateway_list_tools({ serviceId: "selected-service", toolName: ["optional-keyword"] })`
|
|
63
72
|
- `gateway_list_tools({ serviceId: "selected-service", toolName: ["keyword-a", "keyword-b"] })`
|
|
64
|
-
- `
|
|
73
|
+
- `gateway_list_tools({ serviceId: "selected-service", toolName: ["name-keyword"], desc: ["description phrase"] })`
|
|
74
|
+
- add `includeSchema: true` to either list call when every match needs schema inspection
|
|
75
|
+
- otherwise call `gateway_get_tool_schema` after selecting exact tool names
|
|
65
76
|
- `gateway_call_tool({ serviceId: "selected-service", toolName: "selected-tool", arguments: {...} })`
|
|
66
77
|
|
|
67
|
-
- Need to inspect
|
|
68
|
-
- `
|
|
78
|
+
- Need to inspect several filtered candidates before choosing or calling them:
|
|
79
|
+
- `gateway_list_tools({ serviceId: "selected-service", toolName: ["candidate-a", "candidate-b"], includeSchema: true })`
|
|
80
|
+
- compare or reuse the returned `inputSchema` and `outputSchema` without separate schema calls
|
|
81
|
+
|
|
82
|
+
- Need schemas for exact selected tools whose schemas were not included in discovery:
|
|
83
|
+
- `gateway_get_tool_schema({ serviceId: "selected-service", toolName: ["selected-tool"] })`
|
|
84
|
+
- or `gateway_get_tool_schema({ serviceId: "selected-service", toolName: ["selected-tool-a", "selected-tool-b"] })`
|
|
85
|
+
- read each result from `schemas[toolName]`
|
|
69
86
|
- build arguments strictly from `inputSchema`
|
|
70
87
|
- call the tool only after the schema is understood
|
|
71
88
|
|
|
@@ -73,7 +90,8 @@ Operate downstream MCP services through the gateway's fixed, token-efficient dis
|
|
|
73
90
|
|
|
74
91
|
- **Never** flatten all downstream tools into your own notes unless the task explicitly needs a full inventory.
|
|
75
92
|
- **Never** invent arguments for a tool when the schema can be queried cheaply.
|
|
76
|
-
- **Never**
|
|
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.
|
|
77
95
|
- **Never** assume a service is available without checking recent gateway discovery results when availability matters.
|
|
78
96
|
|
|
79
97
|
## Practical Guidance
|