@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 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 configured 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
-
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
- `gateway_list_services` accepts optional `serviceId` and `desc` string arrays as case-insensitive substring filters. Matches across these two fields use OR. The optional `available` boolean further limits those matches by current availability.
181
-
182
- Calls keep the downstream tool's original side effects and confirmation rules. Tools matching `confirmationRequiredTools` are never invoked until the current MCP session reviews the exact service, tool, and arguments and answers `yes` to the form elicitation; sessions without form elicitation support receive an error. A `no`, decline, or cancel returns an explicit rejection without invoking the downstream tool. An uncertain `gateway_call_tool` failure is never replayed automatically. Enabling or disabling a service with `gateway_manage_service` atomically updates the config file.
183
-
184
- `disabledTools` takes precedence over `confirmationRequiredTools` when both match. A disabled tool is hidden and rejected immediately without asking for confirmation.
185
-
186
- Agents with Skills support can use the included [MCP Gateway Skill](./skills/mcp-gateway/SKILL.md) for the discovery and calling workflow.
187
-
188
- ## Development
189
-
190
- ```bash
191
- git clone https://github.com/jadchene/mcp-gateway.git
192
- cd mcp-gateway
193
- npm install
194
- npm run verify
195
- npm run dev -- --config ./config.json
196
- ```
197
-
198
- Build and run the compiled service:
199
-
200
- ```bash
201
- npm run build
202
- npm start -- --config ./config.json
203
- ```
204
-
205
- ## License
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
- `gateway_list_services` 可选传入 `serviceId`、`desc` 字符串数组,按不区分大小写的子串匹配,两类文本条件之间为 OR;还可传入 `available` 布尔值,在文本匹配结果上继续按当前可用状态筛选。
181
-
182
- 工具调用会保留下游工具原有的副作用和确认规则。匹配 `confirmationRequiredTools` 模式的工具会展示实际服务、工具和完整参数,只有当前 MCP 会话在表单 elicitation 中选择 `yes` 后才会调用;会话不支持表单 elicitation,或用户选择 `no`、拒绝、取消时,网关会返回明确的拒绝结果且不会调用下游工具。状态不确定的 `gateway_call_tool` 失败不会自动重放。通过 `gateway_manage_service` 启用或禁用服务会原子更新配置文件。
183
-
184
- 当一个工具同时匹配 `disabledTools` 和 `confirmationRequiredTools` 时,`disabledTools` 优先:工具会被隐藏并直接拒绝,不会发起确认。
185
-
186
- 支持 Skills 的 Agent 可以使用仓库内置的 [MCP Gateway Skill](./skills/mcp-gateway/SKILL.md) 完成工具发现和调用。
187
-
188
- ## 开发
189
-
190
- ```bash
191
- git clone https://github.com/jadchene/mcp-gateway.git
192
- cd mcp-gateway
193
- npm install
194
- npm run verify
195
- npm run dev -- --config ./config.json
196
- ```
197
-
198
- 构建并运行编译产物:
199
-
200
- ```bash
201
- npm run build
202
- npm start -- --config ./config.json
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)
@@ -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 = optionalUniqueNonEmptyStringArray(args.serviceId, "The 'serviceId' argument must be a unique non-empty string array when provided.");
58
- const desc = optionalUniqueNonEmptyStringArray(args.desc, "The 'desc' argument must be a unique non-empty string array when provided.");
59
- const available = optionalBoolean(args.available, "The 'available' argument must be a boolean when provided.");
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 = optionalUniqueNonEmptyStringArray(args.toolName, "The 'toolName' argument must be a unique non-empty string array when provided.");
99
- const desc = optionalUniqueNonEmptyStringArray(args.desc, "The 'desc' argument must be a unique non-empty string array when provided.");
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 = requireUniqueNonEmptyStringArray(args.toolName, "The 'toolName' argument must be a unique non-empty string array.");
121
- const schemas = Object.fromEntries(toolNames.map((toolName) => {
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
- throw new Error(`Unknown tool '${toolName}' in service '${serviceId}'.`);
126
+ missing.push([toolName, `Unknown tool in service '${serviceId}'.`]);
127
+ continue;
125
128
  }
126
- return [toolName, {
129
+ found.push([toolName, {
127
130
  inputSchema: tool.inputSchema ?? null,
128
131
  outputSchema: tool.outputSchema ?? null
129
- }];
130
- }));
131
- return successContent({ schemas });
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: "Lists downstream MCP services by case-insensitive identifier or description substring filters and optional availability.",
186
+ description: "Finds enabled services. Text filters use case-insensitive substrings joined by OR; availability further limits matches.",
178
187
  inputSchema: objectSchema([], {
179
- serviceId: uniqueNonEmptyStringArraySchema("Optional unique service identifier substrings. Matching is case-insensitive; identifier and description filters use OR."),
180
- desc: uniqueNonEmptyStringArraySchema("Optional unique description substrings. Matching is case-insensitive; identifier and description filters use OR."),
181
- available: {
188
+ serviceIdFilter: stringOrArraySchema("Service ID keywords."),
189
+ descFilter: stringOrArraySchema("Description keywords."),
190
+ availableFilter: {
182
191
  type: "boolean",
183
- description: "Optionally limits results to services with the requested current availability."
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: "Returns one downstream service's configured identity, availability, recent error and connection time, protocol version, and server information.",
199
+ description: "Inspects a service's connection status, server metadata, and last error.",
191
200
  inputSchema: objectSchema(["serviceId"], {
192
- serviceId: stringSchema("Logical downstream service identifier returned by gateway_list_services.")
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: "Lists downstream tools by case-insensitive name or description substring filters and optionally includes each matching schema.",
207
+ description: "Finds tools within one service. Text filters use case-insensitive substrings joined by OR.",
199
208
  inputSchema: objectSchema(["serviceId"], {
200
- serviceId: stringSchema("Logical downstream service identifier returned by gateway_list_services."),
201
- toolName: uniqueNonEmptyStringArraySchema("Optional unique name substrings. Matching is case-insensitive; any name or description keyword may match."),
202
- desc: uniqueNonEmptyStringArraySchema("Optional unique literal description substrings. Matching is case-insensitive and may hit negative guidance, so inspect candidate descriptions. Name and description filters use OR."),
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: "Includes inputSchema and outputSchema in every returned tool when true. Defaults to false."
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 for exact, case-sensitive downstream tool names, keyed by name; the whole request fails when any name is unknown.",
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("Logical downstream service identifier returned by gateway_list_services."),
215
- toolName: uniqueNonEmptyStringArraySchema("Unique exact, case-sensitive downstream tool names returned by gateway_list_tools.")
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 a downstream service without changing config, or persistently enables or disables it in the gateway config and reloads the registry.",
230
+ description: "Reconnects, enables, or disables a configured service.",
222
231
  inputSchema: objectSchema(["serviceId", "action"], {
223
- serviceId: stringSchema("Logical downstream service identifier returned by gateway_list_services."),
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 and metadata without changing config; enable and disable persist the enable flag and reload the registry.",
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 exact downstream tool and forwards its result unchanged. The downstream tool may have read or write side effects; inspect its schema and service rules first.",
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("Logical downstream service identifier returned by gateway_list_services."),
237
- toolName: stringSchema("Exact, case-sensitive downstream tool name returned by gateway_list_tools."),
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: "Required arguments object built from the downstream inputSchema. Pass an empty object when the tool has no arguments."
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
- * Builds a standard MCP tool success payload with text and structured content.
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
- * Returns an optional unique non-empty array of non-empty strings.
436
+ * 将字符串或字符串数组统一为非空且不重复的字符串数组。
408
437
  */
409
- function optionalUniqueNonEmptyStringArray(input, message) {
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
- * Returns a required unique non-empty string array.
454
+ * 校验必填字符串或字符串数组并统一返回数组。
423
455
  */
424
- function requireUniqueNonEmptyStringArray(input, message) {
425
- const values = optionalUniqueNonEmptyStringArray(input, message);
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
+ }
@@ -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 = fromJsonSchema(tool.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,6 +1,6 @@
1
1
  {
2
2
  "name": "@jadchene/mcp-gateway-service",
3
- "version": "0.10.0",
3
+ "version": "0.11.1",
4
4
  "description": "A token-efficient MCP gateway that provides one unified entry point for multiple downstream MCP services.",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
@@ -1,27 +1,26 @@
1
- ---
2
- name: mcp-gateway
3
- description: Route work through an MCP gateway with token-efficient downstream service discovery, filtered tool search, exact schema lookup, service diagnostics, and forwarded tool calls. Use when an agent needs to find or call tools behind the gateway without loading every downstream schema.
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`. The unique non-empty `toolName` and `desc` filters are case-insensitive literal substrings joined by OR, so inspect description matches for negative guidance.
14
- 3. Obtain unfamiliar or safety-sensitive schemas with `includeSchema: true` or `gateway_get_tool_schema`; tool names are exact and case-sensitive.
15
- 4. Call `gateway_call_tool` with the confirmed identifiers and an explicit `arguments` object; pass `{}` when the tool has no arguments.
16
- 5. Refresh only the identifier or schema rejected as stale.
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
- - Apply the downstream tool's schema, side-effect rules, and confirmation flow before calling it.
26
- - Treat gateway failures and structured downstream error results as failures.
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.