@jadchene/mcp-gateway-service 0.4.3 → 0.4.4
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 +242 -300
- package/README_zh.md +247 -307
- package/config.example.json +1 -1
- package/dist/gateway-engine.js +76 -17
- package/package.json +1 -1
- package/skills/mcp-gateway/SKILL.md +28 -15
package/dist/gateway-engine.js
CHANGED
|
@@ -123,27 +123,38 @@ export class McpGatewayEngine {
|
|
|
123
123
|
listTools(args) {
|
|
124
124
|
const serviceId = requireString(args.serviceId, "The 'serviceId' argument must be a string.");
|
|
125
125
|
const toolName = optionalStringArray(args.toolName, "The 'toolName' argument must be a string or string array when provided.");
|
|
126
|
+
const includeSchema = optionalBoolean(args.includeSchema, "The 'includeSchema' argument must be a boolean when provided.") ?? false;
|
|
126
127
|
return successContent({
|
|
127
|
-
tools: this.registry.listTools(serviceId, toolName).map((tool) =>
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
128
|
+
tools: this.registry.listTools(serviceId, toolName).map((tool) => {
|
|
129
|
+
const summary = {
|
|
130
|
+
name: tool.name,
|
|
131
|
+
description: tool.description ?? null
|
|
132
|
+
};
|
|
133
|
+
if (includeSchema) {
|
|
134
|
+
summary.inputSchema = tool.inputSchema ?? null;
|
|
135
|
+
summary.outputSchema = tool.outputSchema ?? null;
|
|
136
|
+
}
|
|
137
|
+
return summary;
|
|
138
|
+
})
|
|
131
139
|
});
|
|
132
140
|
}
|
|
133
141
|
/**
|
|
134
|
-
* Returns input and output schemas
|
|
142
|
+
* Returns input and output schemas keyed by downstream tool name.
|
|
135
143
|
*/
|
|
136
144
|
getToolSchema(args) {
|
|
137
145
|
const serviceId = requireString(args.serviceId, "The 'serviceId' argument must be a string.");
|
|
138
|
-
const
|
|
139
|
-
const
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
146
|
+
const toolNames = requireStringArray(args.toolName, "The 'toolName' argument must be a non-empty string or non-empty string array.");
|
|
147
|
+
const schemas = Object.fromEntries(toolNames.map((toolName) => {
|
|
148
|
+
const tool = this.registry.getTool(serviceId, toolName);
|
|
149
|
+
if (!tool) {
|
|
150
|
+
throw new Error(`Unknown tool '${toolName}' in service '${serviceId}'.`);
|
|
151
|
+
}
|
|
152
|
+
return [toolName, {
|
|
153
|
+
inputSchema: tool.inputSchema ?? null,
|
|
154
|
+
outputSchema: tool.outputSchema ?? null
|
|
155
|
+
}];
|
|
156
|
+
}));
|
|
157
|
+
return successContent({ schemas });
|
|
147
158
|
}
|
|
148
159
|
/**
|
|
149
160
|
* Routes one downstream tool call through the service registry.
|
|
@@ -210,7 +221,7 @@ export function buildGatewayTools() {
|
|
|
210
221
|
},
|
|
211
222
|
{
|
|
212
223
|
name: "gateway_list_tools",
|
|
213
|
-
description: "Lists tools exposed by one downstream service, optionally filtered by
|
|
224
|
+
description: "Lists tools exposed by one downstream service, optionally filtered by name keywords and including their schemas.",
|
|
214
225
|
inputSchema: objectSchema(["serviceId"], {
|
|
215
226
|
serviceId: stringSchema("Logical service identifier."),
|
|
216
227
|
toolName: {
|
|
@@ -224,15 +235,36 @@ export function buildGatewayTools() {
|
|
|
224
235
|
}
|
|
225
236
|
}
|
|
226
237
|
]
|
|
238
|
+
},
|
|
239
|
+
includeSchema: {
|
|
240
|
+
type: "boolean",
|
|
241
|
+
description: "Includes inputSchema and outputSchema in every returned tool when true. Defaults to false."
|
|
227
242
|
}
|
|
228
243
|
})
|
|
229
244
|
},
|
|
230
245
|
{
|
|
231
246
|
name: "gateway_get_tool_schema",
|
|
232
|
-
description: "Returns
|
|
247
|
+
description: "Returns input and output schemas for one or more downstream tools, keyed by tool name.",
|
|
233
248
|
inputSchema: objectSchema(["serviceId", "toolName"], {
|
|
234
249
|
serviceId: stringSchema("Logical service identifier."),
|
|
235
|
-
toolName:
|
|
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
|
+
}
|
|
236
268
|
})
|
|
237
269
|
},
|
|
238
270
|
{
|
|
@@ -340,6 +372,33 @@ function optionalStringArray(input, message) {
|
|
|
340
372
|
const trimmed = input.trim();
|
|
341
373
|
return trimmed === "" ? undefined : trimmed;
|
|
342
374
|
}
|
|
375
|
+
/**
|
|
376
|
+
* Returns one or more required non-empty strings with duplicates removed.
|
|
377
|
+
*/
|
|
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() === "")) {
|
|
386
|
+
throw new Error(message);
|
|
387
|
+
}
|
|
388
|
+
return [...new Set(input)];
|
|
389
|
+
}
|
|
390
|
+
/**
|
|
391
|
+
* Returns an optional boolean without coercing other input types.
|
|
392
|
+
*/
|
|
393
|
+
function optionalBoolean(input, message) {
|
|
394
|
+
if (input === undefined || input === null) {
|
|
395
|
+
return undefined;
|
|
396
|
+
}
|
|
397
|
+
if (typeof input !== "boolean") {
|
|
398
|
+
throw new Error(message);
|
|
399
|
+
}
|
|
400
|
+
return input;
|
|
401
|
+
}
|
|
343
402
|
/**
|
|
344
403
|
* Ensures the service management action is supported.
|
|
345
404
|
*/
|
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, 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.
|
|
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 and use optional `toolName` keywords to narrow the result.
|
|
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.
|
|
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,16 +46,19 @@ 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
|
-
- `
|
|
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.
|
|
50
|
+
- `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`.
|
|
48
52
|
- `gateway_call_tool` forwards the downstream MCP result directly with minimal or no gateway wrapping.
|
|
49
53
|
|
|
50
54
|
## Token-Efficient Strategy
|
|
51
55
|
|
|
52
56
|
- Start with the smallest discovery call that can answer the current question.
|
|
53
57
|
- Avoid listing tools for multiple services when the target domain is already obvious.
|
|
54
|
-
-
|
|
55
|
-
-
|
|
58
|
+
- 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
|
+
- Keep `includeSchema` false when only names and descriptions are needed, or when an unfiltered service exposes many tools.
|
|
60
|
+
- 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.
|
|
61
|
+
- Never fetch a tool schema again in the same session when the list response already supplied it, unless metadata may have changed.
|
|
56
62
|
|
|
57
63
|
## Common Patterns
|
|
58
64
|
|
|
@@ -61,11 +67,18 @@ Operate downstream MCP services through the gateway's fixed, token-efficient dis
|
|
|
61
67
|
- choose the most relevant `serviceId`
|
|
62
68
|
- `gateway_list_tools({ serviceId: "selected-service", toolName: "optional-keyword" })`
|
|
63
69
|
- `gateway_list_tools({ serviceId: "selected-service", toolName: ["keyword-a", "keyword-b"] })`
|
|
64
|
-
- `
|
|
70
|
+
- add `includeSchema: true` to either list call when every match needs schema inspection
|
|
71
|
+
- otherwise call `gateway_get_tool_schema` after selecting exact tool names
|
|
65
72
|
- `gateway_call_tool({ serviceId: "selected-service", toolName: "selected-tool", arguments: {...} })`
|
|
66
73
|
|
|
67
|
-
- Need to inspect
|
|
74
|
+
- Need to inspect several filtered candidates before choosing or calling them:
|
|
75
|
+
- `gateway_list_tools({ serviceId: "selected-service", toolName: ["candidate-a", "candidate-b"], includeSchema: true })`
|
|
76
|
+
- compare or reuse the returned `inputSchema` and `outputSchema` without separate schema calls
|
|
77
|
+
|
|
78
|
+
- Need schemas for exact selected tools whose schemas were not included in discovery:
|
|
68
79
|
- `gateway_get_tool_schema({ serviceId: "selected-service", toolName: "selected-tool" })`
|
|
80
|
+
- or `gateway_get_tool_schema({ serviceId: "selected-service", toolName: ["selected-tool-a", "selected-tool-b"] })`
|
|
81
|
+
- read each result from `schemas[toolName]`
|
|
69
82
|
- build arguments strictly from `inputSchema`
|
|
70
83
|
- call the tool only after the schema is understood
|
|
71
84
|
|
|
@@ -73,7 +86,7 @@ Operate downstream MCP services through the gateway's fixed, token-efficient dis
|
|
|
73
86
|
|
|
74
87
|
- **Never** flatten all downstream tools into your own notes unless the task explicitly needs a full inventory.
|
|
75
88
|
- **Never** invent arguments for a tool when the schema can be queried cheaply.
|
|
76
|
-
- **Never**
|
|
89
|
+
- **Never** proceed without a schema from `gateway_list_tools(..., includeSchema: true)` or `gateway_get_tool_schema` when argument names or fields are unclear.
|
|
77
90
|
- **Never** assume a service is available without checking recent gateway discovery results when availability matters.
|
|
78
91
|
|
|
79
92
|
## Practical Guidance
|