@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.
- package/README.md +196 -153
- package/README_zh.md +196 -153
- package/config.example.json +34 -30
- package/dist/config.js +47 -5
- package/dist/file-watcher.js +16 -2
- package/dist/gateway-engine.js +5 -2
- package/dist/http-server.js +57 -1
- package/dist/index.js +41 -6
- package/dist/logger.js +83 -49
- package/dist/mcp/client.js +11 -4
- package/dist/mcp/form-elicitation-bridge.js +51 -2
- package/dist/mcp/sdk-client.js +30 -4
- package/dist/mcp/server.js +5 -5
- package/dist/service-registry.js +97 -31
- package/package.json +16 -12
- package/scripts/install-global.ps1 +46 -15
- package/skills/mcp-gateway/SKILL.md +26 -90
package/dist/service-registry.js
CHANGED
|
@@ -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.
|
|
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
|
|
96
|
+
await disposeNewClients(this.clients, nextClients);
|
|
80
97
|
throw error;
|
|
81
98
|
}
|
|
82
|
-
|
|
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
|
-
|
|
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
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
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.
|
|
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
|
-
|
|
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
|
-
|
|
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:
|
|
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
|
-
|
|
8
|
+
Use the gateway as the single entry point for downstream MCP services.
|
|
9
9
|
|
|
10
|
-
##
|
|
10
|
+
## Routing Workflow
|
|
11
11
|
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
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
|
-
##
|
|
19
|
+
## Discovery Rules
|
|
19
20
|
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
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
|
-
##
|
|
29
|
+
## Diagnostics and Control
|
|
28
30
|
|
|
29
|
-
-
|
|
30
|
-
- Use
|
|
31
|
-
-
|
|
32
|
-
- Treat `
|
|
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
|
-
##
|
|
36
|
+
## Safety
|
|
37
37
|
|
|
38
|
-
-
|
|
39
|
-
-
|
|
40
|
-
-
|
|
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.
|