@jadchene/mcp-gateway-service 0.4.1 → 0.4.3
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 +22 -22
- package/README_zh.md +23 -23
- package/dist/gateway-engine.js +45 -15
- package/dist/service-registry.js +23 -3
- package/package.json +1 -1
- package/skills/mcp-gateway/SKILL.md +22 -19
package/README.md
CHANGED
|
@@ -215,30 +215,30 @@ A service is loaded only when `enable` is missing or set to `true`. If `enable`
|
|
|
215
215
|
|
|
216
216
|
The gateway exposes a fixed set of discovery and routing tools:
|
|
217
217
|
|
|
218
|
-
- `
|
|
219
|
-
- `
|
|
220
|
-
- `
|
|
221
|
-
- `
|
|
222
|
-
- `
|
|
223
|
-
- `
|
|
218
|
+
- `gateway_list_services`
|
|
219
|
+
- `gateway_get_service`
|
|
220
|
+
- `gateway_list_tools`
|
|
221
|
+
- `gateway_get_tool_schema`
|
|
222
|
+
- `gateway_manage_service`
|
|
223
|
+
- `gateway_call_tool`
|
|
224
224
|
|
|
225
225
|
### Response design
|
|
226
226
|
|
|
227
|
-
- `
|
|
228
|
-
- `
|
|
229
|
-
- `
|
|
230
|
-
- `
|
|
231
|
-
- `
|
|
227
|
+
- `gateway_list_services` returns only `serviceId`, `description`, and `available`.
|
|
228
|
+
- `gateway_list_tools` returns only `name` and `description`; pass optional `toolName` as a string or string array to filter names by substring.
|
|
229
|
+
- `gateway_get_tool_schema` returns only `inputSchema` and `outputSchema`.
|
|
230
|
+
- `gateway_manage_service` returns only `serviceId`, `action`, `enabled`, and `available`.
|
|
231
|
+
- `gateway_call_tool` forwards the downstream MCP tool result directly without extra gateway metadata wrapping.
|
|
232
232
|
|
|
233
233
|
### Default workflow vs diagnostics
|
|
234
234
|
|
|
235
|
-
- The default token-efficient workflow still uses four tools: `
|
|
236
|
-
- `
|
|
237
|
-
- `
|
|
235
|
+
- The default token-efficient workflow still uses four tools: `gateway_list_services`, `gateway_list_tools`, `gateway_get_tool_schema`, and `gateway_call_tool`.
|
|
236
|
+
- `gateway_get_service` is primarily for diagnostics, such as checking recent service errors, connection state, protocol version, or downstream server info.
|
|
237
|
+
- `gateway_manage_service` is an operational tool for explicit service control, not part of the normal discovery flow.
|
|
238
238
|
|
|
239
|
-
### `
|
|
239
|
+
### `gateway_manage_service`
|
|
240
240
|
|
|
241
|
-
Use `
|
|
241
|
+
Use `gateway_manage_service` when you explicitly need to reconnect a service or persistently change its enabled state.
|
|
242
242
|
|
|
243
243
|
Input:
|
|
244
244
|
|
|
@@ -260,12 +260,12 @@ Important notes:
|
|
|
260
260
|
|
|
261
261
|
For the best token efficiency, the MCP client should cache discovery results instead of repeatedly querying the gateway:
|
|
262
262
|
|
|
263
|
-
1. Call `
|
|
264
|
-
2. Call `
|
|
265
|
-
3. Call `
|
|
266
|
-
4. Call `
|
|
267
|
-
5. Use `
|
|
268
|
-
6. Use `
|
|
263
|
+
1. Call `gateway_list_services` once at session start.
|
|
264
|
+
2. Call `gateway_list_tools(serviceId)` only when a service is actually needed, optionally with `toolName` to narrow large tool lists by one or more keywords.
|
|
265
|
+
3. Call `gateway_get_tool_schema(serviceId, toolName)` only before the first use of that tool.
|
|
266
|
+
4. Call `gateway_call_tool(...)` for execution.
|
|
267
|
+
5. Use `gateway_get_service` only when diagnostics are explicitly needed.
|
|
268
|
+
6. Use `gateway_manage_service` only when a service must be reconnected or explicitly enabled/disabled.
|
|
269
269
|
7. Refresh discovery data only when a call fails, the config changes, or the client explicitly wants a refresh.
|
|
270
270
|
|
|
271
271
|
## Skill Integration (Recommended)
|
package/README_zh.md
CHANGED
|
@@ -75,7 +75,7 @@
|
|
|
75
75
|
### 稳定的网关接口
|
|
76
76
|
- 不动态展开所有下游工具。
|
|
77
77
|
- 服务列表和工具列表返回精简结构。
|
|
78
|
-
- `
|
|
78
|
+
- `gateway_call_tool` 直接透传下游工具返回结果,减少额外包装。
|
|
79
79
|
|
|
80
80
|
### 实用运维能力
|
|
81
81
|
- 从 JSON 配置文件加载静态服务池。
|
|
@@ -217,30 +217,30 @@ mcp-gateway-service -v
|
|
|
217
217
|
|
|
218
218
|
## 对外网关工具
|
|
219
219
|
|
|
220
|
-
- `
|
|
221
|
-
- `
|
|
222
|
-
- `
|
|
223
|
-
- `
|
|
224
|
-
- `
|
|
225
|
-
- `
|
|
220
|
+
- `gateway_list_services`
|
|
221
|
+
- `gateway_get_service`
|
|
222
|
+
- `gateway_list_tools`
|
|
223
|
+
- `gateway_get_tool_schema`
|
|
224
|
+
- `gateway_manage_service`
|
|
225
|
+
- `gateway_call_tool`
|
|
226
226
|
|
|
227
227
|
### 返回结构约定
|
|
228
228
|
|
|
229
|
-
- `
|
|
230
|
-
- `
|
|
231
|
-
- `
|
|
232
|
-
- `
|
|
233
|
-
- `
|
|
229
|
+
- `gateway_list_services` 只返回 `serviceId`、`description`、`available`
|
|
230
|
+
- `gateway_list_tools` 只返回 `name`、`description`,可传可选参数 `toolName`,支持字符串或字符串数组,按名称片段筛选
|
|
231
|
+
- `gateway_get_tool_schema` 只返回 `inputSchema`、`outputSchema`
|
|
232
|
+
- `gateway_manage_service` 只返回 `serviceId`、`action`、`enabled`、`available`
|
|
233
|
+
- `gateway_call_tool` 直接返回下游 MCP 的结果,不再额外包一层网关元数据
|
|
234
234
|
|
|
235
235
|
### 默认流程与诊断的区别
|
|
236
236
|
|
|
237
|
-
- 默认的节省 token 工作流仍然只依赖 4 个工具:`
|
|
238
|
-
- `
|
|
239
|
-
- `
|
|
237
|
+
- 默认的节省 token 工作流仍然只依赖 4 个工具:`gateway_list_services`、`gateway_list_tools`、`gateway_get_tool_schema`、`gateway_call_tool`
|
|
238
|
+
- `gateway_get_service` 主要用于诊断,例如查看最近错误、连接状态、协议版本、下游服务信息
|
|
239
|
+
- `gateway_manage_service` 是显式运维控制工具,不属于日常 discovery 流程
|
|
240
240
|
|
|
241
|
-
### `
|
|
241
|
+
### `gateway_manage_service`
|
|
242
242
|
|
|
243
|
-
当你明确需要重新拉起某个服务,或者持久化修改某个服务的启用状态时,使用 `
|
|
243
|
+
当你明确需要重新拉起某个服务,或者持久化修改某个服务的启用状态时,使用 `gateway_manage_service`。
|
|
244
244
|
|
|
245
245
|
输入参数:
|
|
246
246
|
|
|
@@ -262,12 +262,12 @@ mcp-gateway-service -v
|
|
|
262
262
|
|
|
263
263
|
为了尽量节省 token,推荐由客户端缓存发现结果,而不是每次都重新调用网关:
|
|
264
264
|
|
|
265
|
-
1. 会话开始时调用一次 `
|
|
266
|
-
2. 真正需要某个服务时,再调用 `
|
|
267
|
-
3. 第一次调用某个工具前,再调用 `
|
|
268
|
-
4. 执行时调用 `
|
|
269
|
-
5. 只有在明确需要诊断时才调用 `
|
|
270
|
-
6. 只有在需要重新拉起服务或显式启用/停用服务时才调用 `
|
|
265
|
+
1. 会话开始时调用一次 `gateway_list_services`
|
|
266
|
+
2. 真正需要某个服务时,再调用 `gateway_list_tools(serviceId)`,工具很多时可传 `toolName` 用一个或多个关键词缩小结果范围
|
|
267
|
+
3. 第一次调用某个工具前,再调用 `gateway_get_tool_schema(serviceId, toolName)`
|
|
268
|
+
4. 执行时调用 `gateway_call_tool(...)`
|
|
269
|
+
5. 只有在明确需要诊断时才调用 `gateway_get_service`
|
|
270
|
+
6. 只有在需要重新拉起服务或显式启用/停用服务时才调用 `gateway_manage_service`
|
|
271
271
|
7. 只有在调用失败、配置变更、或明确需要刷新时才重新发现
|
|
272
272
|
|
|
273
273
|
## Skill 集成(推荐)
|
package/dist/gateway-engine.js
CHANGED
|
@@ -79,19 +79,19 @@ export class McpGatewayEngine {
|
|
|
79
79
|
const toolName = requireString(params.name, "The tool name must be a string.");
|
|
80
80
|
const args = toObject(params.arguments ?? {}, "The tool arguments must be an object.");
|
|
81
81
|
switch (toolName) {
|
|
82
|
-
case "
|
|
82
|
+
case "gateway_list_services":
|
|
83
83
|
return successContent({
|
|
84
84
|
services: this.registry.listServices().map(formatServiceSummary)
|
|
85
85
|
});
|
|
86
|
-
case "
|
|
86
|
+
case "gateway_get_service":
|
|
87
87
|
return this.getService(args);
|
|
88
|
-
case "
|
|
88
|
+
case "gateway_list_tools":
|
|
89
89
|
return this.listTools(args);
|
|
90
|
-
case "
|
|
90
|
+
case "gateway_get_tool_schema":
|
|
91
91
|
return this.getToolSchema(args);
|
|
92
|
-
case "
|
|
92
|
+
case "gateway_manage_service":
|
|
93
93
|
return this.manageService(args);
|
|
94
|
-
case "
|
|
94
|
+
case "gateway_call_tool":
|
|
95
95
|
return this.callDownstreamTool(args);
|
|
96
96
|
default:
|
|
97
97
|
throw new Error(`Unknown gateway tool '${toolName}'.`);
|
|
@@ -122,8 +122,9 @@ export class McpGatewayEngine {
|
|
|
122
122
|
*/
|
|
123
123
|
listTools(args) {
|
|
124
124
|
const serviceId = requireString(args.serviceId, "The 'serviceId' argument must be a string.");
|
|
125
|
+
const toolName = optionalStringArray(args.toolName, "The 'toolName' argument must be a string or string array when provided.");
|
|
125
126
|
return successContent({
|
|
126
|
-
tools: this.registry.listTools(serviceId).map((tool) => ({
|
|
127
|
+
tools: this.registry.listTools(serviceId, toolName).map((tool) => ({
|
|
127
128
|
name: tool.name,
|
|
128
129
|
description: tool.description ?? null
|
|
129
130
|
}))
|
|
@@ -192,7 +193,7 @@ export class McpGatewayEngine {
|
|
|
192
193
|
export function buildGatewayTools() {
|
|
193
194
|
return [
|
|
194
195
|
{
|
|
195
|
-
name: "
|
|
196
|
+
name: "gateway_list_services",
|
|
196
197
|
description: "Lists all MCP services currently managed by the gateway.",
|
|
197
198
|
inputSchema: {
|
|
198
199
|
type: "object",
|
|
@@ -201,21 +202,33 @@ export function buildGatewayTools() {
|
|
|
201
202
|
}
|
|
202
203
|
},
|
|
203
204
|
{
|
|
204
|
-
name: "
|
|
205
|
+
name: "gateway_get_service",
|
|
205
206
|
description: "Returns one service summary, runtime state, and metadata cache details.",
|
|
206
207
|
inputSchema: objectSchema(["serviceId"], {
|
|
207
208
|
serviceId: stringSchema("Logical service identifier.")
|
|
208
209
|
})
|
|
209
210
|
},
|
|
210
211
|
{
|
|
211
|
-
name: "
|
|
212
|
-
description: "Lists
|
|
212
|
+
name: "gateway_list_tools",
|
|
213
|
+
description: "Lists tools exposed by one downstream service, optionally filtered by one or more tool name keywords.",
|
|
213
214
|
inputSchema: objectSchema(["serviceId"], {
|
|
214
|
-
serviceId: stringSchema("Logical service identifier.")
|
|
215
|
+
serviceId: stringSchema("Logical service identifier."),
|
|
216
|
+
toolName: {
|
|
217
|
+
anyOf: [
|
|
218
|
+
stringSchema("Optional keyword matched against downstream tool names."),
|
|
219
|
+
{
|
|
220
|
+
type: "array",
|
|
221
|
+
description: "Optional keywords matched against downstream tool names. A tool is returned when any keyword matches.",
|
|
222
|
+
items: {
|
|
223
|
+
type: "string"
|
|
224
|
+
}
|
|
225
|
+
}
|
|
226
|
+
]
|
|
227
|
+
}
|
|
215
228
|
})
|
|
216
229
|
},
|
|
217
230
|
{
|
|
218
|
-
name: "
|
|
231
|
+
name: "gateway_get_tool_schema",
|
|
219
232
|
description: "Returns the input and output schema for one downstream tool.",
|
|
220
233
|
inputSchema: objectSchema(["serviceId", "toolName"], {
|
|
221
234
|
serviceId: stringSchema("Logical service identifier."),
|
|
@@ -223,7 +236,7 @@ export function buildGatewayTools() {
|
|
|
223
236
|
})
|
|
224
237
|
},
|
|
225
238
|
{
|
|
226
|
-
name: "
|
|
239
|
+
name: "gateway_manage_service",
|
|
227
240
|
description: "Reconnects one service or updates its enabled state with a compact action.",
|
|
228
241
|
inputSchema: objectSchema(["serviceId", "action"], {
|
|
229
242
|
serviceId: stringSchema("Logical service identifier."),
|
|
@@ -235,7 +248,7 @@ export function buildGatewayTools() {
|
|
|
235
248
|
})
|
|
236
249
|
},
|
|
237
250
|
{
|
|
238
|
-
name: "
|
|
251
|
+
name: "gateway_call_tool",
|
|
239
252
|
description: "Calls one downstream tool through the gateway service pool.",
|
|
240
253
|
inputSchema: objectSchema(["serviceId", "toolName", "arguments"], {
|
|
241
254
|
serviceId: stringSchema("Logical service identifier."),
|
|
@@ -310,6 +323,23 @@ function requireString(input, message) {
|
|
|
310
323
|
}
|
|
311
324
|
return input;
|
|
312
325
|
}
|
|
326
|
+
/**
|
|
327
|
+
* Returns optional string keywords, treating blank strings as absent.
|
|
328
|
+
*/
|
|
329
|
+
function optionalStringArray(input, message) {
|
|
330
|
+
if (input === undefined || input === null) {
|
|
331
|
+
return undefined;
|
|
332
|
+
}
|
|
333
|
+
if (typeof input !== "string") {
|
|
334
|
+
if (!Array.isArray(input) || input.some((value) => typeof value !== "string")) {
|
|
335
|
+
throw new Error(message);
|
|
336
|
+
}
|
|
337
|
+
const values = input.map((value) => value.trim()).filter((value) => value !== "");
|
|
338
|
+
return values.length === 0 ? undefined : values;
|
|
339
|
+
}
|
|
340
|
+
const trimmed = input.trim();
|
|
341
|
+
return trimmed === "" ? undefined : trimmed;
|
|
342
|
+
}
|
|
313
343
|
/**
|
|
314
344
|
* Ensures the service management action is supported.
|
|
315
345
|
*/
|
package/dist/service-registry.js
CHANGED
|
@@ -110,10 +110,18 @@ export class ServiceRegistry {
|
|
|
110
110
|
return this.snapshots.get(serviceId) ?? null;
|
|
111
111
|
}
|
|
112
112
|
/**
|
|
113
|
-
* Lists tools for one logical service.
|
|
113
|
+
* Lists tools for one logical service, optionally filtering by one or more tool name keywords.
|
|
114
114
|
*/
|
|
115
|
-
listTools(serviceId) {
|
|
116
|
-
|
|
115
|
+
listTools(serviceId, toolName) {
|
|
116
|
+
const tools = this.requireService(serviceId).metadata.tools;
|
|
117
|
+
const keywords = normalizeToolNameKeywords(toolName);
|
|
118
|
+
if (keywords.length === 0) {
|
|
119
|
+
return tools;
|
|
120
|
+
}
|
|
121
|
+
return tools.filter((tool) => {
|
|
122
|
+
const normalizedName = tool.name.toLowerCase();
|
|
123
|
+
return keywords.some((keyword) => normalizedName.includes(keyword));
|
|
124
|
+
});
|
|
117
125
|
}
|
|
118
126
|
/**
|
|
119
127
|
* Returns one tool definition for a service.
|
|
@@ -353,6 +361,18 @@ function createClient(service, logger) {
|
|
|
353
361
|
throw new Error(`Unsupported transport '${String(service.transport.type)}'.`);
|
|
354
362
|
}
|
|
355
363
|
}
|
|
364
|
+
/**
|
|
365
|
+
* Normalizes optional tool name keywords for case-insensitive filtering.
|
|
366
|
+
*/
|
|
367
|
+
function normalizeToolNameKeywords(toolName) {
|
|
368
|
+
if (!toolName) {
|
|
369
|
+
return [];
|
|
370
|
+
}
|
|
371
|
+
const values = Array.isArray(toolName) ? toolName : [toolName];
|
|
372
|
+
return values
|
|
373
|
+
.map((value) => value.trim().toLowerCase())
|
|
374
|
+
.filter((value) => value !== "");
|
|
375
|
+
}
|
|
356
376
|
/**
|
|
357
377
|
* Loads the raw config document for management edits that must preserve disabled services.
|
|
358
378
|
*/
|
package/package.json
CHANGED
|
@@ -17,33 +17,35 @@ Operate downstream MCP services through the gateway's fixed, token-efficient dis
|
|
|
17
17
|
|
|
18
18
|
## Required Workflow
|
|
19
19
|
|
|
20
|
-
1. Call `
|
|
21
|
-
2. Call `
|
|
22
|
-
3. Call `
|
|
23
|
-
4. Call `
|
|
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, using optional `toolName` as a string or string array when one or more keywords can narrow a large tool list.
|
|
22
|
+
3. Call `gateway_get_tool_schema(serviceId, toolName)` before the first use of that tool, or any time the arguments are not fully certain.
|
|
23
|
+
4. Call `gateway_call_tool(serviceId, toolName, arguments)` for execution.
|
|
24
24
|
5. Re-discover only when a call fails, service availability changes, or the task clearly requires fresh metadata.
|
|
25
25
|
|
|
26
26
|
## Diagnostic Exception
|
|
27
27
|
|
|
28
|
-
- Treat `
|
|
28
|
+
- Treat `gateway_get_service` as a diagnostic tool, not part of the default workflow.
|
|
29
29
|
- Use it only when the user explicitly asks to inspect service health, connection state, protocol details, or recent service errors.
|
|
30
30
|
- Do not call it during normal task execution when the four-tool flow is sufficient.
|
|
31
|
-
- Treat `
|
|
32
|
-
- Use `
|
|
33
|
-
- Use `
|
|
31
|
+
- Treat `gateway_manage_service` as an explicit service-control tool, not part of the default workflow.
|
|
32
|
+
- Use `gateway_manage_service({ serviceId, action: "reconnect" })` only when the user explicitly wants to retry starting a failed service after its dependency becomes ready.
|
|
33
|
+
- Use `gateway_manage_service({ serviceId, action: "enable" | "disable" })` only when the user explicitly wants to persistently change that service's enabled state in the config file.
|
|
34
34
|
|
|
35
35
|
## Strict Argument Rule
|
|
36
36
|
|
|
37
|
-
-
|
|
37
|
+
- 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`.
|
|
38
|
+
- If a tool has any non-trivial arguments, optional flags, confirmation fields, enum values, or write-safety fields, call `gateway_get_tool_schema` before execution unless the exact argument contract is already confirmed in the current session.
|
|
39
|
+
- Apply gateway discovery, schema, management, and routing tools only to downstream services and downstream tools. Do not use them to inspect or call gateway-owned tools such as `gateway_list_tools` or `gateway_call_tool`; gateway-owned tool schemas come from the MCP client's current gateway tool definitions.
|
|
38
40
|
- Do not rely on tool descriptions alone when the argument shape could affect correctness or safety.
|
|
39
41
|
- This is especially important for write tools, confirmation-based tools, and tools with nested argument objects.
|
|
40
42
|
|
|
41
43
|
## Response Shape Expectations
|
|
42
44
|
|
|
43
|
-
- `
|
|
44
|
-
- `
|
|
45
|
-
- `
|
|
46
|
-
- `
|
|
45
|
+
- `gateway_list_services` returns compact service entries with `serviceId`, `description`, and `available`.
|
|
46
|
+
- `gateway_list_tools` returns compact tool entries with `name` and `description`, and supports optional substring filtering by `toolName` as a string or string array.
|
|
47
|
+
- `gateway_get_tool_schema` returns only `inputSchema` and `outputSchema`.
|
|
48
|
+
- `gateway_call_tool` forwards the downstream MCP result directly with minimal or no gateway wrapping.
|
|
47
49
|
|
|
48
50
|
## Token-Efficient Strategy
|
|
49
51
|
|
|
@@ -55,14 +57,15 @@ Operate downstream MCP services through the gateway's fixed, token-efficient dis
|
|
|
55
57
|
## Common Patterns
|
|
56
58
|
|
|
57
59
|
- Need a service for one task domain:
|
|
58
|
-
- `
|
|
60
|
+
- `gateway_list_services`
|
|
59
61
|
- choose the most relevant `serviceId`
|
|
60
|
-
- `
|
|
61
|
-
- `
|
|
62
|
-
- `
|
|
62
|
+
- `gateway_list_tools({ serviceId: "selected-service", toolName: "optional-keyword" })`
|
|
63
|
+
- `gateway_list_tools({ serviceId: "selected-service", toolName: ["keyword-a", "keyword-b"] })`
|
|
64
|
+
- `gateway_get_tool_schema({ serviceId: "selected-service", toolName: "selected-tool" })`
|
|
65
|
+
- `gateway_call_tool({ serviceId: "selected-service", toolName: "selected-tool", arguments: {...} })`
|
|
63
66
|
|
|
64
67
|
- Need to inspect an unfamiliar tool before first use, or any tool whose arguments are not fully certain:
|
|
65
|
-
- `
|
|
68
|
+
- `gateway_get_tool_schema({ serviceId: "selected-service", toolName: "selected-tool" })`
|
|
66
69
|
- build arguments strictly from `inputSchema`
|
|
67
70
|
- call the tool only after the schema is understood
|
|
68
71
|
|
|
@@ -70,7 +73,7 @@ Operate downstream MCP services through the gateway's fixed, token-efficient dis
|
|
|
70
73
|
|
|
71
74
|
- **Never** flatten all downstream tools into your own notes unless the task explicitly needs a full inventory.
|
|
72
75
|
- **Never** invent arguments for a tool when the schema can be queried cheaply.
|
|
73
|
-
- **Never** skip `
|
|
76
|
+
- **Never** skip `gateway_get_tool_schema` when argument names or fields are unclear.
|
|
74
77
|
- **Never** assume a service is available without checking recent gateway discovery results when availability matters.
|
|
75
78
|
|
|
76
79
|
## Practical Guidance
|