@jadchene/mcp-gateway-service 0.4.1 → 0.4.2

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
@@ -225,7 +225,7 @@ The gateway exposes a fixed set of discovery and routing tools:
225
225
  ### Response design
226
226
 
227
227
  - `gateway.listServices` returns only `serviceId`, `description`, and `available`.
228
- - `gateway.listTools` returns only `name` and `description`.
228
+ - `gateway.listTools` returns only `name` and `description`; pass optional `toolName` as a string or string array to filter names by substring.
229
229
  - `gateway.getToolSchema` returns only `inputSchema` and `outputSchema`.
230
230
  - `gateway.manageService` returns only `serviceId`, `action`, `enabled`, and `available`.
231
231
  - `gateway.callTool` forwards the downstream MCP tool result directly without extra gateway metadata wrapping.
@@ -261,7 +261,7 @@ Important notes:
261
261
  For the best token efficiency, the MCP client should cache discovery results instead of repeatedly querying the gateway:
262
262
 
263
263
  1. Call `gateway.listServices` once at session start.
264
- 2. Call `gateway.listTools(serviceId)` only when a service is actually needed.
264
+ 2. Call `gateway.listTools(serviceId)` only when a service is actually needed, optionally with `toolName` to narrow large tool lists by one or more keywords.
265
265
  3. Call `gateway.getToolSchema(serviceId, toolName)` only before the first use of that tool.
266
266
  4. Call `gateway.callTool(...)` for execution.
267
267
  5. Use `gateway.getService` only when diagnostics are explicitly needed.
package/README_zh.md CHANGED
@@ -227,7 +227,7 @@ mcp-gateway-service -v
227
227
  ### 返回结构约定
228
228
 
229
229
  - `gateway.listServices` 只返回 `serviceId`、`description`、`available`
230
- - `gateway.listTools` 只返回 `name`、`description`
230
+ - `gateway.listTools` 只返回 `name`、`description`,可传可选参数 `toolName`,支持字符串或字符串数组,按名称片段筛选
231
231
  - `gateway.getToolSchema` 只返回 `inputSchema`、`outputSchema`
232
232
  - `gateway.manageService` 只返回 `serviceId`、`action`、`enabled`、`available`
233
233
  - `gateway.callTool` 直接返回下游 MCP 的结果,不再额外包一层网关元数据
@@ -263,7 +263,7 @@ mcp-gateway-service -v
263
263
  为了尽量节省 token,推荐由客户端缓存发现结果,而不是每次都重新调用网关:
264
264
 
265
265
  1. 会话开始时调用一次 `gateway.listServices`
266
- 2. 真正需要某个服务时,再调用 `gateway.listTools(serviceId)`
266
+ 2. 真正需要某个服务时,再调用 `gateway.listTools(serviceId)`,工具很多时可传 `toolName` 用一个或多个关键词缩小结果范围
267
267
  3. 第一次调用某个工具前,再调用 `gateway.getToolSchema(serviceId, toolName)`
268
268
  4. 执行时调用 `gateway.callTool(...)`
269
269
  5. 只有在明确需要诊断时才调用 `gateway.getService`
@@ -122,8 +122,9 @@ export class McpGatewayEngine {
122
122
  */
123
123
  listTools(args) {
124
124
  const serviceId = requireString(args.serviceId, "The 'serviceId' argument must be a string.");
125
+ const toolName = optionalStringArray(args.toolName, "The 'toolName' argument must be a string or string array when provided.");
125
126
  return successContent({
126
- tools: this.registry.listTools(serviceId).map((tool) => ({
127
+ tools: this.registry.listTools(serviceId, toolName).map((tool) => ({
127
128
  name: tool.name,
128
129
  description: tool.description ?? null
129
130
  }))
@@ -209,9 +210,21 @@ export function buildGatewayTools() {
209
210
  },
210
211
  {
211
212
  name: "gateway.listTools",
212
- description: "Lists all tools exposed by one downstream service.",
213
+ description: "Lists tools exposed by one downstream service, optionally filtered by one or more tool name keywords.",
213
214
  inputSchema: objectSchema(["serviceId"], {
214
- serviceId: stringSchema("Logical service identifier.")
215
+ serviceId: stringSchema("Logical service identifier."),
216
+ toolName: {
217
+ anyOf: [
218
+ stringSchema("Optional keyword matched against downstream tool names."),
219
+ {
220
+ type: "array",
221
+ description: "Optional keywords matched against downstream tool names. A tool is returned when any keyword matches.",
222
+ items: {
223
+ type: "string"
224
+ }
225
+ }
226
+ ]
227
+ }
215
228
  })
216
229
  },
217
230
  {
@@ -310,6 +323,23 @@ function requireString(input, message) {
310
323
  }
311
324
  return input;
312
325
  }
326
+ /**
327
+ * Returns optional string keywords, treating blank strings as absent.
328
+ */
329
+ function optionalStringArray(input, message) {
330
+ if (input === undefined || input === null) {
331
+ return undefined;
332
+ }
333
+ if (typeof input !== "string") {
334
+ if (!Array.isArray(input) || input.some((value) => typeof value !== "string")) {
335
+ throw new Error(message);
336
+ }
337
+ const values = input.map((value) => value.trim()).filter((value) => value !== "");
338
+ return values.length === 0 ? undefined : values;
339
+ }
340
+ const trimmed = input.trim();
341
+ return trimmed === "" ? undefined : trimmed;
342
+ }
313
343
  /**
314
344
  * Ensures the service management action is supported.
315
345
  */
@@ -110,10 +110,18 @@ export class ServiceRegistry {
110
110
  return this.snapshots.get(serviceId) ?? null;
111
111
  }
112
112
  /**
113
- * Lists tools for one logical service.
113
+ * Lists tools for one logical service, optionally filtering by one or more tool name keywords.
114
114
  */
115
- listTools(serviceId) {
116
- return this.requireService(serviceId).metadata.tools;
115
+ listTools(serviceId, toolName) {
116
+ const tools = this.requireService(serviceId).metadata.tools;
117
+ const keywords = normalizeToolNameKeywords(toolName);
118
+ if (keywords.length === 0) {
119
+ return tools;
120
+ }
121
+ return tools.filter((tool) => {
122
+ const normalizedName = tool.name.toLowerCase();
123
+ return keywords.some((keyword) => normalizedName.includes(keyword));
124
+ });
117
125
  }
118
126
  /**
119
127
  * Returns one tool definition for a service.
@@ -353,6 +361,18 @@ function createClient(service, logger) {
353
361
  throw new Error(`Unsupported transport '${String(service.transport.type)}'.`);
354
362
  }
355
363
  }
364
+ /**
365
+ * Normalizes optional tool name keywords for case-insensitive filtering.
366
+ */
367
+ function normalizeToolNameKeywords(toolName) {
368
+ if (!toolName) {
369
+ return [];
370
+ }
371
+ const values = Array.isArray(toolName) ? toolName : [toolName];
372
+ return values
373
+ .map((value) => value.trim().toLowerCase())
374
+ .filter((value) => value !== "");
375
+ }
356
376
  /**
357
377
  * Loads the raw config document for management edits that must preserve disabled services.
358
378
  */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@jadchene/mcp-gateway-service",
3
- "version": "0.4.1",
3
+ "version": "0.4.2",
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",
@@ -18,7 +18,7 @@ Operate downstream MCP services through the gateway's fixed, token-efficient dis
18
18
  ## Required Workflow
19
19
 
20
20
  1. Call `gateway.listServices` once to find the right downstream service.
21
- 2. Call `gateway.listTools(serviceId)` only for the selected service.
21
+ 2. Call `gateway.listTools(serviceId)` only for the selected service, using optional `toolName` as a string or string array when one or more keywords can narrow a large tool list.
22
22
  3. Call `gateway.getToolSchema(serviceId, toolName)` before the first use of that tool, or any time the arguments are not fully certain.
23
23
  4. Call `gateway.callTool(serviceId, toolName, arguments)` for execution.
24
24
  5. Re-discover only when a call fails, service availability changes, or the task clearly requires fresh metadata.
@@ -41,7 +41,7 @@ Operate downstream MCP services through the gateway's fixed, token-efficient dis
41
41
  ## Response Shape Expectations
42
42
 
43
43
  - `gateway.listServices` returns compact service entries with `serviceId`, `description`, and `available`.
44
- - `gateway.listTools` returns compact tool entries with `name` and `description`.
44
+ - `gateway.listTools` returns compact tool entries with `name` and `description`, and supports optional substring filtering by `toolName` as a string or string array.
45
45
  - `gateway.getToolSchema` returns only `inputSchema` and `outputSchema`.
46
46
  - `gateway.callTool` forwards the downstream MCP result directly with minimal or no gateway wrapping.
47
47
 
@@ -57,7 +57,8 @@ Operate downstream MCP services through the gateway's fixed, token-efficient dis
57
57
  - Need a service for one task domain:
58
58
  - `gateway.listServices`
59
59
  - choose the most relevant `serviceId`
60
- - `gateway.listTools({ serviceId: "selected-service" })`
60
+ - `gateway.listTools({ serviceId: "selected-service", toolName: "optional-keyword" })`
61
+ - `gateway.listTools({ serviceId: "selected-service", toolName: ["keyword-a", "keyword-b"] })`
61
62
  - `gateway.getToolSchema({ serviceId: "selected-service", toolName: "selected-tool" })`
62
63
  - `gateway.callTool({ serviceId: "selected-service", toolName: "selected-tool", arguments: {...} })`
63
64