@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.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.0 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
|
-
```
|
|
66
|
-
|
|
67
|
-
## Configuration
|
|
68
|
-
|
|
69
|
-
Pass the config file by CLI argument:
|
|
70
|
-
|
|
71
|
-
```bash
|
|
72
|
-
mcp-gateway-service --config ./config.json
|
|
73
|
-
```
|
|
40
|
+
When HTTP is enabled, the process serves both stdio and HTTP. Use `--version` or `-v` to print the installed version.
|
|
74
41
|
|
|
75
|
-
|
|
42
|
+
## Protocol Negotiation
|
|
76
43
|
|
|
77
|
-
|
|
78
|
-
MCP_GATEWAY_CONFIG=./config.json mcp-gateway-service
|
|
79
|
-
```
|
|
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. `--json-response` selects the standard inbound Streamable HTTP response shape; it does not create protocol sessions.
|
|
80
45
|
|
|
81
|
-
|
|
46
|
+
## Service Configuration
|
|
82
47
|
|
|
83
|
-
|
|
48
|
+
Pass `--config`, set `MCP_GATEWAY_CONFIG`, or place `config.json` in the current directory.
|
|
84
49
|
|
|
85
50
|
```json
|
|
86
51
|
{
|
|
@@ -90,101 +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
|
|
154
|
-
| `gateway_get_service` |
|
|
155
|
-
| `gateway_list_tools` |
|
|
156
|
-
| `gateway_get_tool_schema` |
|
|
157
|
-
| `gateway_manage_service` | Reconnect
|
|
158
|
-
| `gateway_call_tool` | Call one downstream tool
|
|
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 `toolName` to filter large tool lists by name.
|
|
164
|
-
3. When all filtered matches need schemas, pass `includeSchema: true`; when exact tool names are already known, call `gateway_get_tool_schema` with one name or a 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` accepts `toolName` as a string or non-empty string array and returns a `schemas` object keyed by each requested tool name.
|
|
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. |
|
|
170
110
|
|
|
171
|
-
|
|
111
|
+
Recommended flow:
|
|
172
112
|
|
|
173
|
-
|
|
174
|
-
|
|
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
|
-
|
|
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`.
|
|
178
119
|
|
|
179
|
-
|
|
120
|
+
## Client Examples
|
|
180
121
|
|
|
181
|
-
-
|
|
182
|
-
|
|
183
|
-
Use it when your agent supports skills. It keeps discovery token-efficient and routes downstream calls through the minimal gateway contract.
|
|
184
|
-
|
|
185
|
-
## MCP Client Configuration
|
|
186
|
-
|
|
187
|
-
Codex:
|
|
122
|
+
Stdio (Codex-style 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 mode:
|
|
224
|
-
|
|
225
|
-
Start one shared HTTP gateway process first:
|
|
226
|
-
|
|
227
|
-
```bash
|
|
228
|
-
mcp-gateway-service --config ./config.json --http --host 127.0.0.1 --port 3100 --path /mcp
|
|
229
|
-
```
|
|
230
|
-
|
|
231
|
-
Then point MCP clients at the 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
|
-
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.
|
|
266
|
-
|
|
267
|
-
## Development
|
|
137
|
+
## Development and Verification
|
|
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
|
-
Run the built server:
|
|
282
|
-
|
|
283
|
-
```bash
|
|
284
|
-
node dist/index.js --config ./config.json
|
|
285
|
-
```
|
|
145
|
+
The repository also ships the public skill at `skills/mcp-gateway/SKILL.md`.
|
|
286
146
|
|
|
287
147
|
## License
|
|
288
148
|
|