@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.
- package/README.md +59 -199
- package/README_zh.md +59 -199
- package/config.example.json +5 -6
- package/dist/config.js +17 -17
- package/dist/gateway-engine.js +149 -152
- package/dist/gateway-server.js +17 -33
- package/dist/http-server.js +37 -153
- package/dist/index.js +4 -0
- package/dist/mcp/client.js +61 -567
- package/dist/mcp/http-client.js +24 -473
- package/dist/mcp/sdk-client.js +270 -0
- package/dist/mcp/server.js +68 -0
- package/dist/mcp/versions.js +4 -0
- package/dist/service-registry.js +16 -13
- package/package.json +27 -16
- package/skills/mcp-gateway/SKILL.md +16 -9
- package/dist/mcp/protocol.js +0 -193
|
@@ -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
|
+
}
|
package/dist/service-registry.js
CHANGED
|
@@ -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
|
|
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
|
|
118
|
-
|
|
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
|
-
|
|
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
|
-
*
|
|
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
|
|
369
|
+
* Normalizes optional keywords for case-insensitive filtering.
|
|
366
370
|
*/
|
|
367
|
-
function
|
|
368
|
-
if (!
|
|
371
|
+
function normalizeKeywords(input) {
|
|
372
|
+
if (!input) {
|
|
369
373
|
return [];
|
|
370
374
|
}
|
|
371
|
-
|
|
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.
|
|
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
|
-
"
|
|
22
|
-
"
|
|
23
|
-
"
|
|
24
|
-
"
|
|
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
|
-
"
|
|
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,
|
|
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
|
|
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
|
|
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
|
|
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`
|
|
52
|
-
- `gateway_call_tool`
|
|
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
|