@jadchene/mcp-gateway-service 0.2.1 → 0.3.1
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 +57 -33
- package/README_zh.md +55 -31
- package/dist/gateway-server.js +38 -1
- package/dist/mcp/client.js +42 -4
- package/dist/service-registry.js +101 -0
- package/package.json +1 -1
- package/skills/mcp-gateway/SKILL.md +10 -1
package/README.md
CHANGED
|
@@ -38,14 +38,7 @@ That means the model only sees the minimum amount of MCP metadata needed for the
|
|
|
38
38
|
|
|
39
39
|
### 2. Provide one unified MCP entry point for multiple agents
|
|
40
40
|
|
|
41
|
-
Without a gateway, each agent usually needs its own MCP client configuration for
|
|
42
|
-
|
|
43
|
-
- database MCP
|
|
44
|
-
- SSH MCP
|
|
45
|
-
- IDE MCP
|
|
46
|
-
- Playwright MCP
|
|
47
|
-
- Gitea MCP
|
|
48
|
-
- and more
|
|
41
|
+
Without a gateway, each agent usually needs its own MCP client configuration for multiple downstream services.
|
|
49
42
|
|
|
50
43
|
That quickly becomes hard to maintain:
|
|
51
44
|
|
|
@@ -172,30 +165,60 @@ A service is loaded only when `enable` is missing or set to `true`. If `enable`
|
|
|
172
165
|
|
|
173
166
|
## Public Gateway Tools
|
|
174
167
|
|
|
175
|
-
The gateway exposes a fixed set of discovery and routing tools:
|
|
176
|
-
|
|
177
|
-
- `gateway.listServices`
|
|
178
|
-
- `gateway.getService`
|
|
179
|
-
- `gateway.listTools`
|
|
180
|
-
- `gateway.getToolSchema`
|
|
181
|
-
- `gateway.
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
- `gateway.
|
|
187
|
-
- `gateway.
|
|
188
|
-
- `gateway.
|
|
168
|
+
The gateway exposes a fixed set of discovery and routing tools:
|
|
169
|
+
|
|
170
|
+
- `gateway.listServices`
|
|
171
|
+
- `gateway.getService`
|
|
172
|
+
- `gateway.listTools`
|
|
173
|
+
- `gateway.getToolSchema`
|
|
174
|
+
- `gateway.manageService`
|
|
175
|
+
- `gateway.callTool`
|
|
176
|
+
|
|
177
|
+
### Response design
|
|
178
|
+
|
|
179
|
+
- `gateway.listServices` returns only `serviceId`, `description`, and `available`.
|
|
180
|
+
- `gateway.listTools` returns only `name` and `description`.
|
|
181
|
+
- `gateway.getToolSchema` returns only `inputSchema` and `outputSchema`.
|
|
182
|
+
- `gateway.manageService` returns only `serviceId`, `action`, `enabled`, and `available`.
|
|
183
|
+
- `gateway.callTool` forwards the downstream MCP tool result directly without extra gateway metadata wrapping.
|
|
184
|
+
|
|
185
|
+
### Default workflow vs diagnostics
|
|
186
|
+
|
|
187
|
+
- The default token-efficient workflow still uses four tools: `gateway.listServices`, `gateway.listTools`, `gateway.getToolSchema`, and `gateway.callTool`.
|
|
188
|
+
- `gateway.getService` is primarily for diagnostics, such as checking recent service errors, connection state, protocol version, or downstream server info.
|
|
189
|
+
- `gateway.manageService` is an operational tool for explicit service control, not part of the normal discovery flow.
|
|
190
|
+
|
|
191
|
+
### `gateway.manageService`
|
|
192
|
+
|
|
193
|
+
Use `gateway.manageService` when you explicitly need to reconnect a service or persistently change its enabled state.
|
|
194
|
+
|
|
195
|
+
Input:
|
|
196
|
+
|
|
197
|
+
- `serviceId`: logical service identifier
|
|
198
|
+
- `action`: one of `reconnect`, `enable`, or `disable`
|
|
199
|
+
|
|
200
|
+
Action behavior:
|
|
201
|
+
|
|
202
|
+
- `reconnect`: immediately tries to start and reinitialize the specified downstream MCP again. Use this when a service previously failed because its dependency was not ready, such as an IDE that was not open yet.
|
|
203
|
+
- `enable`: writes `enable: true` to the config file for that service and triggers a reload.
|
|
204
|
+
- `disable`: writes `enable: false` to the config file for that service and triggers a reload.
|
|
205
|
+
|
|
206
|
+
Important notes:
|
|
207
|
+
|
|
208
|
+
- `enable` and `disable` are persisted to the JSON config file. They are not session-only toggles.
|
|
209
|
+
- `reconnect` does not modify the config file. It only retries the current service lifecycle.
|
|
189
210
|
|
|
190
211
|
## Recommended Client Workflow
|
|
191
212
|
|
|
192
213
|
For the best token efficiency, the MCP client should cache discovery results instead of repeatedly querying the gateway:
|
|
193
214
|
|
|
194
|
-
1. Call `gateway.listServices` once at session start.
|
|
195
|
-
2. Call `gateway.listTools(serviceId)` only when a service is actually needed.
|
|
196
|
-
3. Call `gateway.getToolSchema(serviceId, toolName)` only before the first use of that tool.
|
|
197
|
-
4. Call `gateway.callTool(...)` for execution.
|
|
198
|
-
5.
|
|
215
|
+
1. Call `gateway.listServices` once at session start.
|
|
216
|
+
2. Call `gateway.listTools(serviceId)` only when a service is actually needed.
|
|
217
|
+
3. Call `gateway.getToolSchema(serviceId, toolName)` only before the first use of that tool.
|
|
218
|
+
4. Call `gateway.callTool(...)` for execution.
|
|
219
|
+
5. Use `gateway.getService` only when diagnostics are explicitly needed.
|
|
220
|
+
6. Use `gateway.manageService` only when a service must be reconnected or explicitly enabled/disabled.
|
|
221
|
+
7. Refresh discovery data only when a call fails, the config changes, or the client explicitly wants a refresh.
|
|
199
222
|
|
|
200
223
|
## Skill Integration (Recommended)
|
|
201
224
|
|
|
@@ -263,12 +286,13 @@ args = ["--config", "./config.json"]
|
|
|
263
286
|
|
|
264
287
|
## Development Notes
|
|
265
288
|
|
|
266
|
-
- Repository-managed `config.json` and `config.example.json` are examples only.
|
|
267
|
-
- Copy `config.example.json` to your own local `config.json` before running the gateway.
|
|
268
|
-
- Keep real local configs and logs outside the repository.
|
|
269
|
-
- Downstream output schema is returned only when the downstream service exposes it.
|
|
270
|
-
- Windows command resolution supports PowerShell shims such as `.ps1`-backed command aliases.
|
|
289
|
+
- Repository-managed `config.json` and `config.example.json` are examples only.
|
|
290
|
+
- Copy `config.example.json` to your own local `config.json` before running the gateway.
|
|
291
|
+
- Keep real local configs and logs outside the repository.
|
|
292
|
+
- Downstream output schema is returned only when the downstream service exposes it.
|
|
293
|
+
- Windows command resolution supports PowerShell shims such as `.ps1`-backed command aliases.
|
|
294
|
+
- On Windows, the gateway prefers `pwsh` for `.ps1` shim resolution and execution, and automatically falls back to `powershell.exe` when `pwsh` is unavailable.
|
|
271
295
|
|
|
272
296
|
## License
|
|
273
297
|
|
|
274
|
-
Released under the [MIT License](./LICENSE).
|
|
298
|
+
Released under the [MIT License](./LICENSE).
|
package/README_zh.md
CHANGED
|
@@ -44,14 +44,7 @@
|
|
|
44
44
|
|
|
45
45
|
### 2. 给多个 Agent 提供统一的 MCP 接入入口
|
|
46
46
|
|
|
47
|
-
如果没有网关,每个 Agent
|
|
48
|
-
|
|
49
|
-
- database MCP
|
|
50
|
-
- SSH MCP
|
|
51
|
-
- IDE MCP
|
|
52
|
-
- Playwright MCP
|
|
53
|
-
- Gitea MCP
|
|
54
|
-
- 以及其他服务
|
|
47
|
+
如果没有网关,每个 Agent 往往都要分别配置多个下游 MCP 服务。
|
|
55
48
|
|
|
56
49
|
这种方式很快会带来维护问题:
|
|
57
50
|
|
|
@@ -176,28 +169,58 @@ mcp-gateway-service -v
|
|
|
176
169
|
|
|
177
170
|
## 对外网关工具
|
|
178
171
|
|
|
179
|
-
- `gateway.listServices`
|
|
180
|
-
- `gateway.getService`
|
|
181
|
-
- `gateway.listTools`
|
|
182
|
-
- `gateway.getToolSchema`
|
|
183
|
-
- `gateway.
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
- `gateway.
|
|
189
|
-
- `gateway.
|
|
190
|
-
- `gateway.
|
|
172
|
+
- `gateway.listServices`
|
|
173
|
+
- `gateway.getService`
|
|
174
|
+
- `gateway.listTools`
|
|
175
|
+
- `gateway.getToolSchema`
|
|
176
|
+
- `gateway.manageService`
|
|
177
|
+
- `gateway.callTool`
|
|
178
|
+
|
|
179
|
+
### 返回结构约定
|
|
180
|
+
|
|
181
|
+
- `gateway.listServices` 只返回 `serviceId`、`description`、`available`
|
|
182
|
+
- `gateway.listTools` 只返回 `name`、`description`
|
|
183
|
+
- `gateway.getToolSchema` 只返回 `inputSchema`、`outputSchema`
|
|
184
|
+
- `gateway.manageService` 只返回 `serviceId`、`action`、`enabled`、`available`
|
|
185
|
+
- `gateway.callTool` 直接返回下游 MCP 的结果,不再额外包一层网关元数据
|
|
186
|
+
|
|
187
|
+
### 默认流程与诊断的区别
|
|
188
|
+
|
|
189
|
+
- 默认的节省 token 工作流仍然只依赖 4 个工具:`gateway.listServices`、`gateway.listTools`、`gateway.getToolSchema`、`gateway.callTool`
|
|
190
|
+
- `gateway.getService` 主要用于诊断,例如查看最近错误、连接状态、协议版本、下游服务信息
|
|
191
|
+
- `gateway.manageService` 是显式运维控制工具,不属于日常 discovery 流程
|
|
192
|
+
|
|
193
|
+
### `gateway.manageService`
|
|
194
|
+
|
|
195
|
+
当你明确需要重新拉起某个服务,或者持久化修改某个服务的启用状态时,使用 `gateway.manageService`。
|
|
196
|
+
|
|
197
|
+
输入参数:
|
|
198
|
+
|
|
199
|
+
- `serviceId`:逻辑服务标识
|
|
200
|
+
- `action`:只能是 `reconnect`、`enable`、`disable`
|
|
201
|
+
|
|
202
|
+
动作语义:
|
|
203
|
+
|
|
204
|
+
- `reconnect`:立即重新尝试启动并重新初始化指定下游 MCP。适合处理“之前因为依赖没准备好而启动失败”的场景,比如当时 IDE 没开,后来打开后再次尝试拉起 IDE MCP。
|
|
205
|
+
- `enable`:把该服务在配置文件中的 `enable` 写成 `true`,然后触发 reload。
|
|
206
|
+
- `disable`:把该服务在配置文件中的 `enable` 写成 `false`,然后触发 reload。
|
|
207
|
+
|
|
208
|
+
注意:
|
|
209
|
+
|
|
210
|
+
- `enable` 和 `disable` 会持久化写入 JSON 配置文件,不是只在当前会话里生效。
|
|
211
|
+
- `reconnect` 不会修改配置文件,只会重新尝试当前服务生命周期。
|
|
191
212
|
|
|
192
213
|
## 推荐调用流程
|
|
193
214
|
|
|
194
215
|
为了尽量节省 token,推荐由客户端缓存发现结果,而不是每次都重新调用网关:
|
|
195
216
|
|
|
196
|
-
1. 会话开始时调用一次 `gateway.listServices`
|
|
197
|
-
2. 真正需要某个服务时,再调用 `gateway.listTools(serviceId)`
|
|
198
|
-
3. 第一次调用某个工具前,再调用 `gateway.getToolSchema(serviceId, toolName)`
|
|
199
|
-
4. 执行时调用 `gateway.callTool(...)`
|
|
200
|
-
5.
|
|
217
|
+
1. 会话开始时调用一次 `gateway.listServices`
|
|
218
|
+
2. 真正需要某个服务时,再调用 `gateway.listTools(serviceId)`
|
|
219
|
+
3. 第一次调用某个工具前,再调用 `gateway.getToolSchema(serviceId, toolName)`
|
|
220
|
+
4. 执行时调用 `gateway.callTool(...)`
|
|
221
|
+
5. 只有在明确需要诊断时才调用 `gateway.getService`
|
|
222
|
+
6. 只有在需要重新拉起服务或显式启用/停用服务时才调用 `gateway.manageService`
|
|
223
|
+
7. 只有在调用失败、配置变更、或明确需要刷新时才重新发现
|
|
201
224
|
|
|
202
225
|
## Skill 集成(推荐)
|
|
203
226
|
|
|
@@ -265,12 +288,13 @@ args = ["--config", "./config.json"]
|
|
|
265
288
|
|
|
266
289
|
## 开发说明
|
|
267
290
|
|
|
268
|
-
- 仓库只保留 `config.example.json` 作为示例
|
|
269
|
-
- 运行前请自行复制一份本地 `config.json`
|
|
270
|
-
- 真实本地配置和日志建议放在仓库外
|
|
271
|
-
- 只有下游服务自己暴露了 `outputSchema` 时,网关才会返回它
|
|
272
|
-
- Windows 下支持解析 PowerShell shim 命令,例如实际落到 `.ps1` 的全局命令
|
|
291
|
+
- 仓库只保留 `config.example.json` 作为示例
|
|
292
|
+
- 运行前请自行复制一份本地 `config.json`
|
|
293
|
+
- 真实本地配置和日志建议放在仓库外
|
|
294
|
+
- 只有下游服务自己暴露了 `outputSchema` 时,网关才会返回它
|
|
295
|
+
- Windows 下支持解析 PowerShell shim 命令,例如实际落到 `.ps1` 的全局命令
|
|
296
|
+
- 在 Windows 上,网关会优先使用 `pwsh` 解析和执行 `.ps1` shim;如果机器上没有 `pwsh`,会自动回退到 `powershell.exe`
|
|
273
297
|
|
|
274
298
|
## License
|
|
275
299
|
|
|
276
|
-
项目采用 [MIT License](./LICENSE) 开源。
|
|
300
|
+
项目采用 [MIT License](./LICENSE) 开源。
|
package/dist/gateway-server.js
CHANGED
|
@@ -111,6 +111,8 @@ export class GatewayServer {
|
|
|
111
111
|
return this.listTools(args);
|
|
112
112
|
case "gateway.getToolSchema":
|
|
113
113
|
return this.getToolSchema(args);
|
|
114
|
+
case "gateway.manageService":
|
|
115
|
+
return this.manageService(args);
|
|
114
116
|
case "gateway.callTool":
|
|
115
117
|
return this.callDownstreamTool(args);
|
|
116
118
|
default:
|
|
@@ -174,6 +176,20 @@ export class GatewayServer {
|
|
|
174
176
|
const call = await this.registry.callTool(serviceId, toolName, toolArgs);
|
|
175
177
|
return call.result;
|
|
176
178
|
}
|
|
179
|
+
/**
|
|
180
|
+
* Applies one compact service management action.
|
|
181
|
+
*/
|
|
182
|
+
async manageService(args) {
|
|
183
|
+
const serviceId = requireString(args.serviceId, "The 'serviceId' argument must be a string.");
|
|
184
|
+
const action = requireServiceAction(args.action);
|
|
185
|
+
const result = await this.registry.manageService(serviceId, action);
|
|
186
|
+
return successContent({
|
|
187
|
+
serviceId: result.serviceId,
|
|
188
|
+
action: result.action,
|
|
189
|
+
enabled: result.enabled,
|
|
190
|
+
available: result.available
|
|
191
|
+
});
|
|
192
|
+
}
|
|
177
193
|
/**
|
|
178
194
|
* Builds the MCP initialize result advertised by the gateway.
|
|
179
195
|
*/
|
|
@@ -187,7 +203,7 @@ export class GatewayServer {
|
|
|
187
203
|
},
|
|
188
204
|
serverInfo: {
|
|
189
205
|
name: "mcp-gateway",
|
|
190
|
-
version: "0.
|
|
206
|
+
version: "0.3.1"
|
|
191
207
|
}
|
|
192
208
|
};
|
|
193
209
|
}
|
|
@@ -228,6 +244,18 @@ function buildGatewayTools() {
|
|
|
228
244
|
toolName: stringSchema("Downstream tool name.")
|
|
229
245
|
})
|
|
230
246
|
},
|
|
247
|
+
{
|
|
248
|
+
name: "gateway.manageService",
|
|
249
|
+
description: "Reconnects one service or updates its enabled state with a compact action.",
|
|
250
|
+
inputSchema: objectSchema(["serviceId", "action"], {
|
|
251
|
+
serviceId: stringSchema("Logical service identifier."),
|
|
252
|
+
action: {
|
|
253
|
+
type: "string",
|
|
254
|
+
description: "Management action applied to the service.",
|
|
255
|
+
enum: ["reconnect", "enable", "disable"]
|
|
256
|
+
}
|
|
257
|
+
})
|
|
258
|
+
},
|
|
231
259
|
{
|
|
232
260
|
name: "gateway.callTool",
|
|
233
261
|
description: "Calls one downstream tool through the gateway service pool.",
|
|
@@ -304,6 +332,15 @@ function requireString(input, message) {
|
|
|
304
332
|
}
|
|
305
333
|
return input;
|
|
306
334
|
}
|
|
335
|
+
/**
|
|
336
|
+
* Ensures the service management action is supported.
|
|
337
|
+
*/
|
|
338
|
+
function requireServiceAction(input) {
|
|
339
|
+
if (input === "reconnect" || input === "enable" || input === "disable") {
|
|
340
|
+
return input;
|
|
341
|
+
}
|
|
342
|
+
throw new Error("The 'action' argument must be one of 'reconnect', 'enable', or 'disable'.");
|
|
343
|
+
}
|
|
307
344
|
function isJsonRpcRequest(message) {
|
|
308
345
|
return "id" in message && "method" in message && typeof message.method === "string";
|
|
309
346
|
}
|
package/dist/mcp/client.js
CHANGED
|
@@ -310,7 +310,7 @@ export class StdioMcpClient {
|
|
|
310
310
|
},
|
|
311
311
|
clientInfo: {
|
|
312
312
|
name: "mcp-gateway",
|
|
313
|
-
version: "0.
|
|
313
|
+
version: "0.3.1"
|
|
314
314
|
}
|
|
315
315
|
});
|
|
316
316
|
if (isRecord(result)) {
|
|
@@ -441,8 +441,12 @@ function resolveCommandSpec(command, args) {
|
|
|
441
441
|
const powershellResolved = resolveViaPowerShell(command);
|
|
442
442
|
if (powershellResolved) {
|
|
443
443
|
if (powershellResolved.toLowerCase().endsWith(".ps1")) {
|
|
444
|
+
const powerShellHost = resolvePowerShellHost();
|
|
445
|
+
if (!powerShellHost) {
|
|
446
|
+
return { command, args };
|
|
447
|
+
}
|
|
444
448
|
return {
|
|
445
|
-
command:
|
|
449
|
+
command: powerShellHost,
|
|
446
450
|
args: ["-File", powershellResolved, ...args]
|
|
447
451
|
};
|
|
448
452
|
}
|
|
@@ -465,8 +469,12 @@ function resolveCommandSpec(command, args) {
|
|
|
465
469
|
return { command, args };
|
|
466
470
|
}
|
|
467
471
|
if (preferred.toLowerCase().endsWith(".ps1")) {
|
|
472
|
+
const powerShellHost = resolvePowerShellHost();
|
|
473
|
+
if (!powerShellHost) {
|
|
474
|
+
return { command, args };
|
|
475
|
+
}
|
|
468
476
|
return {
|
|
469
|
-
command:
|
|
477
|
+
command: powerShellHost,
|
|
470
478
|
args: ["-File", preferred, ...args]
|
|
471
479
|
};
|
|
472
480
|
}
|
|
@@ -483,8 +491,12 @@ function resolveCommandSpec(command, args) {
|
|
|
483
491
|
* Resolves a command name through PowerShell so script shims map to their real targets.
|
|
484
492
|
*/
|
|
485
493
|
function resolveViaPowerShell(command) {
|
|
494
|
+
const powerShellHost = resolvePowerShellHost();
|
|
495
|
+
if (!powerShellHost) {
|
|
496
|
+
return null;
|
|
497
|
+
}
|
|
486
498
|
try {
|
|
487
|
-
const output = execFileSync(
|
|
499
|
+
const output = execFileSync(powerShellHost, [
|
|
488
500
|
"-NoProfile",
|
|
489
501
|
"-Command",
|
|
490
502
|
`(Get-Command '${escapePowerShellSingleQuotedString(command)}' -ErrorAction Stop).Source`
|
|
@@ -499,12 +511,38 @@ function resolveViaPowerShell(command) {
|
|
|
499
511
|
return null;
|
|
500
512
|
}
|
|
501
513
|
}
|
|
514
|
+
/**
|
|
515
|
+
* Resolves the preferred PowerShell host on Windows.
|
|
516
|
+
*/
|
|
517
|
+
export function resolvePowerShellHost(probe = commandExists) {
|
|
518
|
+
if (probe("pwsh")) {
|
|
519
|
+
return "pwsh";
|
|
520
|
+
}
|
|
521
|
+
if (probe("powershell.exe")) {
|
|
522
|
+
return "powershell.exe";
|
|
523
|
+
}
|
|
524
|
+
return null;
|
|
525
|
+
}
|
|
502
526
|
/**
|
|
503
527
|
* Escapes a string for use inside a single-quoted PowerShell literal.
|
|
504
528
|
*/
|
|
505
529
|
function escapePowerShellSingleQuotedString(value) {
|
|
506
530
|
return value.replace(/'/g, "''");
|
|
507
531
|
}
|
|
532
|
+
/**
|
|
533
|
+
* Checks whether a command exists in the current PATH.
|
|
534
|
+
*/
|
|
535
|
+
function commandExists(command) {
|
|
536
|
+
try {
|
|
537
|
+
execFileSync("where.exe", [command], {
|
|
538
|
+
stdio: ["ignore", "ignore", "ignore"]
|
|
539
|
+
});
|
|
540
|
+
return true;
|
|
541
|
+
}
|
|
542
|
+
catch {
|
|
543
|
+
return false;
|
|
544
|
+
}
|
|
545
|
+
}
|
|
508
546
|
/**
|
|
509
547
|
* Terminates one child process, using process-tree shutdown on Windows when possible.
|
|
510
548
|
*/
|
package/dist/service-registry.js
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { readFile, writeFile } from "node:fs/promises";
|
|
1
2
|
import { resolve } from "node:path";
|
|
2
3
|
import { StdioMcpClient } from "./mcp/client.js";
|
|
3
4
|
/**
|
|
@@ -140,6 +141,21 @@ export class ServiceRegistry {
|
|
|
140
141
|
throw error;
|
|
141
142
|
}
|
|
142
143
|
}
|
|
144
|
+
/**
|
|
145
|
+
* Manages one service runtime or persisted enable flag through a compact action interface.
|
|
146
|
+
*/
|
|
147
|
+
async manageService(serviceId, action) {
|
|
148
|
+
switch (action) {
|
|
149
|
+
case "reconnect":
|
|
150
|
+
return this.reconnectService(serviceId);
|
|
151
|
+
case "enable":
|
|
152
|
+
return this.setServiceEnabled(serviceId, true);
|
|
153
|
+
case "disable":
|
|
154
|
+
return this.setServiceEnabled(serviceId, false);
|
|
155
|
+
default:
|
|
156
|
+
throw new Error(`Unsupported service action '${action}'.`);
|
|
157
|
+
}
|
|
158
|
+
}
|
|
143
159
|
/**
|
|
144
160
|
* Disposes all downstream clients during shutdown.
|
|
145
161
|
*/
|
|
@@ -147,6 +163,74 @@ export class ServiceRegistry {
|
|
|
147
163
|
await disposeClientMap(this.clients);
|
|
148
164
|
this.clients.clear();
|
|
149
165
|
}
|
|
166
|
+
/**
|
|
167
|
+
* Reconnects one currently configured service and refreshes its metadata snapshot.
|
|
168
|
+
*/
|
|
169
|
+
async reconnectService(serviceId) {
|
|
170
|
+
const snapshot = this.requireService(serviceId);
|
|
171
|
+
const currentClient = this.clients.get(serviceId);
|
|
172
|
+
if (!currentClient) {
|
|
173
|
+
throw new Error(`Service '${serviceId}' is unavailable.`);
|
|
174
|
+
}
|
|
175
|
+
const nextClient = new StdioMcpClient(snapshot.config, this.logger);
|
|
176
|
+
try {
|
|
177
|
+
await currentClient.dispose().catch(() => undefined);
|
|
178
|
+
const metadata = await nextClient.getMetadata();
|
|
179
|
+
snapshot.metadata = metadata;
|
|
180
|
+
snapshot.runtime = {
|
|
181
|
+
available: true,
|
|
182
|
+
lastError: null,
|
|
183
|
+
lastConnectedAt: new Date().toISOString(),
|
|
184
|
+
restartAttempts: nextClient.restartCount
|
|
185
|
+
};
|
|
186
|
+
this.clients.set(serviceId, nextClient);
|
|
187
|
+
return {
|
|
188
|
+
serviceId,
|
|
189
|
+
action: "reconnect",
|
|
190
|
+
enabled: true,
|
|
191
|
+
available: true
|
|
192
|
+
};
|
|
193
|
+
}
|
|
194
|
+
catch (error) {
|
|
195
|
+
await nextClient.dispose().catch(() => undefined);
|
|
196
|
+
const message = error instanceof Error ? error.message : String(error);
|
|
197
|
+
snapshot.runtime = {
|
|
198
|
+
available: false,
|
|
199
|
+
lastError: message,
|
|
200
|
+
lastConnectedAt: snapshot.runtime.lastConnectedAt,
|
|
201
|
+
restartAttempts: currentClient.restartCount
|
|
202
|
+
};
|
|
203
|
+
this.clients.set(serviceId, currentClient);
|
|
204
|
+
return {
|
|
205
|
+
serviceId,
|
|
206
|
+
action: "reconnect",
|
|
207
|
+
enabled: true,
|
|
208
|
+
available: false
|
|
209
|
+
};
|
|
210
|
+
}
|
|
211
|
+
}
|
|
212
|
+
/**
|
|
213
|
+
* Persists the service enable flag to the config file and reloads the registry.
|
|
214
|
+
*/
|
|
215
|
+
async setServiceEnabled(serviceId, enabled) {
|
|
216
|
+
const rawConfig = await readRawConfig(this.configPath);
|
|
217
|
+
if (!Array.isArray(rawConfig.services)) {
|
|
218
|
+
throw new Error("The 'services' field must be an array.");
|
|
219
|
+
}
|
|
220
|
+
const service = rawConfig.services.find((candidate) => isRecord(candidate) && candidate.serviceId === serviceId);
|
|
221
|
+
if (!service || !isRecord(service)) {
|
|
222
|
+
throw new Error(`Unknown service '${serviceId}'.`);
|
|
223
|
+
}
|
|
224
|
+
service.enable = enabled;
|
|
225
|
+
await writeFile(resolve(this.configPath), `${JSON.stringify(rawConfig, null, 2)}\n`, "utf8");
|
|
226
|
+
await this.reload();
|
|
227
|
+
return {
|
|
228
|
+
serviceId,
|
|
229
|
+
action: enabled ? "enable" : "disable",
|
|
230
|
+
enabled,
|
|
231
|
+
available: enabled ? (this.getService(serviceId)?.runtime.available ?? false) : false
|
|
232
|
+
};
|
|
233
|
+
}
|
|
150
234
|
/**
|
|
151
235
|
* Builds one runtime snapshot and initializes required metadata.
|
|
152
236
|
*/
|
|
@@ -248,3 +332,20 @@ async function disposeRemovedClients(previous, next) {
|
|
|
248
332
|
}
|
|
249
333
|
await Promise.all(removed.map((client) => client.dispose().catch(() => undefined)));
|
|
250
334
|
}
|
|
335
|
+
/**
|
|
336
|
+
* Loads the raw config document for management edits that must preserve disabled services.
|
|
337
|
+
*/
|
|
338
|
+
async function readRawConfig(configPath) {
|
|
339
|
+
const rawText = await readFile(resolve(configPath), "utf8");
|
|
340
|
+
const parsed = JSON.parse(rawText);
|
|
341
|
+
if (!isRecord(parsed)) {
|
|
342
|
+
throw new Error("The gateway config must be a JSON object.");
|
|
343
|
+
}
|
|
344
|
+
return parsed;
|
|
345
|
+
}
|
|
346
|
+
/**
|
|
347
|
+
* Checks whether a value is a plain record.
|
|
348
|
+
*/
|
|
349
|
+
function isRecord(input) {
|
|
350
|
+
return typeof input === "object" && input !== null && !Array.isArray(input);
|
|
351
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: mcp-gateway
|
|
3
|
-
description: Use the MCP gateway for token-efficient discovery of downstream MCP services, tool lists, tool schemas, and forwarded tool calls. Prefer
|
|
3
|
+
description: Use the MCP gateway for token-efficient discovery of downstream MCP services, tool lists, tool schemas, and forwarded tool calls. Prefer the default four-tool workflow and use detailed service inspection only for explicit diagnosis.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# MCP Gateway
|
|
@@ -23,6 +23,15 @@ Operate downstream MCP services through the gateway's fixed, token-efficient dis
|
|
|
23
23
|
4. Call `gateway.callTool(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
|
+
## Diagnostic Exception
|
|
27
|
+
|
|
28
|
+
- Treat `gateway.getService` as a diagnostic tool, not part of the default workflow.
|
|
29
|
+
- Use it only when the user explicitly asks to inspect service health, connection state, protocol details, or recent service errors.
|
|
30
|
+
- Do not call it during normal task execution when the four-tool flow is sufficient.
|
|
31
|
+
- Treat `gateway.manageService` as an explicit service-control tool, not part of the default workflow.
|
|
32
|
+
- Use `gateway.manageService({ serviceId, action: "reconnect" })` only when the user explicitly wants to retry starting a failed service after its dependency becomes ready.
|
|
33
|
+
- Use `gateway.manageService({ serviceId, action: "enable" | "disable" })` only when the user explicitly wants to persistently change that service's enabled state in the config file.
|
|
34
|
+
|
|
26
35
|
## Response Shape Expectations
|
|
27
36
|
|
|
28
37
|
- `gateway.listServices` returns compact service entries with `serviceId`, `description`, and `available`.
|