@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 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
- ```
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
- Or by environment variable:
42
+ ## Protocol Negotiation
76
43
 
77
- ```bash
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
- If neither is provided, the service tries `config.json` in the current working directory.
46
+ ## Service Configuration
82
47
 
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,101 +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 all downstream MCP services managed by the gateway, including each `serviceId`, description, and availability. |
154
- | `gateway_get_service` | Return one service summary, runtime state, recent errors, and cached metadata. Use this for diagnostics. |
155
- | `gateway_list_tools` | List tools exposed by one downstream service. Optional `toolName` filters by one or more name fragments; `includeSchema: true` includes each matching tool's input and output schemas. |
156
- | `gateway_get_tool_schema` | Return input and output schemas for one or more exact tool names, keyed by tool name. |
157
- | `gateway_manage_service` | Reconnect a service or persistently enable/disable it in the config file. |
158
- | `gateway_call_tool` | Call one downstream tool through the gateway and return the downstream MCP result. |
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
- `gateway_manage_service` actions:
111
+ Recommended flow:
172
112
 
173
- - `reconnect`: retry the current downstream lifecycle without modifying config.
174
- - `enable`: persist `enable: true` for the service and reload config.
175
- - `disable`: persist `enable: false` for the service and reload config.
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
- ## Skill Integration
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
- This repository includes a public gateway skill:
120
+ ## Client Examples
180
121
 
181
- - Skill path: `skills/mcp-gateway/SKILL.md`
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
- 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 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
- 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
- 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 dev
141
+ npm run verify
142
+ node dist/index.js --config ./config.json --version
272
143
  ```
273
144
 
274
- Build and test:
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