@jadchene/mcp-gateway-service 0.4.3 → 0.5.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
@@ -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,173 @@ 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_list_services`
219
- - `gateway_get_service`
220
- - `gateway_list_tools`
221
- - `gateway_get_tool_schema`
222
- - `gateway_manage_service`
223
- - `gateway_call_tool`
224
-
225
- ### Response design
226
-
227
- - `gateway_list_services` returns only `serviceId`, `description`, and `available`.
228
- - `gateway_list_tools` returns only `name` and `description`; pass optional `toolName` as a string or string array to filter names by substring.
229
- - `gateway_get_tool_schema` returns only `inputSchema` and `outputSchema`.
230
- - `gateway_manage_service` returns only `serviceId`, `action`, `enabled`, and `available`.
231
- - `gateway_call_tool` 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_list_services`, `gateway_list_tools`, `gateway_get_tool_schema`, and `gateway_call_tool`.
236
- - `gateway_get_service` is primarily for diagnostics, such as checking recent service errors, connection state, protocol version, or downstream server info.
237
- - `gateway_manage_service` is an operational tool for explicit service control, not part of the normal discovery flow.
238
-
239
- ### `gateway_manage_service`
240
-
241
- Use `gateway_manage_service` 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_list_services` once at session start.
264
- 2. Call `gateway_list_tools(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_get_tool_schema(serviceId, toolName)` only before the first use of that tool.
266
- 4. Call `gateway_call_tool(...)` for execution.
267
- 5. Use `gateway_get_service` only when diagnostics are explicitly needed.
268
- 6. Use `gateway_manage_service` 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 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.
172
+
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.
174
+
175
+ `gateway_manage_service` actions:
176
+
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.
180
+
181
+ ## Skill Integration
182
+
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:
192
+
193
+ ```toml
194
+ [mcp_servers.gateway]
195
+ command = "mcp-gateway-service"
196
+ args = ["--config", "./config.json"]
197
+ ```
198
+
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:
238
+
239
+ ```toml
240
+ [mcp_servers.gateway]
241
+ url = "http://127.0.0.1:3100/mcp"
242
+ ```
243
+
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
272
+
273
+ ```bash
274
+ npm install
275
+ npm run dev
276
+ ```
277
+
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
+ ```
290
+
291
+ ## License
292
+
293
+ MIT. See [LICENSE](LICENSE).