@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 +196 -153
- package/README_zh.md +196 -153
- package/config.example.json +34 -30
- package/dist/config.js +47 -5
- package/dist/file-watcher.js +16 -2
- package/dist/gateway-engine.js +5 -2
- package/dist/http-server.js +57 -1
- package/dist/index.js +41 -6
- package/dist/logger.js +83 -49
- package/dist/mcp/client.js +11 -4
- package/dist/mcp/form-elicitation-bridge.js +51 -2
- package/dist/mcp/sdk-client.js +30 -4
- package/dist/mcp/server.js +5 -5
- package/dist/service-registry.js +97 -31
- package/package.json +16 -12
- package/scripts/install-global.ps1 +46 -15
- package/skills/mcp-gateway/SKILL.md +26 -90
package/README.md
CHANGED
|
@@ -1,153 +1,196 @@
|
|
|
1
|
-
English | [简体中文](./README_zh.md)
|
|
2
|
-
|
|
3
|
-
# MCP Gateway
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
MCP Gateway
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
-
|
|
17
|
-
-
|
|
18
|
-
-
|
|
19
|
-
-
|
|
20
|
-
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
```
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
```
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
```
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
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)
|