@jadchene/mcp-gateway-service 0.4.4 → 0.6.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.
@@ -0,0 +1,270 @@
1
+ import { Client, ProtocolError, SdkHttpError } from "@modelcontextprotocol/client";
2
+ import { VERSION } from "../version.js";
3
+ import { SUPPORTED_MCP_PROTOCOL_VERSIONS } from "./versions.js";
4
+ const MAX_RESTART_ATTEMPTS = 3;
5
+ const CONNECT_TIMEOUT_MS = 30_000;
6
+ /**
7
+ * Implements shared MCP SDK v2 client behavior for stdio and HTTP transports.
8
+ */
9
+ export class SdkMcpClient {
10
+ /**
11
+ * Identifies this client in logs.
12
+ */
13
+ key;
14
+ service;
15
+ logger;
16
+ transportFactory;
17
+ client = null;
18
+ connecting = null;
19
+ restartAttempts = 0;
20
+ unavailableReason = null;
21
+ tools = new Map();
22
+ /**
23
+ * Creates a reusable SDK-backed downstream client.
24
+ */
25
+ constructor(service, logger, transportFactory) {
26
+ this.service = structuredClone(service);
27
+ this.key = service.serviceId;
28
+ this.logger = logger;
29
+ this.transportFactory = transportFactory;
30
+ }
31
+ /**
32
+ * Indicates whether recovery attempts have been exhausted.
33
+ */
34
+ get isUnavailable() {
35
+ return this.unavailableReason !== null;
36
+ }
37
+ /**
38
+ * Returns the terminal unavailability reason.
39
+ */
40
+ get unavailableMessage() {
41
+ return this.unavailableReason;
42
+ }
43
+ /**
44
+ * Returns restart attempts consumed by this lifecycle.
45
+ */
46
+ get restartCount() {
47
+ return this.restartAttempts;
48
+ }
49
+ /**
50
+ * Checks whether this client can be reused after config reload.
51
+ */
52
+ matchesConfig(service) {
53
+ return JSON.stringify(this.service) === JSON.stringify(service);
54
+ }
55
+ /**
56
+ * Establishes an SDK connection with the configured era negotiation policy.
57
+ */
58
+ async ensureConnected() {
59
+ if (this.client) {
60
+ return;
61
+ }
62
+ if (this.unavailableReason) {
63
+ throw new Error(this.unavailableReason);
64
+ }
65
+ if (this.connecting) {
66
+ return this.connecting;
67
+ }
68
+ this.connecting = this.connectOnce();
69
+ try {
70
+ await this.connecting;
71
+ }
72
+ finally {
73
+ this.connecting = null;
74
+ }
75
+ }
76
+ /**
77
+ * Closes the SDK client and clears lifecycle errors.
78
+ */
79
+ async dispose() {
80
+ this.restartAttempts = 0;
81
+ this.unavailableReason = null;
82
+ await this.disposeConnection();
83
+ }
84
+ /**
85
+ * Refreshes server identity and the complete tool catalog.
86
+ */
87
+ async getMetadata() {
88
+ return this.executeWithRecovery(async () => {
89
+ const client = await this.requireClient();
90
+ const tools = await this.requestToolsList(client);
91
+ return {
92
+ protocolVersion: client.getNegotiatedProtocolVersion() ?? null,
93
+ protocolEra: client.getProtocolEra() ?? null,
94
+ serverInfo: toJsonObject(client.getServerVersion()),
95
+ tools,
96
+ refreshedAt: new Date().toISOString()
97
+ };
98
+ });
99
+ }
100
+ /**
101
+ * Lists the downstream tools using SDK caching and pagination behavior.
102
+ */
103
+ async listTools() {
104
+ return this.executeWithRecovery(async () => this.requestToolsList(await this.requireClient()));
105
+ }
106
+ /**
107
+ * Calls a downstream tool while preserving cancellation, custom headers, and MRTR state.
108
+ */
109
+ async callTool(name, args, context = {}) {
110
+ return this.executeWithRecovery(async () => {
111
+ const client = await this.requireClient();
112
+ const params = {
113
+ name,
114
+ arguments: args,
115
+ ...(context.inputResponses ? { inputResponses: context.inputResponses } : {}),
116
+ ...(context.requestState ? { requestState: context.requestState } : {})
117
+ };
118
+ const result = await client.callTool(params, {
119
+ signal: context.signal,
120
+ allowInputRequired: true,
121
+ toolDefinition: this.tools.get(name)
122
+ });
123
+ return result;
124
+ });
125
+ }
126
+ /**
127
+ * Connects one fresh SDK client and transport.
128
+ */
129
+ async connectOnce() {
130
+ await this.connectCandidate(this.transportFactory);
131
+ }
132
+ /**
133
+ * Connects one transport candidate with its own protocol negotiation policy.
134
+ */
135
+ async connectCandidate(transportFactory) {
136
+ const options = {
137
+ supportedProtocolVersions: [...SUPPORTED_MCP_PROTOCOL_VERSIONS],
138
+ capabilities: {
139
+ elicitation: {
140
+ form: {}
141
+ }
142
+ },
143
+ versionNegotiation: {
144
+ mode: "auto",
145
+ probe: {
146
+ timeoutMs: 5_000
147
+ }
148
+ },
149
+ inputRequired: {
150
+ autoFulfill: false,
151
+ maxRounds: 8
152
+ }
153
+ };
154
+ const client = new Client({ name: "mcp-gateway", version: VERSION }, options);
155
+ client.onerror = (error) => {
156
+ this.logger.warn("downstream.sdk_error", {
157
+ serviceId: this.key,
158
+ message: error.message
159
+ });
160
+ };
161
+ const transport = transportFactory();
162
+ try {
163
+ await client.connect(transport, { timeout: CONNECT_TIMEOUT_MS });
164
+ this.client = client;
165
+ this.logger.info("downstream.connected", {
166
+ serviceId: this.key,
167
+ protocolEra: client.getProtocolEra(),
168
+ protocolVersion: client.getNegotiatedProtocolVersion()
169
+ });
170
+ }
171
+ catch (error) {
172
+ await client.close().catch(() => undefined);
173
+ throw error;
174
+ }
175
+ }
176
+ /**
177
+ * Returns the connected client after awaiting any in-flight connection.
178
+ */
179
+ async requireClient() {
180
+ await this.ensureConnected();
181
+ if (!this.client) {
182
+ throw new Error(`Downstream service '${this.key}' is not connected.`);
183
+ }
184
+ return this.client;
185
+ }
186
+ /**
187
+ * Fetches and stores full SDK tool definitions without simplifying JSON Schema.
188
+ */
189
+ async requestToolsList(client) {
190
+ const result = await client.listTools();
191
+ this.tools = new Map(result.tools.map((tool) => [tool.name, tool]));
192
+ return result.tools.map(normalizeToolDefinition);
193
+ }
194
+ /**
195
+ * Retries transport failures while leaving protocol and HTTP client errors untouched.
196
+ */
197
+ async executeWithRecovery(operation) {
198
+ while (true) {
199
+ if (this.unavailableReason) {
200
+ throw new Error(this.unavailableReason);
201
+ }
202
+ try {
203
+ return await operation();
204
+ }
205
+ catch (error) {
206
+ const normalized = normalizeError(error);
207
+ if (isNonRetryable(normalized)) {
208
+ throw normalized;
209
+ }
210
+ await this.disposeConnection();
211
+ if (this.restartAttempts >= MAX_RESTART_ATTEMPTS) {
212
+ this.unavailableReason = `Service '${this.key}' is unavailable after ${MAX_RESTART_ATTEMPTS} restart attempts. Last error: ${normalized.message}`;
213
+ throw new Error(this.unavailableReason);
214
+ }
215
+ this.restartAttempts += 1;
216
+ this.logger.warn("downstream.restart_attempt", {
217
+ serviceId: this.key,
218
+ attempt: this.restartAttempts,
219
+ message: normalized.message
220
+ });
221
+ }
222
+ }
223
+ }
224
+ /**
225
+ * Closes the active SDK connection and clears derived tool views.
226
+ */
227
+ async disposeConnection() {
228
+ const client = this.client;
229
+ this.client = null;
230
+ this.tools.clear();
231
+ await client?.close().catch(() => undefined);
232
+ }
233
+ }
234
+ /**
235
+ * Preserves the complete MCP tool definition in the gateway metadata view.
236
+ */
237
+ function normalizeToolDefinition(tool) {
238
+ return {
239
+ name: tool.name,
240
+ title: tool.title,
241
+ description: tool.description,
242
+ inputSchema: tool.inputSchema,
243
+ outputSchema: tool.outputSchema ?? null,
244
+ annotations: tool.annotations,
245
+ icons: tool.icons,
246
+ execution: tool.execution,
247
+ _meta: tool._meta
248
+ };
249
+ }
250
+ /**
251
+ * Converts optional SDK identity values to the gateway JSON object type.
252
+ */
253
+ function toJsonObject(input) {
254
+ return input ?? null;
255
+ }
256
+ /**
257
+ * Prevents protocol and explicit HTTP failures from being disguised as reconnects.
258
+ */
259
+ function isNonRetryable(error) {
260
+ if (error instanceof ProtocolError) {
261
+ return true;
262
+ }
263
+ return error instanceof SdkHttpError && error.status >= 400 && error.status < 500;
264
+ }
265
+ /**
266
+ * Normalizes unknown thrown values into Error instances.
267
+ */
268
+ function normalizeError(error) {
269
+ return error instanceof Error ? error : new Error(String(error));
270
+ }
@@ -0,0 +1,68 @@
1
+ import { CLIENT_CAPABILITIES_META_KEY, McpServer, fromJsonSchema } from "@modelcontextprotocol/server";
2
+ import { buildGatewayTools } from "../gateway-engine.js";
3
+ import { VERSION } from "../version.js";
4
+ import { SUPPORTED_MCP_PROTOCOL_VERSIONS } from "./versions.js";
5
+ /**
6
+ * Creates one SDK server instance with all six stable gateway tools.
7
+ */
8
+ export function createGatewayMcpServer(engine) {
9
+ const options = {
10
+ supportedProtocolVersions: [...SUPPORTED_MCP_PROTOCOL_VERSIONS],
11
+ capabilities: {
12
+ tools: {
13
+ listChanged: false
14
+ }
15
+ },
16
+ cacheHints: {
17
+ "server/discover": {
18
+ ttlMs: 60_000,
19
+ cacheScope: "public"
20
+ },
21
+ "tools/list": {
22
+ ttlMs: 300_000,
23
+ cacheScope: "public"
24
+ }
25
+ },
26
+ inputRequired: {
27
+ maxRounds: 8
28
+ }
29
+ };
30
+ const server = new McpServer({ name: "mcp-gateway", version: VERSION }, options);
31
+ for (const tool of buildGatewayTools()) {
32
+ const inputSchema = fromJsonSchema(tool.inputSchema);
33
+ const outputSchema = tool.outputSchema
34
+ ? fromJsonSchema(tool.outputSchema)
35
+ : undefined;
36
+ server.registerTool(tool.name, {
37
+ description: tool.description,
38
+ inputSchema,
39
+ ...(outputSchema ? { outputSchema } : {})
40
+ }, async (args, context) => {
41
+ const downstreamContext = toDownstreamContext(context, server.server.getClientCapabilities());
42
+ return engine.executeTool(tool.name, args, downstreamContext);
43
+ });
44
+ }
45
+ return server;
46
+ }
47
+ /**
48
+ * Extracts request-scoped MRTR, capability, and cancellation state for the downstream call.
49
+ */
50
+ function toDownstreamContext(context, mcp2025ClientCapabilities) {
51
+ const envelope = context.mcpReq.envelope;
52
+ const envelopeCapabilities = envelope?.[CLIENT_CAPABILITIES_META_KEY];
53
+ const clientCapabilities = isRecord(envelopeCapabilities)
54
+ ? envelopeCapabilities
55
+ : mcp2025ClientCapabilities;
56
+ return {
57
+ signal: context.mcpReq.signal,
58
+ ...(clientCapabilities ? { clientCapabilities } : {}),
59
+ ...(context.mcpReq.inputResponses ? { inputResponses: context.mcpReq.inputResponses } : {}),
60
+ ...(context.mcpReq.requestState() ? { requestState: context.mcpReq.requestState() } : {})
61
+ };
62
+ }
63
+ /**
64
+ * Checks whether a value is a plain record.
65
+ */
66
+ function isRecord(value) {
67
+ return typeof value === "object" && value !== null && !Array.isArray(value);
68
+ }
@@ -0,0 +1,4 @@
1
+ /**
2
+ * Lists the only MCP protocol revisions accepted by the gateway.
3
+ */
4
+ export const SUPPORTED_MCP_PROTOCOL_VERSIONS = ["2026-07-28", "2025-06-18"];
@@ -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 filtering by one or more tool name keywords.
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 keywords = normalizeToolNameKeywords(toolName);
118
- if (keywords.length === 0) {
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
- return keywords.some((keyword) => normalizedName.includes(keyword));
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
  /**
@@ -132,7 +135,7 @@ export class ServiceRegistry {
132
135
  /**
133
136
  * Calls one downstream tool using the only configured service process.
134
137
  */
135
- async callTool(serviceId, toolName, args) {
138
+ async callTool(serviceId, toolName, args, context = {}) {
136
139
  const snapshot = this.requireService(serviceId);
137
140
  const client = this.clients.get(serviceId);
138
141
  if (!client) {
@@ -140,7 +143,7 @@ export class ServiceRegistry {
140
143
  }
141
144
  const startedAt = Date.now();
142
145
  try {
143
- const result = await client.callTool(toolName, args);
146
+ const result = await client.callTool(toolName, args, context);
144
147
  this.markServiceAvailable(serviceId, client.restartCount);
145
148
  return {
146
149
  result,
@@ -158,7 +161,7 @@ export class ServiceRegistry {
158
161
  }
159
162
  }
160
163
  /**
161
- * Manages one service runtime or persisted enable flag through a compact action interface.
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) {
@@ -258,6 +261,7 @@ export class ServiceRegistry {
258
261
  nextClients.set(service.serviceId, client);
259
262
  let metadata = {
260
263
  protocolVersion: null,
264
+ protocolEra: null,
261
265
  serverInfo: null,
262
266
  tools: [],
263
267
  refreshedAt: null
@@ -362,14 +366,13 @@ function createClient(service, logger) {
362
366
  }
363
367
  }
364
368
  /**
365
- * Normalizes optional tool name keywords for case-insensitive filtering.
369
+ * Normalizes optional keywords for case-insensitive filtering.
366
370
  */
367
- function normalizeToolNameKeywords(toolName) {
368
- if (!toolName) {
371
+ function normalizeKeywords(input) {
372
+ if (!input) {
369
373
  return [];
370
374
  }
371
- const values = Array.isArray(toolName) ? toolName : [toolName];
372
- return values
375
+ return input
373
376
  .map((value) => value.trim().toLowerCase())
374
377
  .filter((value) => value !== "");
375
378
  }
package/package.json CHANGED
@@ -1,29 +1,34 @@
1
1
  {
2
2
  "name": "@jadchene/mcp-gateway-service",
3
- "version": "0.4.4",
3
+ "version": "0.6.0",
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",
7
7
  "bin": {
8
8
  "mcp-gateway-service": "dist/index.js"
9
9
  },
10
- "license": "MIT",
11
- "author": "jadchene",
12
- "repository": {
13
- "type": "git",
14
- "url": "git+https://github.com/jadchene/mcp-gateway.git"
15
- },
16
- "homepage": "https://github.com/jadchene/mcp-gateway#readme",
17
- "bugs": {
18
- "url": "https://github.com/jadchene/mcp-gateway/issues"
19
- },
10
+ "license": "MIT",
11
+ "author": "jadchene",
12
+ "repository": {
13
+ "type": "git",
14
+ "url": "git+https://github.com/jadchene/mcp-gateway.git"
15
+ },
16
+ "homepage": "https://github.com/jadchene/mcp-gateway#readme",
17
+ "bugs": {
18
+ "url": "https://github.com/jadchene/mcp-gateway/issues"
19
+ },
20
20
  "scripts": {
21
- "build": "tsc -p tsconfig.build.json",
22
- "dev": "node --experimental-strip-types src/index.ts",
23
- "start": "node dist/index.js",
24
- "test": "node --test --experimental-strip-types test/**/*.test.ts",
21
+ "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
22
+ "prebuild": "npm run clean",
23
+ "build": "tsc -p tsconfig.build.json",
24
+ "dev": "node --experimental-strip-types src/index.ts",
25
+ "start": "node dist/index.js",
26
+ "pretest": "npm run build",
27
+ "test": "node --test --experimental-strip-types test/**/*.test.ts",
28
+ "typecheck": "tsc -p tsconfig.json --noEmit",
29
+ "verify": "npm run typecheck && npm test",
25
30
  "version": "node dist/index.js --version",
26
- "prepare": "npm run build",
31
+ "prepack": "npm run build",
27
32
  "prepublishOnly": "npm run build"
28
33
  },
29
34
  "files": [
@@ -48,5 +53,11 @@
48
53
  "devDependencies": {
49
54
  "@types/node": "^24.0.0",
50
55
  "typescript": "^5.8.0"
56
+ },
57
+ "dependencies": {
58
+ "@modelcontextprotocol/client": "2.0.0",
59
+ "@modelcontextprotocol/node": "2.0.0",
60
+ "@modelcontextprotocol/server": "2.0.0",
61
+ "zod": "4.4.3"
51
62
  }
52
63
  }
@@ -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, 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.
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 and use optional `toolName` keywords to narrow the result.
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 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.
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,20 @@ 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`, 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.
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` 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.
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.
55
+ - `gateway_call_tool` may return an MCP `input_required` continuation. Never auto-approve it; obtain the required user input and retry with the returned opaque `requestState` and matching `inputResponses`.
56
+ - Treat downstream `structuredContent` as arbitrary JSON rather than assuming it is an object.
53
57
 
54
58
  ## Token-Efficient Strategy
55
59
 
56
60
  - Start with the smallest discovery call that can answer the current question.
57
61
  - Avoid listing tools for multiple services when the target domain is already obvious.
62
+ - 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
63
  - 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
64
  - Keep `includeSchema` false when only names and descriptions are needed, or when an unfiltered service exposes many tools.
60
65
  - 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 +70,9 @@ Operate downstream MCP services through the gateway's fixed, token-efficient dis
65
70
  - Need a service for one task domain:
66
71
  - `gateway_list_services`
67
72
  - choose the most relevant `serviceId`
68
- - `gateway_list_tools({ serviceId: "selected-service", toolName: "optional-keyword" })`
73
+ - `gateway_list_tools({ serviceId: "selected-service", toolName: ["optional-keyword"] })`
69
74
  - `gateway_list_tools({ serviceId: "selected-service", toolName: ["keyword-a", "keyword-b"] })`
75
+ - `gateway_list_tools({ serviceId: "selected-service", toolName: ["name-keyword"], desc: ["description phrase"] })`
70
76
  - add `includeSchema: true` to either list call when every match needs schema inspection
71
77
  - otherwise call `gateway_get_tool_schema` after selecting exact tool names
72
78
  - `gateway_call_tool({ serviceId: "selected-service", toolName: "selected-tool", arguments: {...} })`
@@ -76,7 +82,7 @@ Operate downstream MCP services through the gateway's fixed, token-efficient dis
76
82
  - compare or reuse the returned `inputSchema` and `outputSchema` without separate schema calls
77
83
 
78
84
  - Need schemas for exact selected tools whose schemas were not included in discovery:
79
- - `gateway_get_tool_schema({ serviceId: "selected-service", toolName: "selected-tool" })`
85
+ - `gateway_get_tool_schema({ serviceId: "selected-service", toolName: ["selected-tool"] })`
80
86
  - or `gateway_get_tool_schema({ serviceId: "selected-service", toolName: ["selected-tool-a", "selected-tool-b"] })`
81
87
  - read each result from `schemas[toolName]`
82
88
  - build arguments strictly from `inputSchema`
@@ -87,6 +93,7 @@ Operate downstream MCP services through the gateway's fixed, token-efficient dis
87
93
  - **Never** flatten all downstream tools into your own notes unless the task explicitly needs a full inventory.
88
94
  - **Never** invent arguments for a tool when the schema can be queried cheaply.
89
95
  - **Never** proceed without a schema from `gateway_list_tools(..., includeSchema: true)` or `gateway_get_tool_schema` when argument names or fields are unclear.
96
+ - **Never** omit `gateway_call_tool.arguments`; pass `{}` when the downstream input schema has no properties.
90
97
  - **Never** assume a service is available without checking recent gateway discovery results when availability matters.
91
98
 
92
99
  ## Practical Guidance