@jadchene/mcp-gateway-service 0.1.2 → 0.2.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_zh.md CHANGED
@@ -1,280 +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
- 网关会把日志写到 `logDirectory` 目录下的 `mcp-gateway.log`。如果没有配置 `logDirectory`,默认写到当前工作目录。
150
-
151
- 只有当 `enable` 未填写或显式为 `true` 时,服务才会被加载;如果 `enable` 为 `false`,网关会跳过该服务。热刷新时,如果某个服务被禁用或从配置中删除,网关也会停掉它当前已启动的下游进程。
152
-
153
- - `logDirectory` 可选,不填时会把 `mcp-gateway.log` 写到当前工作目录
154
- - `enable` 可选,不填时默认按启用处理
155
- - `cwd` 可选,不填时使用当前工作目录
156
- - `env` 可选
157
- - `framing` 可选,不填时先尝试 `line`,再尝试 `content-length`
158
-
159
- ```json
160
- {
161
- "logDirectory": "./logs",
162
- "services": [
163
- {
164
- "serviceId": "demo-echo",
165
- "enable": true,
166
- "name": "Demo Echo Service",
167
- "description": "Sample echo MCP service.",
168
- "transport": {
169
- "type": "stdio",
170
- "command": "node",
171
- "args": [
172
- "--experimental-strip-types",
173
- "examples/echo-service.ts"
174
- ]
175
- }
176
- }
177
- ]
178
- }
179
- ```
180
-
181
- ## 对外网关工具
182
-
183
- - `gateway.listServices`
184
- - `gateway.getService`
185
- - `gateway.listTools`
186
- - `gateway.getToolSchema`
187
- - `gateway.callTool`
188
-
189
- ### 返回结构约定
190
-
191
- - `gateway.listServices` 只返回 `serviceId`、`description`、`available`
192
- - `gateway.listTools` 只返回 `name`、`description`
193
- - `gateway.getToolSchema` 只返回 `inputSchema`、`outputSchema`
194
- - `gateway.callTool` 直接返回下游 MCP 的结果,不再额外包一层网关元数据
195
-
196
- ## 推荐调用流程
197
-
198
- 为了尽量节省 token,推荐由客户端缓存发现结果,而不是每次都重新调用网关:
199
-
200
- 1. 会话开始时调用一次 `gateway.listServices`
201
- 2. 真正需要某个服务时,再调用 `gateway.listTools(serviceId)`
202
- 3. 第一次调用某个工具前,再调用 `gateway.getToolSchema(serviceId, toolName)`
203
- 4. 执行时调用 `gateway.callTool(...)`
204
- 5. 只有在调用失败、配置变更、或明确需要刷新时才重新发现
205
-
206
- ## Skill 集成(推荐)
207
-
208
- 仓库内包含一个面向公开使用者的 skill:
209
-
210
- - 路径:`skills/mcp-gateway/SKILL.md`
211
-
212
- 主要用于指导代理:
213
-
214
- - 按需发现服务和工具
215
- - 避免无意义地枚举大量 tool
216
- - 通过网关的最小接口完成下游调用
217
-
218
- ## MCP 客户端接入示例
219
-
220
- 下面示例都使用相对路径,方便迁移。
221
-
222
- ### Codex
223
-
224
- `~/.codex/config.toml`
225
-
226
- ```toml
227
- [mcp_servers.gateway]
228
- command = "mcp-gateway-service"
229
- args = ["--config", "./config.json"]
230
- ```
231
-
232
- ### Gemini CLI
233
-
234
- `~/.gemini/settings.json`
235
-
236
- ```json
237
- {
238
- "mcpServers": {
239
- "gateway": {
240
- "type": "stdio",
241
- "command": "mcp-gateway-service",
242
- "args": [
243
- "--config",
244
- "./config.json"
245
- ]
246
- }
247
- }
248
- }
249
- ```
250
-
251
- ### Claude Code
252
-
253
- `~/.claude.json`
254
-
255
- ```json
256
- {
257
- "mcpServers": {
258
- "gateway": {
259
- "type": "stdio",
260
- "command": "mcp-gateway-service",
261
- "args": [
262
- "--config",
263
- "./config.json"
264
- ]
265
- }
266
- }
267
- }
268
- ```
269
-
270
- ## 开发说明
271
-
272
- - 仓库只保留 `config.example.json` 作为示例
273
- - 运行前请自行复制一份本地 `config.json`
274
- - 真实本地配置和日志建议放在仓库外
275
- - 只有下游服务自己暴露了 `outputSchema` 时,网关才会返回它
276
- - Windows 下支持解析 PowerShell shim 命令,例如实际落到 `.ps1` 的全局命令
277
-
278
- ## License
279
-
280
- 项目采用 [MIT License](./LICENSE) 开源。
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) 开源。
@@ -1,19 +1,18 @@
1
- {
2
- "logDirectory": "./logs",
3
- "services": [
4
- {
5
- "serviceId": "demo-echo",
6
- "enable": true,
7
- "name": "Demo Echo Service",
8
- "description": "Sample echo MCP service.",
9
- "transport": {
10
- "type": "stdio",
11
- "command": "node",
12
- "args": [
13
- "--experimental-strip-types",
14
- "examples/echo-service.ts"
15
- ]
16
- }
17
- }
18
- ]
19
- }
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
+ }
package/dist/config.js CHANGED
@@ -21,7 +21,6 @@ export function validateGatewayConfig(input) {
21
21
  if (!isRecord(input)) {
22
22
  throw new Error("The gateway config must be a JSON object.");
23
23
  }
24
- const logDirectory = optionalString(input.logDirectory, "logDirectory");
25
24
  if (!Array.isArray(input.services)) {
26
25
  throw new Error("The 'services' field must be an array.");
27
26
  }
@@ -34,7 +33,6 @@ export function validateGatewayConfig(input) {
34
33
  seenServiceIds.add(service.serviceId);
35
34
  }
36
35
  return {
37
- logDirectory,
38
36
  services: services.filter((service) => service.enable)
39
37
  };
40
38
  }
@@ -187,7 +187,7 @@ export class GatewayServer {
187
187
  },
188
188
  serverInfo: {
189
189
  name: "mcp-gateway",
190
- version: "0.1.2"
190
+ version: "0.2.1"
191
191
  }
192
192
  };
193
193
  }