@jadchene/mcp-gateway-service 0.3.1 → 0.3.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 +23 -13
- package/README_zh.md +24 -14
- package/config.example.json +9 -5
- package/dist/config.js +33 -3
- package/dist/gateway-server.js +1 -1
- package/dist/logger.js +45 -6
- package/dist/mcp/client.js +1 -1
- package/dist/service-registry.js +8 -1
- package/package.json +1 -1
- package/skills/mcp-gateway/SKILL.md +11 -3
package/README.md
CHANGED
|
@@ -131,22 +131,31 @@ mcp-gateway-service -v
|
|
|
131
131
|
|
|
132
132
|
## Configuration
|
|
133
133
|
|
|
134
|
-
The gateway currently supports `stdio` downstream transports only.
|
|
135
|
-
|
|
136
|
-
A service is loaded only when `enable` is missing or set to `true`. If `enable` is set to `false`, the gateway skips that service entirely. During hot reload, disabling or removing a service also stops its existing downstream process if one is running.
|
|
137
|
-
|
|
138
|
-
- `enable` is optional
|
|
139
|
-
- `
|
|
140
|
-
- `
|
|
141
|
-
- `
|
|
134
|
+
The gateway currently supports `stdio` downstream transports only.
|
|
135
|
+
|
|
136
|
+
A service is loaded only when `enable` is missing or set to `true`. If `enable` is set to `false`, the gateway skips that service entirely. During hot reload, disabling or removing a service also stops its existing downstream process if one is running.
|
|
137
|
+
|
|
138
|
+
- `logging.enable` is optional and defaults to `false`.
|
|
139
|
+
- `logging.path` is required only when `logging.enable` is `true`.
|
|
140
|
+
- When enabled, the gateway writes newline-delimited JSON logs to the configured file and never writes operational logs to MCP `stdout` or `stderr`.
|
|
141
|
+
- Relative `logging.path` values are resolved from the config file directory.
|
|
142
|
+
- Logging config supports hot reload, so changing `logging.enable` or `logging.path` in the config file takes effect without restarting the gateway.
|
|
143
|
+
- `enable` is optional. When omitted, the gateway treats the service as enabled.
|
|
144
|
+
- `cwd` is optional. When omitted, the gateway uses its current working directory.
|
|
145
|
+
- `env` is optional.
|
|
146
|
+
- `framing` is optional. When omitted, the gateway tries `line` first and then `content-length`.
|
|
142
147
|
|
|
143
148
|
### Config shape
|
|
144
149
|
|
|
145
|
-
```json
|
|
146
|
-
{
|
|
147
|
-
"
|
|
148
|
-
|
|
149
|
-
|
|
150
|
+
```json
|
|
151
|
+
{
|
|
152
|
+
"logging": {
|
|
153
|
+
"enable": false,
|
|
154
|
+
"path": "./logs/mcp-gateway.log"
|
|
155
|
+
},
|
|
156
|
+
"services": [
|
|
157
|
+
{
|
|
158
|
+
"serviceId": "demo-echo",
|
|
150
159
|
"enable": true,
|
|
151
160
|
"name": "Demo Echo Service",
|
|
152
161
|
"description": "Sample echo MCP service.",
|
|
@@ -289,6 +298,7 @@ args = ["--config", "./config.json"]
|
|
|
289
298
|
- Repository-managed `config.json` and `config.example.json` are examples only.
|
|
290
299
|
- Copy `config.example.json` to your own local `config.json` before running the gateway.
|
|
291
300
|
- Keep real local configs and logs outside the repository.
|
|
301
|
+
- File logging is disabled by default so MCP startup stays quiet unless you explicitly enable it.
|
|
292
302
|
- Downstream output schema is returned only when the downstream service exposes it.
|
|
293
303
|
- Windows command resolution supports PowerShell shims such as `.ps1`-backed command aliases.
|
|
294
304
|
- On Windows, the gateway prefers `pwsh` for `.ps1` shim resolution and execution, and automatically falls back to `powershell.exe` when `pwsh` is unavailable.
|
package/README_zh.md
CHANGED
|
@@ -137,20 +137,29 @@ mcp-gateway-service -v
|
|
|
137
137
|
|
|
138
138
|
## 配置格式
|
|
139
139
|
|
|
140
|
-
当前只支持 `stdio` 类型的下游传输。
|
|
141
|
-
|
|
142
|
-
只有当 `enable` 未填写或显式为 `true` 时,服务才会被加载;如果 `enable` 为 `false`,网关会跳过该服务。热刷新时,如果某个服务被禁用或从配置中删除,网关也会停掉它当前已启动的下游进程。
|
|
143
|
-
|
|
144
|
-
- `enable`
|
|
145
|
-
- `
|
|
146
|
-
- `
|
|
147
|
-
- `
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
140
|
+
当前只支持 `stdio` 类型的下游传输。
|
|
141
|
+
|
|
142
|
+
只有当 `enable` 未填写或显式为 `true` 时,服务才会被加载;如果 `enable` 为 `false`,网关会跳过该服务。热刷新时,如果某个服务被禁用或从配置中删除,网关也会停掉它当前已启动的下游进程。
|
|
143
|
+
|
|
144
|
+
- `logging.enable` 可选,默认是 `false`
|
|
145
|
+
- 只有当 `logging.enable` 为 `true` 时,`logging.path` 才是必填
|
|
146
|
+
- 启用后,网关会把换行分隔的 JSON 日志写入指定文件,不再把运行日志写到 MCP 的 `stdout` 或 `stderr`
|
|
147
|
+
- 相对 `logging.path` 会按配置文件所在目录解析
|
|
148
|
+
- 日志配置支持热更新,直接修改 `logging.enable` 或 `logging.path` 并保存即可生效,无需重启网关
|
|
149
|
+
- `enable` 可选,不填时默认按启用处理
|
|
150
|
+
- `cwd` 可选,不填时使用当前工作目录
|
|
151
|
+
- `env` 可选
|
|
152
|
+
- `framing` 可选,不填时先尝试 `line`,再尝试 `content-length`
|
|
153
|
+
|
|
154
|
+
```json
|
|
155
|
+
{
|
|
156
|
+
"logging": {
|
|
157
|
+
"enable": false,
|
|
158
|
+
"path": "./logs/mcp-gateway.log"
|
|
159
|
+
},
|
|
160
|
+
"services": [
|
|
161
|
+
{
|
|
162
|
+
"serviceId": "demo-echo",
|
|
154
163
|
"enable": true,
|
|
155
164
|
"name": "Demo Echo Service",
|
|
156
165
|
"description": "Sample echo MCP service.",
|
|
@@ -291,6 +300,7 @@ args = ["--config", "./config.json"]
|
|
|
291
300
|
- 仓库只保留 `config.example.json` 作为示例
|
|
292
301
|
- 运行前请自行复制一份本地 `config.json`
|
|
293
302
|
- 真实本地配置和日志建议放在仓库外
|
|
303
|
+
- 默认关闭文件日志,避免 MCP 启动阶段产生额外标准流输出
|
|
294
304
|
- 只有下游服务自己暴露了 `outputSchema` 时,网关才会返回它
|
|
295
305
|
- Windows 下支持解析 PowerShell shim 命令,例如实际落到 `.ps1` 的全局命令
|
|
296
306
|
- 在 Windows 上,网关会优先使用 `pwsh` 解析和执行 `.ps1` shim;如果机器上没有 `pwsh`,会自动回退到 `powershell.exe`
|
package/config.example.json
CHANGED
|
@@ -1,7 +1,11 @@
|
|
|
1
|
-
{
|
|
2
|
-
"
|
|
3
|
-
|
|
4
|
-
|
|
1
|
+
{
|
|
2
|
+
"logging": {
|
|
3
|
+
"enable": false,
|
|
4
|
+
"path": "./logs/mcp-gateway.log"
|
|
5
|
+
},
|
|
6
|
+
"services": [
|
|
7
|
+
{
|
|
8
|
+
"serviceId": "demo-echo",
|
|
5
9
|
"enable": true,
|
|
6
10
|
"name": "Demo Echo Service",
|
|
7
11
|
"description": "Sample echo MCP service.",
|
|
@@ -15,4 +19,4 @@
|
|
|
15
19
|
}
|
|
16
20
|
}
|
|
17
21
|
]
|
|
18
|
-
}
|
|
22
|
+
}
|
package/dist/config.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { readFile } from "node:fs/promises";
|
|
2
|
-
import { resolve } from "node:path";
|
|
2
|
+
import { dirname, resolve } from "node:path";
|
|
3
3
|
/**
|
|
4
4
|
* Provides config loading and validation for the gateway service pool definition.
|
|
5
5
|
*/
|
|
@@ -11,13 +11,13 @@ export class ConfigLoader {
|
|
|
11
11
|
const absolutePath = resolve(configPath);
|
|
12
12
|
const rawText = await readFile(absolutePath, "utf8");
|
|
13
13
|
const parsed = JSON.parse(rawText);
|
|
14
|
-
return validateGatewayConfig(parsed);
|
|
14
|
+
return validateGatewayConfig(parsed, dirname(absolutePath));
|
|
15
15
|
}
|
|
16
16
|
}
|
|
17
17
|
/**
|
|
18
18
|
* Validates the top-level config object and normalizes optional fields.
|
|
19
19
|
*/
|
|
20
|
-
export function validateGatewayConfig(input) {
|
|
20
|
+
export function validateGatewayConfig(input, baseDir = process.cwd()) {
|
|
21
21
|
if (!isRecord(input)) {
|
|
22
22
|
throw new Error("The gateway config must be a JSON object.");
|
|
23
23
|
}
|
|
@@ -33,9 +33,39 @@ export function validateGatewayConfig(input) {
|
|
|
33
33
|
seenServiceIds.add(service.serviceId);
|
|
34
34
|
}
|
|
35
35
|
return {
|
|
36
|
+
logging: validateLoggingConfig(input.logging, baseDir),
|
|
36
37
|
services: services.filter((service) => service.enable)
|
|
37
38
|
};
|
|
38
39
|
}
|
|
40
|
+
/**
|
|
41
|
+
* Validates the optional logging config and resolves the log path.
|
|
42
|
+
*/
|
|
43
|
+
function validateLoggingConfig(input, baseDir) {
|
|
44
|
+
if (input === undefined) {
|
|
45
|
+
return {
|
|
46
|
+
enable: false,
|
|
47
|
+
path: null
|
|
48
|
+
};
|
|
49
|
+
}
|
|
50
|
+
if (!isRecord(input)) {
|
|
51
|
+
throw new Error("The 'logging' field must be a JSON object when present.");
|
|
52
|
+
}
|
|
53
|
+
const enable = optionalBoolean(input.enable, "logging.enable") ?? false;
|
|
54
|
+
const path = optionalString(input.path, "logging.path");
|
|
55
|
+
if (!enable) {
|
|
56
|
+
return {
|
|
57
|
+
enable: false,
|
|
58
|
+
path: path ? resolve(baseDir, path) : null
|
|
59
|
+
};
|
|
60
|
+
}
|
|
61
|
+
if (!path || path.trim() === "") {
|
|
62
|
+
throw new Error("The 'logging.path' field must be a non-empty string when logging is enabled.");
|
|
63
|
+
}
|
|
64
|
+
return {
|
|
65
|
+
enable: true,
|
|
66
|
+
path: resolve(baseDir, path)
|
|
67
|
+
};
|
|
68
|
+
}
|
|
39
69
|
/**
|
|
40
70
|
* Validates one logical service definition.
|
|
41
71
|
*/
|
package/dist/gateway-server.js
CHANGED
package/dist/logger.js
CHANGED
|
@@ -1,35 +1,74 @@
|
|
|
1
|
+
import { mkdirSync, appendFileSync } from "node:fs";
|
|
2
|
+
import { dirname, resolve } from "node:path";
|
|
1
3
|
/**
|
|
2
|
-
* Provides a minimal structured logger that
|
|
4
|
+
* Provides a minimal structured logger that appends newline-delimited JSON to a file.
|
|
3
5
|
*/
|
|
4
6
|
export class Logger {
|
|
5
7
|
/**
|
|
6
|
-
*
|
|
8
|
+
* Stores the current effective logging config.
|
|
9
|
+
*/
|
|
10
|
+
config = {
|
|
11
|
+
enable: false,
|
|
12
|
+
path: null
|
|
13
|
+
};
|
|
14
|
+
/**
|
|
15
|
+
* Updates the effective logging config at runtime.
|
|
16
|
+
*/
|
|
17
|
+
configure(config) {
|
|
18
|
+
this.config = {
|
|
19
|
+
enable: config.enable,
|
|
20
|
+
path: config.path ? resolve(config.path) : null
|
|
21
|
+
};
|
|
22
|
+
if (!this.config.enable || !this.config.path) {
|
|
23
|
+
return;
|
|
24
|
+
}
|
|
25
|
+
try {
|
|
26
|
+
mkdirSync(dirname(this.config.path), { recursive: true });
|
|
27
|
+
}
|
|
28
|
+
catch {
|
|
29
|
+
/**
|
|
30
|
+
* Ignores directory creation failures so logging never blocks MCP traffic.
|
|
31
|
+
*/
|
|
32
|
+
}
|
|
33
|
+
}
|
|
34
|
+
/**
|
|
35
|
+
* Logs one structured info event.
|
|
7
36
|
*/
|
|
8
37
|
info(event, details = {}) {
|
|
9
38
|
this.write("info", event, details);
|
|
10
39
|
}
|
|
11
40
|
/**
|
|
12
|
-
* Logs one warning event.
|
|
41
|
+
* Logs one structured warning event.
|
|
13
42
|
*/
|
|
14
43
|
warn(event, details = {}) {
|
|
15
44
|
this.write("warn", event, details);
|
|
16
45
|
}
|
|
17
46
|
/**
|
|
18
|
-
* Logs one error event.
|
|
47
|
+
* Logs one structured error event.
|
|
19
48
|
*/
|
|
20
49
|
error(event, details = {}) {
|
|
21
50
|
this.write("error", event, details);
|
|
22
51
|
}
|
|
23
52
|
/**
|
|
24
|
-
* Serializes
|
|
53
|
+
* Serializes one log entry to the configured file without touching MCP stdio streams.
|
|
25
54
|
*/
|
|
26
55
|
write(level, event, details) {
|
|
56
|
+
if (!this.config.enable || !this.config.path) {
|
|
57
|
+
return;
|
|
58
|
+
}
|
|
27
59
|
const payload = {
|
|
28
60
|
timestamp: new Date().toISOString(),
|
|
29
61
|
level,
|
|
30
62
|
event,
|
|
31
63
|
...details
|
|
32
64
|
};
|
|
33
|
-
|
|
65
|
+
try {
|
|
66
|
+
appendFileSync(this.config.path, `${JSON.stringify(payload)}\n`, "utf8");
|
|
67
|
+
}
|
|
68
|
+
catch {
|
|
69
|
+
/**
|
|
70
|
+
* Ignores append failures so the gateway stays usable even if logging breaks.
|
|
71
|
+
*/
|
|
72
|
+
}
|
|
34
73
|
}
|
|
35
74
|
}
|
package/dist/mcp/client.js
CHANGED
package/dist/service-registry.js
CHANGED
|
@@ -20,7 +20,13 @@ export class ServiceRegistry {
|
|
|
20
20
|
/**
|
|
21
21
|
* Stores the last valid config snapshot.
|
|
22
22
|
*/
|
|
23
|
-
currentConfig = {
|
|
23
|
+
currentConfig = {
|
|
24
|
+
logging: {
|
|
25
|
+
enable: false,
|
|
26
|
+
path: null
|
|
27
|
+
},
|
|
28
|
+
services: []
|
|
29
|
+
};
|
|
24
30
|
/**
|
|
25
31
|
* Stores the current immutable runtime view used by request handlers.
|
|
26
32
|
*/
|
|
@@ -55,6 +61,7 @@ export class ServiceRegistry {
|
|
|
55
61
|
const absolutePath = resolve(this.configPath);
|
|
56
62
|
this.logger.info("config.reload.started", { configPath: absolutePath });
|
|
57
63
|
const nextConfig = await this.configLoader.load(absolutePath);
|
|
64
|
+
this.logger.configure(nextConfig.logging);
|
|
58
65
|
const nextSnapshots = new Map();
|
|
59
66
|
const nextClients = new Map();
|
|
60
67
|
try {
|
package/package.json
CHANGED
|
@@ -11,7 +11,7 @@ Operate downstream MCP services through the gateway's fixed, token-efficient dis
|
|
|
11
11
|
|
|
12
12
|
- **Discovery First**: Never guess a `serviceId` or downstream `toolName`. Discover them through the gateway.
|
|
13
13
|
- **Token Efficiency**: Do not enumerate every service and every tool unless the task genuinely needs it.
|
|
14
|
-
- **Schema Before
|
|
14
|
+
- **Schema Before Unclear Arguments**: If the tool arguments are not fully certain, fetch the schema before calling the tool. Do not guess argument names, shapes, or confirmation fields.
|
|
15
15
|
- **Cache Mentally Per Session**: Reuse known service lists, tool lists, and schemas within the current session instead of asking again without reason.
|
|
16
16
|
- **Compression Recovery Gate**: After any context compression event, re-read `AGENTS.md` and this `SKILL.md` before continuing.
|
|
17
17
|
|
|
@@ -19,7 +19,7 @@ Operate downstream MCP services through the gateway's fixed, token-efficient dis
|
|
|
19
19
|
|
|
20
20
|
1. Call `gateway.listServices` once to find the right downstream service.
|
|
21
21
|
2. Call `gateway.listTools(serviceId)` only for the selected service.
|
|
22
|
-
3. Call `gateway.getToolSchema(serviceId, toolName)`
|
|
22
|
+
3. Call `gateway.getToolSchema(serviceId, toolName)` before the first use of that tool, or any time the arguments are not fully certain.
|
|
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
|
|
|
@@ -32,6 +32,12 @@ Operate downstream MCP services through the gateway's fixed, token-efficient dis
|
|
|
32
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
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
34
|
|
|
35
|
+
## Strict Argument Rule
|
|
36
|
+
|
|
37
|
+
- If a tool has any non-trivial arguments, optional flags, confirmation fields, enum values, or write-safety fields, call `gateway.getToolSchema` before execution unless the exact argument contract is already confirmed in the current session.
|
|
38
|
+
- Do not rely on tool descriptions alone when the argument shape could affect correctness or safety.
|
|
39
|
+
- This is especially important for write tools, confirmation-based tools, and tools with nested argument objects.
|
|
40
|
+
|
|
35
41
|
## Response Shape Expectations
|
|
36
42
|
|
|
37
43
|
- `gateway.listServices` returns compact service entries with `serviceId`, `description`, and `available`.
|
|
@@ -55,7 +61,7 @@ Operate downstream MCP services through the gateway's fixed, token-efficient dis
|
|
|
55
61
|
- `gateway.getToolSchema({ serviceId: "selected-service", toolName: "selected-tool" })`
|
|
56
62
|
- `gateway.callTool({ serviceId: "selected-service", toolName: "selected-tool", arguments: {...} })`
|
|
57
63
|
|
|
58
|
-
- Need to inspect an unfamiliar tool before first use:
|
|
64
|
+
- Need to inspect an unfamiliar tool before first use, or any tool whose arguments are not fully certain:
|
|
59
65
|
- `gateway.getToolSchema({ serviceId: "selected-service", toolName: "selected-tool" })`
|
|
60
66
|
- build arguments strictly from `inputSchema`
|
|
61
67
|
- call the tool only after the schema is understood
|
|
@@ -64,6 +70,7 @@ Operate downstream MCP services through the gateway's fixed, token-efficient dis
|
|
|
64
70
|
|
|
65
71
|
- **Never** flatten all downstream tools into your own notes unless the task explicitly needs a full inventory.
|
|
66
72
|
- **Never** invent arguments for a tool when the schema can be queried cheaply.
|
|
73
|
+
- **Never** skip `gateway.getToolSchema` when argument names or fields are unclear.
|
|
67
74
|
- **Never** assume a service is available without checking recent gateway discovery results when availability matters.
|
|
68
75
|
|
|
69
76
|
## Practical Guidance
|
|
@@ -71,3 +78,4 @@ Operate downstream MCP services through the gateway's fixed, token-efficient dis
|
|
|
71
78
|
- Choose `serviceId` by task domain and service description instead of assuming a fixed service naming scheme.
|
|
72
79
|
- Prefer the smallest discovery step that can answer the question.
|
|
73
80
|
- If a downstream tool fails with a validation error, fetch or re-check its schema before retrying.
|
|
81
|
+
- If there is any doubt about required parameters, confirmation tokens, or argument structure, fetch the schema first instead of guessing.
|