@jadchene/mcp-gateway-service 0.4.2 → 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.
@@ -79,19 +79,19 @@ export class McpGatewayEngine {
79
79
  const toolName = requireString(params.name, "The tool name must be a string.");
80
80
  const args = toObject(params.arguments ?? {}, "The tool arguments must be an object.");
81
81
  switch (toolName) {
82
- case "gateway.listServices":
82
+ case "gateway_list_services":
83
83
  return successContent({
84
84
  services: this.registry.listServices().map(formatServiceSummary)
85
85
  });
86
- case "gateway.getService":
86
+ case "gateway_get_service":
87
87
  return this.getService(args);
88
- case "gateway.listTools":
88
+ case "gateway_list_tools":
89
89
  return this.listTools(args);
90
- case "gateway.getToolSchema":
90
+ case "gateway_get_tool_schema":
91
91
  return this.getToolSchema(args);
92
- case "gateway.manageService":
92
+ case "gateway_manage_service":
93
93
  return this.manageService(args);
94
- case "gateway.callTool":
94
+ case "gateway_call_tool":
95
95
  return this.callDownstreamTool(args);
96
96
  default:
97
97
  throw new Error(`Unknown gateway tool '${toolName}'.`);
@@ -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.
@@ -193,7 +204,7 @@ export class McpGatewayEngine {
193
204
  export function buildGatewayTools() {
194
205
  return [
195
206
  {
196
- name: "gateway.listServices",
207
+ name: "gateway_list_services",
197
208
  description: "Lists all MCP services currently managed by the gateway.",
198
209
  inputSchema: {
199
210
  type: "object",
@@ -202,15 +213,15 @@ export function buildGatewayTools() {
202
213
  }
203
214
  },
204
215
  {
205
- name: "gateway.getService",
216
+ name: "gateway_get_service",
206
217
  description: "Returns one service summary, runtime state, and metadata cache details.",
207
218
  inputSchema: objectSchema(["serviceId"], {
208
219
  serviceId: stringSchema("Logical service identifier.")
209
220
  })
210
221
  },
211
222
  {
212
- name: "gateway.listTools",
213
- description: "Lists tools exposed by one downstream service, optionally filtered by one or more tool name keywords.",
223
+ name: "gateway_list_tools",
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,19 +235,40 @@ 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
- name: "gateway.getToolSchema",
232
- description: "Returns the input and output schema for one downstream tool.",
246
+ name: "gateway_get_tool_schema",
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
  {
239
- name: "gateway.manageService",
271
+ name: "gateway_manage_service",
240
272
  description: "Reconnects one service or updates its enabled state with a compact action.",
241
273
  inputSchema: objectSchema(["serviceId", "action"], {
242
274
  serviceId: stringSchema("Logical service identifier."),
@@ -248,7 +280,7 @@ export function buildGatewayTools() {
248
280
  })
249
281
  },
250
282
  {
251
- name: "gateway.callTool",
283
+ name: "gateway_call_tool",
252
284
  description: "Calls one downstream tool through the gateway service pool.",
253
285
  inputSchema: objectSchema(["serviceId", "toolName", "arguments"], {
254
286
  serviceId: stringSchema("Logical service identifier."),
@@ -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.2",
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,60 +10,75 @@ 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.
17
17
 
18
18
  ## Required Workflow
19
19
 
20
- 1. Call `gateway.listServices` once to find the right downstream service.
21
- 2. Call `gateway.listTools(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.getToolSchema(serviceId, toolName)` before the first use of that tool, or any time the arguments are not fully certain.
23
- 4. Call `gateway.callTool(serviceId, toolName, arguments)` for execution.
24
- 5. Re-discover only when a call fails, service availability changes, or the task clearly requires fresh metadata.
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.
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
- - Treat `gateway.getService` as a diagnostic tool, not part of the default workflow.
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
- - Treat `gateway.manageService` as an explicit service-control tool, not part of the default workflow.
32
- - Use `gateway.manageService({ serviceId, action: "reconnect" })` only when the user explicitly wants to retry starting a failed service after its dependency becomes ready.
33
- - Use `gateway.manageService({ serviceId, action: "enable" | "disable" })` only when the user explicitly wants to persistently change that service's enabled state in the config file.
31
+ - Do not call it during normal routing when service discovery, filtered tool discovery, and execution are sufficient.
32
+ - Treat `gateway_manage_service` as an explicit service-control tool, not part of the default workflow.
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.
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.
34
35
 
35
36
  ## Strict Argument Rule
36
37
 
37
- - If a tool has any non-trivial arguments, optional flags, confirmation fields, enum values, or write-safety fields, call `gateway.getToolSchema` before execution unless the exact argument contract is already confirmed in the current session.
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`.
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.
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.
38
43
  - Do not rely on tool descriptions alone when the argument shape could affect correctness or safety.
39
44
  - This is especially important for write tools, confirmation-based tools, and tools with nested argument objects.
40
45
 
41
46
  ## Response Shape Expectations
42
47
 
43
- - `gateway.listServices` returns compact service entries with `serviceId`, `description`, and `available`.
44
- - `gateway.listTools` returns compact tool entries with `name` and `description`, and supports optional substring filtering by `toolName` as a string or string array.
45
- - `gateway.getToolSchema` returns only `inputSchema` and `outputSchema`.
46
- - `gateway.callTool` forwards the downstream MCP result directly with minimal or no gateway wrapping.
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.
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`.
52
+ - `gateway_call_tool` forwards the downstream MCP result directly with minimal or no gateway wrapping.
47
53
 
48
54
  ## Token-Efficient Strategy
49
55
 
50
56
  - Start with the smallest discovery call that can answer the current question.
51
57
  - Avoid listing tools for multiple services when the target domain is already obvious.
52
- - Avoid fetching schemas for multiple tools when only one likely matches the task.
53
- - 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.
54
62
 
55
63
  ## Common Patterns
56
64
 
57
65
  - Need a service for one task domain:
58
- - `gateway.listServices`
66
+ - `gateway_list_services`
59
67
  - choose the most relevant `serviceId`
60
- - `gateway.listTools({ serviceId: "selected-service", toolName: "optional-keyword" })`
61
- - `gateway.listTools({ serviceId: "selected-service", toolName: ["keyword-a", "keyword-b"] })`
62
- - `gateway.getToolSchema({ serviceId: "selected-service", toolName: "selected-tool" })`
63
- - `gateway.callTool({ serviceId: "selected-service", toolName: "selected-tool", arguments: {...} })`
64
-
65
- - Need to inspect an unfamiliar tool before first use, or any tool whose arguments are not fully certain:
66
- - `gateway.getToolSchema({ serviceId: "selected-service", toolName: "selected-tool" })`
68
+ - `gateway_list_tools({ serviceId: "selected-service", toolName: "optional-keyword" })`
69
+ - `gateway_list_tools({ serviceId: "selected-service", toolName: ["keyword-a", "keyword-b"] })`
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
72
+ - `gateway_call_tool({ serviceId: "selected-service", toolName: "selected-tool", arguments: {...} })`
73
+
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:
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]`
67
82
  - build arguments strictly from `inputSchema`
68
83
  - call the tool only after the schema is understood
69
84
 
@@ -71,7 +86,7 @@ Operate downstream MCP services through the gateway's fixed, token-efficient dis
71
86
 
72
87
  - **Never** flatten all downstream tools into your own notes unless the task explicitly needs a full inventory.
73
88
  - **Never** invent arguments for a tool when the schema can be queried cheaply.
74
- - **Never** skip `gateway.getToolSchema` 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.
75
90
  - **Never** assume a service is available without checking recent gateway discovery results when availability matters.
76
91
 
77
92
  ## Practical Guidance