@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.
@@ -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
- name: tool.name,
129
- description: tool.description ?? null
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 for one downstream tool.
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 toolName = requireString(args.toolName, "The 'toolName' argument must be a string.");
139
- const tool = this.registry.getTool(serviceId, toolName);
140
- if (!tool) {
141
- throw new Error(`Unknown tool '${toolName}' in service '${serviceId}'.`);
142
- }
143
- return successContent({
144
- inputSchema: tool.inputSchema ?? null,
145
- outputSchema: tool.outputSchema ?? null
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 one or more tool name keywords.",
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 the input and output schema for one downstream tool.",
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: stringSchema("Downstream tool name.")
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": "@jadchene/mcp-gateway-service",
3
- "version": "0.4.3",
3
+ "version": "0.4.4",
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 MCP services, tool lists, tool schemas, and forwarded tool calls. Prefer the default four-tool workflow and use detailed service inspection only for explicit diagnosis.
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**: Do not enumerate every service and every tool unless the task genuinely needs it.
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, using optional `toolName` as a string or string array when one or more keywords can narrow a large tool list.
22
- 3. Call `gateway_get_tool_schema(serviceId, toolName)` before the first use of that tool, or any time the arguments are not fully certain.
23
- 4. Call `gateway_call_tool(serviceId, toolName, arguments)` for execution.
24
- 5. Re-discover only when a call fails, service availability changes, or the task clearly requires fresh metadata.
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 task execution when the four-tool flow is sufficient.
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, call `gateway_get_tool_schema` before execution unless the exact argument contract is already confirmed in the current session.
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`, and supports optional substring filtering by `toolName` as a string or string array.
47
- - `gateway_get_tool_schema` returns only `inputSchema` and `outputSchema`.
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
- - Avoid fetching schemas for multiple tools when only one likely matches the task.
55
- - Do not repeatedly fetch schemas for the same tool within the same active session unless the tool appears to have changed.
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
- - `gateway_get_tool_schema({ serviceId: "selected-service", toolName: "selected-tool" })`
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 an unfamiliar tool before first use, or any tool whose arguments are not fully certain:
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** skip `gateway_get_tool_schema` when argument names or fields are unclear.
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