@jadchene/mcp-gateway-service 0.10.0 → 0.11.1
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 +203 -205
- package/README_zh.md +203 -205
- package/dist/gateway-engine.js +79 -47
- package/dist/mcp/input-schema.js +95 -0
- package/dist/mcp/server.js +2 -1
- package/package.json +1 -1
- package/skills/mcp-gateway/SKILL.md +25 -26
package/README.md
CHANGED
|
@@ -1,207 +1,205 @@
|
|
|
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
|
-
- Require user confirmation for selected tool-name patterns, or hide and block matching tools entirely.
|
|
21
|
-
- Reload config changes without restarting the gateway.
|
|
22
|
-
|
|
23
|
-
## Quick Start
|
|
24
|
-
|
|
25
|
-
### Install
|
|
26
|
-
|
|
27
|
-
```bash
|
|
28
|
-
npm install -g @jadchene/mcp-gateway-service
|
|
29
|
-
```
|
|
30
|
-
|
|
31
|
-
Create `config.json`. Replace `your-mcp-service` with the command of an installed MCP server:
|
|
32
|
-
|
|
33
|
-
```json
|
|
34
|
-
{
|
|
35
|
-
"services": [
|
|
36
|
-
{
|
|
37
|
-
"serviceId": "tools",
|
|
38
|
-
"name": "Tools",
|
|
39
|
-
"transport": {
|
|
40
|
-
"type": "stdio",
|
|
41
|
-
"command": "your-mcp-service"
|
|
42
|
-
}
|
|
43
|
-
}
|
|
44
|
-
]
|
|
45
|
-
}
|
|
46
|
-
```
|
|
47
|
-
|
|
48
|
-
### Stdio
|
|
49
|
-
|
|
50
|
-
The agent starts the gateway process, so no separate startup command is needed.
|
|
51
|
-
|
|
52
|
-
Codex `config.toml`:
|
|
53
|
-
|
|
54
|
-
```toml
|
|
55
|
-
[mcp_servers.gateway]
|
|
56
|
-
command = "mcp-gateway-service"
|
|
57
|
-
args = ["--config", "./config.json"]
|
|
58
|
-
```
|
|
59
|
-
|
|
60
|
-
Claude Code:
|
|
61
|
-
|
|
62
|
-
```bash
|
|
63
|
-
claude mcp add gateway -- mcp-gateway-service --config ./config.json
|
|
64
|
-
```
|
|
65
|
-
|
|
66
|
-
### Streamable HTTP
|
|
67
|
-
|
|
68
|
-
Start the gateway:
|
|
69
|
-
|
|
70
|
-
```bash
|
|
71
|
-
mcp-gateway-service --http --config ./config.json
|
|
72
|
-
```
|
|
73
|
-
|
|
74
|
-
The default endpoint is `http://127.0.0.1:3000/mcp`.
|
|
75
|
-
HTTP hides `gateway_manage_service` by default. Non-loopback binds require a bearer token in `MCP_GATEWAY_AUTH_TOKEN`.
|
|
76
|
-
|
|
77
|
-
Codex `config.toml`:
|
|
78
|
-
|
|
79
|
-
```toml
|
|
80
|
-
[mcp_servers.gateway]
|
|
81
|
-
url = "http://127.0.0.1:3000/mcp"
|
|
82
|
-
```
|
|
83
|
-
|
|
84
|
-
Claude Code:
|
|
85
|
-
|
|
86
|
-
```bash
|
|
87
|
-
claude mcp add --transport http gateway http://127.0.0.1:3000/mcp
|
|
88
|
-
```
|
|
89
|
-
|
|
90
|
-
## Configuration and Tools
|
|
91
|
-
|
|
92
|
-
### CLI Options
|
|
93
|
-
|
|
94
|
-
| Option | Description | Default |
|
|
95
|
-
| --- | --- | --- |
|
|
96
|
-
| `--config <path>` | Config file path. | `MCP_GATEWAY_CONFIG`, then `./config.json` |
|
|
97
|
-
| `--http` | Enables the Streamable HTTP endpoint. | Disabled |
|
|
98
|
-
| `--host <host>` | HTTP bind address. | `127.0.0.1` |
|
|
99
|
-
| `--port <port>` | HTTP port. | `3000` |
|
|
100
|
-
| `--path <path>` | HTTP endpoint path. | `/mcp` |
|
|
101
|
-
| `--auth-token-env <name>` | Environment variable containing the HTTP bearer token. | `MCP_GATEWAY_AUTH_TOKEN` |
|
|
102
|
-
| `--http-admin-tools` | Exposes `gateway_manage_service` over authenticated HTTP. | Disabled |
|
|
103
|
-
| `--max-concurrent-requests <n>` | Bounds in-flight HTTP requests. | `64` |
|
|
104
|
-
| `--max-request-body-bytes <n>` | Rejects HTTP request bodies above this byte limit; maximum configurable value is 64 MiB. | `16777216` (16 MiB) |
|
|
105
|
-
| `--max-legacy-sessions <n>` | Bounds retained stateful legacy HTTP sessions. | `256` |
|
|
106
|
-
| `--version`, `-v` | Prints the installed version. | — |
|
|
107
|
-
|
|
108
|
-
Stdio remains available when `--http` is enabled.
|
|
109
|
-
|
|
110
|
-
### Config File
|
|
111
|
-
|
|
112
|
-
```json
|
|
113
|
-
{
|
|
114
|
-
"logging": {
|
|
115
|
-
"enable": false,
|
|
116
|
-
"path": "./logs/mcp-gateway.log"
|
|
117
|
-
},
|
|
118
|
-
"services": [
|
|
119
|
-
{
|
|
120
|
-
"serviceId": "local-tools",
|
|
121
|
-
"name": "Local Tools",
|
|
122
|
-
"confirmationRequiredTools": ["delete_*", "deploy_?"],
|
|
123
|
-
"disabledTools": ["internal_*", "legacy_tool"],
|
|
124
|
-
"transport": {
|
|
125
|
-
"type": "stdio",
|
|
126
|
-
"command": "your-mcp-service",
|
|
127
|
-
"args": []
|
|
128
|
-
}
|
|
129
|
-
},
|
|
130
|
-
{
|
|
131
|
-
"serviceId": "remote-tools",
|
|
132
|
-
"name": "Remote Tools",
|
|
133
|
-
"transport": {
|
|
134
|
-
"type": "http",
|
|
135
|
-
"url": "http://127.0.0.1:3200/mcp"
|
|
136
|
-
}
|
|
137
|
-
}
|
|
138
|
-
]
|
|
139
|
-
}
|
|
140
|
-
```
|
|
141
|
-
|
|
142
|
-
| Field | Description |
|
|
143
|
-
| --- | --- |
|
|
144
|
-
| `services` | List of downstream MCP services. |
|
|
145
|
-
| `serviceId` | Required unique identifier used by gateway tools. |
|
|
146
|
-
| `name` | Required display name. |
|
|
147
|
-
| `description` | Optional service description. |
|
|
148
|
-
| `enable` | Optional; defaults to `true`. |
|
|
149
|
-
| `callTimeoutMs` | Optional downstream tool-call timeout; defaults to 120 seconds. |
|
|
150
|
-
| `confirmationRequiredTools` | Optional unique array of case-sensitive full-name glob patterns. `*` matches zero or more characters and `?` matches one character. The gateway asks the upstream user for form elicitation confirmation before calling a matching tool. |
|
|
151
|
-
| `disabledTools` | Optional unique array using the same glob syntax. Matching tools are hidden from tool listing and schema lookup, and calls are rejected before reaching the downstream service. |
|
|
152
|
-
| `transport.type` | `stdio` or `http`. |
|
|
153
|
-
| `transport.command` | Required command for a stdio service. |
|
|
154
|
-
| `transport.args` | Optional command arguments for a stdio service. |
|
|
155
|
-
| `transport.cwd` | Optional working directory for a stdio service. |
|
|
156
|
-
| `transport.env` | Optional environment variables for a stdio service. |
|
|
157
|
-
| `transport.inheritEnv` | Opts into inheriting the complete gateway environment; defaults to `false`. |
|
|
158
|
-
| `transport.envAllowlist` | Additional process environment names passed to stdio services. |
|
|
159
|
-
| `transport.url` | Required Streamable HTTP URL for an HTTP service. |
|
|
160
|
-
| `transport.headers` | Optional static headers for an HTTP service. |
|
|
161
|
-
| `logging.enable` | Enables file logging; defaults to `false`. |
|
|
162
|
-
| `logging.path` | Log file path. Relative paths use the config file directory. |
|
|
163
|
-
| `logging.maxBytes` | Active log size before rotation; defaults to 10 MiB. |
|
|
164
|
-
|
|
165
|
-
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.
|
|
166
|
-
|
|
167
|
-
### Gateway Tools
|
|
168
|
-
|
|
169
|
-
| Tool | Description |
|
|
170
|
-
| --- | --- |
|
|
171
|
-
| `gateway_list_services` | Searches
|
|
172
|
-
| `gateway_get_service` | Shows one service's connection state, protocol revision, server identity, and recent error. |
|
|
173
|
-
| `gateway_list_tools` | Searches a service's tools by name or description and can include schemas. |
|
|
174
|
-
| `gateway_get_tool_schema` | Returns schemas for exact tool names. |
|
|
175
|
-
| `gateway_manage_service` | Reconnects a service or enables/disables it in the config file. |
|
|
176
|
-
| `gateway_call_tool` | Calls one downstream tool and returns its MCP result. |
|
|
177
|
-
|
|
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
|
+
- Require user confirmation for selected tool-name patterns, or hide and block matching tools entirely.
|
|
21
|
+
- Reload config changes without restarting the gateway.
|
|
22
|
+
|
|
23
|
+
## Quick Start
|
|
24
|
+
|
|
25
|
+
### Install
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
npm install -g @jadchene/mcp-gateway-service
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
Create `config.json`. Replace `your-mcp-service` with the command of an installed MCP server:
|
|
32
|
+
|
|
33
|
+
```json
|
|
34
|
+
{
|
|
35
|
+
"services": [
|
|
36
|
+
{
|
|
37
|
+
"serviceId": "tools",
|
|
38
|
+
"name": "Tools",
|
|
39
|
+
"transport": {
|
|
40
|
+
"type": "stdio",
|
|
41
|
+
"command": "your-mcp-service"
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
]
|
|
45
|
+
}
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
### Stdio
|
|
49
|
+
|
|
50
|
+
The agent starts the gateway process, so no separate startup command is needed.
|
|
51
|
+
|
|
52
|
+
Codex `config.toml`:
|
|
53
|
+
|
|
54
|
+
```toml
|
|
55
|
+
[mcp_servers.gateway]
|
|
56
|
+
command = "mcp-gateway-service"
|
|
57
|
+
args = ["--config", "./config.json"]
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
Claude Code:
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
claude mcp add gateway -- mcp-gateway-service --config ./config.json
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
### Streamable HTTP
|
|
67
|
+
|
|
68
|
+
Start the gateway:
|
|
69
|
+
|
|
70
|
+
```bash
|
|
71
|
+
mcp-gateway-service --http --config ./config.json
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
The default endpoint is `http://127.0.0.1:3000/mcp`.
|
|
75
|
+
HTTP hides `gateway_manage_service` by default. Non-loopback binds require a bearer token in `MCP_GATEWAY_AUTH_TOKEN`.
|
|
76
|
+
|
|
77
|
+
Codex `config.toml`:
|
|
78
|
+
|
|
79
|
+
```toml
|
|
80
|
+
[mcp_servers.gateway]
|
|
81
|
+
url = "http://127.0.0.1:3000/mcp"
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
Claude Code:
|
|
85
|
+
|
|
86
|
+
```bash
|
|
87
|
+
claude mcp add --transport http gateway http://127.0.0.1:3000/mcp
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
## Configuration and Tools
|
|
91
|
+
|
|
92
|
+
### CLI Options
|
|
93
|
+
|
|
94
|
+
| Option | Description | Default |
|
|
95
|
+
| --- | --- | --- |
|
|
96
|
+
| `--config <path>` | Config file path. | `MCP_GATEWAY_CONFIG`, then `./config.json` |
|
|
97
|
+
| `--http` | Enables the Streamable HTTP endpoint. | Disabled |
|
|
98
|
+
| `--host <host>` | HTTP bind address. | `127.0.0.1` |
|
|
99
|
+
| `--port <port>` | HTTP port. | `3000` |
|
|
100
|
+
| `--path <path>` | HTTP endpoint path. | `/mcp` |
|
|
101
|
+
| `--auth-token-env <name>` | Environment variable containing the HTTP bearer token. | `MCP_GATEWAY_AUTH_TOKEN` |
|
|
102
|
+
| `--http-admin-tools` | Exposes `gateway_manage_service` over authenticated HTTP. | Disabled |
|
|
103
|
+
| `--max-concurrent-requests <n>` | Bounds in-flight HTTP requests. | `64` |
|
|
104
|
+
| `--max-request-body-bytes <n>` | Rejects HTTP request bodies above this byte limit; maximum configurable value is 64 MiB. | `16777216` (16 MiB) |
|
|
105
|
+
| `--max-legacy-sessions <n>` | Bounds retained stateful legacy HTTP sessions. | `256` |
|
|
106
|
+
| `--version`, `-v` | Prints the installed version. | — |
|
|
107
|
+
|
|
108
|
+
Stdio remains available when `--http` is enabled.
|
|
109
|
+
|
|
110
|
+
### Config File
|
|
111
|
+
|
|
112
|
+
```json
|
|
113
|
+
{
|
|
114
|
+
"logging": {
|
|
115
|
+
"enable": false,
|
|
116
|
+
"path": "./logs/mcp-gateway.log"
|
|
117
|
+
},
|
|
118
|
+
"services": [
|
|
119
|
+
{
|
|
120
|
+
"serviceId": "local-tools",
|
|
121
|
+
"name": "Local Tools",
|
|
122
|
+
"confirmationRequiredTools": ["delete_*", "deploy_?"],
|
|
123
|
+
"disabledTools": ["internal_*", "legacy_tool"],
|
|
124
|
+
"transport": {
|
|
125
|
+
"type": "stdio",
|
|
126
|
+
"command": "your-mcp-service",
|
|
127
|
+
"args": []
|
|
128
|
+
}
|
|
129
|
+
},
|
|
130
|
+
{
|
|
131
|
+
"serviceId": "remote-tools",
|
|
132
|
+
"name": "Remote Tools",
|
|
133
|
+
"transport": {
|
|
134
|
+
"type": "http",
|
|
135
|
+
"url": "http://127.0.0.1:3200/mcp"
|
|
136
|
+
}
|
|
137
|
+
}
|
|
138
|
+
]
|
|
139
|
+
}
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
| Field | Description |
|
|
143
|
+
| --- | --- |
|
|
144
|
+
| `services` | List of downstream MCP services. |
|
|
145
|
+
| `serviceId` | Required unique identifier used by gateway tools. |
|
|
146
|
+
| `name` | Required display name. |
|
|
147
|
+
| `description` | Optional service description. |
|
|
148
|
+
| `enable` | Optional; defaults to `true`. |
|
|
149
|
+
| `callTimeoutMs` | Optional downstream tool-call timeout; defaults to 120 seconds. |
|
|
150
|
+
| `confirmationRequiredTools` | Optional unique array of case-sensitive full-name glob patterns. `*` matches zero or more characters and `?` matches one character. The gateway asks the upstream user for form elicitation confirmation before calling a matching tool. |
|
|
151
|
+
| `disabledTools` | Optional unique array using the same glob syntax. Matching tools are hidden from tool listing and schema lookup, and calls are rejected before reaching the downstream service. |
|
|
152
|
+
| `transport.type` | `stdio` or `http`. |
|
|
153
|
+
| `transport.command` | Required command for a stdio service. |
|
|
154
|
+
| `transport.args` | Optional command arguments for a stdio service. |
|
|
155
|
+
| `transport.cwd` | Optional working directory for a stdio service. |
|
|
156
|
+
| `transport.env` | Optional environment variables for a stdio service. |
|
|
157
|
+
| `transport.inheritEnv` | Opts into inheriting the complete gateway environment; defaults to `false`. |
|
|
158
|
+
| `transport.envAllowlist` | Additional process environment names passed to stdio services. |
|
|
159
|
+
| `transport.url` | Required Streamable HTTP URL for an HTTP service. |
|
|
160
|
+
| `transport.headers` | Optional static headers for an HTTP service. |
|
|
161
|
+
| `logging.enable` | Enables file logging; defaults to `false`. |
|
|
162
|
+
| `logging.path` | Log file path. Relative paths use the config file directory. |
|
|
163
|
+
| `logging.maxBytes` | Active log size before rotation; defaults to 10 MiB. |
|
|
164
|
+
|
|
165
|
+
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.
|
|
166
|
+
|
|
167
|
+
### Gateway Tools
|
|
168
|
+
|
|
169
|
+
| Tool | Description |
|
|
170
|
+
| --- | --- |
|
|
171
|
+
| `gateway_list_services` | Searches enabled services by identifier or description and can filter by availability. |
|
|
172
|
+
| `gateway_get_service` | Shows one service's connection state, protocol revision, server identity, and recent error. |
|
|
173
|
+
| `gateway_list_tools` | Searches a service's tools by name or description and can include schemas. |
|
|
174
|
+
| `gateway_get_tool_schema` | Returns schemas for exact tool names. |
|
|
175
|
+
| `gateway_manage_service` | Reconnects a service or enables/disables it in the config file. |
|
|
176
|
+
| `gateway_call_tool` | Calls one downstream tool and returns its MCP result. |
|
|
177
|
+
|
|
178
178
|
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.
|
|
179
179
|
|
|
180
|
-
`
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
npm
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
[MIT](./LICENSE)
|
|
180
|
+
Calls matching `confirmationRequiredTools` show the service, tool, and arguments and require approval in the current MCP session. Clients without form elicitation support cannot invoke them. Calls with uncertain outcomes are not retried automatically.
|
|
181
|
+
|
|
182
|
+
`disabledTools` takes precedence over `confirmationRequiredTools` when both match. A disabled tool is hidden and rejected immediately without asking for confirmation.
|
|
183
|
+
|
|
184
|
+
Agents with Skills support can use the included [MCP Gateway Skill](./skills/mcp-gateway/SKILL.md) for the discovery and calling workflow.
|
|
185
|
+
|
|
186
|
+
## Development
|
|
187
|
+
|
|
188
|
+
```bash
|
|
189
|
+
git clone https://github.com/jadchene/mcp-gateway.git
|
|
190
|
+
cd mcp-gateway
|
|
191
|
+
npm install
|
|
192
|
+
npm run verify
|
|
193
|
+
npm run dev -- --config ./config.json
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
Build and run the compiled service:
|
|
197
|
+
|
|
198
|
+
```bash
|
|
199
|
+
npm run build
|
|
200
|
+
npm start -- --config ./config.json
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
## License
|
|
204
|
+
|
|
205
|
+
[MIT](./LICENSE)
|
package/README_zh.md
CHANGED
|
@@ -1,207 +1,205 @@
|
|
|
1
|
-
[English](./README.md) | 简体中文
|
|
2
|
-
|
|
3
|
-
# MCP Gateway
|
|
4
|
-
|
|
5
|
-
## 简介
|
|
6
|
-
|
|
7
|
-
MCP Gateway 把多个 MCP 服务收拢到一个入口。Agent 连接网关后只会看到 6 个路由工具,具体的下游服务、工具和 schema 在需要时再查询。
|
|
8
|
-
|
|
9
|
-
项目使用官方 TypeScript SDK v2,需要 Node.js 24 或更高版本。
|
|
10
|
-
|
|
11
|
-
> [!IMPORTANT]
|
|
12
|
-
> MCP Gateway v0.6.2 及后续版本仅接受 MCP `2026-07-28`、`2025-11-25` 和 `2025-06-18`。传输方式仅支持换行分隔 stdio 和单端点 Streamable HTTP。不支持独立 HTTP+SSE(`/sse`)、`Content-Length` framing 和其他协议版本。
|
|
13
|
-
|
|
14
|
-
## 为什么使用
|
|
15
|
-
|
|
16
|
-
- 即使配置了很多 MCP 服务,也不会一次性占用大量 Agent 上下文。
|
|
17
|
-
- Agent 只需接入一次,后续增减下游服务只改网关配置。
|
|
18
|
-
- 可以按名称或描述查找工具,需要时再读取 schema。
|
|
19
|
-
- Stdio 和 Streamable HTTP 服务使用同一套调用方式。
|
|
20
|
-
- 可按工具名模式要求用户确认,或隐藏并禁止调用指定工具。
|
|
21
|
-
- 修改配置文件后自动重载,不必重启网关。
|
|
22
|
-
|
|
23
|
-
## 快速开始
|
|
24
|
-
|
|
25
|
-
### 安装
|
|
26
|
-
|
|
27
|
-
```bash
|
|
28
|
-
npm install -g @jadchene/mcp-gateway-service
|
|
29
|
-
```
|
|
30
|
-
|
|
31
|
-
创建 `config.json`,将 `your-mcp-service` 替换为已经安装的 MCP 服务命令:
|
|
32
|
-
|
|
33
|
-
```json
|
|
34
|
-
{
|
|
35
|
-
"services": [
|
|
36
|
-
{
|
|
37
|
-
"serviceId": "tools",
|
|
38
|
-
"name": "Tools",
|
|
39
|
-
"transport": {
|
|
40
|
-
"type": "stdio",
|
|
41
|
-
"command": "your-mcp-service"
|
|
42
|
-
}
|
|
43
|
-
}
|
|
44
|
-
]
|
|
45
|
-
}
|
|
46
|
-
```
|
|
47
|
-
|
|
48
|
-
### Stdio
|
|
49
|
-
|
|
50
|
-
网关进程由 Agent 启动,不需要单独运行启动命令。
|
|
51
|
-
|
|
52
|
-
Codex `config.toml`:
|
|
53
|
-
|
|
54
|
-
```toml
|
|
55
|
-
[mcp_servers.gateway]
|
|
56
|
-
command = "mcp-gateway-service"
|
|
57
|
-
args = ["--config", "./config.json"]
|
|
58
|
-
```
|
|
59
|
-
|
|
60
|
-
Claude Code:
|
|
61
|
-
|
|
62
|
-
```bash
|
|
63
|
-
claude mcp add gateway -- mcp-gateway-service --config ./config.json
|
|
64
|
-
```
|
|
65
|
-
|
|
66
|
-
### Streamable HTTP
|
|
67
|
-
|
|
68
|
-
启动网关:
|
|
69
|
-
|
|
70
|
-
```bash
|
|
71
|
-
mcp-gateway-service --http --config ./config.json
|
|
72
|
-
```
|
|
73
|
-
|
|
74
|
-
默认地址为 `http://127.0.0.1:3000/mcp`。
|
|
75
|
-
HTTP 默认隐藏 `gateway_manage_service`。监听非回环地址时,必须通过 `MCP_GATEWAY_AUTH_TOKEN` 配置 Bearer Token。
|
|
76
|
-
|
|
77
|
-
Codex `config.toml`:
|
|
78
|
-
|
|
79
|
-
```toml
|
|
80
|
-
[mcp_servers.gateway]
|
|
81
|
-
url = "http://127.0.0.1:3000/mcp"
|
|
82
|
-
```
|
|
83
|
-
|
|
84
|
-
Claude Code:
|
|
85
|
-
|
|
86
|
-
```bash
|
|
87
|
-
claude mcp add --transport http gateway http://127.0.0.1:3000/mcp
|
|
88
|
-
```
|
|
89
|
-
|
|
90
|
-
## 配置与工具
|
|
91
|
-
|
|
92
|
-
### 启动参数
|
|
93
|
-
|
|
94
|
-
| 参数 | 说明 | 默认值 |
|
|
95
|
-
| --- | --- | --- |
|
|
96
|
-
| `--config <path>` | 配置文件路径。 | `MCP_GATEWAY_CONFIG`,其次为 `./config.json` |
|
|
97
|
-
| `--http` | 启用 Streamable HTTP。 | 不启用 |
|
|
98
|
-
| `--host <host>` | HTTP 监听地址。 | `127.0.0.1` |
|
|
99
|
-
| `--port <port>` | HTTP 监听端口。 | `3000` |
|
|
100
|
-
| `--path <path>` | HTTP endpoint 路径。 | `/mcp` |
|
|
101
|
-
| `--auth-token-env <名称>` | 保存 HTTP Bearer Token 的环境变量名。 | `MCP_GATEWAY_AUTH_TOKEN` |
|
|
102
|
-
| `--http-admin-tools` | 在已认证 HTTP 入口暴露 `gateway_manage_service`。 | 不启用 |
|
|
103
|
-
| `--max-concurrent-requests <数量>` | HTTP 并发请求上限。 | `64` |
|
|
104
|
-
| `--max-request-body-bytes <字节数>` | HTTP 请求体字节上限,最大可配置为 64 MiB,超限返回 `413`。 | `16777216`(16 MiB) |
|
|
105
|
-
| `--max-legacy-sessions <数量>` | 有状态旧版 HTTP 会话的保留上限。 | `256` |
|
|
106
|
-
| `--version`、`-v` | 输出已安装版本。 | — |
|
|
107
|
-
|
|
108
|
-
启用 `--http` 后,stdio 入口仍然可用。
|
|
109
|
-
|
|
110
|
-
### 配置文件
|
|
111
|
-
|
|
112
|
-
```json
|
|
113
|
-
{
|
|
114
|
-
"logging": {
|
|
115
|
-
"enable": false,
|
|
116
|
-
"path": "./logs/mcp-gateway.log"
|
|
117
|
-
},
|
|
118
|
-
"services": [
|
|
119
|
-
{
|
|
120
|
-
"serviceId": "local-tools",
|
|
121
|
-
"name": "Local Tools",
|
|
122
|
-
"confirmationRequiredTools": ["delete_*", "deploy_?"],
|
|
123
|
-
"disabledTools": ["internal_*", "legacy_tool"],
|
|
124
|
-
"transport": {
|
|
125
|
-
"type": "stdio",
|
|
126
|
-
"command": "your-mcp-service",
|
|
127
|
-
"args": []
|
|
128
|
-
}
|
|
129
|
-
},
|
|
130
|
-
{
|
|
131
|
-
"serviceId": "remote-tools",
|
|
132
|
-
"name": "Remote Tools",
|
|
133
|
-
"transport": {
|
|
134
|
-
"type": "http",
|
|
135
|
-
"url": "http://127.0.0.1:3200/mcp"
|
|
136
|
-
}
|
|
137
|
-
}
|
|
138
|
-
]
|
|
139
|
-
}
|
|
140
|
-
```
|
|
141
|
-
|
|
142
|
-
| 字段 | 说明 |
|
|
143
|
-
| --- | --- |
|
|
144
|
-
| `services` | 下游 MCP 服务列表。 |
|
|
145
|
-
| `serviceId` | 必填,网关工具使用的唯一服务标识。 |
|
|
146
|
-
| `name` | 必填,服务名称。 |
|
|
147
|
-
| `description` | 可选,服务说明。 |
|
|
148
|
-
| `enable` | 可选,默认为 `true`。 |
|
|
149
|
-
| `callTimeoutMs` | 可选,下游工具调用超时;默认 120 秒。 |
|
|
150
|
-
| `confirmationRequiredTools` | 可选,填写区分大小写的完整工具名 glob 模式;`*` 匹配零个或多个字符,`?` 匹配一个字符。数组项必须唯一且非空,网关在调用匹配的工具前会向上游用户发起表单 elicitation。 |
|
|
151
|
-
| `disabledTools` | 可选,使用相同 glob 语法。匹配的工具不会出现在工具列表和 schema 查询中,调用也会在到达下游服务前被拒绝。 |
|
|
152
|
-
| `transport.type` | `stdio` 或 `http`。 |
|
|
153
|
-
| `transport.command` | stdio 服务必填,启动命令。 |
|
|
154
|
-
| `transport.args` | stdio 服务的可选命令参数。 |
|
|
155
|
-
| `transport.cwd` | stdio 服务的可选工作目录。 |
|
|
156
|
-
| `transport.env` | stdio 服务的可选环境变量。 |
|
|
157
|
-
| `transport.inheritEnv` | 是否继承网关完整环境;默认为 `false`。 |
|
|
158
|
-
| `transport.envAllowlist` | 额外传递给 stdio 服务的进程环境变量名。 |
|
|
159
|
-
| `transport.url` | HTTP 服务必填,Streamable HTTP 地址。 |
|
|
160
|
-
| `transport.headers` | HTTP 服务的可选静态请求头。 |
|
|
161
|
-
| `logging.enable` | 是否写入文件日志,默认为 `false`。 |
|
|
162
|
-
| `logging.path` | 日志文件路径;相对路径按配置文件目录解析。 |
|
|
163
|
-
| `logging.maxBytes` | 当前日志轮转前的大小上限;默认 10 MiB。 |
|
|
164
|
-
|
|
165
|
-
网关会监听配置文件变化。配置有误时不会替换当前配置,服务继续按最后一次有效配置运行。其他示例见 [config.example.json](./config.example.json)。
|
|
166
|
-
|
|
167
|
-
### 网关工具
|
|
168
|
-
|
|
169
|
-
| 工具 | 说明 |
|
|
170
|
-
| --- | --- |
|
|
171
|
-
| `gateway_list_services` |
|
|
172
|
-
| `gateway_get_service` | 查看服务连接状态、协议版本、服务端信息和最近一次错误。 |
|
|
173
|
-
| `gateway_list_tools` | 按名称或描述搜索服务中的工具,可同时返回 schema。 |
|
|
174
|
-
| `gateway_get_tool_schema` | 获取准确工具名称对应的 schema。 |
|
|
175
|
-
| `gateway_manage_service` | 重连服务,或在配置文件中启用、禁用服务。 |
|
|
176
|
-
| `gateway_call_tool` | 调用一个下游工具并返回 MCP 结果。 |
|
|
177
|
-
|
|
1
|
+
[English](./README.md) | 简体中文
|
|
2
|
+
|
|
3
|
+
# MCP Gateway
|
|
4
|
+
|
|
5
|
+
## 简介
|
|
6
|
+
|
|
7
|
+
MCP Gateway 把多个 MCP 服务收拢到一个入口。Agent 连接网关后只会看到 6 个路由工具,具体的下游服务、工具和 schema 在需要时再查询。
|
|
8
|
+
|
|
9
|
+
项目使用官方 TypeScript SDK v2,需要 Node.js 24 或更高版本。
|
|
10
|
+
|
|
11
|
+
> [!IMPORTANT]
|
|
12
|
+
> MCP Gateway v0.6.2 及后续版本仅接受 MCP `2026-07-28`、`2025-11-25` 和 `2025-06-18`。传输方式仅支持换行分隔 stdio 和单端点 Streamable HTTP。不支持独立 HTTP+SSE(`/sse`)、`Content-Length` framing 和其他协议版本。
|
|
13
|
+
|
|
14
|
+
## 为什么使用
|
|
15
|
+
|
|
16
|
+
- 即使配置了很多 MCP 服务,也不会一次性占用大量 Agent 上下文。
|
|
17
|
+
- Agent 只需接入一次,后续增减下游服务只改网关配置。
|
|
18
|
+
- 可以按名称或描述查找工具,需要时再读取 schema。
|
|
19
|
+
- Stdio 和 Streamable HTTP 服务使用同一套调用方式。
|
|
20
|
+
- 可按工具名模式要求用户确认,或隐藏并禁止调用指定工具。
|
|
21
|
+
- 修改配置文件后自动重载,不必重启网关。
|
|
22
|
+
|
|
23
|
+
## 快速开始
|
|
24
|
+
|
|
25
|
+
### 安装
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
npm install -g @jadchene/mcp-gateway-service
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
创建 `config.json`,将 `your-mcp-service` 替换为已经安装的 MCP 服务命令:
|
|
32
|
+
|
|
33
|
+
```json
|
|
34
|
+
{
|
|
35
|
+
"services": [
|
|
36
|
+
{
|
|
37
|
+
"serviceId": "tools",
|
|
38
|
+
"name": "Tools",
|
|
39
|
+
"transport": {
|
|
40
|
+
"type": "stdio",
|
|
41
|
+
"command": "your-mcp-service"
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
]
|
|
45
|
+
}
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
### Stdio
|
|
49
|
+
|
|
50
|
+
网关进程由 Agent 启动,不需要单独运行启动命令。
|
|
51
|
+
|
|
52
|
+
Codex `config.toml`:
|
|
53
|
+
|
|
54
|
+
```toml
|
|
55
|
+
[mcp_servers.gateway]
|
|
56
|
+
command = "mcp-gateway-service"
|
|
57
|
+
args = ["--config", "./config.json"]
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
Claude Code:
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
claude mcp add gateway -- mcp-gateway-service --config ./config.json
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
### Streamable HTTP
|
|
67
|
+
|
|
68
|
+
启动网关:
|
|
69
|
+
|
|
70
|
+
```bash
|
|
71
|
+
mcp-gateway-service --http --config ./config.json
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
默认地址为 `http://127.0.0.1:3000/mcp`。
|
|
75
|
+
HTTP 默认隐藏 `gateway_manage_service`。监听非回环地址时,必须通过 `MCP_GATEWAY_AUTH_TOKEN` 配置 Bearer Token。
|
|
76
|
+
|
|
77
|
+
Codex `config.toml`:
|
|
78
|
+
|
|
79
|
+
```toml
|
|
80
|
+
[mcp_servers.gateway]
|
|
81
|
+
url = "http://127.0.0.1:3000/mcp"
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
Claude Code:
|
|
85
|
+
|
|
86
|
+
```bash
|
|
87
|
+
claude mcp add --transport http gateway http://127.0.0.1:3000/mcp
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
## 配置与工具
|
|
91
|
+
|
|
92
|
+
### 启动参数
|
|
93
|
+
|
|
94
|
+
| 参数 | 说明 | 默认值 |
|
|
95
|
+
| --- | --- | --- |
|
|
96
|
+
| `--config <path>` | 配置文件路径。 | `MCP_GATEWAY_CONFIG`,其次为 `./config.json` |
|
|
97
|
+
| `--http` | 启用 Streamable HTTP。 | 不启用 |
|
|
98
|
+
| `--host <host>` | HTTP 监听地址。 | `127.0.0.1` |
|
|
99
|
+
| `--port <port>` | HTTP 监听端口。 | `3000` |
|
|
100
|
+
| `--path <path>` | HTTP endpoint 路径。 | `/mcp` |
|
|
101
|
+
| `--auth-token-env <名称>` | 保存 HTTP Bearer Token 的环境变量名。 | `MCP_GATEWAY_AUTH_TOKEN` |
|
|
102
|
+
| `--http-admin-tools` | 在已认证 HTTP 入口暴露 `gateway_manage_service`。 | 不启用 |
|
|
103
|
+
| `--max-concurrent-requests <数量>` | HTTP 并发请求上限。 | `64` |
|
|
104
|
+
| `--max-request-body-bytes <字节数>` | HTTP 请求体字节上限,最大可配置为 64 MiB,超限返回 `413`。 | `16777216`(16 MiB) |
|
|
105
|
+
| `--max-legacy-sessions <数量>` | 有状态旧版 HTTP 会话的保留上限。 | `256` |
|
|
106
|
+
| `--version`、`-v` | 输出已安装版本。 | — |
|
|
107
|
+
|
|
108
|
+
启用 `--http` 后,stdio 入口仍然可用。
|
|
109
|
+
|
|
110
|
+
### 配置文件
|
|
111
|
+
|
|
112
|
+
```json
|
|
113
|
+
{
|
|
114
|
+
"logging": {
|
|
115
|
+
"enable": false,
|
|
116
|
+
"path": "./logs/mcp-gateway.log"
|
|
117
|
+
},
|
|
118
|
+
"services": [
|
|
119
|
+
{
|
|
120
|
+
"serviceId": "local-tools",
|
|
121
|
+
"name": "Local Tools",
|
|
122
|
+
"confirmationRequiredTools": ["delete_*", "deploy_?"],
|
|
123
|
+
"disabledTools": ["internal_*", "legacy_tool"],
|
|
124
|
+
"transport": {
|
|
125
|
+
"type": "stdio",
|
|
126
|
+
"command": "your-mcp-service",
|
|
127
|
+
"args": []
|
|
128
|
+
}
|
|
129
|
+
},
|
|
130
|
+
{
|
|
131
|
+
"serviceId": "remote-tools",
|
|
132
|
+
"name": "Remote Tools",
|
|
133
|
+
"transport": {
|
|
134
|
+
"type": "http",
|
|
135
|
+
"url": "http://127.0.0.1:3200/mcp"
|
|
136
|
+
}
|
|
137
|
+
}
|
|
138
|
+
]
|
|
139
|
+
}
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
| 字段 | 说明 |
|
|
143
|
+
| --- | --- |
|
|
144
|
+
| `services` | 下游 MCP 服务列表。 |
|
|
145
|
+
| `serviceId` | 必填,网关工具使用的唯一服务标识。 |
|
|
146
|
+
| `name` | 必填,服务名称。 |
|
|
147
|
+
| `description` | 可选,服务说明。 |
|
|
148
|
+
| `enable` | 可选,默认为 `true`。 |
|
|
149
|
+
| `callTimeoutMs` | 可选,下游工具调用超时;默认 120 秒。 |
|
|
150
|
+
| `confirmationRequiredTools` | 可选,填写区分大小写的完整工具名 glob 模式;`*` 匹配零个或多个字符,`?` 匹配一个字符。数组项必须唯一且非空,网关在调用匹配的工具前会向上游用户发起表单 elicitation。 |
|
|
151
|
+
| `disabledTools` | 可选,使用相同 glob 语法。匹配的工具不会出现在工具列表和 schema 查询中,调用也会在到达下游服务前被拒绝。 |
|
|
152
|
+
| `transport.type` | `stdio` 或 `http`。 |
|
|
153
|
+
| `transport.command` | stdio 服务必填,启动命令。 |
|
|
154
|
+
| `transport.args` | stdio 服务的可选命令参数。 |
|
|
155
|
+
| `transport.cwd` | stdio 服务的可选工作目录。 |
|
|
156
|
+
| `transport.env` | stdio 服务的可选环境变量。 |
|
|
157
|
+
| `transport.inheritEnv` | 是否继承网关完整环境;默认为 `false`。 |
|
|
158
|
+
| `transport.envAllowlist` | 额外传递给 stdio 服务的进程环境变量名。 |
|
|
159
|
+
| `transport.url` | HTTP 服务必填,Streamable HTTP 地址。 |
|
|
160
|
+
| `transport.headers` | HTTP 服务的可选静态请求头。 |
|
|
161
|
+
| `logging.enable` | 是否写入文件日志,默认为 `false`。 |
|
|
162
|
+
| `logging.path` | 日志文件路径;相对路径按配置文件目录解析。 |
|
|
163
|
+
| `logging.maxBytes` | 当前日志轮转前的大小上限;默认 10 MiB。 |
|
|
164
|
+
|
|
165
|
+
网关会监听配置文件变化。配置有误时不会替换当前配置,服务继续按最后一次有效配置运行。其他示例见 [config.example.json](./config.example.json)。
|
|
166
|
+
|
|
167
|
+
### 网关工具
|
|
168
|
+
|
|
169
|
+
| 工具 | 说明 |
|
|
170
|
+
| --- | --- |
|
|
171
|
+
| `gateway_list_services` | 按服务标识或描述搜索已启用服务,并可按可用状态筛选。 |
|
|
172
|
+
| `gateway_get_service` | 查看服务连接状态、协议版本、服务端信息和最近一次错误。 |
|
|
173
|
+
| `gateway_list_tools` | 按名称或描述搜索服务中的工具,可同时返回 schema。 |
|
|
174
|
+
| `gateway_get_tool_schema` | 获取准确工具名称对应的 schema。 |
|
|
175
|
+
| `gateway_manage_service` | 重连服务,或在配置文件中启用、禁用服务。 |
|
|
176
|
+
| `gateway_call_tool` | 调用一个下游工具并返回 MCP 结果。 |
|
|
177
|
+
|
|
178
178
|
通常按 `gateway_list_services` → `gateway_list_tools` → 按需调用 `gateway_get_tool_schema` → `gateway_call_tool` 的顺序使用。下游工具没有参数时,`gateway_call_tool` 的 `arguments` 传 `{}`。
|
|
179
179
|
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
npm
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
[MIT](./LICENSE)
|
|
180
|
+
匹配 `confirmationRequiredTools` 的调用会展示服务、工具和参数,须由当前 MCP 会话确认后才执行;不支持表单确认的客户端无法调用。状态不确定的失败调用不会自动重试。
|
|
181
|
+
|
|
182
|
+
当一个工具同时匹配 `disabledTools` 和 `confirmationRequiredTools` 时,`disabledTools` 优先:工具会被隐藏并直接拒绝,不会发起确认。
|
|
183
|
+
|
|
184
|
+
支持 Skills 的 Agent 可以使用仓库内置的 [MCP Gateway Skill](./skills/mcp-gateway/SKILL.md) 完成工具发现和调用。
|
|
185
|
+
|
|
186
|
+
## 开发
|
|
187
|
+
|
|
188
|
+
```bash
|
|
189
|
+
git clone https://github.com/jadchene/mcp-gateway.git
|
|
190
|
+
cd mcp-gateway
|
|
191
|
+
npm install
|
|
192
|
+
npm run verify
|
|
193
|
+
npm run dev -- --config ./config.json
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
构建并运行编译产物:
|
|
197
|
+
|
|
198
|
+
```bash
|
|
199
|
+
npm run build
|
|
200
|
+
npm start -- --config ./config.json
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
## 版权声明
|
|
204
|
+
|
|
205
|
+
[MIT](./LICENSE)
|
package/dist/gateway-engine.js
CHANGED
|
@@ -54,9 +54,9 @@ export class McpGatewayEngine {
|
|
|
54
54
|
* Returns service summaries optionally matching identifiers, descriptions, and availability.
|
|
55
55
|
*/
|
|
56
56
|
listServices(args) {
|
|
57
|
-
const serviceId =
|
|
58
|
-
const desc =
|
|
59
|
-
const available = optionalBoolean(args.
|
|
57
|
+
const serviceId = optionalStringOrArray(args.serviceIdFilter, "The 'serviceIdFilter' argument must be a non-empty string or unique non-empty string array when provided.");
|
|
58
|
+
const desc = optionalStringOrArray(args.descFilter, "The 'descFilter' argument must be a non-empty string or unique non-empty string array when provided.");
|
|
59
|
+
const available = optionalBoolean(args.availableFilter, "The 'availableFilter' argument must be a boolean when provided.");
|
|
60
60
|
const serviceIdKeywords = normalizeKeywords(serviceId);
|
|
61
61
|
const descriptionKeywords = normalizeKeywords(desc);
|
|
62
62
|
const services = this.registry.listServices().filter((snapshot) => {
|
|
@@ -95,8 +95,8 @@ export class McpGatewayEngine {
|
|
|
95
95
|
*/
|
|
96
96
|
listTools(args) {
|
|
97
97
|
const serviceId = requireString(args.serviceId, "The 'serviceId' argument must be a string.");
|
|
98
|
-
const toolName =
|
|
99
|
-
const desc =
|
|
98
|
+
const toolName = optionalStringOrArray(args.toolNameFilter, "The 'toolNameFilter' argument must be a non-empty string or unique non-empty string array when provided.");
|
|
99
|
+
const desc = optionalStringOrArray(args.descFilter, "The 'descFilter' argument must be a non-empty string or unique non-empty string array when provided.");
|
|
100
100
|
const includeSchema = optionalBoolean(args.includeSchema, "The 'includeSchema' argument must be a boolean when provided.") ?? false;
|
|
101
101
|
return successContent({
|
|
102
102
|
tools: this.registry.listTools(serviceId, toolName, desc).map((tool) => {
|
|
@@ -117,18 +117,27 @@ export class McpGatewayEngine {
|
|
|
117
117
|
*/
|
|
118
118
|
getToolSchema(args) {
|
|
119
119
|
const serviceId = requireString(args.serviceId, "The 'serviceId' argument must be a string.");
|
|
120
|
-
const toolNames =
|
|
121
|
-
const
|
|
120
|
+
const toolNames = requireStringOrArray(args.toolName, "The 'toolName' argument must be a non-empty string or unique non-empty string array.");
|
|
121
|
+
const found = [];
|
|
122
|
+
const missing = [];
|
|
123
|
+
for (const toolName of toolNames) {
|
|
122
124
|
const tool = this.registry.getTool(serviceId, toolName);
|
|
123
125
|
if (!tool) {
|
|
124
|
-
|
|
126
|
+
missing.push([toolName, `Unknown tool in service '${serviceId}'.`]);
|
|
127
|
+
continue;
|
|
125
128
|
}
|
|
126
|
-
|
|
129
|
+
found.push([toolName, {
|
|
127
130
|
inputSchema: tool.inputSchema ?? null,
|
|
128
131
|
outputSchema: tool.outputSchema ?? null
|
|
129
|
-
}];
|
|
130
|
-
}
|
|
131
|
-
return
|
|
132
|
+
}]);
|
|
133
|
+
}
|
|
134
|
+
return {
|
|
135
|
+
...successContent({
|
|
136
|
+
schemas: Object.fromEntries(found),
|
|
137
|
+
...(missing.length ? { errors: Object.fromEntries(missing) } : {})
|
|
138
|
+
}),
|
|
139
|
+
...(found.length === 0 ? { isError: true } : {})
|
|
140
|
+
};
|
|
132
141
|
}
|
|
133
142
|
/**
|
|
134
143
|
* Routes one downstream tool call through the service registry.
|
|
@@ -174,56 +183,56 @@ export function buildGatewayTools(options = {}) {
|
|
|
174
183
|
const tools = [
|
|
175
184
|
{
|
|
176
185
|
name: "gateway_list_services",
|
|
177
|
-
description: "
|
|
186
|
+
description: "Finds enabled services. Text filters use case-insensitive substrings joined by OR; availability further limits matches.",
|
|
178
187
|
inputSchema: objectSchema([], {
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
188
|
+
serviceIdFilter: stringOrArraySchema("Service ID keywords."),
|
|
189
|
+
descFilter: stringOrArraySchema("Description keywords."),
|
|
190
|
+
availableFilter: {
|
|
182
191
|
type: "boolean",
|
|
183
|
-
description: "
|
|
192
|
+
description: "true: available services; false: unavailable services; omitted or null: either."
|
|
184
193
|
}
|
|
185
194
|
}),
|
|
186
195
|
outputSchema: outputSchemas.listServices
|
|
187
196
|
},
|
|
188
197
|
{
|
|
189
198
|
name: "gateway_get_service",
|
|
190
|
-
description: "
|
|
199
|
+
description: "Inspects a service's connection status, server metadata, and last error.",
|
|
191
200
|
inputSchema: objectSchema(["serviceId"], {
|
|
192
|
-
serviceId: stringSchema("
|
|
201
|
+
serviceId: stringSchema("Exact, case-sensitive service ID from gateway_list_services.")
|
|
193
202
|
}),
|
|
194
203
|
outputSchema: outputSchemas.getService
|
|
195
204
|
},
|
|
196
205
|
{
|
|
197
206
|
name: "gateway_list_tools",
|
|
198
|
-
description: "
|
|
207
|
+
description: "Finds tools within one service. Text filters use case-insensitive substrings joined by OR.",
|
|
199
208
|
inputSchema: objectSchema(["serviceId"], {
|
|
200
|
-
serviceId: stringSchema("
|
|
201
|
-
|
|
202
|
-
|
|
209
|
+
serviceId: stringSchema("Exact, case-sensitive service ID from gateway_list_services."),
|
|
210
|
+
toolNameFilter: stringOrArraySchema("Tool name keywords."),
|
|
211
|
+
descFilter: stringOrArraySchema("Description keywords. Matches may include negative guidance."),
|
|
203
212
|
includeSchema: {
|
|
204
213
|
type: "boolean",
|
|
205
|
-
description: "
|
|
214
|
+
description: "Include inputSchema and outputSchema. Omitted or null: false."
|
|
206
215
|
}
|
|
207
216
|
}),
|
|
208
217
|
outputSchema: outputSchemas.listTools
|
|
209
218
|
},
|
|
210
219
|
{
|
|
211
220
|
name: "gateway_get_tool_schema",
|
|
212
|
-
description: "Returns schemas
|
|
221
|
+
description: "Returns schemas keyed by tool name. Unknown names appear in errors; valid schemas are retained.",
|
|
213
222
|
inputSchema: objectSchema(["serviceId", "toolName"], {
|
|
214
|
-
serviceId: stringSchema("
|
|
215
|
-
toolName:
|
|
223
|
+
serviceId: stringSchema("Exact, case-sensitive service ID from gateway_list_services."),
|
|
224
|
+
toolName: stringOrArraySchema("Exact, case-sensitive tool names from gateway_list_tools.")
|
|
216
225
|
}),
|
|
217
226
|
outputSchema: outputSchemas.getToolSchema
|
|
218
227
|
},
|
|
219
228
|
{
|
|
220
229
|
name: "gateway_manage_service",
|
|
221
|
-
description: "Reconnects
|
|
230
|
+
description: "Reconnects, enables, or disables a configured service.",
|
|
222
231
|
inputSchema: objectSchema(["serviceId", "action"], {
|
|
223
|
-
serviceId: stringSchema("
|
|
232
|
+
serviceId: stringSchema("Exact, case-sensitive service ID from configuration. Disabled services are absent from gateway_list_services."),
|
|
224
233
|
action: {
|
|
225
234
|
type: "string",
|
|
226
|
-
description: "reconnect refreshes the connection
|
|
235
|
+
description: "reconnect refreshes the connection; enable and disable persist to config.",
|
|
227
236
|
enum: ["reconnect", "enable", "disable"]
|
|
228
237
|
}
|
|
229
238
|
}),
|
|
@@ -231,17 +240,31 @@ export function buildGatewayTools(options = {}) {
|
|
|
231
240
|
},
|
|
232
241
|
{
|
|
233
242
|
name: "gateway_call_tool",
|
|
234
|
-
description: "Calls one
|
|
243
|
+
description: "Calls one downstream tool and forwards its result. Side effects and confirmation requirements depend on that tool.",
|
|
235
244
|
inputSchema: objectSchema(["serviceId", "toolName", "arguments"], {
|
|
236
|
-
serviceId: stringSchema("
|
|
237
|
-
toolName: stringSchema("Exact, case-sensitive
|
|
245
|
+
serviceId: stringSchema("Exact, case-sensitive service ID from gateway_list_services."),
|
|
246
|
+
toolName: stringSchema("Exact, case-sensitive tool name from gateway_list_tools."),
|
|
238
247
|
arguments: {
|
|
239
248
|
type: "object",
|
|
240
|
-
description: "
|
|
249
|
+
description: "Downstream tool arguments matching its inputSchema. Use {} for no arguments."
|
|
241
250
|
}
|
|
242
251
|
})
|
|
243
252
|
}
|
|
244
253
|
];
|
|
254
|
+
// 可选参数允许显式传 null,运行时统一按未传处理。
|
|
255
|
+
for (const tool of tools) {
|
|
256
|
+
const required = tool.inputSchema.required;
|
|
257
|
+
const properties = tool.inputSchema.properties;
|
|
258
|
+
for (const [name, schema] of Object.entries(properties)) {
|
|
259
|
+
if (!required.includes(name)) {
|
|
260
|
+
const { description, ...shape } = schema;
|
|
261
|
+
properties[name] = {
|
|
262
|
+
...(description ? { description } : {}),
|
|
263
|
+
...nullableSchema(shape)
|
|
264
|
+
};
|
|
265
|
+
}
|
|
266
|
+
}
|
|
267
|
+
}
|
|
245
268
|
return options.includeAdminTools === false
|
|
246
269
|
? tools.filter((tool) => tool.name !== "gateway_manage_service")
|
|
247
270
|
: tools;
|
|
@@ -257,16 +280,11 @@ function formatServiceSummary(snapshot) {
|
|
|
257
280
|
};
|
|
258
281
|
}
|
|
259
282
|
/**
|
|
260
|
-
*
|
|
283
|
+
* 返回单份结构化结果,避免在文本内容中重复同一份 JSON。
|
|
261
284
|
*/
|
|
262
285
|
function successContent(data) {
|
|
263
286
|
return {
|
|
264
|
-
content: [
|
|
265
|
-
{
|
|
266
|
-
type: "text",
|
|
267
|
-
text: JSON.stringify(data, null, 2)
|
|
268
|
-
}
|
|
269
|
-
],
|
|
287
|
+
content: [],
|
|
270
288
|
structuredContent: data
|
|
271
289
|
};
|
|
272
290
|
}
|
|
@@ -332,11 +350,14 @@ function buildGatewayOutputSchemas() {
|
|
|
332
350
|
getToolSchema: objectSchema(["schemas"], {
|
|
333
351
|
schemas: {
|
|
334
352
|
type: "object",
|
|
335
|
-
minProperties: 1,
|
|
336
353
|
additionalProperties: objectSchema(["inputSchema", "outputSchema"], {
|
|
337
354
|
inputSchema: nullableToolSchema,
|
|
338
355
|
outputSchema: nullableToolSchema
|
|
339
356
|
})
|
|
357
|
+
},
|
|
358
|
+
errors: {
|
|
359
|
+
type: "object",
|
|
360
|
+
additionalProperties: { type: "string" }
|
|
340
361
|
}
|
|
341
362
|
}),
|
|
342
363
|
manageService: objectSchema(["serviceId", "action", "enabled", "available"], {
|
|
@@ -385,6 +406,14 @@ function uniqueNonEmptyStringArraySchema(description) {
|
|
|
385
406
|
}
|
|
386
407
|
};
|
|
387
408
|
}
|
|
409
|
+
/**
|
|
410
|
+
* 接受单个非空字符串或非空且不重复的字符串数组。
|
|
411
|
+
*/
|
|
412
|
+
function stringOrArraySchema(description) {
|
|
413
|
+
const { description: _stringDescription, ...string } = stringSchema(description);
|
|
414
|
+
const { description: _arrayDescription, ...array } = uniqueNonEmptyStringArraySchema(description);
|
|
415
|
+
return { description, anyOf: [string, array] };
|
|
416
|
+
}
|
|
388
417
|
/**
|
|
389
418
|
* Ensures the input is a plain object.
|
|
390
419
|
*/
|
|
@@ -404,12 +433,15 @@ function requireString(input, message) {
|
|
|
404
433
|
return input;
|
|
405
434
|
}
|
|
406
435
|
/**
|
|
407
|
-
*
|
|
436
|
+
* 将字符串或字符串数组统一为非空且不重复的字符串数组。
|
|
408
437
|
*/
|
|
409
|
-
function
|
|
438
|
+
function optionalStringOrArray(input, message) {
|
|
410
439
|
if (input === undefined || input === null) {
|
|
411
440
|
return undefined;
|
|
412
441
|
}
|
|
442
|
+
if (typeof input === "string") {
|
|
443
|
+
input = [input];
|
|
444
|
+
}
|
|
413
445
|
if (!Array.isArray(input)
|
|
414
446
|
|| input.length === 0
|
|
415
447
|
|| input.some((value) => typeof value !== "string" || value.trim() === "")
|
|
@@ -419,10 +451,10 @@ function optionalUniqueNonEmptyStringArray(input, message) {
|
|
|
419
451
|
return input;
|
|
420
452
|
}
|
|
421
453
|
/**
|
|
422
|
-
*
|
|
454
|
+
* 校验必填字符串或字符串数组并统一返回数组。
|
|
423
455
|
*/
|
|
424
|
-
function
|
|
425
|
-
const values =
|
|
456
|
+
function requireStringOrArray(input, message) {
|
|
457
|
+
const values = optionalStringOrArray(input, message);
|
|
426
458
|
if (!values) {
|
|
427
459
|
throw new Error(message);
|
|
428
460
|
}
|
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
import { fromJsonSchema } from "@modelcontextprotocol/server";
|
|
2
|
+
/**
|
|
3
|
+
* 保留 SDK 的完整校验和 schema 导出,仅整理输入失败时的提示。
|
|
4
|
+
*/
|
|
5
|
+
export function createInputSchema(schema) {
|
|
6
|
+
const base = fromJsonSchema(schema);
|
|
7
|
+
const properties = schema.properties;
|
|
8
|
+
const required = new Set(schema.required);
|
|
9
|
+
const validators = Object.fromEntries(Object.entries(properties).map(([name, field]) => [
|
|
10
|
+
name, fromJsonSchema(field)
|
|
11
|
+
]));
|
|
12
|
+
return {
|
|
13
|
+
"~standard": {
|
|
14
|
+
...base["~standard"],
|
|
15
|
+
validate: async (input) => {
|
|
16
|
+
const result = await base["~standard"].validate(input);
|
|
17
|
+
if (!result.issues) {
|
|
18
|
+
return result;
|
|
19
|
+
}
|
|
20
|
+
if (!isObject(input)) {
|
|
21
|
+
return { issues: [{ message: "Arguments must be an object." }] };
|
|
22
|
+
}
|
|
23
|
+
const messages = [];
|
|
24
|
+
for (const name of Object.keys(input)) {
|
|
25
|
+
if (!Object.hasOwn(properties, name)) {
|
|
26
|
+
messages.push(`Unsupported parameter ${JSON.stringify(name)}. Allowed parameters: ${Object.keys(properties).join(", ")}.`);
|
|
27
|
+
}
|
|
28
|
+
}
|
|
29
|
+
for (const [name, field] of Object.entries(properties)) {
|
|
30
|
+
if (input[name] === undefined) {
|
|
31
|
+
if (required.has(name)) {
|
|
32
|
+
messages.push(`Missing required parameter ${JSON.stringify(name)}.`);
|
|
33
|
+
}
|
|
34
|
+
continue;
|
|
35
|
+
}
|
|
36
|
+
const checked = await validators[name]["~standard"].validate(input[name]);
|
|
37
|
+
if (checked.issues) {
|
|
38
|
+
messages.push(`${name}: ${describeInvalid(input[name], field)}`);
|
|
39
|
+
}
|
|
40
|
+
}
|
|
41
|
+
return messages.length ? { issues: messages.map(message => ({ message })) } : result;
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
};
|
|
45
|
+
}
|
|
46
|
+
/**
|
|
47
|
+
* 展开网关参数的联合类型,避免把每个分支的错误逐条返回。
|
|
48
|
+
*/
|
|
49
|
+
function alternatives(schema) {
|
|
50
|
+
return Array.isArray(schema.anyOf)
|
|
51
|
+
? schema.anyOf.flatMap(alternatives)
|
|
52
|
+
: [schema];
|
|
53
|
+
}
|
|
54
|
+
/**
|
|
55
|
+
* 按参数 schema 生成可纠正的提示,不回显参数值。
|
|
56
|
+
*/
|
|
57
|
+
function describeInvalid(value, schema) {
|
|
58
|
+
const choices = alternatives(schema);
|
|
59
|
+
const type = value === null ? "null" : Array.isArray(value) ? "array" : typeof value;
|
|
60
|
+
const branch = choices.find(choice => choice.type === type);
|
|
61
|
+
const expected = choices.map(choice => {
|
|
62
|
+
if (Array.isArray(choice.enum)) {
|
|
63
|
+
return choice.enum.map(item => JSON.stringify(item)).join(" | ");
|
|
64
|
+
}
|
|
65
|
+
if (choice.type === "string" && choice.pattern === "\\S") {
|
|
66
|
+
return "non-blank string";
|
|
67
|
+
}
|
|
68
|
+
if (choice.type === "array") {
|
|
69
|
+
return `${choice.minItems ? "non-empty " : ""}${choice.uniqueItems ? "unique " : ""}string array`;
|
|
70
|
+
}
|
|
71
|
+
return String(choice.type);
|
|
72
|
+
}).join(" or ");
|
|
73
|
+
let reason = "";
|
|
74
|
+
if (branch && Array.isArray(value)) {
|
|
75
|
+
if (typeof branch.minItems === "number" && value.length < branch.minItems) {
|
|
76
|
+
reason = "Array must not be empty. ";
|
|
77
|
+
}
|
|
78
|
+
else if (branch.uniqueItems && new Set(value).size !== value.length) {
|
|
79
|
+
reason = "Array items must be unique. ";
|
|
80
|
+
}
|
|
81
|
+
else if (isObject(branch.items) && branch.items.type === "string") {
|
|
82
|
+
const index = value.findIndex(item => typeof item !== "string" || !item.trim());
|
|
83
|
+
if (index >= 0) {
|
|
84
|
+
reason = `Item at index ${index} must be a non-blank string. `;
|
|
85
|
+
}
|
|
86
|
+
}
|
|
87
|
+
}
|
|
88
|
+
return `${reason}Expected ${expected}.`;
|
|
89
|
+
}
|
|
90
|
+
/**
|
|
91
|
+
* 识别参数对象,排除 null 和数组。
|
|
92
|
+
*/
|
|
93
|
+
function isObject(value) {
|
|
94
|
+
return typeof value === "object" && value !== null && !Array.isArray(value);
|
|
95
|
+
}
|
package/dist/mcp/server.js
CHANGED
|
@@ -2,6 +2,7 @@ import { CLIENT_CAPABILITIES_META_KEY, McpServer, fromJsonSchema } from "@modelc
|
|
|
2
2
|
import { buildGatewayTools } from "../gateway-engine.js";
|
|
3
3
|
import { VERSION } from "../version.js";
|
|
4
4
|
import { SUPPORTED_MCP_PROTOCOL_VERSIONS } from "./versions.js";
|
|
5
|
+
import { createInputSchema } from "./input-schema.js";
|
|
5
6
|
/**
|
|
6
7
|
* Creates one SDK server instance with the selected gateway tool surface.
|
|
7
8
|
*/
|
|
@@ -29,7 +30,7 @@ export function createGatewayMcpServer(engine, options = {}) {
|
|
|
29
30
|
};
|
|
30
31
|
const server = new McpServer({ name: "mcp-gateway", version: VERSION }, serverOptions);
|
|
31
32
|
for (const tool of buildGatewayTools(options)) {
|
|
32
|
-
const inputSchema =
|
|
33
|
+
const inputSchema = createInputSchema(tool.inputSchema);
|
|
33
34
|
const outputSchema = tool.outputSchema
|
|
34
35
|
? fromJsonSchema(tool.outputSchema)
|
|
35
36
|
: undefined;
|
package/package.json
CHANGED
|
@@ -1,27 +1,26 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: mcp-gateway
|
|
3
|
-
description:
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# MCP Gateway
|
|
7
|
-
|
|
8
|
-
Use the gateway as the single entry point for downstream MCP services.
|
|
9
|
-
|
|
10
|
-
## Workflow
|
|
11
|
-
|
|
1
|
+
---
|
|
2
|
+
name: mcp-gateway
|
|
3
|
+
description: Use when discovering or calling downstream tools through MCP Gateway without loading every tool schema.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# MCP Gateway
|
|
7
|
+
|
|
8
|
+
Use the gateway as the single entry point for downstream MCP services.
|
|
9
|
+
|
|
10
|
+
## Workflow
|
|
11
|
+
|
|
12
12
|
1. Reuse an exact `serviceId` already confirmed in the current session; otherwise call `gateway_list_services`.
|
|
13
|
-
2. Reuse an exact downstream tool name already confirmed in the session; otherwise search only that service with `gateway_list_tools`.
|
|
14
|
-
3. Obtain unfamiliar or safety-sensitive schemas with `includeSchema: true` or `gateway_get_tool_schema
|
|
15
|
-
4. Call `gateway_call_tool` with the confirmed identifiers and
|
|
16
|
-
5.
|
|
17
|
-
|
|
18
|
-
## Diagnostics and Control
|
|
19
|
-
|
|
20
|
-
- Treat `serviceId` as a downstream identifier, never as a gateway-owned tool.
|
|
21
|
-
- Use `gateway_get_service` for connection diagnostics. Use `gateway_manage_service` only when explicitly requested: `reconnect` does not change config, while `enable` and `disable` persist.
|
|
22
|
-
|
|
23
|
-
## Safety
|
|
24
|
-
|
|
25
|
-
-
|
|
26
|
-
-
|
|
27
|
-
- Never auto-approve an `input_required` result. Obtain the requested user input and retry with the returned opaque state and matching responses.
|
|
13
|
+
2. Reuse an exact downstream tool name already confirmed in the session; otherwise search only that service with `gateway_list_tools`.
|
|
14
|
+
3. Obtain unfamiliar or safety-sensitive schemas with `includeSchema: true` or `gateway_get_tool_schema`.
|
|
15
|
+
4. Call `gateway_call_tool` with the confirmed identifiers and arguments.
|
|
16
|
+
5. Retain successful batch schemas; resolve only names listed in `errors`. Refresh only stale identifiers or schemas.
|
|
17
|
+
|
|
18
|
+
## Diagnostics and Control
|
|
19
|
+
|
|
20
|
+
- Treat `serviceId` as a downstream identifier, never as a gateway-owned tool.
|
|
21
|
+
- Use `gateway_get_service` for connection diagnostics. Use `gateway_manage_service` only when explicitly requested: `reconnect` does not change config, while `enable` and `disable` persist.
|
|
22
|
+
|
|
23
|
+
## Safety
|
|
24
|
+
|
|
25
|
+
- Treat gateway failures and structured downstream error results as failures.
|
|
26
|
+
- Never auto-approve an `input_required` result. Obtain the requested user input and retry with the returned opaque state and matching responses.
|