@jadchene/mcp-gateway-service 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +274 -0
- package/README_zh.md +276 -0
- package/config.example.json +18 -0
- package/dist/config.js +163 -0
- package/dist/file-watcher.js +82 -0
- package/dist/gateway-server.js +298 -0
- package/dist/index.js +82 -0
- package/dist/logger.js +35 -0
- package/dist/mcp/client.js +571 -0
- package/dist/mcp/protocol.js +193 -0
- package/dist/service-registry.js +250 -0
- package/dist/types.js +1 -0
- package/dist/version.js +8 -0
- package/package.json +44 -0
- package/scripts/install-global.ps1 +111 -0
- package/scripts/publish-npm.ps1 +108 -0
- package/skills/mcp-gateway/SKILL.md +64 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 jadchene
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,274 @@
|
|
|
1
|
+
English | [简体中文](./README_zh.md)
|
|
2
|
+
|
|
3
|
+
# MCP Gateway
|
|
4
|
+
|
|
5
|
+
This project provides a lightweight Model Context Protocol (MCP) gateway for **token-efficient, on-demand discovery** and **one unified entry point for multiple downstream services**.
|
|
6
|
+
|
|
7
|
+
Instead of exposing every downstream MCP tool up front, the gateway keeps a small fixed tool surface and lets the client discover services, list tools for a specific service, fetch one tool schema when needed, and then forward the actual tool call.
|
|
8
|
+
|
|
9
|
+
## Why Use This Gateway
|
|
10
|
+
|
|
11
|
+
This gateway is designed for a practical problem that appears quickly once you use multiple MCP services across multiple agents.
|
|
12
|
+
|
|
13
|
+
If every agent connects directly to every MCP service, two problems show up:
|
|
14
|
+
|
|
15
|
+
1. The tool surface becomes too large.
|
|
16
|
+
2. The MCP configuration becomes too repetitive.
|
|
17
|
+
|
|
18
|
+
### 1. Reduce token consumption
|
|
19
|
+
|
|
20
|
+
Many MCP services expose dozens or even hundreds of tools.
|
|
21
|
+
|
|
22
|
+
If an agent connects directly to several MCP services, the client often needs to expose or describe a very large tool inventory up front. That increases:
|
|
23
|
+
|
|
24
|
+
- prompt size
|
|
25
|
+
- tool discovery cost
|
|
26
|
+
- repeated schema/context overhead across sessions
|
|
27
|
+
|
|
28
|
+
This gateway avoids that by exposing a **small fixed discovery interface** instead of flattening every downstream tool into the initial tool list.
|
|
29
|
+
|
|
30
|
+
The normal flow becomes:
|
|
31
|
+
|
|
32
|
+
1. list available services
|
|
33
|
+
2. inspect tools for one selected service
|
|
34
|
+
3. fetch schema for one selected tool
|
|
35
|
+
4. call that tool
|
|
36
|
+
|
|
37
|
+
That means the model only sees the minimum amount of MCP metadata needed for the current task.
|
|
38
|
+
|
|
39
|
+
### 2. Provide one unified MCP entry point for multiple agents
|
|
40
|
+
|
|
41
|
+
Without a gateway, each agent usually needs its own MCP client configuration for every downstream service:
|
|
42
|
+
|
|
43
|
+
- database MCP
|
|
44
|
+
- SSH MCP
|
|
45
|
+
- IDE MCP
|
|
46
|
+
- Playwright MCP
|
|
47
|
+
- Gitea MCP
|
|
48
|
+
- and more
|
|
49
|
+
|
|
50
|
+
That quickly becomes hard to maintain:
|
|
51
|
+
|
|
52
|
+
- every agent config needs to be updated when services change
|
|
53
|
+
- command paths and environment variables are repeated
|
|
54
|
+
- secrets and local machine details are spread across multiple client configs
|
|
55
|
+
- different agents may drift out of sync over time
|
|
56
|
+
|
|
57
|
+
With this gateway, the downstream MCP pool is defined once in one config file, and every agent only needs to connect to the gateway itself.
|
|
58
|
+
|
|
59
|
+
That gives you a cleaner architecture:
|
|
60
|
+
|
|
61
|
+
- one MCP entry point for many services
|
|
62
|
+
- one place to add, remove, or update downstream MCP definitions
|
|
63
|
+
- one place to control what is exposed to agents
|
|
64
|
+
- less duplicated local configuration
|
|
65
|
+
- easier reuse across Codex, Claude Code, Gemini CLI, or other MCP-capable clients
|
|
66
|
+
|
|
67
|
+
In short, this gateway is useful when you want to treat multiple MCP services as a managed service pool rather than reconfiguring the same MCP stack separately for every agent.
|
|
68
|
+
|
|
69
|
+
## Key Pillars
|
|
70
|
+
|
|
71
|
+
### Token-Efficient Discovery
|
|
72
|
+
- Keep the public tool surface small and stable.
|
|
73
|
+
- Discover services first, then tools for one service, then schema for one tool.
|
|
74
|
+
- Avoid sending hundreds of downstream tools to the model at session start.
|
|
75
|
+
|
|
76
|
+
### Stable Gateway Surface
|
|
77
|
+
- Expose a fixed gateway contract instead of dynamically flattening downstream tools.
|
|
78
|
+
- Return compact discovery payloads for service and tool enumeration.
|
|
79
|
+
- Forward downstream tool results directly to the caller for minimal wrapping.
|
|
80
|
+
|
|
81
|
+
### Practical Operations
|
|
82
|
+
- Load a static service pool from JSON.
|
|
83
|
+
- Reload config automatically when the file changes.
|
|
84
|
+
- Stop removed, disabled, or replaced downstream processes during hot reload.
|
|
85
|
+
- Restart failed downstream processes up to 3 times before marking them unavailable.
|
|
86
|
+
- Preserve the last valid config snapshot when a reload fails.
|
|
87
|
+
|
|
88
|
+
## Quick Start
|
|
89
|
+
|
|
90
|
+
### Install globally
|
|
91
|
+
|
|
92
|
+
```bash
|
|
93
|
+
npm install -g @jadchene/mcp-gateway-service
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
Start the gateway:
|
|
97
|
+
|
|
98
|
+
```bash
|
|
99
|
+
mcp-gateway-service
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
With an explicit config path:
|
|
103
|
+
|
|
104
|
+
```bash
|
|
105
|
+
mcp-gateway-service --config ./config.json
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
### Run from source
|
|
109
|
+
|
|
110
|
+
Create a local `config.json` from `config.example.json`, then start the gateway:
|
|
111
|
+
|
|
112
|
+
```bash
|
|
113
|
+
npm install
|
|
114
|
+
npm run dev
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
By default the gateway loads `./config.json`.
|
|
118
|
+
Use `--config <path>` to override it for the current process. If `--config` is omitted, the gateway falls back to `MCP_GATEWAY_CONFIG`, then `./config.json`.
|
|
119
|
+
|
|
120
|
+
Override it with:
|
|
121
|
+
|
|
122
|
+
```bash
|
|
123
|
+
$env:MCP_GATEWAY_CONFIG="config/gateway/config.json"
|
|
124
|
+
npm run dev
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
### Version
|
|
128
|
+
|
|
129
|
+
```bash
|
|
130
|
+
mcp-gateway-service --version
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
Short form:
|
|
134
|
+
|
|
135
|
+
```bash
|
|
136
|
+
mcp-gateway-service -v
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
## Configuration
|
|
140
|
+
|
|
141
|
+
The gateway currently supports `stdio` downstream transports only.
|
|
142
|
+
|
|
143
|
+
A service is loaded only when `enable` is missing or set to `true`. If `enable` is set to `false`, the gateway skips that service entirely. During hot reload, disabling or removing a service also stops its existing downstream process if one is running.
|
|
144
|
+
|
|
145
|
+
- `enable` is optional. When omitted, the gateway treats the service as enabled.
|
|
146
|
+
- `cwd` is optional. When omitted, the gateway uses its current working directory.
|
|
147
|
+
- `env` is optional.
|
|
148
|
+
- `framing` is optional. When omitted, the gateway tries `line` first and then `content-length`.
|
|
149
|
+
|
|
150
|
+
### Config shape
|
|
151
|
+
|
|
152
|
+
```json
|
|
153
|
+
{
|
|
154
|
+
"services": [
|
|
155
|
+
{
|
|
156
|
+
"serviceId": "demo-echo",
|
|
157
|
+
"enable": true,
|
|
158
|
+
"name": "Demo Echo Service",
|
|
159
|
+
"description": "Sample echo MCP service.",
|
|
160
|
+
"transport": {
|
|
161
|
+
"type": "stdio",
|
|
162
|
+
"command": "node",
|
|
163
|
+
"args": [
|
|
164
|
+
"--experimental-strip-types",
|
|
165
|
+
"examples/echo-service.ts"
|
|
166
|
+
]
|
|
167
|
+
}
|
|
168
|
+
}
|
|
169
|
+
]
|
|
170
|
+
}
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
## Public Gateway Tools
|
|
174
|
+
|
|
175
|
+
The gateway exposes a fixed set of discovery and routing tools:
|
|
176
|
+
|
|
177
|
+
- `gateway.listServices`
|
|
178
|
+
- `gateway.getService`
|
|
179
|
+
- `gateway.listTools`
|
|
180
|
+
- `gateway.getToolSchema`
|
|
181
|
+
- `gateway.callTool`
|
|
182
|
+
|
|
183
|
+
### Response design
|
|
184
|
+
|
|
185
|
+
- `gateway.listServices` returns only `serviceId`, `description`, and `available`.
|
|
186
|
+
- `gateway.listTools` returns only `name` and `description`.
|
|
187
|
+
- `gateway.getToolSchema` returns only `inputSchema` and `outputSchema`.
|
|
188
|
+
- `gateway.callTool` forwards the downstream MCP tool result directly without extra gateway metadata wrapping.
|
|
189
|
+
|
|
190
|
+
## Recommended Client Workflow
|
|
191
|
+
|
|
192
|
+
For the best token efficiency, the MCP client should cache discovery results instead of repeatedly querying the gateway:
|
|
193
|
+
|
|
194
|
+
1. Call `gateway.listServices` once at session start.
|
|
195
|
+
2. Call `gateway.listTools(serviceId)` only when a service is actually needed.
|
|
196
|
+
3. Call `gateway.getToolSchema(serviceId, toolName)` only before the first use of that tool.
|
|
197
|
+
4. Call `gateway.callTool(...)` for execution.
|
|
198
|
+
5. Refresh discovery data only when a call fails, the config changes, or the client explicitly wants a refresh.
|
|
199
|
+
|
|
200
|
+
## Skill Integration (Recommended)
|
|
201
|
+
|
|
202
|
+
This repository includes a public skill for agent frameworks that support skill loading:
|
|
203
|
+
|
|
204
|
+
- Skill path: `skills/mcp-gateway/SKILL.md`
|
|
205
|
+
|
|
206
|
+
The skill focuses on:
|
|
207
|
+
|
|
208
|
+
- token-efficient discovery flow
|
|
209
|
+
- avoiding unnecessary schema/tool enumeration
|
|
210
|
+
- calling downstream tools through the minimal gateway contract
|
|
211
|
+
|
|
212
|
+
## MCP Client Configuration
|
|
213
|
+
|
|
214
|
+
The examples below intentionally use relative config paths so they stay portable.
|
|
215
|
+
|
|
216
|
+
### Codex
|
|
217
|
+
|
|
218
|
+
`~/.codex/config.toml`
|
|
219
|
+
|
|
220
|
+
```toml
|
|
221
|
+
[mcp_servers.gateway]
|
|
222
|
+
command = "mcp-gateway-service"
|
|
223
|
+
args = ["--config", "./config.json"]
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
### Gemini CLI
|
|
227
|
+
|
|
228
|
+
`~/.gemini/settings.json`
|
|
229
|
+
|
|
230
|
+
```json
|
|
231
|
+
{
|
|
232
|
+
"mcpServers": {
|
|
233
|
+
"gateway": {
|
|
234
|
+
"type": "stdio",
|
|
235
|
+
"command": "mcp-gateway-service",
|
|
236
|
+
"args": [
|
|
237
|
+
"--config",
|
|
238
|
+
"./config.json"
|
|
239
|
+
]
|
|
240
|
+
}
|
|
241
|
+
}
|
|
242
|
+
}
|
|
243
|
+
```
|
|
244
|
+
|
|
245
|
+
### Claude Code
|
|
246
|
+
|
|
247
|
+
`~/.claude.json`
|
|
248
|
+
|
|
249
|
+
```json
|
|
250
|
+
{
|
|
251
|
+
"mcpServers": {
|
|
252
|
+
"gateway": {
|
|
253
|
+
"type": "stdio",
|
|
254
|
+
"command": "mcp-gateway-service",
|
|
255
|
+
"args": [
|
|
256
|
+
"--config",
|
|
257
|
+
"./config.json"
|
|
258
|
+
]
|
|
259
|
+
}
|
|
260
|
+
}
|
|
261
|
+
}
|
|
262
|
+
```
|
|
263
|
+
|
|
264
|
+
## Development Notes
|
|
265
|
+
|
|
266
|
+
- Repository-managed `config.json` and `config.example.json` are examples only.
|
|
267
|
+
- Copy `config.example.json` to your own local `config.json` before running the gateway.
|
|
268
|
+
- Keep real local configs and logs outside the repository.
|
|
269
|
+
- Downstream output schema is returned only when the downstream service exposes it.
|
|
270
|
+
- Windows command resolution supports PowerShell shims such as `.ps1`-backed command aliases.
|
|
271
|
+
|
|
272
|
+
## License
|
|
273
|
+
|
|
274
|
+
Released under the [MIT License](./LICENSE).
|
package/README_zh.md
ADDED
|
@@ -0,0 +1,276 @@
|
|
|
1
|
+
[English](./README.md) | 简体中文
|
|
2
|
+
|
|
3
|
+
# MCP Gateway
|
|
4
|
+
|
|
5
|
+
这个项目提供了一个轻量的 MCP 网关,用于实现**按需发现、节省 token**,并为多个下游 MCP 服务提供**统一接入入口**。
|
|
6
|
+
|
|
7
|
+
它不会在会话开始时把所有下游 MCP 工具一次性暴露给 AI,而是保持一个固定且很小的网关工具集合,让客户端按需:
|
|
8
|
+
|
|
9
|
+
- 先发现可用服务
|
|
10
|
+
- 再查看某个服务的工具列表
|
|
11
|
+
- 再查询某个工具的 schema
|
|
12
|
+
- 最后转发真实工具调用
|
|
13
|
+
|
|
14
|
+
## 为什么要用这个网关
|
|
15
|
+
|
|
16
|
+
这个网关主要解决的是一个很实际的问题:
|
|
17
|
+
当你有多个 MCP 服务、多个 Agent 时,直接让每个 Agent 去分别配置所有 MCP,成本会越来越高。
|
|
18
|
+
|
|
19
|
+
通常会出现两个核心问题:
|
|
20
|
+
|
|
21
|
+
1. 工具太多,token 消耗太高
|
|
22
|
+
2. MCP 配置重复,维护成本太高
|
|
23
|
+
|
|
24
|
+
### 1. 降低 token 消耗
|
|
25
|
+
|
|
26
|
+
很多 MCP 服务本身会暴露几十甚至上百个工具。
|
|
27
|
+
|
|
28
|
+
如果一个 Agent 直接连接多个 MCP,客户端通常需要在会话开始时就把大量 tool 信息暴露给模型,这会带来:
|
|
29
|
+
|
|
30
|
+
- prompt 变长
|
|
31
|
+
- 工具发现成本变高
|
|
32
|
+
- schema 和工具描述反复进入上下文
|
|
33
|
+
|
|
34
|
+
这个网关的做法不是把所有下游工具都直接展开,而是只暴露一个很小的固定发现接口。
|
|
35
|
+
|
|
36
|
+
正常调用流程变成:
|
|
37
|
+
|
|
38
|
+
1. 先查看有哪些服务
|
|
39
|
+
2. 再查看某个服务下有哪些工具
|
|
40
|
+
3. 再查看某个工具的 schema
|
|
41
|
+
4. 最后真正调用这个工具
|
|
42
|
+
|
|
43
|
+
这样模型只会在需要时看到最少量的 MCP 元数据,更适合“按需发现”的使用方式。
|
|
44
|
+
|
|
45
|
+
### 2. 给多个 Agent 提供统一的 MCP 接入入口
|
|
46
|
+
|
|
47
|
+
如果没有网关,每个 Agent 往往都要单独配置一遍这些 MCP:
|
|
48
|
+
|
|
49
|
+
- database MCP
|
|
50
|
+
- SSH MCP
|
|
51
|
+
- IDE MCP
|
|
52
|
+
- Playwright MCP
|
|
53
|
+
- Gitea MCP
|
|
54
|
+
- 以及其他服务
|
|
55
|
+
|
|
56
|
+
这种方式很快会带来维护问题:
|
|
57
|
+
|
|
58
|
+
- 下游服务一变,每个 Agent 配置都要改
|
|
59
|
+
- 命令路径、环境变量、工作目录会重复出现
|
|
60
|
+
- 密钥和本地路径分散在多个客户端配置里
|
|
61
|
+
- 不同 Agent 的配置很容易逐渐不一致
|
|
62
|
+
|
|
63
|
+
用了这个网关之后,下游 MCP 服务池只需要在网关配置里维护一次,多个 Agent 只需要连接这一个网关即可。
|
|
64
|
+
|
|
65
|
+
这样带来的好处是:
|
|
66
|
+
|
|
67
|
+
- 多个 MCP 统一成一个入口
|
|
68
|
+
- 下游服务的增删改集中在一个地方处理
|
|
69
|
+
- 更容易控制哪些服务对 Agent 可见
|
|
70
|
+
- 减少本地重复配置
|
|
71
|
+
- 更方便在 Codex、Claude Code、Gemini CLI 等不同客户端之间复用
|
|
72
|
+
|
|
73
|
+
简单说,这个网关的价值不只是“转发调用”,而是把多个 MCP 统一成一个可管理的服务池,同时把模型看到的工具上下文压缩到最小。
|
|
74
|
+
|
|
75
|
+
## 核心特点
|
|
76
|
+
|
|
77
|
+
### 按需发现,节省 Token
|
|
78
|
+
- 对外只暴露少量固定网关工具。
|
|
79
|
+
- 只在真正需要时查询服务工具列表和工具 schema。
|
|
80
|
+
- 避免把数百个下游 tool 在初始化阶段全部发给模型。
|
|
81
|
+
|
|
82
|
+
### 稳定的网关接口
|
|
83
|
+
- 不动态展开所有下游工具。
|
|
84
|
+
- 服务列表和工具列表返回精简结构。
|
|
85
|
+
- `gateway.callTool` 直接透传下游工具返回结果,减少额外包装。
|
|
86
|
+
|
|
87
|
+
### 实用运维能力
|
|
88
|
+
- 从 JSON 配置文件加载静态服务池。
|
|
89
|
+
- 监听配置文件变化并自动热刷新。
|
|
90
|
+
- 热刷新时会停掉已删除、已禁用或已被替换配置对应的下游进程。
|
|
91
|
+
- 下游进程异常时最多自动重启 3 次。
|
|
92
|
+
- 配置刷新失败时保留上一版有效快照。
|
|
93
|
+
|
|
94
|
+
## 快速开始
|
|
95
|
+
|
|
96
|
+
### 全局安装
|
|
97
|
+
|
|
98
|
+
```bash
|
|
99
|
+
npm install -g @jadchene/mcp-gateway-service
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
启动网关:
|
|
103
|
+
|
|
104
|
+
```bash
|
|
105
|
+
mcp-gateway-service
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
显式指定配置文件:
|
|
109
|
+
|
|
110
|
+
```bash
|
|
111
|
+
mcp-gateway-service --config ./config.json
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
### 从源码运行
|
|
115
|
+
|
|
116
|
+
先基于 `config.example.json` 自行创建本地 `config.json`,再启动网关:
|
|
117
|
+
|
|
118
|
+
```bash
|
|
119
|
+
npm install
|
|
120
|
+
npm run dev
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
默认读取 `./config.json`。
|
|
124
|
+
可以通过 `--config <path>` 为当前进程指定配置文件;如果未传 `--config`,则按 `MCP_GATEWAY_CONFIG`,再回退到 `./config.json`。
|
|
125
|
+
|
|
126
|
+
也可以通过环境变量指定:
|
|
127
|
+
|
|
128
|
+
```bash
|
|
129
|
+
$env:MCP_GATEWAY_CONFIG="config/gateway/config.json"
|
|
130
|
+
npm run dev
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
### 查看版本号
|
|
134
|
+
|
|
135
|
+
```bash
|
|
136
|
+
mcp-gateway-service --version
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
短参数:
|
|
140
|
+
|
|
141
|
+
```bash
|
|
142
|
+
mcp-gateway-service -v
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
## 配置格式
|
|
146
|
+
|
|
147
|
+
当前只支持 `stdio` 类型的下游传输。
|
|
148
|
+
|
|
149
|
+
只有当 `enable` 未填写或显式为 `true` 时,服务才会被加载;如果 `enable` 为 `false`,网关会跳过该服务。热刷新时,如果某个服务被禁用或从配置中删除,网关也会停掉它当前已启动的下游进程。
|
|
150
|
+
|
|
151
|
+
- `enable` 可选,不填时默认按启用处理
|
|
152
|
+
- `cwd` 可选,不填时使用当前工作目录
|
|
153
|
+
- `env` 可选
|
|
154
|
+
- `framing` 可选,不填时先尝试 `line`,再尝试 `content-length`
|
|
155
|
+
|
|
156
|
+
```json
|
|
157
|
+
{
|
|
158
|
+
"services": [
|
|
159
|
+
{
|
|
160
|
+
"serviceId": "demo-echo",
|
|
161
|
+
"enable": true,
|
|
162
|
+
"name": "Demo Echo Service",
|
|
163
|
+
"description": "Sample echo MCP service.",
|
|
164
|
+
"transport": {
|
|
165
|
+
"type": "stdio",
|
|
166
|
+
"command": "node",
|
|
167
|
+
"args": [
|
|
168
|
+
"--experimental-strip-types",
|
|
169
|
+
"examples/echo-service.ts"
|
|
170
|
+
]
|
|
171
|
+
}
|
|
172
|
+
}
|
|
173
|
+
]
|
|
174
|
+
}
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
## 对外网关工具
|
|
178
|
+
|
|
179
|
+
- `gateway.listServices`
|
|
180
|
+
- `gateway.getService`
|
|
181
|
+
- `gateway.listTools`
|
|
182
|
+
- `gateway.getToolSchema`
|
|
183
|
+
- `gateway.callTool`
|
|
184
|
+
|
|
185
|
+
### 返回结构约定
|
|
186
|
+
|
|
187
|
+
- `gateway.listServices` 只返回 `serviceId`、`description`、`available`
|
|
188
|
+
- `gateway.listTools` 只返回 `name`、`description`
|
|
189
|
+
- `gateway.getToolSchema` 只返回 `inputSchema`、`outputSchema`
|
|
190
|
+
- `gateway.callTool` 直接返回下游 MCP 的结果,不再额外包一层网关元数据
|
|
191
|
+
|
|
192
|
+
## 推荐调用流程
|
|
193
|
+
|
|
194
|
+
为了尽量节省 token,推荐由客户端缓存发现结果,而不是每次都重新调用网关:
|
|
195
|
+
|
|
196
|
+
1. 会话开始时调用一次 `gateway.listServices`
|
|
197
|
+
2. 真正需要某个服务时,再调用 `gateway.listTools(serviceId)`
|
|
198
|
+
3. 第一次调用某个工具前,再调用 `gateway.getToolSchema(serviceId, toolName)`
|
|
199
|
+
4. 执行时调用 `gateway.callTool(...)`
|
|
200
|
+
5. 只有在调用失败、配置变更、或明确需要刷新时才重新发现
|
|
201
|
+
|
|
202
|
+
## Skill 集成(推荐)
|
|
203
|
+
|
|
204
|
+
仓库内包含一个面向公开使用者的 skill:
|
|
205
|
+
|
|
206
|
+
- 路径:`skills/mcp-gateway/SKILL.md`
|
|
207
|
+
|
|
208
|
+
主要用于指导代理:
|
|
209
|
+
|
|
210
|
+
- 按需发现服务和工具
|
|
211
|
+
- 避免无意义地枚举大量 tool
|
|
212
|
+
- 通过网关的最小接口完成下游调用
|
|
213
|
+
|
|
214
|
+
## MCP 客户端接入示例
|
|
215
|
+
|
|
216
|
+
下面示例都使用相对路径,方便迁移。
|
|
217
|
+
|
|
218
|
+
### Codex
|
|
219
|
+
|
|
220
|
+
`~/.codex/config.toml`
|
|
221
|
+
|
|
222
|
+
```toml
|
|
223
|
+
[mcp_servers.gateway]
|
|
224
|
+
command = "mcp-gateway-service"
|
|
225
|
+
args = ["--config", "./config.json"]
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
### Gemini CLI
|
|
229
|
+
|
|
230
|
+
`~/.gemini/settings.json`
|
|
231
|
+
|
|
232
|
+
```json
|
|
233
|
+
{
|
|
234
|
+
"mcpServers": {
|
|
235
|
+
"gateway": {
|
|
236
|
+
"type": "stdio",
|
|
237
|
+
"command": "mcp-gateway-service",
|
|
238
|
+
"args": [
|
|
239
|
+
"--config",
|
|
240
|
+
"./config.json"
|
|
241
|
+
]
|
|
242
|
+
}
|
|
243
|
+
}
|
|
244
|
+
}
|
|
245
|
+
```
|
|
246
|
+
|
|
247
|
+
### Claude Code
|
|
248
|
+
|
|
249
|
+
`~/.claude.json`
|
|
250
|
+
|
|
251
|
+
```json
|
|
252
|
+
{
|
|
253
|
+
"mcpServers": {
|
|
254
|
+
"gateway": {
|
|
255
|
+
"type": "stdio",
|
|
256
|
+
"command": "mcp-gateway-service",
|
|
257
|
+
"args": [
|
|
258
|
+
"--config",
|
|
259
|
+
"./config.json"
|
|
260
|
+
]
|
|
261
|
+
}
|
|
262
|
+
}
|
|
263
|
+
}
|
|
264
|
+
```
|
|
265
|
+
|
|
266
|
+
## 开发说明
|
|
267
|
+
|
|
268
|
+
- 仓库只保留 `config.example.json` 作为示例
|
|
269
|
+
- 运行前请自行复制一份本地 `config.json`
|
|
270
|
+
- 真实本地配置和日志建议放在仓库外
|
|
271
|
+
- 只有下游服务自己暴露了 `outputSchema` 时,网关才会返回它
|
|
272
|
+
- Windows 下支持解析 PowerShell shim 命令,例如实际落到 `.ps1` 的全局命令
|
|
273
|
+
|
|
274
|
+
## License
|
|
275
|
+
|
|
276
|
+
项目采用 [MIT License](./LICENSE) 开源。
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
{
|
|
2
|
+
"services": [
|
|
3
|
+
{
|
|
4
|
+
"serviceId": "demo-echo",
|
|
5
|
+
"enable": true,
|
|
6
|
+
"name": "Demo Echo Service",
|
|
7
|
+
"description": "Sample echo MCP service.",
|
|
8
|
+
"transport": {
|
|
9
|
+
"type": "stdio",
|
|
10
|
+
"command": "node",
|
|
11
|
+
"args": [
|
|
12
|
+
"--experimental-strip-types",
|
|
13
|
+
"examples/echo-service.ts"
|
|
14
|
+
]
|
|
15
|
+
}
|
|
16
|
+
}
|
|
17
|
+
]
|
|
18
|
+
}
|