@jadchene/mcp-gateway-service 0.1.2 → 0.2.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,278 +1,274 @@
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 every downstream service:
42
-
43
- - database MCP
44
- - SSH MCP
45
- - IDE MCP
46
- - Playwright MCP
47
- - Gitea MCP
48
- - and more
49
-
50
- That quickly becomes hard to maintain:
51
-
52
- - every agent config needs to be updated when services change
53
- - command paths and environment variables are repeated
54
- - secrets and local machine details are spread across multiple client configs
55
- - different agents may drift out of sync over time
56
-
57
- 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.
58
-
59
- That gives you a cleaner architecture:
60
-
61
- - one MCP entry point for many services
62
- - one place to add, remove, or update downstream MCP definitions
63
- - one place to control what is exposed to agents
64
- - less duplicated local configuration
65
- - easier reuse across Codex, Claude Code, Gemini CLI, or other MCP-capable clients
66
-
67
- 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.
68
-
69
- ## Key Pillars
70
-
71
- ### Token-Efficient Discovery
72
- - Keep the public tool surface small and stable.
73
- - Discover services first, then tools for one service, then schema for one tool.
74
- - Avoid sending hundreds of downstream tools to the model at session start.
75
-
76
- ### Stable Gateway Surface
77
- - Expose a fixed gateway contract instead of dynamically flattening downstream tools.
78
- - Return compact discovery payloads for service and tool enumeration.
79
- - Forward downstream tool results directly to the caller for minimal wrapping.
80
-
81
- ### Practical Operations
82
- - Load a static service pool from JSON.
83
- - Reload config automatically when the file changes.
84
- - Stop removed, disabled, or replaced downstream processes during hot reload.
85
- - Restart failed downstream processes up to 3 times before marking them unavailable.
86
- - Preserve the last valid config snapshot when a reload fails.
87
-
88
- ## Quick Start
89
-
90
- ### Install globally
91
-
92
- ```bash
93
- npm install -g @jadchene/mcp-gateway-service
94
- ```
95
-
96
- Start the gateway:
97
-
98
- ```bash
99
- mcp-gateway-service
100
- ```
101
-
102
- With an explicit config path:
103
-
104
- ```bash
105
- mcp-gateway-service --config ./config.json
106
- ```
107
-
108
- ### Run from source
109
-
110
- Create a local `config.json` from `config.example.json`, then start the gateway:
111
-
112
- ```bash
113
- npm install
114
- npm run dev
115
- ```
116
-
117
- By default the gateway loads `./config.json`.
118
- 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`.
119
-
120
- Override it with:
121
-
122
- ```bash
123
- $env:MCP_GATEWAY_CONFIG="config/gateway/config.json"
124
- npm run dev
125
- ```
126
-
127
- ### Version
128
-
129
- ```bash
130
- mcp-gateway-service --version
131
- ```
132
-
133
- Short form:
134
-
135
- ```bash
136
- mcp-gateway-service -v
137
- ```
138
-
139
- ## Configuration
140
-
141
- The gateway currently supports `stdio` downstream transports only.
142
-
143
- A gateway log file is written to `mcp-gateway.log` under `logDirectory`. If `logDirectory` is omitted, the gateway writes logs to the current working directory.
144
-
145
- 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.
146
-
147
- - `logDirectory` is optional. When omitted, the gateway writes `mcp-gateway.log` to the current working directory.
148
- - `enable` is optional. When omitted, the gateway treats the service as enabled.
149
- - `cwd` is optional. When omitted, the gateway uses its current working directory.
150
- - `env` is optional.
151
- - `framing` is optional. When omitted, the gateway tries `line` first and then `content-length`.
152
-
153
- ### Config shape
154
-
155
- ```json
156
- {
157
- "logDirectory": "./logs",
158
- "services": [
159
- {
160
- "serviceId": "demo-echo",
161
- "enable": true,
162
- "name": "Demo Echo Service",
163
- "description": "Sample echo MCP service.",
164
- "transport": {
165
- "type": "stdio",
166
- "command": "node",
167
- "args": [
168
- "--experimental-strip-types",
169
- "examples/echo-service.ts"
170
- ]
171
- }
172
- }
173
- ]
174
- }
175
- ```
176
-
177
- ## Public Gateway Tools
178
-
179
- The gateway exposes a fixed set of discovery and routing tools:
180
-
181
- - `gateway.listServices`
182
- - `gateway.getService`
183
- - `gateway.listTools`
184
- - `gateway.getToolSchema`
185
- - `gateway.callTool`
186
-
187
- ### Response design
188
-
189
- - `gateway.listServices` returns only `serviceId`, `description`, and `available`.
190
- - `gateway.listTools` returns only `name` and `description`.
191
- - `gateway.getToolSchema` returns only `inputSchema` and `outputSchema`.
192
- - `gateway.callTool` forwards the downstream MCP tool result directly without extra gateway metadata wrapping.
193
-
194
- ## Recommended Client Workflow
195
-
196
- For the best token efficiency, the MCP client should cache discovery results instead of repeatedly querying the gateway:
197
-
198
- 1. Call `gateway.listServices` once at session start.
199
- 2. Call `gateway.listTools(serviceId)` only when a service is actually needed.
200
- 3. Call `gateway.getToolSchema(serviceId, toolName)` only before the first use of that tool.
201
- 4. Call `gateway.callTool(...)` for execution.
202
- 5. Refresh discovery data only when a call fails, the config changes, or the client explicitly wants a refresh.
203
-
204
- ## Skill Integration (Recommended)
205
-
206
- This repository includes a public skill for agent frameworks that support skill loading:
207
-
208
- - Skill path: `skills/mcp-gateway/SKILL.md`
209
-
210
- The skill focuses on:
211
-
212
- - token-efficient discovery flow
213
- - avoiding unnecessary schema/tool enumeration
214
- - calling downstream tools through the minimal gateway contract
215
-
216
- ## MCP Client Configuration
217
-
218
- The examples below intentionally use relative config paths so they stay portable.
219
-
220
- ### Codex
221
-
222
- `~/.codex/config.toml`
223
-
224
- ```toml
225
- [mcp_servers.gateway]
226
- command = "mcp-gateway-service"
227
- args = ["--config", "./config.json"]
228
- ```
229
-
230
- ### Gemini CLI
231
-
232
- `~/.gemini/settings.json`
233
-
234
- ```json
235
- {
236
- "mcpServers": {
237
- "gateway": {
238
- "type": "stdio",
239
- "command": "mcp-gateway-service",
240
- "args": [
241
- "--config",
242
- "./config.json"
243
- ]
244
- }
245
- }
246
- }
247
- ```
248
-
249
- ### Claude Code
250
-
251
- `~/.claude.json`
252
-
253
- ```json
254
- {
255
- "mcpServers": {
256
- "gateway": {
257
- "type": "stdio",
258
- "command": "mcp-gateway-service",
259
- "args": [
260
- "--config",
261
- "./config.json"
262
- ]
263
- }
264
- }
265
- }
266
- ```
267
-
268
- ## Development Notes
269
-
270
- - Repository-managed `config.json` and `config.example.json` are examples only.
271
- - Copy `config.example.json` to your own local `config.json` before running the gateway.
272
- - Keep real local configs and logs outside the repository.
273
- - Downstream output schema is returned only when the downstream service exposes it.
274
- - Windows command resolution supports PowerShell shims such as `.ps1`-backed command aliases.
275
-
276
- ## License
277
-
278
- Released under the [MIT License](./LICENSE).
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 every downstream service:
42
+
43
+ - database MCP
44
+ - SSH MCP
45
+ - IDE MCP
46
+ - Playwright MCP
47
+ - Gitea MCP
48
+ - and more
49
+
50
+ That quickly becomes hard to maintain:
51
+
52
+ - every agent config needs to be updated when services change
53
+ - command paths and environment variables are repeated
54
+ - secrets and local machine details are spread across multiple client configs
55
+ - different agents may drift out of sync over time
56
+
57
+ 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.
58
+
59
+ That gives you a cleaner architecture:
60
+
61
+ - one MCP entry point for many services
62
+ - one place to add, remove, or update downstream MCP definitions
63
+ - one place to control what is exposed to agents
64
+ - less duplicated local configuration
65
+ - easier reuse across Codex, Claude Code, Gemini CLI, or other MCP-capable clients
66
+
67
+ 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.
68
+
69
+ ## Key Pillars
70
+
71
+ ### Token-Efficient Discovery
72
+ - Keep the public tool surface small and stable.
73
+ - Discover services first, then tools for one service, then schema for one tool.
74
+ - Avoid sending hundreds of downstream tools to the model at session start.
75
+
76
+ ### Stable Gateway Surface
77
+ - Expose a fixed gateway contract instead of dynamically flattening downstream tools.
78
+ - Return compact discovery payloads for service and tool enumeration.
79
+ - Forward downstream tool results directly to the caller for minimal wrapping.
80
+
81
+ ### Practical Operations
82
+ - Load a static service pool from JSON.
83
+ - Reload config automatically when the file changes.
84
+ - Stop removed, disabled, or replaced downstream processes during hot reload.
85
+ - Restart failed downstream processes up to 3 times before marking them unavailable.
86
+ - Preserve the last valid config snapshot when a reload fails.
87
+
88
+ ## Quick Start
89
+
90
+ ### Install globally
91
+
92
+ ```bash
93
+ npm install -g @jadchene/mcp-gateway-service
94
+ ```
95
+
96
+ Start the gateway:
97
+
98
+ ```bash
99
+ mcp-gateway-service
100
+ ```
101
+
102
+ With an explicit config path:
103
+
104
+ ```bash
105
+ mcp-gateway-service --config ./config.json
106
+ ```
107
+
108
+ ### Run from source
109
+
110
+ Create a local `config.json` from `config.example.json`, then start the gateway:
111
+
112
+ ```bash
113
+ npm install
114
+ npm run dev
115
+ ```
116
+
117
+ By default the gateway loads `./config.json`.
118
+ 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`.
119
+
120
+ Override it with:
121
+
122
+ ```bash
123
+ $env:MCP_GATEWAY_CONFIG="config/gateway/config.json"
124
+ npm run dev
125
+ ```
126
+
127
+ ### Version
128
+
129
+ ```bash
130
+ mcp-gateway-service --version
131
+ ```
132
+
133
+ Short form:
134
+
135
+ ```bash
136
+ mcp-gateway-service -v
137
+ ```
138
+
139
+ ## Configuration
140
+
141
+ The gateway currently supports `stdio` downstream transports only.
142
+
143
+ 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.
144
+
145
+ - `enable` is optional. When omitted, the gateway treats the service as enabled.
146
+ - `cwd` is optional. When omitted, the gateway uses its current working directory.
147
+ - `env` is optional.
148
+ - `framing` is optional. When omitted, the gateway tries `line` first and then `content-length`.
149
+
150
+ ### Config shape
151
+
152
+ ```json
153
+ {
154
+ "services": [
155
+ {
156
+ "serviceId": "demo-echo",
157
+ "enable": true,
158
+ "name": "Demo Echo Service",
159
+ "description": "Sample echo MCP service.",
160
+ "transport": {
161
+ "type": "stdio",
162
+ "command": "node",
163
+ "args": [
164
+ "--experimental-strip-types",
165
+ "examples/echo-service.ts"
166
+ ]
167
+ }
168
+ }
169
+ ]
170
+ }
171
+ ```
172
+
173
+ ## Public Gateway Tools
174
+
175
+ The gateway exposes a fixed set of discovery and routing tools:
176
+
177
+ - `gateway.listServices`
178
+ - `gateway.getService`
179
+ - `gateway.listTools`
180
+ - `gateway.getToolSchema`
181
+ - `gateway.callTool`
182
+
183
+ ### Response design
184
+
185
+ - `gateway.listServices` returns only `serviceId`, `description`, and `available`.
186
+ - `gateway.listTools` returns only `name` and `description`.
187
+ - `gateway.getToolSchema` returns only `inputSchema` and `outputSchema`.
188
+ - `gateway.callTool` forwards the downstream MCP tool result directly without extra gateway metadata wrapping.
189
+
190
+ ## Recommended Client Workflow
191
+
192
+ For the best token efficiency, the MCP client should cache discovery results instead of repeatedly querying the gateway:
193
+
194
+ 1. Call `gateway.listServices` once at session start.
195
+ 2. Call `gateway.listTools(serviceId)` only when a service is actually needed.
196
+ 3. Call `gateway.getToolSchema(serviceId, toolName)` only before the first use of that tool.
197
+ 4. Call `gateway.callTool(...)` for execution.
198
+ 5. Refresh discovery data only when a call fails, the config changes, or the client explicitly wants a refresh.
199
+
200
+ ## Skill Integration (Recommended)
201
+
202
+ This repository includes a public skill for agent frameworks that support skill loading:
203
+
204
+ - Skill path: `skills/mcp-gateway/SKILL.md`
205
+
206
+ The skill focuses on:
207
+
208
+ - token-efficient discovery flow
209
+ - avoiding unnecessary schema/tool enumeration
210
+ - calling downstream tools through the minimal gateway contract
211
+
212
+ ## MCP Client Configuration
213
+
214
+ The examples below intentionally use relative config paths so they stay portable.
215
+
216
+ ### Codex
217
+
218
+ `~/.codex/config.toml`
219
+
220
+ ```toml
221
+ [mcp_servers.gateway]
222
+ command = "mcp-gateway-service"
223
+ args = ["--config", "./config.json"]
224
+ ```
225
+
226
+ ### Gemini CLI
227
+
228
+ `~/.gemini/settings.json`
229
+
230
+ ```json
231
+ {
232
+ "mcpServers": {
233
+ "gateway": {
234
+ "type": "stdio",
235
+ "command": "mcp-gateway-service",
236
+ "args": [
237
+ "--config",
238
+ "./config.json"
239
+ ]
240
+ }
241
+ }
242
+ }
243
+ ```
244
+
245
+ ### Claude Code
246
+
247
+ `~/.claude.json`
248
+
249
+ ```json
250
+ {
251
+ "mcpServers": {
252
+ "gateway": {
253
+ "type": "stdio",
254
+ "command": "mcp-gateway-service",
255
+ "args": [
256
+ "--config",
257
+ "./config.json"
258
+ ]
259
+ }
260
+ }
261
+ }
262
+ ```
263
+
264
+ ## Development Notes
265
+
266
+ - Repository-managed `config.json` and `config.example.json` are examples only.
267
+ - Copy `config.example.json` to your own local `config.json` before running the gateway.
268
+ - Keep real local configs and logs outside the repository.
269
+ - Downstream output schema is returned only when the downstream service exposes it.
270
+ - Windows command resolution supports PowerShell shims such as `.ps1`-backed command aliases.
271
+
272
+ ## License
273
+
274
+ Released under the [MIT License](./LICENSE).