@jadchene/mcp-gateway-service 0.5.0 → 0.6.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 +59 -203
- package/README_zh.md +59 -203
- package/config.example.json +5 -6
- package/dist/config.js +14 -17
- package/dist/gateway-engine.js +7 -78
- package/dist/gateway-server.js +17 -33
- package/dist/http-server.js +36 -154
- package/dist/index.js +5 -3
- 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.md
CHANGED
|
@@ -2,85 +2,50 @@ English | [简体中文](./README_zh.md)
|
|
|
2
2
|
|
|
3
3
|
# MCP Gateway
|
|
4
4
|
|
|
5
|
-
MCP Gateway is a
|
|
5
|
+
MCP Gateway is a token-efficient Model Context Protocol gateway. It exposes six stable routing tools instead of flattening every downstream tool into each client's startup context.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
MCP Gateway v0.6.1 uses the official TypeScript SDK v2.
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
> [!IMPORTANT]
|
|
10
|
+
> v0.6.0 and later support only MCP `2026-07-28` and `2025-06-18`, using standard newline-delimited stdio or single-endpoint Streamable HTTP. Compatibility with older protocol revisions, standalone HTTP+SSE (`/sse`), and `Content-Length` framing has been removed.
|
|
10
11
|
|
|
11
|
-
|
|
12
|
-
- Token-efficient discovery through a small fixed gateway tool surface.
|
|
13
|
-
- Stdio and Streamable HTTP downstream transports.
|
|
14
|
-
- Optional inbound Streamable HTTP endpoint enabled by CLI flags.
|
|
15
|
-
- Hot reload for service-pool config changes.
|
|
16
|
-
- Stops removed, disabled, or replaced downstream services during reload.
|
|
17
|
-
- Restarts failed downstream processes up to three times before marking them unavailable.
|
|
18
|
-
- Atomic config reload that keeps the previous valid config when a new config is invalid.
|
|
19
|
-
- Optional newline-delimited JSON file logging that never writes operational logs to MCP stdout.
|
|
20
|
-
- Version reporting through `--version` or `-v`.
|
|
12
|
+
## Capabilities
|
|
21
13
|
|
|
22
|
-
|
|
14
|
+
- Inbound MCP server over stdio and stateless Streamable HTTP.
|
|
15
|
+
- Outbound MCP client over standard stdio and Streamable HTTP.
|
|
16
|
+
- Automatic negotiation between MCP `2026-07-28` and `2025-06-18`.
|
|
17
|
+
- Both standard revisions are served automatically on inbound transports.
|
|
18
|
+
- Full downstream tool metadata and JSON Schema 2020-12 preservation.
|
|
19
|
+
- MRTR elicitation forwarding, opaque `requestState` forwarding, arbitrary JSON `structuredContent`, cancellation, and `x-mcp-header` handling through the SDK.
|
|
20
|
+
- SDK-managed response cache hints and client-local private caches.
|
|
21
|
+
- Hot reload, lifecycle recovery, atomic invalid-config rejection, and optional file logging.
|
|
22
|
+
- Host and Origin validation for inbound HTTP. Operational logs never use MCP stdout.
|
|
23
23
|
|
|
24
|
-
|
|
25
|
-
- Reduce initial tool context: agents discover only the service, tool, and schema needed for the current task.
|
|
26
|
-
- Keep service lifecycle control centralized instead of duplicating command paths, environment variables, and secrets across multiple clients.
|
|
24
|
+
## Requirements and Installation
|
|
27
25
|
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
Install globally:
|
|
26
|
+
- Node.js 24 or later.
|
|
31
27
|
|
|
32
28
|
```bash
|
|
33
29
|
npm install -g @jadchene/mcp-gateway-service
|
|
34
|
-
```
|
|
35
|
-
|
|
36
|
-
Create a local config:
|
|
37
|
-
|
|
38
|
-
```bash
|
|
39
30
|
cp config.example.json config.json
|
|
40
|
-
```
|
|
41
|
-
|
|
42
|
-
Start the stdio gateway:
|
|
43
|
-
|
|
44
|
-
```bash
|
|
45
31
|
mcp-gateway-service --config ./config.json
|
|
46
32
|
```
|
|
47
33
|
|
|
48
|
-
|
|
34
|
+
Enable the additional inbound HTTP endpoint:
|
|
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
|
-
Check the installed version:
|
|
61
|
-
|
|
62
|
-
```bash
|
|
63
|
-
mcp-gateway-service --version
|
|
64
|
-
mcp-gateway-service -v
|
|
65
|
-
```
|
|
40
|
+
When HTTP is enabled, the process serves both stdio and HTTP. Use `--version` or `-v` to print the installed version.
|
|
66
41
|
|
|
67
|
-
##
|
|
42
|
+
## Protocol Negotiation
|
|
68
43
|
|
|
69
|
-
|
|
44
|
+
Protocol selection is automatic. The gateway and its downstream clients negotiate MCP `2026-07-28` first and use `2025-06-18` when the peer supports only that standard revision. These are the only accepted protocol revisions. Inbound Streamable HTTP response shaping is selected automatically by the official SDK.
|
|
70
45
|
|
|
71
|
-
|
|
72
|
-
mcp-gateway-service --config ./config.json
|
|
73
|
-
```
|
|
46
|
+
## Service Configuration
|
|
74
47
|
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
```bash
|
|
78
|
-
MCP_GATEWAY_CONFIG=./config.json mcp-gateway-service
|
|
79
|
-
```
|
|
80
|
-
|
|
81
|
-
If neither is provided, the service tries `config.json` in the current working directory.
|
|
82
|
-
|
|
83
|
-
Config example:
|
|
48
|
+
Pass `--config`, set `MCP_GATEWAY_CONFIG`, or place `config.json` in the current directory.
|
|
84
49
|
|
|
85
50
|
```json
|
|
86
51
|
{
|
|
@@ -90,105 +55,71 @@ Config example:
|
|
|
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
|
+
Common fields:
|
|
125
84
|
|
|
126
|
-
- `
|
|
127
|
-
- `logging.
|
|
128
|
-
-
|
|
129
|
-
-
|
|
130
|
-
-
|
|
131
|
-
-
|
|
132
|
-
- HTTP downstream services use `transport.type: "http"` and `transport.url`.
|
|
133
|
-
- HTTP `transport.headers` provides static request headers.
|
|
134
|
-
- HTTP `transport.enableJsonResponse` enables stateless JSON response mode for that downstream service.
|
|
85
|
+
- `enable` defaults to `true`.
|
|
86
|
+
- `logging.enable` defaults to `false`. A relative log path is resolved from the config file directory.
|
|
87
|
+
- Stdio always uses the standard newline-delimited JSON-RPC transport.
|
|
88
|
+
- HTTP always uses the standard single-endpoint Streamable HTTP transport.
|
|
89
|
+
- Protocol revision negotiation is automatic and has no configuration switch.
|
|
90
|
+
- Static HTTP headers are supported. Header values and environment secrets are not written to logs.
|
|
135
91
|
|
|
136
92
|
## Inbound Streamable HTTP
|
|
137
93
|
|
|
138
|
-
|
|
94
|
+
MCP `2026-07-28` HTTP is stateless: each request is an independent `POST /mcp`. The gateway does not create `Mcp-Session-Id` sessions, and `GET`/`DELETE` return `405`. The SDK validates `MCP-Protocol-Version`, `Mcp-Method`, `Mcp-Name`, request metadata, and protocol errors.
|
|
139
95
|
|
|
140
|
-
The
|
|
96
|
+
The same endpoint serves MCP `2025-06-18` through its standard stateless Streamable HTTP form. As a downstream client, the gateway also preserves a `2025-06-18` session when a server issues `Mcp-Session-Id`.
|
|
141
97
|
|
|
142
|
-
|
|
143
|
-
- `POST /mcp` sends JSON-RPC messages. New clients should bind the session through the `Mcp-Session-Id` request header.
|
|
144
|
-
- Query-string `sessionId` is accepted for compatibility.
|
|
145
|
-
- The `endpoint` SSE event advertises the single path, such as `/mcp`.
|
|
98
|
+
The default bind address is `127.0.0.1`. Host and Origin checks protect the local endpoint from DNS rebinding. Do not expose it beyond a trusted local network without an authentication layer.
|
|
146
99
|
|
|
147
100
|
## Gateway Tools
|
|
148
101
|
|
|
149
|
-
The gateway exposes six public tools:
|
|
150
|
-
|
|
151
102
|
| Tool | Purpose |
|
|
152
103
|
| --- | --- |
|
|
153
|
-
| `gateway_list_services` | List downstream services
|
|
154
|
-
| `gateway_get_service` |
|
|
155
|
-
| `gateway_list_tools` | Search tool names
|
|
156
|
-
| `gateway_get_tool_schema` |
|
|
157
|
-
| `gateway_manage_service` | Reconnect
|
|
158
|
-
| `gateway_call_tool` | Call one
|
|
159
|
-
|
|
160
|
-
Default token-efficient workflow:
|
|
161
|
-
|
|
162
|
-
1. Call `gateway_list_services` once.
|
|
163
|
-
2. Call `gateway_list_tools(serviceId)` only when a service is needed. Use a `toolName` array for name keywords and a `desc` array for description keywords.
|
|
164
|
-
3. When all filtered matches need schemas, pass `includeSchema: true`; when exact tool names are already known, call `gateway_get_tool_schema` with a non-empty name array.
|
|
165
|
-
4. Call `gateway_call_tool` to execute the downstream tool.
|
|
166
|
-
5. Use `gateway_get_service` only for diagnostics.
|
|
167
|
-
6. Use `gateway_manage_service` only to reconnect, enable, or disable a service.
|
|
168
|
-
|
|
169
|
-
`gateway_get_tool_schema.toolName` is a required unique non-empty string array and returns a `schemas` object keyed by each requested exact tool name. Use a one-element array when requesting one schema.
|
|
170
|
-
|
|
171
|
-
`gateway_list_tools.toolName` and `gateway_list_tools.desc` are optional unique non-empty string arrays. Matching is case-insensitive and uses literal substrings. When both are present, a tool is returned when either its name or description matches any supplied keyword. Description matching can also hit negative guidance such as "when not to use", so inspect the returned descriptions before selecting a tool.
|
|
104
|
+
| `gateway_list_services` | List configured downstream services and availability. |
|
|
105
|
+
| `gateway_get_service` | Inspect one service's status, protocol version, and server identity. |
|
|
106
|
+
| `gateway_list_tools` | Search tool names/descriptions; optionally include schemas. |
|
|
107
|
+
| `gateway_get_tool_schema` | Fetch schemas for exact, case-sensitive tool names in one batch. |
|
|
108
|
+
| `gateway_manage_service` | Reconnect or persistently enable/disable one configured service. |
|
|
109
|
+
| `gateway_call_tool` | Call one downstream tool and preserve its MCP result. |
|
|
172
110
|
|
|
173
|
-
|
|
111
|
+
Recommended flow:
|
|
174
112
|
|
|
175
|
-
`
|
|
113
|
+
1. Call `gateway_list_services`.
|
|
114
|
+
2. Call `gateway_list_tools` only for the relevant service, using `toolName` and/or `desc` filters.
|
|
115
|
+
3. Reuse schemas returned by `includeSchema: true`, or batch exact names with `gateway_get_tool_schema`.
|
|
116
|
+
4. Call `gateway_call_tool`; always provide `arguments`, using `{}` for a no-argument tool.
|
|
176
117
|
|
|
177
|
-
|
|
178
|
-
- `enable`: persist `enable: true` for the service and reload config.
|
|
179
|
-
- `disable`: persist `enable: false` for the service and reload config.
|
|
118
|
+
`gateway_call_tool` intentionally has no fixed output schema because downstream `structuredContent` may be any JSON value. Modern MRTR `input_required` results are forwarded without automatic approval; the upstream client must declare the required capability and retry with `inputResponses` and the opaque `requestState`.
|
|
180
119
|
|
|
181
|
-
##
|
|
120
|
+
## Client Examples
|
|
182
121
|
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
- Skill path: `skills/mcp-gateway/SKILL.md`
|
|
186
|
-
|
|
187
|
-
Use it when your agent supports skills. It keeps discovery token-efficient and routes downstream calls through the minimal gateway contract.
|
|
188
|
-
|
|
189
|
-
## MCP Client Configuration
|
|
190
|
-
|
|
191
|
-
Codex:
|
|
122
|
+
Stdio (Codex-style 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 mode:
|
|
228
|
-
|
|
229
|
-
Start one shared HTTP gateway process first:
|
|
230
|
-
|
|
231
|
-
```bash
|
|
232
|
-
mcp-gateway-service --config ./config.json --http --host 127.0.0.1 --port 3100 --path /mcp
|
|
233
|
-
```
|
|
234
|
-
|
|
235
|
-
Then point MCP clients at the 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
|
-
Use the same URL for every client that should share the gateway service pool. Use `--json-response` only when your HTTP client expects stateless JSON-RPC responses directly from `POST` requests.
|
|
270
|
-
|
|
271
|
-
## Development
|
|
137
|
+
## Development and Verification
|
|
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
|
-
Run the built server:
|
|
286
|
-
|
|
287
|
-
```bash
|
|
288
|
-
node dist/index.js --config ./config.json
|
|
289
|
-
```
|
|
145
|
+
The repository also ships the public skill at `skills/mcp-gateway/SKILL.md`.
|
|
290
146
|
|
|
291
147
|
## License
|
|
292
148
|
|