@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_zh.md CHANGED
@@ -2,85 +2,50 @@
2
2
 
3
3
  # MCP Gateway
4
4
 
5
- MCP Gateway 是一个轻量级 Model Context Protocol 网关,用一个小型 MCP 入口管理多个下游 MCP 服务。
5
+ MCP Gateway 是一个节省 token 的 Model Context Protocol 网关。它不把所有下游工具展开到每个客户端的启动上下文,而是通过 6 个稳定工具完成发现、管理和转发。
6
6
 
7
- 它不会在客户端启动时把所有下游工具直接展开,而是提供固定的发现和转发 API。Agent 可以先列出服务,再查看某个服务的工具,按需获取单个工具 schema,最后转发真实工具调用。
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
- - 用一个 MCP 入口接入多个下游 MCP 服务。
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
- - 简化 Agent 侧 MCP 配置:每个 Agent 只连接网关,下游服务统一在一个配置文件中管理。
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
- 启动入站 Streamable HTTP:
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
- 如果 HTTP 客户端希望 `POST` 直接返回 JSON-RPC 响应,可启用无状态 JSON 直返:
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
- ```bash
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
- 如果两者都没有提供,服务会尝试读取当前工作目录下的 `config.json`。
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": "demo-echo",
58
+ "serviceId": "local-tools",
94
59
  "enable": true,
95
- "name": "Demo Echo Service",
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-http",
108
- "enable": false,
109
- "name": "Remote Streamable HTTP Service",
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 ${MCP_TOKEN}"
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
- - `logging.enable` 默认为 `false`。
127
- - 只有 `logging.enable` 为 `true` 时,`logging.path` 才必填。
128
- - 相对 `logging.path` 会按配置文件所在目录解析。
129
- - 服务 `enable` 默认为 `true`;设为 `false` 时跳过该服务。
130
- - stdio 服务的 `cwd` 和 `env` 可选。
131
- - stdio `transport.framing` 可为 `line` 或 `content-length`。不填写时网关先尝试 `line`,再尝试 `content-length`。
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
- 入站 HTTP 只有传入 `--http` 时才会启用。只传 `--host`、`--port`、`--path` 或 `--json-response`,但不传 `--http`,不会启动 HTTP 监听。
94
+ MCP `2026-07-28` HTTP 是无状态的:每个请求都是独立的 `POST /mcp`。网关不创建 `Mcp-Session-Id`,`GET` 和 `DELETE` 返回 `405`。标准版本头、方法头、名称头、每请求 metadata 和协议错误由 SDK 校验。
139
95
 
140
- HTTP endpoint 使用同一路径处理 `GET` 和 `POST`:
96
+ 同一 endpoint 通过标准无状态 Streamable HTTP 服务 MCP `2025-06-18`。作为下游客户端,如果 `2025-06-18` 服务端签发 `Mcp-Session-Id`,网关会按标准维持该 session。
141
97
 
142
- - `GET /mcp` 打开 SSE 读取通道,并通过 `Mcp-Session-Id` 响应头返回 session。
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` | 列出网关管理的所有下游 MCP 服务,包括 `serviceId`、描述和可用状态。 |
154
- | `gateway_get_service` | 返回单个服务的摘要、运行状态、最近错误和缓存元数据。主要用于诊断。 |
155
- | `gateway_list_tools` | 列出某个下游服务暴露的工具。可用 `toolName` 按一个或多个名称片段过滤;传入 `includeSchema: true` 时返回每个匹配工具的输入和输出 schema。 |
156
- | `gateway_get_tool_schema` | 按一个或多个准确工具名返回输入和输出 schema,并以工具名作为结果 key。 |
157
- | `gateway_manage_service` | 重连服务,或把启用/禁用状态持久化写入配置文件。 |
158
- | `gateway_call_tool` | 通过网关调用一个下游工具,并返回下游 MCP 结果。 |
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
- `gateway_manage_service` 动作:
111
+ 推荐流程:
172
112
 
173
- - `reconnect`:不修改配置,只重试当前下游服务生命周期。
174
- - `enable`:把该服务的 `enable: true` 持久化到配置文件,然后刷新配置。
175
- - `disable`:把该服务的 `enable: false` 持久化到配置文件,然后刷新配置。
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
- ## Skill 集成
118
+ `gateway_call_tool` 不声明固定输出 schema,因为下游 `structuredContent` 可以是任意 JSON。modern MRTR 的 `input_required` 不会被自动同意;上游必须声明所需能力,并使用 `inputResponses` 和 opaque `requestState` 重试。
178
119
 
179
- 仓库内包含一个公开网关 skill:
120
+ ## 客户端示例
180
121
 
181
- - Skill 路径:`skills/mcp-gateway/SKILL.md`
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
- Gemini CLI:
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
- Gemini CLI:
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 dev
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
 
@@ -6,15 +6,15 @@
6
6
  "services": [
7
7
  {
8
8
  "serviceId": "demo-echo",
9
- "enable": true,
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
- const framing = optionalFraming(input.framing, `service '${serviceId}' transport.framing`);
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
- }