@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
package/README_zh.md
CHANGED
|
@@ -2,85 +2,50 @@
|
|
|
2
2
|
|
|
3
3
|
# MCP Gateway
|
|
4
4
|
|
|
5
|
-
MCP Gateway
|
|
5
|
+
MCP Gateway 是一个节省 token 的 Model Context Protocol 网关。它不把所有下游工具展开到每个客户端的启动上下文,而是通过 6 个稳定工具完成发现、管理和转发。
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
MCP Gateway v0.6.0 使用官方 TypeScript SDK v2。
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
> [!IMPORTANT]
|
|
10
|
+
> v0.6.0 及后续版本仅支持 MCP `2026-07-28` 和 `2025-06-18`,传输方式仅支持标准换行分隔 stdio 和单端点 Streamable HTTP。已移除对更早协议版本、独立 HTTP+SSE(`/sse`)和 `Content-Length` framing 的兼容支持。
|
|
10
11
|
|
|
11
|
-
|
|
12
|
-
- 通过固定的小型网关工具面实现按需发现,减少初始 token 消耗。
|
|
13
|
-
- 支持 stdio 和 Streamable HTTP 下游传输。
|
|
14
|
-
- 可通过 CLI 参数启用入站 Streamable HTTP。
|
|
15
|
-
- 支持服务池配置热刷新。
|
|
16
|
-
- 热刷新时会停止已删除、已禁用或配置被替换的下游服务。
|
|
17
|
-
- 下游进程失败后最多自动重启 3 次,然后标记为不可用。
|
|
18
|
-
- 配置刷新是原子的,新配置无效时保留上一份有效配置。
|
|
19
|
-
- 支持可选的换行 JSON 文件日志,不把运行日志写入 MCP stdout。
|
|
20
|
-
- 支持通过 `--version` 或 `-v` 查看版本。
|
|
12
|
+
## 能力
|
|
21
13
|
|
|
22
|
-
|
|
14
|
+
- 上游同时支持 stdio 和无状态 Streamable HTTP。
|
|
15
|
+
- 下游支持标准 stdio 和 Streamable HTTP。
|
|
16
|
+
- 在 MCP `2026-07-28` 与 `2025-06-18` 之间自动协商。
|
|
17
|
+
- 入站传输自动服务这两个标准版本。
|
|
18
|
+
- 完整转发下游工具元数据和 JSON Schema 2020-12。
|
|
19
|
+
- 由 SDK 处理 MRTR elicitation、opaque `requestState`、任意 JSON `structuredContent`、取消传播和 `x-mcp-header`。
|
|
20
|
+
- 遵守 SDK 缓存提示,private 缓存按客户端实例隔离。
|
|
21
|
+
- 支持配置热更新、生命周期恢复、无效配置原子拒绝和可选文件日志。
|
|
22
|
+
- 入站 HTTP 校验 Host 和 Origin;运行日志不会写入 MCP stdout。
|
|
23
23
|
|
|
24
|
-
|
|
25
|
-
- 减少初始工具上下文:Agent 只发现当前任务需要的服务、工具和 schema。
|
|
26
|
-
- 集中管理服务生命周期,避免在多个客户端中重复维护命令路径、环境变量和密钥。
|
|
24
|
+
## 环境与安装
|
|
27
25
|
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
全局安装:
|
|
26
|
+
- Node.js 24 或更高版本。
|
|
31
27
|
|
|
32
28
|
```bash
|
|
33
29
|
npm install -g @jadchene/mcp-gateway-service
|
|
34
|
-
```
|
|
35
|
-
|
|
36
|
-
创建本地配置:
|
|
37
|
-
|
|
38
|
-
```bash
|
|
39
30
|
cp config.example.json config.json
|
|
40
|
-
```
|
|
41
|
-
|
|
42
|
-
启动 stdio 网关:
|
|
43
|
-
|
|
44
|
-
```bash
|
|
45
31
|
mcp-gateway-service --config ./config.json
|
|
46
32
|
```
|
|
47
33
|
|
|
48
|
-
|
|
34
|
+
额外启用入站 HTTP:
|
|
49
35
|
|
|
50
36
|
```bash
|
|
51
37
|
mcp-gateway-service --config ./config.json --http --host 127.0.0.1 --port 3100 --path /mcp
|
|
52
38
|
```
|
|
53
39
|
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
```bash
|
|
57
|
-
mcp-gateway-service --config ./config.json --http --port 3100 --path /mcp --json-response
|
|
58
|
-
```
|
|
59
|
-
|
|
60
|
-
查看安装版本:
|
|
61
|
-
|
|
62
|
-
```bash
|
|
63
|
-
mcp-gateway-service --version
|
|
64
|
-
mcp-gateway-service -v
|
|
65
|
-
```
|
|
66
|
-
|
|
67
|
-
## 配置
|
|
68
|
-
|
|
69
|
-
通过 CLI 参数指定配置文件:
|
|
70
|
-
|
|
71
|
-
```bash
|
|
72
|
-
mcp-gateway-service --config ./config.json
|
|
73
|
-
```
|
|
40
|
+
启用 HTTP 时,进程同时提供 stdio 和 HTTP 入口。使用 `--version` 或 `-v` 查看版本。
|
|
74
41
|
|
|
75
|
-
|
|
42
|
+
## 协议协商
|
|
76
43
|
|
|
77
|
-
|
|
78
|
-
MCP_GATEWAY_CONFIG=./config.json mcp-gateway-service
|
|
79
|
-
```
|
|
44
|
+
协议选择完全自动:网关及其下游客户端优先协商 MCP `2026-07-28`,对端仅支持 `2025-06-18` 时使用该标准版本。只接受这两个协议版本。`--json-response` 只选择标准入站 Streamable HTTP 的响应形态,不会创建协议 session。
|
|
80
45
|
|
|
81
|
-
|
|
46
|
+
## 服务配置
|
|
82
47
|
|
|
83
|
-
|
|
48
|
+
可通过 `--config`、`MCP_GATEWAY_CONFIG` 或当前目录的 `config.json` 指定配置。
|
|
84
49
|
|
|
85
50
|
```json
|
|
86
51
|
{
|
|
@@ -90,101 +55,71 @@ MCP_GATEWAY_CONFIG=./config.json mcp-gateway-service
|
|
|
90
55
|
},
|
|
91
56
|
"services": [
|
|
92
57
|
{
|
|
93
|
-
"serviceId": "
|
|
58
|
+
"serviceId": "local-tools",
|
|
94
59
|
"enable": true,
|
|
95
|
-
"name": "
|
|
96
|
-
"description": "Sample echo MCP service.",
|
|
60
|
+
"name": "Local Tools",
|
|
97
61
|
"transport": {
|
|
98
62
|
"type": "stdio",
|
|
99
63
|
"command": "node",
|
|
100
|
-
"args": [
|
|
101
|
-
"--experimental-strip-types",
|
|
102
|
-
"examples/echo-service.ts"
|
|
103
|
-
]
|
|
64
|
+
"args": ["./server.js"]
|
|
104
65
|
}
|
|
105
66
|
},
|
|
106
67
|
{
|
|
107
|
-
"serviceId": "remote-
|
|
108
|
-
"enable":
|
|
109
|
-
"name": "Remote
|
|
110
|
-
"description": "Example downstream MCP service over Streamable HTTP.",
|
|
68
|
+
"serviceId": "remote-tools",
|
|
69
|
+
"enable": true,
|
|
70
|
+
"name": "Remote Tools",
|
|
111
71
|
"transport": {
|
|
112
72
|
"type": "http",
|
|
113
73
|
"url": "http://127.0.0.1:3200/mcp",
|
|
114
74
|
"headers": {
|
|
115
|
-
"Authorization": "Bearer
|
|
116
|
-
}
|
|
117
|
-
"enableJsonResponse": false
|
|
75
|
+
"Authorization": "Bearer example-token"
|
|
76
|
+
}
|
|
118
77
|
}
|
|
119
78
|
}
|
|
120
79
|
]
|
|
121
80
|
}
|
|
122
81
|
```
|
|
123
82
|
|
|
124
|
-
|
|
83
|
+
配置要点:
|
|
125
84
|
|
|
126
|
-
- `
|
|
127
|
-
-
|
|
128
|
-
-
|
|
129
|
-
-
|
|
130
|
-
-
|
|
131
|
-
-
|
|
132
|
-
- HTTP 下游服务使用 `transport.type: "http"` 和 `transport.url`。
|
|
133
|
-
- HTTP `transport.headers` 用于提供静态请求头。
|
|
134
|
-
- HTTP `transport.enableJsonResponse` 为该下游服务启用无状态 JSON 直返模式。
|
|
85
|
+
- `enable` 默认为 `true`。
|
|
86
|
+
- `logging.enable` 默认为 `false`;相对日志路径按配置文件所在目录解析。
|
|
87
|
+
- stdio 始终使用标准的换行分隔 JSON-RPC 传输。
|
|
88
|
+
- HTTP 始终使用标准的单端点 Streamable HTTP 传输。
|
|
89
|
+
- 协议版本自动协商,不提供手动切换配置。
|
|
90
|
+
- 支持静态 HTTP 请求头;请求头值和环境变量密钥不会写入日志。
|
|
135
91
|
|
|
136
92
|
## 入站 Streamable HTTP
|
|
137
93
|
|
|
138
|
-
|
|
94
|
+
MCP `2026-07-28` HTTP 是无状态的:每个请求都是独立的 `POST /mcp`。网关不创建 `Mcp-Session-Id`,`GET` 和 `DELETE` 返回 `405`。标准版本头、方法头、名称头、每请求 metadata 和协议错误由 SDK 校验。
|
|
139
95
|
|
|
140
|
-
|
|
96
|
+
同一 endpoint 通过标准无状态 Streamable HTTP 服务 MCP `2025-06-18`。作为下游客户端,如果 `2025-06-18` 服务端签发 `Mcp-Session-Id`,网关会按标准维持该 session。
|
|
141
97
|
|
|
142
|
-
|
|
143
|
-
- `POST /mcp` 发送 JSON-RPC 消息。新客户端应通过 `Mcp-Session-Id` 请求头绑定 session。
|
|
144
|
-
- 为兼容旧客户端,仍接受 query string 中的 `sessionId`。
|
|
145
|
-
- `endpoint` SSE 事件只返回统一路径,例如 `/mcp`。
|
|
98
|
+
默认只绑定 `127.0.0.1`。Host 和 Origin 校验用于防护 DNS rebinding;没有额外认证层时,不应把端口暴露到不可信网络。
|
|
146
99
|
|
|
147
100
|
## 网关工具
|
|
148
101
|
|
|
149
|
-
网关暴露 6 个公开工具:
|
|
150
|
-
|
|
151
102
|
| 工具 | 用途 |
|
|
152
103
|
| --- | --- |
|
|
153
|
-
| `gateway_list_services` |
|
|
154
|
-
| `gateway_get_service` |
|
|
155
|
-
| `gateway_list_tools` |
|
|
156
|
-
| `gateway_get_tool_schema` |
|
|
157
|
-
| `gateway_manage_service` |
|
|
158
|
-
| `gateway_call_tool` |
|
|
159
|
-
|
|
160
|
-
默认的节省 token 流程:
|
|
161
|
-
|
|
162
|
-
1. 调用一次 `gateway_list_services`。
|
|
163
|
-
2. 真正需要某个服务时,再调用 `gateway_list_tools(serviceId)`。工具很多时可用 `toolName` 按名称过滤。
|
|
164
|
-
3. 所有筛选结果都需要 schema 时,传入 `includeSchema: true`;已知准确工具名时,调用 `gateway_get_tool_schema` 并传入单个名称或名称数组。
|
|
165
|
-
4. 调用 `gateway_call_tool` 执行下游工具。
|
|
166
|
-
5. 只有诊断时才使用 `gateway_get_service`。
|
|
167
|
-
6. 只有需要重连、启用或禁用服务时才使用 `gateway_manage_service`。
|
|
168
|
-
|
|
169
|
-
`gateway_get_tool_schema` 的 `toolName` 接受字符串或非空字符串数组,返回的 `schemas` 对象以每个请求的工具名为 key。
|
|
104
|
+
| `gateway_list_services` | 列出下游服务和可用状态。 |
|
|
105
|
+
| `gateway_get_service` | 查看服务状态、协议版本和服务端身份。 |
|
|
106
|
+
| `gateway_list_tools` | 按名称或描述搜索工具,可选返回 schema。 |
|
|
107
|
+
| `gateway_get_tool_schema` | 批量获取准确、区分大小写的工具 schema。 |
|
|
108
|
+
| `gateway_manage_service` | 重连,或持久化启用/禁用一个服务。 |
|
|
109
|
+
| `gateway_call_tool` | 调用一个下游工具并原样转发其 MCP 结果。 |
|
|
170
110
|
|
|
171
|
-
|
|
111
|
+
推荐流程:
|
|
172
112
|
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
113
|
+
1. 调用 `gateway_list_services`。
|
|
114
|
+
2. 只对相关服务调用 `gateway_list_tools`,使用 `toolName` 和/或 `desc` 缩小范围。
|
|
115
|
+
3. 复用 `includeSchema: true` 返回的 schema;已知准确名称时用 `gateway_get_tool_schema` 一次批量查询。
|
|
116
|
+
4. 使用 `gateway_call_tool` 调用;`arguments` 始终必填,无参数工具传 `{}`。
|
|
176
117
|
|
|
177
|
-
|
|
118
|
+
`gateway_call_tool` 不声明固定输出 schema,因为下游 `structuredContent` 可以是任意 JSON。modern MRTR 的 `input_required` 不会被自动同意;上游必须声明所需能力,并使用 `inputResponses` 和 opaque `requestState` 重试。
|
|
178
119
|
|
|
179
|
-
|
|
120
|
+
## 客户端示例
|
|
180
121
|
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
当你的 Agent 支持 skills 时建议加载它。它会保持按需发现、节省 token,并通过最小网关契约转发下游调用。
|
|
184
|
-
|
|
185
|
-
## MCP 客户端配置
|
|
186
|
-
|
|
187
|
-
Codex:
|
|
122
|
+
stdio(Codex 风格 TOML):
|
|
188
123
|
|
|
189
124
|
```toml
|
|
190
125
|
[mcp_servers.gateway]
|
|
@@ -192,97 +127,22 @@ command = "mcp-gateway-service"
|
|
|
192
127
|
args = ["--config", "./config.json"]
|
|
193
128
|
```
|
|
194
129
|
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
```json
|
|
198
|
-
{
|
|
199
|
-
"mcpServers": {
|
|
200
|
-
"gateway": {
|
|
201
|
-
"type": "stdio",
|
|
202
|
-
"command": "mcp-gateway-service",
|
|
203
|
-
"args": ["--config", "./config.json"]
|
|
204
|
-
}
|
|
205
|
-
}
|
|
206
|
-
}
|
|
207
|
-
```
|
|
208
|
-
|
|
209
|
-
Claude Code:
|
|
210
|
-
|
|
211
|
-
```json
|
|
212
|
-
{
|
|
213
|
-
"mcpServers": {
|
|
214
|
-
"gateway": {
|
|
215
|
-
"type": "stdio",
|
|
216
|
-
"command": "mcp-gateway-service",
|
|
217
|
-
"args": ["--config", "./config.json"]
|
|
218
|
-
}
|
|
219
|
-
}
|
|
220
|
-
}
|
|
221
|
-
```
|
|
222
|
-
|
|
223
|
-
Streamable HTTP 模式:
|
|
224
|
-
|
|
225
|
-
先启动一个共享 HTTP 网关进程:
|
|
226
|
-
|
|
227
|
-
```bash
|
|
228
|
-
mcp-gateway-service --config ./config.json --http --host 127.0.0.1 --port 3100 --path /mcp
|
|
229
|
-
```
|
|
230
|
-
|
|
231
|
-
然后让 MCP 客户端连接这个 HTTP endpoint。
|
|
232
|
-
|
|
233
|
-
Codex:
|
|
130
|
+
Streamable HTTP:
|
|
234
131
|
|
|
235
132
|
```toml
|
|
236
133
|
[mcp_servers.gateway]
|
|
237
134
|
url = "http://127.0.0.1:3100/mcp"
|
|
238
135
|
```
|
|
239
136
|
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
```json
|
|
243
|
-
{
|
|
244
|
-
"mcpServers": {
|
|
245
|
-
"gateway": {
|
|
246
|
-
"httpUrl": "http://127.0.0.1:3100/mcp"
|
|
247
|
-
}
|
|
248
|
-
}
|
|
249
|
-
}
|
|
250
|
-
```
|
|
251
|
-
|
|
252
|
-
Claude Code:
|
|
253
|
-
|
|
254
|
-
```json
|
|
255
|
-
{
|
|
256
|
-
"mcpServers": {
|
|
257
|
-
"gateway": {
|
|
258
|
-
"type": "http",
|
|
259
|
-
"url": "http://127.0.0.1:3100/mcp"
|
|
260
|
-
}
|
|
261
|
-
}
|
|
262
|
-
}
|
|
263
|
-
```
|
|
264
|
-
|
|
265
|
-
需要共享同一个网关服务池的客户端都使用同一个 URL。只有当 HTTP 客户端希望 `POST` 直接返回无状态 JSON-RPC 响应时,才需要在启动网关时加 `--json-response`。
|
|
266
|
-
|
|
267
|
-
## 开发
|
|
137
|
+
## 开发与验证
|
|
268
138
|
|
|
269
139
|
```bash
|
|
270
140
|
npm install
|
|
271
|
-
npm run
|
|
141
|
+
npm run verify
|
|
142
|
+
node dist/index.js --config ./config.json --version
|
|
272
143
|
```
|
|
273
144
|
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
```bash
|
|
277
|
-
npm run build
|
|
278
|
-
npm test
|
|
279
|
-
```
|
|
280
|
-
|
|
281
|
-
运行构建后的服务:
|
|
282
|
-
|
|
283
|
-
```bash
|
|
284
|
-
node dist/index.js --config ./config.json
|
|
285
|
-
```
|
|
145
|
+
仓库还包含公开 Skill:`skills/mcp-gateway/SKILL.md`。
|
|
286
146
|
|
|
287
147
|
## License
|
|
288
148
|
|
package/config.example.json
CHANGED
|
@@ -6,15 +6,15 @@
|
|
|
6
6
|
"services": [
|
|
7
7
|
{
|
|
8
8
|
"serviceId": "demo-echo",
|
|
9
|
-
"enable":
|
|
9
|
+
"enable": false,
|
|
10
10
|
"name": "Demo Echo Service",
|
|
11
11
|
"description": "Sample echo MCP service.",
|
|
12
12
|
"transport": {
|
|
13
13
|
"type": "stdio",
|
|
14
14
|
"command": "node",
|
|
15
|
-
"args": [
|
|
16
|
-
"--experimental-strip-types",
|
|
17
|
-
"examples/echo-service.ts"
|
|
15
|
+
"args": [
|
|
16
|
+
"--experimental-strip-types",
|
|
17
|
+
"examples/echo-service.ts"
|
|
18
18
|
]
|
|
19
19
|
}
|
|
20
20
|
},
|
|
@@ -28,8 +28,7 @@
|
|
|
28
28
|
"url": "http://127.0.0.1:3200/mcp",
|
|
29
29
|
"headers": {
|
|
30
30
|
"Authorization": "Bearer example-token"
|
|
31
|
-
}
|
|
32
|
-
"enableJsonResponse": false
|
|
31
|
+
}
|
|
33
32
|
}
|
|
34
33
|
}
|
|
35
34
|
]
|
package/dist/config.js
CHANGED
|
@@ -103,14 +103,18 @@ function validateTransportConfig(serviceId, input) {
|
|
|
103
103
|
const args = optionalStringArray(input.args, `service '${serviceId}' transport.args`);
|
|
104
104
|
const cwd = optionalString(input.cwd, `service '${serviceId}' transport.cwd`);
|
|
105
105
|
const env = optionalStringRecord(input.env, `service '${serviceId}' transport.env`);
|
|
106
|
-
|
|
106
|
+
if (input.protocolMode !== undefined) {
|
|
107
|
+
throw new Error(`Service '${serviceId}' transport.protocolMode is no longer supported; protocol negotiation is automatic.`);
|
|
108
|
+
}
|
|
109
|
+
if (input.framing !== undefined) {
|
|
110
|
+
throw new Error(`Service '${serviceId}' transport.framing is no longer supported; stdio always uses newline-delimited JSON-RPC.`);
|
|
111
|
+
}
|
|
107
112
|
return {
|
|
108
113
|
type: "stdio",
|
|
109
114
|
command,
|
|
110
115
|
args,
|
|
111
116
|
cwd,
|
|
112
|
-
env
|
|
113
|
-
framing
|
|
117
|
+
env
|
|
114
118
|
};
|
|
115
119
|
}
|
|
116
120
|
/**
|
|
@@ -127,11 +131,19 @@ function validateHttpTransportConfig(serviceId, input) {
|
|
|
127
131
|
catch {
|
|
128
132
|
throw new Error(`The 'service ${serviceId} transport.url' field must be a valid http or https URL.`);
|
|
129
133
|
}
|
|
134
|
+
if (input.mode !== undefined) {
|
|
135
|
+
throw new Error(`Service '${serviceId}' transport.mode is no longer supported; HTTP always uses Streamable HTTP.`);
|
|
136
|
+
}
|
|
137
|
+
if (input.enableJsonResponse !== undefined) {
|
|
138
|
+
throw new Error(`Service '${serviceId}' transport.enableJsonResponse is no longer supported.`);
|
|
139
|
+
}
|
|
140
|
+
if (input.protocolMode !== undefined) {
|
|
141
|
+
throw new Error(`Service '${serviceId}' transport.protocolMode is no longer supported; protocol negotiation is automatic.`);
|
|
142
|
+
}
|
|
130
143
|
return {
|
|
131
144
|
type: "http",
|
|
132
145
|
url,
|
|
133
|
-
headers: optionalStringRecord(input.headers, `service '${serviceId}' transport.headers`)
|
|
134
|
-
enableJsonResponse: optionalBoolean(input.enableJsonResponse, `service '${serviceId}' transport.enableJsonResponse`)
|
|
146
|
+
headers: optionalStringRecord(input.headers, `service '${serviceId}' transport.headers`)
|
|
135
147
|
};
|
|
136
148
|
}
|
|
137
149
|
/**
|
|
@@ -203,15 +215,3 @@ function optionalStringRecord(input, label) {
|
|
|
203
215
|
}
|
|
204
216
|
return Object.fromEntries(entries);
|
|
205
217
|
}
|
|
206
|
-
/**
|
|
207
|
-
* Reads an optional stdio framing field.
|
|
208
|
-
*/
|
|
209
|
-
function optionalFraming(input, label) {
|
|
210
|
-
if (input === undefined) {
|
|
211
|
-
return undefined;
|
|
212
|
-
}
|
|
213
|
-
if (input !== "line" && input !== "content-length") {
|
|
214
|
-
throw new Error(`The '${label}' field must be 'line' or 'content-length' when present.`);
|
|
215
|
-
}
|
|
216
|
-
return input;
|
|
217
|
-
}
|