@jadchene/mcp-gateway-service 0.5.0 → 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 -203
- package/README_zh.md +59 -203
- package/config.example.json +5 -6
- package/dist/config.js +17 -17
- package/dist/gateway-engine.js +7 -78
- 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 +3 -2
- package/package.json +27 -16
- package/skills/mcp-gateway/SKILL.md +2 -0
- 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
|
-
```
|
|
40
|
+
启用 HTTP 时,进程同时提供 stdio 和 HTTP 入口。使用 `--version` 或 `-v` 查看版本。
|
|
66
41
|
|
|
67
|
-
##
|
|
42
|
+
## 协议协商
|
|
68
43
|
|
|
69
|
-
|
|
44
|
+
协议选择完全自动:网关及其下游客户端优先协商 MCP `2026-07-28`,对端仅支持 `2025-06-18` 时使用该标准版本。只接受这两个协议版本。`--json-response` 只选择标准入站 Streamable HTTP 的响应形态,不会创建协议 session。
|
|
70
45
|
|
|
71
|
-
|
|
72
|
-
mcp-gateway-service --config ./config.json
|
|
73
|
-
```
|
|
46
|
+
## 服务配置
|
|
74
47
|
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
```bash
|
|
78
|
-
MCP_GATEWAY_CONFIG=./config.json mcp-gateway-service
|
|
79
|
-
```
|
|
80
|
-
|
|
81
|
-
如果两者都没有提供,服务会尝试读取当前工作目录下的 `config.json`。
|
|
82
|
-
|
|
83
|
-
配置示例:
|
|
48
|
+
可通过 `--config`、`MCP_GATEWAY_CONFIG` 或当前目录的 `config.json` 指定配置。
|
|
84
49
|
|
|
85
50
|
```json
|
|
86
51
|
{
|
|
@@ -90,105 +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` 数组按名称关键词筛选,或用 `desc` 数组按描述关键词筛选。
|
|
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。只查询一个 schema 时使用单元素数组。
|
|
170
|
-
|
|
171
|
-
`gateway_list_tools.toolName` 和 `gateway_list_tools.desc` 都是可选的唯一非空字符串数组,按字面子串进行不区分大小写的匹配。同时传入时,只要工具名称或描述匹配任一关键词就会返回。描述匹配也可能命中 “when not to use” 等负向说明,因此选择工具前应检查完整描述。
|
|
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 结果。 |
|
|
172
110
|
|
|
173
|
-
|
|
111
|
+
推荐流程:
|
|
174
112
|
|
|
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
|
-
|
|
178
|
-
- `enable`:把该服务的 `enable: true` 持久化到配置文件,然后刷新配置。
|
|
179
|
-
- `disable`:把该服务的 `enable: false` 持久化到配置文件,然后刷新配置。
|
|
118
|
+
`gateway_call_tool` 不声明固定输出 schema,因为下游 `structuredContent` 可以是任意 JSON。modern MRTR 的 `input_required` 不会被自动同意;上游必须声明所需能力,并使用 `inputResponses` 和 opaque `requestState` 重试。
|
|
180
119
|
|
|
181
|
-
##
|
|
120
|
+
## 客户端示例
|
|
182
121
|
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
- Skill 路径:`skills/mcp-gateway/SKILL.md`
|
|
186
|
-
|
|
187
|
-
当你的 Agent 支持 skills 时建议加载它。它会保持按需发现、节省 token,并通过最小网关契约转发下游调用。
|
|
188
|
-
|
|
189
|
-
## MCP 客户端配置
|
|
190
|
-
|
|
191
|
-
Codex:
|
|
122
|
+
stdio(Codex 风格 TOML):
|
|
192
123
|
|
|
193
124
|
```toml
|
|
194
125
|
[mcp_servers.gateway]
|
|
@@ -196,97 +127,22 @@ command = "mcp-gateway-service"
|
|
|
196
127
|
args = ["--config", "./config.json"]
|
|
197
128
|
```
|
|
198
129
|
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
```json
|
|
202
|
-
{
|
|
203
|
-
"mcpServers": {
|
|
204
|
-
"gateway": {
|
|
205
|
-
"type": "stdio",
|
|
206
|
-
"command": "mcp-gateway-service",
|
|
207
|
-
"args": ["--config", "./config.json"]
|
|
208
|
-
}
|
|
209
|
-
}
|
|
210
|
-
}
|
|
211
|
-
```
|
|
212
|
-
|
|
213
|
-
Claude Code:
|
|
214
|
-
|
|
215
|
-
```json
|
|
216
|
-
{
|
|
217
|
-
"mcpServers": {
|
|
218
|
-
"gateway": {
|
|
219
|
-
"type": "stdio",
|
|
220
|
-
"command": "mcp-gateway-service",
|
|
221
|
-
"args": ["--config", "./config.json"]
|
|
222
|
-
}
|
|
223
|
-
}
|
|
224
|
-
}
|
|
225
|
-
```
|
|
226
|
-
|
|
227
|
-
Streamable HTTP 模式:
|
|
228
|
-
|
|
229
|
-
先启动一个共享 HTTP 网关进程:
|
|
230
|
-
|
|
231
|
-
```bash
|
|
232
|
-
mcp-gateway-service --config ./config.json --http --host 127.0.0.1 --port 3100 --path /mcp
|
|
233
|
-
```
|
|
234
|
-
|
|
235
|
-
然后让 MCP 客户端连接这个 HTTP endpoint。
|
|
236
|
-
|
|
237
|
-
Codex:
|
|
130
|
+
Streamable HTTP:
|
|
238
131
|
|
|
239
132
|
```toml
|
|
240
133
|
[mcp_servers.gateway]
|
|
241
134
|
url = "http://127.0.0.1:3100/mcp"
|
|
242
135
|
```
|
|
243
136
|
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
```json
|
|
247
|
-
{
|
|
248
|
-
"mcpServers": {
|
|
249
|
-
"gateway": {
|
|
250
|
-
"httpUrl": "http://127.0.0.1:3100/mcp"
|
|
251
|
-
}
|
|
252
|
-
}
|
|
253
|
-
}
|
|
254
|
-
```
|
|
255
|
-
|
|
256
|
-
Claude Code:
|
|
257
|
-
|
|
258
|
-
```json
|
|
259
|
-
{
|
|
260
|
-
"mcpServers": {
|
|
261
|
-
"gateway": {
|
|
262
|
-
"type": "http",
|
|
263
|
-
"url": "http://127.0.0.1:3100/mcp"
|
|
264
|
-
}
|
|
265
|
-
}
|
|
266
|
-
}
|
|
267
|
-
```
|
|
268
|
-
|
|
269
|
-
需要共享同一个网关服务池的客户端都使用同一个 URL。只有当 HTTP 客户端希望 `POST` 直接返回无状态 JSON-RPC 响应时,才需要在启动网关时加 `--json-response`。
|
|
270
|
-
|
|
271
|
-
## 开发
|
|
137
|
+
## 开发与验证
|
|
272
138
|
|
|
273
139
|
```bash
|
|
274
140
|
npm install
|
|
275
|
-
npm run
|
|
141
|
+
npm run verify
|
|
142
|
+
node dist/index.js --config ./config.json --version
|
|
276
143
|
```
|
|
277
144
|
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
```bash
|
|
281
|
-
npm run build
|
|
282
|
-
npm test
|
|
283
|
-
```
|
|
284
|
-
|
|
285
|
-
运行构建后的服务:
|
|
286
|
-
|
|
287
|
-
```bash
|
|
288
|
-
node dist/index.js --config ./config.json
|
|
289
|
-
```
|
|
145
|
+
仓库还包含公开 Skill:`skills/mcp-gateway/SKILL.md`。
|
|
290
146
|
|
|
291
147
|
## License
|
|
292
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
|
-
}
|
package/dist/gateway-engine.js
CHANGED
|
@@ -1,5 +1,3 @@
|
|
|
1
|
-
import { jsonRpcError, jsonRpcResult } from "./mcp/protocol.js";
|
|
2
|
-
import { VERSION } from "./version.js";
|
|
3
1
|
/**
|
|
4
2
|
* Handles MCP JSON-RPC requests independently of the outer transport.
|
|
5
3
|
*/
|
|
@@ -8,10 +6,6 @@ export class McpGatewayEngine {
|
|
|
8
6
|
* Stores the registry used for metadata lookup and routing.
|
|
9
7
|
*/
|
|
10
8
|
registry;
|
|
11
|
-
/**
|
|
12
|
-
* Stores the shared logger instance.
|
|
13
|
-
*/
|
|
14
|
-
logger;
|
|
15
9
|
/**
|
|
16
10
|
* Stores the startup barrier that must resolve before gateway tools can use the registry.
|
|
17
11
|
*/
|
|
@@ -19,9 +13,8 @@ export class McpGatewayEngine {
|
|
|
19
13
|
/**
|
|
20
14
|
* Creates the transport-neutral gateway engine.
|
|
21
15
|
*/
|
|
22
|
-
constructor(registry,
|
|
16
|
+
constructor(registry, _logger) {
|
|
23
17
|
this.registry = registry;
|
|
24
|
-
this.logger = logger;
|
|
25
18
|
}
|
|
26
19
|
/**
|
|
27
20
|
* Sets the startup barrier used to delay tool handling until the registry is ready.
|
|
@@ -30,54 +23,10 @@ export class McpGatewayEngine {
|
|
|
30
23
|
this.startupBarrier = barrier;
|
|
31
24
|
}
|
|
32
25
|
/**
|
|
33
|
-
*
|
|
34
|
-
*/
|
|
35
|
-
async handleMessage(message) {
|
|
36
|
-
if (!isJsonRpcRequest(message)) {
|
|
37
|
-
return null;
|
|
38
|
-
}
|
|
39
|
-
return this.handleRequest(message);
|
|
40
|
-
}
|
|
41
|
-
/**
|
|
42
|
-
* Handles one inbound JSON-RPC request.
|
|
26
|
+
* Executes one registered gateway tool independently of the outer SDK transport.
|
|
43
27
|
*/
|
|
44
|
-
async
|
|
45
|
-
|
|
46
|
-
if (request.method === "initialize") {
|
|
47
|
-
return jsonRpcResult(request.id, this.buildInitializeResult());
|
|
48
|
-
}
|
|
49
|
-
if (request.method === "ping") {
|
|
50
|
-
return jsonRpcResult(request.id, {});
|
|
51
|
-
}
|
|
52
|
-
if (request.method === "tools/list") {
|
|
53
|
-
return jsonRpcResult(request.id, { tools: buildGatewayTools() });
|
|
54
|
-
}
|
|
55
|
-
if (request.method === "tools/call") {
|
|
56
|
-
await this.startupBarrier;
|
|
57
|
-
const result = await this.handleToolCall(request);
|
|
58
|
-
return jsonRpcResult(request.id, result);
|
|
59
|
-
}
|
|
60
|
-
if (request.method === "notifications/initialized") {
|
|
61
|
-
return null;
|
|
62
|
-
}
|
|
63
|
-
return jsonRpcError(request.id, -32601, `Unsupported method '${request.method}'.`);
|
|
64
|
-
}
|
|
65
|
-
catch (error) {
|
|
66
|
-
const message = error instanceof Error ? error.message : String(error);
|
|
67
|
-
this.logger.error("gateway.request_failed", {
|
|
68
|
-
method: request.method,
|
|
69
|
-
message
|
|
70
|
-
});
|
|
71
|
-
return jsonRpcError(request.id, -32000, message);
|
|
72
|
-
}
|
|
73
|
-
}
|
|
74
|
-
/**
|
|
75
|
-
* Handles one gateway tool invocation.
|
|
76
|
-
*/
|
|
77
|
-
async handleToolCall(request) {
|
|
78
|
-
const params = toObject(request.params, "The tools/call params must be an object.");
|
|
79
|
-
const toolName = requireString(params.name, "The tool name must be a string.");
|
|
80
|
-
const args = toObject(params.arguments ?? {}, "The tool arguments must be an object.");
|
|
28
|
+
async executeTool(toolName, args, context = {}) {
|
|
29
|
+
await this.startupBarrier;
|
|
81
30
|
switch (toolName) {
|
|
82
31
|
case "gateway_list_services":
|
|
83
32
|
return successContent({
|
|
@@ -92,7 +41,7 @@ export class McpGatewayEngine {
|
|
|
92
41
|
case "gateway_manage_service":
|
|
93
42
|
return this.manageService(args);
|
|
94
43
|
case "gateway_call_tool":
|
|
95
|
-
return this.callDownstreamTool(args);
|
|
44
|
+
return this.callDownstreamTool(args, context);
|
|
96
45
|
default:
|
|
97
46
|
throw new Error(`Unknown gateway tool '${toolName}'.`);
|
|
98
47
|
}
|
|
@@ -160,11 +109,11 @@ export class McpGatewayEngine {
|
|
|
160
109
|
/**
|
|
161
110
|
* Routes one downstream tool call through the service registry.
|
|
162
111
|
*/
|
|
163
|
-
async callDownstreamTool(args) {
|
|
112
|
+
async callDownstreamTool(args, context = {}) {
|
|
164
113
|
const serviceId = requireString(args.serviceId, "The 'serviceId' argument must be a string.");
|
|
165
114
|
const toolName = requireString(args.toolName, "The 'toolName' argument must be a string.");
|
|
166
115
|
const toolArgs = toObject(args.arguments, "The 'arguments' field must be an object.");
|
|
167
|
-
const call = await this.registry.callTool(serviceId, toolName, toolArgs);
|
|
116
|
+
const call = await this.registry.callTool(serviceId, toolName, toolArgs, context);
|
|
168
117
|
return call.result;
|
|
169
118
|
}
|
|
170
119
|
/**
|
|
@@ -181,23 +130,6 @@ export class McpGatewayEngine {
|
|
|
181
130
|
available: result.available
|
|
182
131
|
});
|
|
183
132
|
}
|
|
184
|
-
/**
|
|
185
|
-
* Builds the MCP initialize result advertised by the gateway.
|
|
186
|
-
*/
|
|
187
|
-
buildInitializeResult() {
|
|
188
|
-
return {
|
|
189
|
-
protocolVersion: "2025-06-18",
|
|
190
|
-
capabilities: {
|
|
191
|
-
tools: {
|
|
192
|
-
listChanged: false
|
|
193
|
-
}
|
|
194
|
-
},
|
|
195
|
-
serverInfo: {
|
|
196
|
-
name: "mcp-gateway",
|
|
197
|
-
version: VERSION
|
|
198
|
-
}
|
|
199
|
-
};
|
|
200
|
-
}
|
|
201
133
|
}
|
|
202
134
|
/**
|
|
203
135
|
* Builds the fixed gateway tool definitions exposed to all MCP clients.
|
|
@@ -476,6 +408,3 @@ function requireServiceAction(input) {
|
|
|
476
408
|
}
|
|
477
409
|
throw new Error("The 'action' argument must be one of 'reconnect', 'enable', or 'disable'.");
|
|
478
410
|
}
|
|
479
|
-
function isJsonRpcRequest(message) {
|
|
480
|
-
return "id" in message && "method" in message && typeof message.method === "string";
|
|
481
|
-
}
|
package/dist/gateway-server.js
CHANGED
|
@@ -1,25 +1,13 @@
|
|
|
1
|
+
import { serveStdio } from "@modelcontextprotocol/server/stdio";
|
|
1
2
|
import { McpGatewayEngine } from "./gateway-engine.js";
|
|
2
|
-
import {
|
|
3
|
+
import { createGatewayMcpServer } from "./mcp/server.js";
|
|
3
4
|
/**
|
|
4
|
-
* Exposes the MCP gateway
|
|
5
|
+
* Exposes the MCP gateway over stdio through the official SDK v2.
|
|
5
6
|
*/
|
|
6
7
|
export class GatewayServer {
|
|
7
|
-
/**
|
|
8
|
-
* Stores the transport-neutral gateway engine.
|
|
9
|
-
*/
|
|
10
8
|
engine;
|
|
11
|
-
/**
|
|
12
|
-
* Stores the shared logger instance.
|
|
13
|
-
*/
|
|
14
9
|
logger;
|
|
15
|
-
|
|
16
|
-
* Stores the stdio message reader bound to the current process.
|
|
17
|
-
*/
|
|
18
|
-
reader = createMessageReader(process.stdin);
|
|
19
|
-
/**
|
|
20
|
-
* Stores the stdio message writer bound to the current process.
|
|
21
|
-
*/
|
|
22
|
-
writer = createMessageWriter(process.stdout);
|
|
10
|
+
handle = null;
|
|
23
11
|
/**
|
|
24
12
|
* Creates the stdio gateway server.
|
|
25
13
|
*/
|
|
@@ -34,29 +22,25 @@ export class GatewayServer {
|
|
|
34
22
|
this.engine.setStartupBarrier(barrier);
|
|
35
23
|
}
|
|
36
24
|
/**
|
|
37
|
-
* Starts
|
|
25
|
+
* Starts the dual-era SDK server on the current process streams.
|
|
38
26
|
*/
|
|
39
27
|
start() {
|
|
40
|
-
this.
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
28
|
+
if (this.handle) {
|
|
29
|
+
return;
|
|
30
|
+
}
|
|
31
|
+
this.handle = serveStdio(() => createGatewayMcpServer(this.engine), {
|
|
32
|
+
legacy: "serve",
|
|
33
|
+
onerror: (error) => {
|
|
34
|
+
this.logger.error("gateway.protocol_error", { message: error.message });
|
|
44
35
|
}
|
|
45
|
-
void this.handleMessage(message);
|
|
46
|
-
});
|
|
47
|
-
this.reader.on("error", (error) => {
|
|
48
|
-
this.logger.error("gateway.protocol_error", {
|
|
49
|
-
message: error instanceof Error ? error.message : String(error)
|
|
50
|
-
});
|
|
51
36
|
});
|
|
52
37
|
}
|
|
53
38
|
/**
|
|
54
|
-
*
|
|
39
|
+
* Stops the stdio serving entry.
|
|
55
40
|
*/
|
|
56
|
-
async
|
|
57
|
-
const
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
}
|
|
41
|
+
async stop() {
|
|
42
|
+
const handle = this.handle;
|
|
43
|
+
this.handle = null;
|
|
44
|
+
await handle?.close();
|
|
61
45
|
}
|
|
62
46
|
}
|