@jadchene/mcp-gateway-service 0.4.2 → 0.4.4

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
@@ -1,166 +1,86 @@
1
- English | [简体中文](./README_zh.md)
2
-
3
- # MCP Gateway
4
-
5
- This project provides a lightweight Model Context Protocol (MCP) gateway for **token-efficient, on-demand discovery** and **one unified entry point for multiple downstream services**.
6
-
7
- Instead of exposing every downstream MCP tool up front, the gateway keeps a small fixed tool surface and lets the client discover services, list tools for a specific service, fetch one tool schema when needed, and then forward the actual tool call.
8
-
9
- ## Why Use This Gateway
10
-
11
- This gateway is designed for a practical problem that appears quickly once you use multiple MCP services across multiple agents.
12
-
13
- If every agent connects directly to every MCP service, two problems show up:
14
-
15
- 1. The tool surface becomes too large.
16
- 2. The MCP configuration becomes too repetitive.
17
-
18
- ### 1. Reduce token consumption
19
-
20
- Many MCP services expose dozens or even hundreds of tools.
21
-
22
- If an agent connects directly to several MCP services, the client often needs to expose or describe a very large tool inventory up front. That increases:
23
-
24
- - prompt size
25
- - tool discovery cost
26
- - repeated schema/context overhead across sessions
27
-
28
- This gateway avoids that by exposing a **small fixed discovery interface** instead of flattening every downstream tool into the initial tool list.
29
-
30
- The normal flow becomes:
31
-
32
- 1. list available services
33
- 2. inspect tools for one selected service
34
- 3. fetch schema for one selected tool
35
- 4. call that tool
36
-
37
- That means the model only sees the minimum amount of MCP metadata needed for the current task.
38
-
39
- ### 2. Provide one unified MCP entry point for multiple agents
40
-
41
- Without a gateway, each agent usually needs its own MCP client configuration for multiple downstream services.
42
-
43
- That quickly becomes hard to maintain:
44
-
45
- - every agent config needs to be updated when services change
46
- - command paths and environment variables are repeated
47
- - secrets and local machine details are spread across multiple client configs
48
- - different agents may drift out of sync over time
49
-
50
- With this gateway, the downstream MCP pool is defined once in one config file, and every agent only needs to connect to the gateway itself.
51
-
52
- That gives you a cleaner architecture:
53
-
54
- - one MCP entry point for many services
55
- - one place to add, remove, or update downstream MCP definitions
56
- - one place to control what is exposed to agents
57
- - less duplicated local configuration
58
- - easier reuse across Codex, Claude Code, Gemini CLI, or other MCP-capable clients
59
-
60
- In short, this gateway is useful when you want to treat multiple MCP services as a managed service pool rather than reconfiguring the same MCP stack separately for every agent.
61
-
62
- ## Key Pillars
63
-
64
- ### Token-Efficient Discovery
65
- - Keep the public tool surface small and stable.
66
- - Discover services first, then tools for one service, then schema for one tool.
67
- - Avoid sending hundreds of downstream tools to the model at session start.
68
-
69
- ### Stable Gateway Surface
70
- - Expose a fixed gateway contract instead of dynamically flattening downstream tools.
71
- - Return compact discovery payloads for service and tool enumeration.
72
- - Forward downstream tool results directly to the caller for minimal wrapping.
73
-
74
- ### Practical Operations
75
- - Load a static service pool from JSON.
76
- - Reload config automatically when the file changes.
77
- - Stop removed, disabled, or replaced downstream processes during hot reload.
78
- - Restart failed downstream processes up to 3 times before marking them unavailable.
79
- - Preserve the last valid config snapshot when a reload fails.
80
-
81
- ## Quick Start
82
-
83
- ### Install globally
84
-
85
- ```bash
86
- npm install -g @jadchene/mcp-gateway-service
87
- ```
88
-
89
- Start the gateway:
90
-
91
- ```bash
92
- mcp-gateway-service
93
- ```
94
-
95
- With an explicit config path:
1
+ English | [简体中文](./README_zh.md)
2
+
3
+ # MCP Gateway
4
+
5
+ MCP Gateway is a lightweight Model Context Protocol gateway that exposes one small MCP entry point for multiple downstream MCP services.
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.
8
+
9
+ ## Features
10
+
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`.
21
+
22
+ ## Why Use It
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.
27
+
28
+ ## Quick Start
29
+
30
+ Install globally:
31
+
32
+ ```bash
33
+ npm install -g @jadchene/mcp-gateway-service
34
+ ```
35
+
36
+ Create a local config:
37
+
38
+ ```bash
39
+ cp config.example.json config.json
40
+ ```
41
+
42
+ Start the stdio gateway:
96
43
 
97
44
  ```bash
98
45
  mcp-gateway-service --config ./config.json
99
46
  ```
100
47
 
101
- Expose the same gateway over Streamable HTTP with CLI arguments:
48
+ Start with inbound Streamable HTTP:
49
+
50
+ ```bash
51
+ mcp-gateway-service --config ./config.json --http --host 127.0.0.1 --port 3100 --path /mcp
52
+ ```
53
+
54
+ Use stateless JSON responses for HTTP clients that expect direct JSON-RPC responses from `POST`:
102
55
 
103
56
  ```bash
104
- mcp-gateway-service --config ./config.json --http --port 3100 --path /mcp
57
+ mcp-gateway-service --config ./config.json --http --port 3100 --path /mcp --json-response
105
58
  ```
106
59
 
107
- Use `--json-response` when the HTTP client expects stateless JSON-RPC responses directly from `POST` requests:
60
+ Check the installed version:
108
61
 
109
62
  ```bash
110
- mcp-gateway-service --config ./config.json --http --port 3100 --json-response
63
+ mcp-gateway-service --version
64
+ mcp-gateway-service -v
111
65
  ```
112
-
113
- ### Run from source
114
-
115
- Create a local `config.json` from `config.example.json`, then start the gateway:
116
-
117
- ```bash
118
- npm install
119
- npm run dev
120
- ```
121
-
122
- By default the gateway loads `./config.json`.
123
- Use `--config <path>` to override it for the current process. If `--config` is omitted, the gateway falls back to `MCP_GATEWAY_CONFIG`, then `./config.json`.
124
-
125
- Override it with:
126
-
127
- ```bash
128
- $env:MCP_GATEWAY_CONFIG="config/gateway/config.json"
129
- npm run dev
130
- ```
131
-
132
- ### Version
133
-
134
- ```bash
135
- mcp-gateway-service --version
136
- ```
137
-
138
- Short form:
139
-
140
- ```bash
141
- mcp-gateway-service -v
142
- ```
143
-
66
+
144
67
  ## Configuration
145
68
 
146
- The gateway supports `stdio` and Streamable HTTP downstream transports. Inbound Streamable HTTP is enabled only with CLI arguments, not with `config.json`, so stdio-based agents can safely share the same service-pool config without accidentally starting an HTTP listener.
69
+ Pass the config file by CLI argument:
147
70
 
148
- A service is loaded only when `enable` is missing or set to `true`. If `enable` is set to `false`, the gateway skips that service entirely. During hot reload, disabling or removing a service also stops its existing downstream process if one is running.
71
+ ```bash
72
+ mcp-gateway-service --config ./config.json
73
+ ```
149
74
 
150
- - `logging.enable` is optional and defaults to `false`.
151
- - `logging.path` is required only when `logging.enable` is `true`.
152
- - When enabled, the gateway writes newline-delimited JSON logs to the configured file and never writes operational logs to MCP `stdout` or `stderr`.
153
- - Relative `logging.path` values are resolved from the config file directory.
154
- - Logging config supports hot reload, so changing `logging.enable` or `logging.path` in the config file takes effect without restarting the gateway.
155
- - `enable` is optional. When omitted, the gateway treats the service as enabled.
156
- - `cwd` is optional. When omitted, the gateway uses its current working directory.
157
- - `env` is optional.
158
- - `framing` is optional. When omitted, the gateway tries `line` first and then `content-length`.
159
- - HTTP downstream transports use `transport.type: "http"` and a single `transport.url`.
160
- - `transport.headers` can provide static headers for an HTTP downstream service.
161
- - `transport.enableJsonResponse` enables stateless JSON response mode for an HTTP downstream service.
75
+ Or by environment variable:
162
76
 
163
- ### Config shape
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:
164
84
 
165
85
  ```json
166
86
  {
@@ -171,15 +91,15 @@ A service is loaded only when `enable` is missing or set to `true`. If `enable`
171
91
  "services": [
172
92
  {
173
93
  "serviceId": "demo-echo",
174
- "enable": true,
175
- "name": "Demo Echo Service",
176
- "description": "Sample echo MCP service.",
177
- "transport": {
178
- "type": "stdio",
179
- "command": "node",
180
- "args": [
181
- "--experimental-strip-types",
182
- "examples/echo-service.ts"
94
+ "enable": true,
95
+ "name": "Demo Echo Service",
96
+ "description": "Sample echo MCP service.",
97
+ "transport": {
98
+ "type": "stdio",
99
+ "command": "node",
100
+ "args": [
101
+ "--experimental-strip-types",
102
+ "examples/echo-service.ts"
183
103
  ]
184
104
  }
185
105
  },
@@ -192,7 +112,7 @@ A service is loaded only when `enable` is missing or set to `true`. If `enable`
192
112
  "type": "http",
193
113
  "url": "http://127.0.0.1:3200/mcp",
194
114
  "headers": {
195
- "Authorization": "Bearer replace-me"
115
+ "Authorization": "Bearer ${MCP_TOKEN}"
196
116
  },
197
117
  "enableJsonResponse": false
198
118
  }
@@ -201,147 +121,169 @@ A service is loaded only when `enable` is missing or set to `true`. If `enable`
201
121
  }
202
122
  ```
203
123
 
204
- ### Streamable HTTP notes
205
-
206
- - The gateway uses one endpoint for both `GET` and `POST`.
207
- - Inbound HTTP is enabled only by the explicit `--http` CLI option, optionally with settings such as `--port 3100 --path /mcp`.
208
- - Passing `--port`, `--host`, `--path`, or `--json-response` without `--http` does not start an HTTP listener.
209
- - `GET /mcp` opens the SSE read channel and returns the session in the `Mcp-Session-Id` header.
210
- - `POST /mcp` sends JSON-RPC messages. The preferred session binding is the `Mcp-Session-Id` header.
211
- - Query-string `sessionId` is accepted for compatibility, but new clients should use the header.
212
- - The `endpoint` SSE event advertises the single path, such as `/mcp`, without embedding the session id in the URL.
213
-
214
- ## Public Gateway Tools
215
-
216
- The gateway exposes a fixed set of discovery and routing tools:
217
-
218
- - `gateway.listServices`
219
- - `gateway.getService`
220
- - `gateway.listTools`
221
- - `gateway.getToolSchema`
222
- - `gateway.manageService`
223
- - `gateway.callTool`
224
-
225
- ### Response design
226
-
227
- - `gateway.listServices` returns only `serviceId`, `description`, and `available`.
228
- - `gateway.listTools` returns only `name` and `description`; pass optional `toolName` as a string or string array to filter names by substring.
229
- - `gateway.getToolSchema` returns only `inputSchema` and `outputSchema`.
230
- - `gateway.manageService` returns only `serviceId`, `action`, `enabled`, and `available`.
231
- - `gateway.callTool` forwards the downstream MCP tool result directly without extra gateway metadata wrapping.
232
-
233
- ### Default workflow vs diagnostics
234
-
235
- - The default token-efficient workflow still uses four tools: `gateway.listServices`, `gateway.listTools`, `gateway.getToolSchema`, and `gateway.callTool`.
236
- - `gateway.getService` is primarily for diagnostics, such as checking recent service errors, connection state, protocol version, or downstream server info.
237
- - `gateway.manageService` is an operational tool for explicit service control, not part of the normal discovery flow.
238
-
239
- ### `gateway.manageService`
240
-
241
- Use `gateway.manageService` when you explicitly need to reconnect a service or persistently change its enabled state.
242
-
243
- Input:
244
-
245
- - `serviceId`: logical service identifier
246
- - `action`: one of `reconnect`, `enable`, or `disable`
247
-
248
- Action behavior:
249
-
250
- - `reconnect`: immediately tries to start and reinitialize the specified downstream MCP again. Use this when a service previously failed because its dependency was not ready, such as an IDE that was not open yet.
251
- - `enable`: writes `enable: true` to the config file for that service and triggers a reload.
252
- - `disable`: writes `enable: false` to the config file for that service and triggers a reload.
253
-
254
- Important notes:
255
-
256
- - `enable` and `disable` are persisted to the JSON config file. They are not session-only toggles.
257
- - `reconnect` does not modify the config file. It only retries the current service lifecycle.
258
-
259
- ## Recommended Client Workflow
260
-
261
- For the best token efficiency, the MCP client should cache discovery results instead of repeatedly querying the gateway:
262
-
263
- 1. Call `gateway.listServices` once at session start.
264
- 2. Call `gateway.listTools(serviceId)` only when a service is actually needed, optionally with `toolName` to narrow large tool lists by one or more keywords.
265
- 3. Call `gateway.getToolSchema(serviceId, toolName)` only before the first use of that tool.
266
- 4. Call `gateway.callTool(...)` for execution.
267
- 5. Use `gateway.getService` only when diagnostics are explicitly needed.
268
- 6. Use `gateway.manageService` only when a service must be reconnected or explicitly enabled/disabled.
269
- 7. Refresh discovery data only when a call fails, the config changes, or the client explicitly wants a refresh.
270
-
271
- ## Skill Integration (Recommended)
272
-
273
- This repository includes a public skill for agent frameworks that support skill loading:
274
-
275
- - Skill path: `skills/mcp-gateway/SKILL.md`
276
-
277
- The skill focuses on:
278
-
279
- - token-efficient discovery flow
280
- - avoiding unnecessary schema/tool enumeration
281
- - calling downstream tools through the minimal gateway contract
282
-
283
- ## MCP Client Configuration
284
-
285
- The examples below intentionally use relative config paths so they stay portable.
286
-
287
- ### Codex
288
-
289
- `~/.codex/config.toml`
290
-
291
- ```toml
292
- [mcp_servers.gateway]
293
- command = "mcp-gateway-service"
294
- args = ["--config", "./config.json"]
295
- ```
296
-
297
- ### Gemini CLI
298
-
299
- `~/.gemini/settings.json`
300
-
301
- ```json
302
- {
303
- "mcpServers": {
304
- "gateway": {
305
- "type": "stdio",
306
- "command": "mcp-gateway-service",
307
- "args": [
308
- "--config",
309
- "./config.json"
310
- ]
311
- }
312
- }
313
- }
314
- ```
315
-
316
- ### Claude Code
317
-
318
- `~/.claude.json`
319
-
320
- ```json
321
- {
322
- "mcpServers": {
323
- "gateway": {
324
- "type": "stdio",
325
- "command": "mcp-gateway-service",
326
- "args": [
327
- "--config",
328
- "./config.json"
329
- ]
330
- }
331
- }
332
- }
333
- ```
334
-
335
- ## Development Notes
336
-
337
- - Repository-managed `config.json` and `config.example.json` are examples only.
338
- - Copy `config.example.json` to your own local `config.json` before running the gateway.
339
- - Keep real local configs and logs outside the repository.
340
- - File logging is disabled by default so MCP startup stays quiet unless you explicitly enable it.
341
- - Downstream output schema is returned only when the downstream service exposes it.
342
- - Windows command resolution supports PowerShell shims such as `.ps1`-backed command aliases.
343
- - On Windows, the gateway prefers `pwsh` for `.ps1` shim resolution and execution, and automatically falls back to `powershell.exe` when `pwsh` is unavailable.
344
-
345
- ## License
346
-
347
- Released under the [MIT License](./LICENSE).
124
+ Configuration notes:
125
+
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.
135
+
136
+ ## Inbound Streamable HTTP
137
+
138
+ Inbound HTTP is enabled only with `--http`. Passing `--host`, `--port`, `--path`, or `--json-response` without `--http` does not start an HTTP listener.
139
+
140
+ The HTTP endpoint uses the same path for `GET` and `POST`:
141
+
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`.
146
+
147
+ ## Gateway Tools
148
+
149
+ The gateway exposes six public tools:
150
+
151
+ | Tool | Purpose |
152
+ | --- | --- |
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.
170
+
171
+ `gateway_manage_service` actions:
172
+
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.
176
+
177
+ ## Skill Integration
178
+
179
+ This repository includes a public gateway skill:
180
+
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:
188
+
189
+ ```toml
190
+ [mcp_servers.gateway]
191
+ command = "mcp-gateway-service"
192
+ args = ["--config", "./config.json"]
193
+ ```
194
+
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:
234
+
235
+ ```toml
236
+ [mcp_servers.gateway]
237
+ url = "http://127.0.0.1:3100/mcp"
238
+ ```
239
+
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
268
+
269
+ ```bash
270
+ npm install
271
+ npm run dev
272
+ ```
273
+
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
+ ```
286
+
287
+ ## License
288
+
289
+ MIT. See [LICENSE](LICENSE).