@jadchene/mcp-gateway-service 0.6.4 → 0.7.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,153 +1,196 @@
1
- English | [简体中文](./README_zh.md)
2
-
3
- # MCP Gateway
4
-
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
-
7
- MCP Gateway v0.6.4 uses the official TypeScript SDK v2.
8
-
9
- > [!IMPORTANT]
10
- > MCP Gateway v0.6.2 and later accept only MCP `2026-07-28`, `2025-11-25`, and `2025-06-18`, using standard newline-delimited stdio or single-endpoint Streamable HTTP. Standalone HTTP+SSE (`/sse`), `Content-Length` framing, and other protocol revisions are not supported.
11
-
12
- ## Capabilities
13
-
14
- - Inbound MCP server over stdio and stateless Streamable HTTP.
15
- - Outbound MCP client over standard stdio and Streamable HTTP.
16
- - Automatic negotiation among MCP `2026-07-28`, `2025-11-25`, and `2025-06-18`.
17
- - All three standard revisions are served automatically on inbound transports.
18
- - Full downstream tool metadata and JSON Schema 2020-12 preservation.
19
- - Form-mode elicitation bridging across all supported revisions, 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
-
24
- ## Requirements and Installation
25
-
26
- - Node.js 24 or later.
27
-
28
- ```bash
29
- npm install -g @jadchene/mcp-gateway-service
30
- cp config.example.json config.json
31
- mcp-gateway-service --config ./config.json
32
- ```
33
-
34
- Enable the additional inbound HTTP endpoint:
35
-
36
- ```bash
37
- mcp-gateway-service --config ./config.json --http --host 127.0.0.1 --port 3100 --path /mcp
38
- ```
39
-
40
- When HTTP is enabled, the process serves both stdio and HTTP. Use `--version` or `-v` to print the installed version.
41
-
42
- ## Protocol Negotiation
43
-
44
- Protocol selection is automatic. The gateway and its downstream clients prefer MCP `2026-07-28`, then negotiate `2025-11-25` or `2025-06-18` when required by the peer. These are the only accepted protocol revisions. Inbound Streamable HTTP response shaping is selected automatically by the official SDK.
45
-
46
- Form-mode elicitation works across all three revisions. A 2025 downstream `elicitation/create` request is forwarded directly to a 2025 upstream client; for a 2026 upstream client, it is converted into `input_required` and resumed with the returned opaque `requestState` and `inputResponses`. Tool calls on each 2025 downstream connection are serialized so form responses cannot cross between calls.
47
-
48
- For MCP `2025-11-25`, the gateway negotiates only capabilities it implements. Experimental Tasks, URL-mode elicitation, and sampling tool calls are not advertised.
49
-
50
- ## Service Configuration
51
-
52
- Pass `--config`, set `MCP_GATEWAY_CONFIG`, or place `config.json` in the current directory.
53
-
54
- ```json
55
- {
56
- "logging": {
57
- "enable": false,
58
- "path": "./logs/mcp-gateway.log"
59
- },
60
- "services": [
61
- {
62
- "serviceId": "local-tools",
63
- "enable": true,
64
- "name": "Local Tools",
65
- "transport": {
66
- "type": "stdio",
67
- "command": "node",
68
- "args": ["./server.js"]
69
- }
70
- },
71
- {
72
- "serviceId": "remote-tools",
73
- "enable": true,
74
- "name": "Remote Tools",
75
- "transport": {
76
- "type": "http",
77
- "url": "http://127.0.0.1:3200/mcp",
78
- "headers": {
79
- "Authorization": "Bearer example-token"
80
- }
81
- }
82
- }
83
- ]
84
- }
85
- ```
86
-
87
- Common fields:
88
-
89
- - `enable` defaults to `true`.
90
- - `logging.enable` defaults to `false`. A relative log path is resolved from the config file directory.
91
- - Stdio always uses the standard newline-delimited JSON-RPC transport.
92
- - HTTP always uses the standard single-endpoint Streamable HTTP transport.
93
- - Protocol revision negotiation is automatic and has no configuration switch.
94
- - Static HTTP headers are supported. Header values and environment secrets are not written to logs.
95
-
96
- ## Inbound Streamable HTTP
97
-
98
- 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.
99
-
100
- The same endpoint serves MCP `2025-11-25` and `2025-06-18` through their standard stateless Streamable HTTP form. As a downstream client, the gateway preserves a session for either revision when a server issues `Mcp-Session-Id`.
101
-
102
- 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.
103
-
104
- ## Gateway Tools
105
-
106
- | Tool | Purpose |
107
- | --- | --- |
108
- | `gateway_list_services` | List configured downstream services and availability. |
109
- | `gateway_get_service` | Inspect one service's status, protocol version, and server identity. |
110
- | `gateway_list_tools` | Search tool names/descriptions; optionally include schemas. |
111
- | `gateway_get_tool_schema` | Fetch schemas for exact, case-sensitive tool names in one batch. |
112
- | `gateway_manage_service` | Reconnect or persistently enable/disable one configured service. |
113
- | `gateway_call_tool` | Call one downstream tool and preserve its MCP result. |
114
-
115
- Recommended flow:
116
-
117
- 1. Call `gateway_list_services`.
118
- 2. Call `gateway_list_tools` only for the relevant service, using `toolName` and/or `desc` filters.
119
- 3. Reuse schemas returned by `includeSchema: true`, or batch exact names with `gateway_get_tool_schema`.
120
- 4. Call `gateway_call_tool`; always provide `arguments`, using `{}` for a no-argument tool.
121
-
122
- `gateway_call_tool` intentionally has no fixed output schema because downstream `structuredContent` may be any JSON value. MCP `2026-07-28` MRTR results and bridged 2025 form elicitation are returned as `input_required` without automatic approval; the upstream client must declare form elicitation support and retry with matching `inputResponses` and the opaque `requestState`.
123
-
124
- ## Client Examples
125
-
126
- Stdio (Codex-style TOML):
127
-
128
- ```toml
129
- [mcp_servers.gateway]
130
- command = "mcp-gateway-service"
131
- args = ["--config", "./config.json"]
132
- ```
133
-
134
- Streamable HTTP:
135
-
136
- ```toml
137
- [mcp_servers.gateway]
138
- url = "http://127.0.0.1:3100/mcp"
139
- ```
140
-
141
- ## Development and Verification
142
-
143
- ```bash
144
- npm install
145
- npm run verify
146
- node dist/index.js --config ./config.json --version
147
- ```
148
-
149
- The repository also ships the public skill at `skills/mcp-gateway/SKILL.md`.
150
-
151
- ## License
152
-
153
- MIT. See [LICENSE](LICENSE).
1
+ English | [简体中文](./README_zh.md)
2
+
3
+ # MCP Gateway
4
+
5
+ ## Introduction
6
+
7
+ MCP Gateway puts multiple MCP services behind one endpoint. An agent connects to the gateway and sees six routing tools; downstream services, tools, and schemas are looked up only when they are needed.
8
+
9
+ The project uses the official TypeScript SDK v2 and requires Node.js 24 or later.
10
+
11
+ > [!IMPORTANT]
12
+ > MCP Gateway v0.6.2 and later accept only MCP `2026-07-28`, `2025-11-25`, and `2025-06-18`. Supported transports are newline-delimited stdio and single-endpoint Streamable HTTP. Standalone HTTP+SSE (`/sse`), `Content-Length` framing, and other protocol revisions are not supported.
13
+
14
+ ## Why Use It
15
+
16
+ - Keep the agent context small even when many MCP services are configured.
17
+ - Connect the agent once, then add or remove downstream services in the gateway config.
18
+ - Find tools by name or description and load schemas only when required.
19
+ - Use stdio and Streamable HTTP services through the same interface.
20
+ - Reload config changes without restarting the gateway.
21
+
22
+ ## Quick Start
23
+
24
+ ### Install
25
+
26
+ ```bash
27
+ npm install -g @jadchene/mcp-gateway-service
28
+ ```
29
+
30
+ Create `config.json`. Replace `your-mcp-service` with the command of an installed MCP server:
31
+
32
+ ```json
33
+ {
34
+ "services": [
35
+ {
36
+ "serviceId": "tools",
37
+ "name": "Tools",
38
+ "transport": {
39
+ "type": "stdio",
40
+ "command": "your-mcp-service"
41
+ }
42
+ }
43
+ ]
44
+ }
45
+ ```
46
+
47
+ ### Stdio
48
+
49
+ The agent starts the gateway process, so no separate startup command is needed.
50
+
51
+ Codex `config.toml`:
52
+
53
+ ```toml
54
+ [mcp_servers.gateway]
55
+ command = "mcp-gateway-service"
56
+ args = ["--config", "./config.json"]
57
+ ```
58
+
59
+ Claude Code:
60
+
61
+ ```bash
62
+ claude mcp add gateway -- mcp-gateway-service --config ./config.json
63
+ ```
64
+
65
+ ### Streamable HTTP
66
+
67
+ Start the gateway:
68
+
69
+ ```bash
70
+ mcp-gateway-service --http --config ./config.json
71
+ ```
72
+
73
+ The default endpoint is `http://127.0.0.1:3000/mcp`.
74
+ HTTP hides `gateway_manage_service` by default. Non-loopback binds require a bearer token in `MCP_GATEWAY_AUTH_TOKEN`.
75
+
76
+ Codex `config.toml`:
77
+
78
+ ```toml
79
+ [mcp_servers.gateway]
80
+ url = "http://127.0.0.1:3000/mcp"
81
+ ```
82
+
83
+ Claude Code:
84
+
85
+ ```bash
86
+ claude mcp add --transport http gateway http://127.0.0.1:3000/mcp
87
+ ```
88
+
89
+ ## Configuration and Tools
90
+
91
+ ### CLI Options
92
+
93
+ | Option | Description | Default |
94
+ | --- | --- | --- |
95
+ | `--config <path>` | Config file path. | `MCP_GATEWAY_CONFIG`, then `./config.json` |
96
+ | `--http` | Enables the Streamable HTTP endpoint. | Disabled |
97
+ | `--host <host>` | HTTP bind address. | `127.0.0.1` |
98
+ | `--port <port>` | HTTP port. | `3000` |
99
+ | `--path <path>` | HTTP endpoint path. | `/mcp` |
100
+ | `--auth-token-env <name>` | Environment variable containing the HTTP bearer token. | `MCP_GATEWAY_AUTH_TOKEN` |
101
+ | `--http-admin-tools` | Exposes `gateway_manage_service` over authenticated HTTP. | Disabled |
102
+ | `--max-concurrent-requests <n>` | Bounds in-flight HTTP requests. | `64` |
103
+ | `--version`, `-v` | Prints the installed version. | — |
104
+
105
+ Stdio remains available when `--http` is enabled.
106
+
107
+ ### Config File
108
+
109
+ ```json
110
+ {
111
+ "logging": {
112
+ "enable": false,
113
+ "path": "./logs/mcp-gateway.log"
114
+ },
115
+ "services": [
116
+ {
117
+ "serviceId": "local-tools",
118
+ "name": "Local Tools",
119
+ "transport": {
120
+ "type": "stdio",
121
+ "command": "your-mcp-service",
122
+ "args": []
123
+ }
124
+ },
125
+ {
126
+ "serviceId": "remote-tools",
127
+ "name": "Remote Tools",
128
+ "transport": {
129
+ "type": "http",
130
+ "url": "http://127.0.0.1:3200/mcp"
131
+ }
132
+ }
133
+ ]
134
+ }
135
+ ```
136
+
137
+ | Field | Description |
138
+ | --- | --- |
139
+ | `services` | List of downstream MCP services. |
140
+ | `serviceId` | Required unique identifier used by gateway tools. |
141
+ | `name` | Required display name. |
142
+ | `description` | Optional service description. |
143
+ | `enable` | Optional; defaults to `true`. |
144
+ | `callTimeoutMs` | Optional downstream tool-call timeout; defaults to 120 seconds. |
145
+ | `transport.type` | `stdio` or `http`. |
146
+ | `transport.command` | Required command for a stdio service. |
147
+ | `transport.args` | Optional command arguments for a stdio service. |
148
+ | `transport.cwd` | Optional working directory for a stdio service. |
149
+ | `transport.env` | Optional environment variables for a stdio service. |
150
+ | `transport.inheritEnv` | Opts into inheriting the complete gateway environment; defaults to `false`. |
151
+ | `transport.envAllowlist` | Additional process environment names passed to stdio services. |
152
+ | `transport.url` | Required Streamable HTTP URL for an HTTP service. |
153
+ | `transport.headers` | Optional static headers for an HTTP service. |
154
+ | `logging.enable` | Enables file logging; defaults to `false`. |
155
+ | `logging.path` | Log file path. Relative paths use the config file directory. |
156
+ | `logging.maxBytes` | Active log size before rotation; defaults to 10 MiB. |
157
+
158
+ The config file is watched for changes. Invalid updates are rejected and the last valid config stays active. See [config.example.json](./config.example.json) for another example.
159
+
160
+ ### Gateway Tools
161
+
162
+ | Tool | Description |
163
+ | --- | --- |
164
+ | `gateway_list_services` | Lists configured services and their availability. |
165
+ | `gateway_get_service` | Shows one service's connection state, protocol revision, server identity, and recent error. |
166
+ | `gateway_list_tools` | Searches a service's tools by name or description and can include schemas. |
167
+ | `gateway_get_tool_schema` | Returns schemas for exact tool names. |
168
+ | `gateway_manage_service` | Reconnects a service or enables/disables it in the config file. |
169
+ | `gateway_call_tool` | Calls one downstream tool and returns its MCP result. |
170
+
171
+ The usual flow is `gateway_list_services` → `gateway_list_tools` → `gateway_get_tool_schema` when needed → `gateway_call_tool`. Pass `{}` to `gateway_call_tool` when the downstream tool has no arguments.
172
+
173
+ Calls keep the downstream tool's original side effects and confirmation rules. An uncertain `gateway_call_tool` failure is never replayed automatically. Enabling or disabling a service with `gateway_manage_service` atomically updates the config file.
174
+
175
+ Agents with Skills support can use the included [MCP Gateway Skill](./skills/mcp-gateway/SKILL.md) for the discovery and calling workflow.
176
+
177
+ ## Development
178
+
179
+ ```bash
180
+ git clone https://github.com/jadchene/mcp-gateway.git
181
+ cd mcp-gateway
182
+ npm install
183
+ npm run verify
184
+ npm run dev -- --config ./config.json
185
+ ```
186
+
187
+ Build and run the compiled service:
188
+
189
+ ```bash
190
+ npm run build
191
+ npm start -- --config ./config.json
192
+ ```
193
+
194
+ ## License
195
+
196
+ [MIT](./LICENSE)