@jadchene/mcp-gateway-service 0.6.4 → 0.7.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.
@@ -1,5 +1,6 @@
1
- import { readFile, writeFile } from "node:fs/promises";
2
- import { resolve } from "node:path";
1
+ import { open, readFile, rename, unlink, writeFile } from "node:fs/promises";
2
+ import { dirname, resolve } from "node:path";
3
+ import { randomUUID } from "node:crypto";
3
4
  import { StdioMcpClient } from "./mcp/client.js";
4
5
  import { StreamableHttpClient } from "./mcp/http-client.js";
5
6
  /**
@@ -40,6 +41,7 @@ export class ServiceRegistry {
40
41
  * Prevents overlapping config reload operations.
41
42
  */
42
43
  reloadPromise = Promise.resolve();
44
+ managementPromise = Promise.resolve();
43
45
  /**
44
46
  * Creates a registry bound to one config file path.
45
47
  */
@@ -52,12 +54,27 @@ export class ServiceRegistry {
52
54
  * Loads the initial config snapshot.
53
55
  */
54
56
  async initialize() {
55
- await this.reload();
57
+ await this.reloadStrict();
56
58
  }
57
59
  /**
58
60
  * Reloads the config file and atomically swaps the runtime snapshot on success.
59
61
  */
60
62
  async reload() {
63
+ try {
64
+ await this.reloadStrict();
65
+ }
66
+ catch (error) {
67
+ this.logger.error("config.reload.failed", {
68
+ configPath: resolve(this.configPath),
69
+ message: error instanceof Error ? error.message : String(error)
70
+ });
71
+ await this.logger.flush();
72
+ }
73
+ }
74
+ /**
75
+ * Serializes reloads and lets startup and management callers observe failures.
76
+ */
77
+ async reloadStrict() {
61
78
  this.reloadPromise = this.reloadPromise.catch(() => undefined).then(async () => {
62
79
  const absolutePath = resolve(this.configPath);
63
80
  this.logger.info("config.reload.started", { configPath: absolutePath });
@@ -76,26 +93,21 @@ export class ServiceRegistry {
76
93
  configPath: absolutePath,
77
94
  message: error instanceof Error ? error.message : String(error)
78
95
  });
79
- await disposeClientMap(nextClients);
96
+ await disposeNewClients(this.clients, nextClients);
80
97
  throw error;
81
98
  }
82
- await disposeRemovedClients(this.clients, nextClients);
99
+ const previousClients = this.clients;
83
100
  this.currentConfig = nextConfig;
84
101
  this.snapshots = nextSnapshots;
85
102
  this.clients = nextClients;
103
+ await disposeRemovedClients(previousClients, nextClients);
86
104
  this.logger.info("config.reload.succeeded", {
87
105
  configPath: absolutePath,
88
106
  serviceCount: nextConfig.services.length
89
107
  });
108
+ await this.logger.flush();
90
109
  });
91
- try {
92
- await this.reloadPromise;
93
- }
94
- catch {
95
- /**
96
- * Keeps the last valid snapshot active while surfacing the error through logs.
97
- */
98
- }
110
+ await this.reloadPromise;
99
111
  }
100
112
  /**
101
113
  * Returns a sorted list of runtime service snapshots.
@@ -232,23 +244,36 @@ export class ServiceRegistry {
232
244
  * Persists the service enable flag to the config file and reloads the registry.
233
245
  */
234
246
  async setServiceEnabled(serviceId, enabled) {
235
- const rawConfig = await readRawConfig(this.configPath);
236
- if (!Array.isArray(rawConfig.services)) {
237
- throw new Error("The 'services' field must be an array.");
238
- }
239
- const service = rawConfig.services.find((candidate) => isRecord(candidate) && candidate.serviceId === serviceId);
240
- if (!service || !isRecord(service)) {
241
- throw new Error(`Unknown service '${serviceId}'.`);
242
- }
243
- service.enable = enabled;
244
- await writeFile(resolve(this.configPath), `${JSON.stringify(rawConfig, null, 2)}\n`, "utf8");
245
- await this.reload();
246
- return {
247
- serviceId,
248
- action: enabled ? "enable" : "disable",
249
- enabled,
250
- available: enabled ? (this.getService(serviceId)?.runtime.available ?? false) : false
251
- };
247
+ let result;
248
+ const operation = this.managementPromise.catch(() => undefined).then(async () => {
249
+ const { config: rawConfig, rawText: original } = await readRawConfig(this.configPath);
250
+ if (!Array.isArray(rawConfig.services)) {
251
+ throw new Error("The 'services' field must be an array.");
252
+ }
253
+ const service = rawConfig.services.find((candidate) => isRecord(candidate) && candidate.serviceId === serviceId);
254
+ if (!service || !isRecord(service)) {
255
+ throw new Error(`Unknown service '${serviceId}'.`);
256
+ }
257
+ service.enable = enabled;
258
+ const absolutePath = resolve(this.configPath);
259
+ await writeFileAtomically(absolutePath, `${JSON.stringify(rawConfig, null, 2)}\n`);
260
+ try {
261
+ await this.reloadStrict();
262
+ }
263
+ catch (error) {
264
+ await writeFileAtomically(absolutePath, original);
265
+ throw error;
266
+ }
267
+ result = {
268
+ serviceId,
269
+ action: enabled ? "enable" : "disable",
270
+ enabled,
271
+ available: enabled ? (this.getService(serviceId)?.runtime.available ?? false) : false
272
+ };
273
+ });
274
+ this.managementPromise = operation;
275
+ await operation;
276
+ return result;
252
277
  }
253
278
  /**
254
279
  * Builds one runtime snapshot and initializes required metadata.
@@ -352,6 +377,13 @@ async function disposeRemovedClients(previous, next) {
352
377
  }
353
378
  await Promise.all(removed.map((client) => client.dispose().catch(() => undefined)));
354
379
  }
380
+ /** Disposes only clients created by a failed reload, preserving reused active clients. */
381
+ async function disposeNewClients(previous, next) {
382
+ const created = [...next.entries()]
383
+ .filter(([key, client]) => previous.get(key) !== client)
384
+ .map(([, client]) => client);
385
+ await Promise.all(created.map((client) => client.dispose().catch(() => undefined)));
386
+ }
355
387
  /**
356
388
  * Creates a downstream client implementation for one service config.
357
389
  */
@@ -385,7 +417,41 @@ async function readRawConfig(configPath) {
385
417
  if (!isRecord(parsed)) {
386
418
  throw new Error("The gateway config must be a JSON object.");
387
419
  }
388
- return parsed;
420
+ return { config: parsed, rawText };
421
+ }
422
+ /**
423
+ * Replaces a config file through a flushed same-directory temporary file.
424
+ */
425
+ async function writeFileAtomically(path, content) {
426
+ const tempPath = resolve(dirname(path), `.${randomUUID()}.tmp`);
427
+ try {
428
+ await writeFile(tempPath, content, { encoding: "utf8", mode: 0o600 });
429
+ const handle = await open(tempPath, "r");
430
+ try {
431
+ if (process.platform !== "win32") {
432
+ await handle.sync();
433
+ }
434
+ }
435
+ finally {
436
+ await handle.close();
437
+ }
438
+ await rename(tempPath, path);
439
+ if (process.platform !== "win32") {
440
+ const directory = await open(dirname(path), "r").catch(() => null);
441
+ if (directory) {
442
+ try {
443
+ await directory.sync();
444
+ }
445
+ finally {
446
+ await directory.close();
447
+ }
448
+ }
449
+ }
450
+ }
451
+ catch (error) {
452
+ await unlink(tempPath).catch(() => undefined);
453
+ throw error;
454
+ }
389
455
  }
390
456
  /**
391
457
  * Checks whether a value is a plain record.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@jadchene/mcp-gateway-service",
3
- "version": "0.6.4",
3
+ "version": "0.7.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",
@@ -17,18 +17,18 @@
17
17
  "bugs": {
18
18
  "url": "https://github.com/jadchene/mcp-gateway/issues"
19
19
  },
20
- "scripts": {
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",
20
+ "scripts": {
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",
30
30
  "version": "node dist/index.js --version",
31
- "prepack": "npm run build",
31
+ "prepack": "npm run build",
32
32
  "prepublishOnly": "npm run build"
33
33
  },
34
34
  "files": [
@@ -59,5 +59,9 @@
59
59
  "@modelcontextprotocol/node": "2.0.0",
60
60
  "@modelcontextprotocol/server": "2.0.0",
61
61
  "zod": "4.4.3"
62
+ },
63
+ "overrides": {
64
+ "@hono/node-server": "2.1.0",
65
+ "hono": "4.12.34"
62
66
  }
63
67
  }
@@ -47,41 +47,72 @@ function Invoke-CaptureStep {
47
47
  return @()
48
48
  }
49
49
 
50
+ function Resolve-PackedTarballPath {
51
+ param(
52
+ [string[]]$PackOutput,
53
+ [string]$ProjectRoot
54
+ )
55
+
56
+ if ($PackOutput.Count -eq 0) {
57
+ throw "npm pack did not return package metadata."
58
+ }
59
+
60
+ $parsedOutput = $PackOutput -join "`n" | ConvertFrom-Json
61
+ $packInfo = if ($parsedOutput -is [System.Array]) {
62
+ $parsedOutput[0]
63
+ }
64
+ else {
65
+ @($parsedOutput.PSObject.Properties.Value)[0]
66
+ }
67
+ $filename = [string]$packInfo.filename
68
+
69
+ if ([string]::IsNullOrWhiteSpace($filename)) {
70
+ throw "npm pack metadata did not contain a tarball filename."
71
+ }
72
+ if ([IO.Path]::GetFileName($filename) -ne $filename -or [IO.Path]::GetExtension($filename) -ne ".tgz") {
73
+ throw "npm pack returned an unsafe tarball filename: $filename"
74
+ }
75
+
76
+ $tarballPath = [IO.Path]::GetFullPath((Join-Path $ProjectRoot $filename))
77
+ $tarballParent = [IO.Path]::GetDirectoryName($tarballPath)
78
+ if (-not [StringComparer]::OrdinalIgnoreCase.Equals($tarballParent, $ProjectRoot)) {
79
+ throw "npm pack returned a tarball outside the project root: $tarballPath"
80
+ }
81
+ if (-not (Test-Path -LiteralPath $tarballPath -PathType Leaf)) {
82
+ throw "Packed tarball was not created: $tarballPath"
83
+ }
84
+
85
+ return $tarballPath
86
+ }
87
+
50
88
  $resolvedProjectRoot = (Resolve-Path $ProjectRoot).Path
51
89
  $packageJsonPath = Join-Path $resolvedProjectRoot "package.json"
52
90
  $defaultConfigPath = Join-Path $resolvedProjectRoot "config.example.json"
53
91
  $resolvedConfigPath = if ($ExampleConfigPath) { $ExampleConfigPath } else { $defaultConfigPath }
54
- $packageName = "mcp-gateway-service"
55
92
 
56
93
  if (-not (Test-Path $packageJsonPath)) {
57
94
  throw "package.json not found under project root: $resolvedProjectRoot"
58
95
  }
59
96
 
60
97
  $packageInfo = Get-Content -Raw $packageJsonPath | ConvertFrom-Json
98
+ $packageName = [string]$packageInfo.name
99
+ if ([string]::IsNullOrWhiteSpace($packageName)) {
100
+ throw "package.json does not contain a package name."
101
+ }
61
102
 
62
103
  Push-Location $resolvedProjectRoot
63
104
  try {
64
105
  Invoke-Step -FilePath "npm" -Arguments @("install") -Description "Install project dependencies"
65
106
  Invoke-Step -FilePath "npm" -Arguments @("run", "build") -Description "Build the MCP gateway"
66
107
  $packOutput = Invoke-CaptureStep -FilePath "npm" -Arguments @("pack", "--json") -Description "Create a package tarball for global installation"
67
- if ($packOutput.Count -gt 0) {
68
- $packInfo = ($packOutput -join "`n" | ConvertFrom-Json)[0]
69
- $tarballPath = Join-Path $resolvedProjectRoot $packInfo.filename
70
- } else {
71
- $tarballPath = Join-Path $resolvedProjectRoot "$($packageInfo.name)-$($packageInfo.version).tgz"
72
- }
108
+ $tarballPath = Resolve-PackedTarballPath -PackOutput $packOutput -ProjectRoot $resolvedProjectRoot
73
109
 
74
- try {
75
- Invoke-Step -FilePath "npm" -Arguments @("uninstall", "-g", $packageName) -Description "Remove any previous global installation of mcp-gateway-service"
76
- }
77
- catch {
78
- Write-Host "Previous global installation was not removed cleanly. Continuing with fresh install."
79
- }
110
+ Invoke-Step -FilePath "npm" -Arguments @("uninstall", "-g", $packageName) -Description "Remove any previous global installation of $packageName"
80
111
 
81
112
  Invoke-Step -FilePath "npm" -Arguments @("install", "-g", $tarballPath) -Description "Install the packaged mcp-gateway-service tarball globally"
82
113
 
83
- if (-not $KeepTarball -and (Test-Path $tarballPath)) {
84
- Remove-Item $tarballPath -Force
114
+ if (-not $KeepTarball -and (Test-Path -LiteralPath $tarballPath -PathType Leaf)) {
115
+ Remove-Item -LiteralPath $tarballPath -Force
85
116
  }
86
117
  }
87
118
  finally {
@@ -1,104 +1,40 @@
1
1
  ---
2
2
  name: mcp-gateway
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.
3
+ description: Route work through an MCP gateway with token-efficient downstream service discovery, filtered tool search, exact schema lookup, service diagnostics, and forwarded tool calls. Use when an agent needs to find or call tools behind the gateway without loading every downstream schema.
4
4
  ---
5
5
 
6
6
  # MCP Gateway
7
7
 
8
- Operate downstream MCP services through the gateway's fixed, token-efficient discovery interface.
8
+ Use the gateway as the single entry point for downstream MCP services.
9
9
 
10
- ## Core Mandates
10
+ ## Routing Workflow
11
11
 
12
- - **Discovery First**: Never guess a `serviceId` or downstream `toolName`. Discover them through the gateway.
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
- - **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
- - **Cache Mentally Per Session**: Reuse known service lists, tool lists, and schemas within the current session instead of asking again without reason.
16
- - **Compression Recovery Gate**: After any context compression event, re-read `AGENTS.md` and this `SKILL.md` before continuing.
12
+ 1. Reuse an exact `serviceId` already confirmed in the current session; otherwise call `gateway_list_services`.
13
+ 2. Reuse an exact downstream tool name already confirmed in the current session; otherwise call `gateway_list_tools` for only the selected service.
14
+ 3. Filter discovery with unique non-empty `toolName` and/or `desc` string arrays. Treat both filters as case-insensitive literal substring matches joined by OR.
15
+ 4. Obtain the input schema when arguments are unfamiliar, incomplete, or safety-sensitive. Use `includeSchema: true` during filtered discovery or call `gateway_get_tool_schema` with exact case-sensitive tool names.
16
+ 5. Call `gateway_call_tool` with the confirmed `serviceId`, exact `toolName`, and an explicit `arguments` object. Pass `{}` for a no-argument tool.
17
+ 6. Refresh only stale service, tool, or schema information after an unknown-identifier or validation failure.
17
18
 
18
- ## Required Workflow
19
+ ## Discovery Rules
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. 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.
21
+ - Never guess a service identifier, tool name, or argument shape.
22
+ - Treat `serviceId` as a downstream identifier returned by `gateway_list_services`; never use a gateway-owned tool name as a service identifier.
23
+ - Search only the relevant service instead of collecting every downstream tool.
24
+ - Inspect description matches because negative guidance may also contain the search term.
25
+ - Reuse schemas returned by `gateway_list_tools(includeSchema: true)` instead of fetching them again.
26
+ - Batch exact names in one `gateway_get_tool_schema` call when several selected tools need schemas.
27
+ - Treat downstream `structuredContent` as arbitrary JSON.
26
28
 
27
- ## Diagnostic Exception
29
+ ## Diagnostics and Control
28
30
 
29
- - Treat `gateway_get_service` as a diagnostic tool, not part of the default workflow.
30
- - Use it only when the user explicitly asks to inspect service health, connection state, protocol details, or recent service errors.
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.
31
+ - Use `gateway_get_service` only when connection state, protocol details, server identity, or recent errors matter.
32
+ - Use `gateway_manage_service` only when the user explicitly requests reconnecting, enabling, or disabling a service.
33
+ - Treat `reconnect` as a connection refresh that does not change config.
34
+ - Treat `enable` and `disable` as persistent config changes.
35
35
 
36
- ## Strict Argument Rule
36
+ ## Safety
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`.
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.
43
- - Do not rely on tool descriptions alone when the argument shape could affect correctness or safety.
44
- - This is especially important for write tools, confirmation-based tools, and tools with nested argument objects.
45
-
46
- ## Response Shape Expectations
47
-
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`. 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.
55
- - `gateway_call_tool` may return an MCP `input_required` continuation, including one converted from a 2025 downstream form elicitation. 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.
57
-
58
- ## Token-Efficient Strategy
59
-
60
- - Start with the smallest discovery call that can answer the current question.
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.
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.
64
- - Keep `includeSchema` false when only names and descriptions are needed, or when an unfiltered service exposes many tools.
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.
66
- - Never fetch a tool schema again in the same session when the list response already supplied it, unless metadata may have changed.
67
-
68
- ## Common Patterns
69
-
70
- - Need a service for one task domain:
71
- - `gateway_list_services`
72
- - choose the most relevant `serviceId`
73
- - `gateway_list_tools({ serviceId: "selected-service", toolName: ["optional-keyword"] })`
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"] })`
76
- - add `includeSchema: true` to either list call when every match needs schema inspection
77
- - otherwise call `gateway_get_tool_schema` after selecting exact tool names
78
- - `gateway_call_tool({ serviceId: "selected-service", toolName: "selected-tool", arguments: {...} })`
79
-
80
- - Need to inspect several filtered candidates before choosing or calling them:
81
- - `gateway_list_tools({ serviceId: "selected-service", toolName: ["candidate-a", "candidate-b"], includeSchema: true })`
82
- - compare or reuse the returned `inputSchema` and `outputSchema` without separate schema calls
83
-
84
- - Need schemas for exact selected tools whose schemas were not included in discovery:
85
- - `gateway_get_tool_schema({ serviceId: "selected-service", toolName: ["selected-tool"] })`
86
- - or `gateway_get_tool_schema({ serviceId: "selected-service", toolName: ["selected-tool-a", "selected-tool-b"] })`
87
- - read each result from `schemas[toolName]`
88
- - build arguments strictly from `inputSchema`
89
- - call the tool only after the schema is understood
90
-
91
- ## Prohibited Patterns
92
-
93
- - **Never** flatten all downstream tools into your own notes unless the task explicitly needs a full inventory.
94
- - **Never** invent arguments for a tool when the schema can be queried cheaply.
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.
97
- - **Never** assume a service is available without checking recent gateway discovery results when availability matters.
98
-
99
- ## Practical Guidance
100
-
101
- - Choose `serviceId` by task domain and service description instead of assuming a fixed service naming scheme.
102
- - Prefer the smallest discovery step that can answer the question.
103
- - If a downstream tool fails with a validation error, fetch or re-check its schema before retrying.
104
- - If there is any doubt about required parameters, confirmation tokens, or argument structure, fetch the schema first instead of guessing.
38
+ - Apply the downstream tool's schema, side-effect rules, and confirmation flow before calling it.
39
+ - Treat gateway failures and structured downstream error results as failures.
40
+ - Never auto-approve an `input_required` result. Obtain the requested user input and retry with the returned opaque state and matching responses.