@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 CHANGED
@@ -2,85 +2,50 @@ English | [简体中文](./README_zh.md)
2
2
 
3
3
  # MCP Gateway
4
4
 
5
- MCP Gateway is a lightweight Model Context Protocol gateway that exposes one small MCP entry point for multiple downstream MCP services.
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
- Instead of flattening every downstream tool into the client at startup, the gateway exposes a fixed discovery and routing API. Agents can list services, inspect tools for one service, fetch one schema, and then forward the actual tool call.
7
+ MCP Gateway v0.6.0 uses the official TypeScript SDK v2.
8
8
 
9
- ## Features
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
- - One MCP entry point for multiple downstream MCP services.
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
- ## Why Use It
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
- - Keep agent-side MCP configuration small: every agent connects to the gateway, while downstream services are managed in one config file.
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
- ## Quick Start
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
- Start with inbound Streamable HTTP:
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
- Use stateless JSON responses for HTTP clients that expect direct JSON-RPC responses from `POST`:
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
- ## Configuration
42
+ ## Protocol Negotiation
68
43
 
69
- Pass the config file by CLI argument:
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.
70
45
 
71
- ```bash
72
- mcp-gateway-service --config ./config.json
73
- ```
46
+ ## Service Configuration
74
47
 
75
- Or by environment variable:
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": "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
- Configuration notes:
83
+ Common fields:
125
84
 
126
- - `logging.enable` defaults to `false`.
127
- - `logging.path` is required only when `logging.enable` is `true`.
128
- - Relative `logging.path` values are resolved from the config file directory.
129
- - Service `enable` defaults to `true`; setting it to `false` skips that service.
130
- - `cwd` and `env` are optional for stdio services.
131
- - Stdio `transport.framing` may be `line` or `content-length`. When omitted, the gateway tries `line` and then `content-length`.
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
- Inbound HTTP is enabled only with `--http`. Passing `--host`, `--port`, `--path`, or `--json-response` without `--http` does not start an HTTP listener.
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 HTTP endpoint uses the same path for `GET` and `POST`:
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
- - `GET /mcp` opens the SSE read channel and returns the session in the `Mcp-Session-Id` response header.
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 with each logical `serviceId`, description, and current availability. |
154
- | `gateway_get_service` | Return one service's identity, availability, recent error and connection time, protocol version, and server information. Use this for diagnostics. |
155
- | `gateway_list_tools` | Search tool names or descriptions by case-insensitive literal substrings. Optional unique non-empty `toolName` and `desc` arrays use OR; `includeSchema: true` includes schemas. |
156
- | `gateway_get_tool_schema` | Return schemas for unique exact, case-sensitive tool names. Results are keyed by name, and any unknown name fails the whole request. |
157
- | `gateway_manage_service` | Reconnect without changing config, or persistently enable/disable a service in the config and reload the registry. |
158
- | `gateway_call_tool` | Call one exact downstream tool and forward its result unchanged. The downstream tool may have read or write side effects. |
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
- All gateway tools with stable structured content expose an `outputSchema`. `gateway_call_tool` intentionally omits a fixed output schema because it forwards arbitrary downstream results. Its `arguments` object is always required; pass `{}` for a downstream tool with no arguments.
111
+ Recommended flow:
174
112
 
175
- `gateway_manage_service` actions:
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
- - `reconnect`: retry the current downstream lifecycle without modifying config.
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
- ## Skill Integration
120
+ ## Client Examples
182
121
 
183
- This repository includes a public gateway skill:
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
- Gemini CLI:
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
- Gemini CLI:
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 dev
141
+ npm run verify
142
+ node dist/index.js --config ./config.json --version
276
143
  ```
277
144
 
278
- Build and test:
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