mes-mcp 0.3.3 → 0.3.5

package/.env.example

@@ -2,6 +2,8 @@ MES_BASE_URL=http://127.0.0.1:6033
 MES_API_PREFIX=/api
 MES_AGENT_TOKEN=
 MES_TIMEOUT_MS=30000
+MES_MAX_CONCURRENT_REQUESTS=4
+MES_MAX_QUEUED_REQUESTS=8
 # 动作目录缓存 TTL（毫秒，兜底），默认 12h。另外跨自然日必刷新：
 # 每天第一次调用 mes_action.* 时自动拉最新动作目录；用户也可用 mes_action.catalog 手动强刷。
 MES_ACTION_CACHE_TTL_MS=43200000

package/README.md

@@ -18,6 +18,8 @@ MES_BASE_URL=http://127.0.0.1:6033
 MES_API_PREFIX=/api
 MES_AGENT_TOKEN=BearerTokenWithoutBearerPrefix
 MES_TIMEOUT_MS=30000
+MES_MAX_CONCURRENT_REQUESTS=4
+MES_MAX_QUEUED_REQUESTS=8
 MES_REGISTER_DYNAMIC_TOOLS=false
 ```
 

package/dist/clients/mes-agent-api.client.js

@@ -1,3 +1,4 @@
+import { ConcurrencyLimiter } from "../utils/concurrency-limiter.js";
 function buildMesErrorMessage(path, status, message) {
     const hints = [];
     if (/pageSize must not be greater than 100/i.test(message)) {
@@ -29,36 +30,41 @@ export class MesAgentApiClient {
     // 动作目录缓存最近成功刷新时间；驱动每日首用/TTL 自动刷新，并对外报告。
     // undefined 且 promise 存在 = 拉取在途（并发复用同一 promise，避免重复请求）。
     businessActionsFetchedAt;
+    businessActionsVersion = 0;
+    requestLimiter;
     constructor(config) {
         this.config = config;
+        this.requestLimiter = new ConcurrencyLimiter(config.maxConcurrentRequests, config.maxQueuedRequests);
     }
     async post(path, payload) {
-        const controller = new AbortController();
-        const timeout = setTimeout(() => controller.abort(), this.config.timeoutMs);
-        try {
-            const response = await fetch(this.buildUrl(path), {
-                method: "POST",
-                headers: {
-                    Authorization: `Bearer ${this.config.mesAgentToken}`,
-                    "Content-Type": "application/json",
-                },
-                body: JSON.stringify(payload ?? {}),
-                signal: controller.signal,
-            });
-            const text = await response.text();
-            const body = this.parseBody(text);
-            if (!response.ok) {
-                const message = body?.msg || body?.message || text || response.statusText;
-                throw new Error(buildMesErrorMessage(path, response.status, message));
+        return this.requestLimiter.run(async () => {
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), this.config.timeoutMs);
+            try {
+                const response = await fetch(this.buildUrl(path), {
+                    method: "POST",
+                    headers: {
+                        Authorization: `Bearer ${this.config.mesAgentToken}`,
+                        "Content-Type": "application/json",
+                    },
+                    body: JSON.stringify(payload ?? {}),
+                    signal: controller.signal,
+                });
+                const text = await response.text();
+                const body = this.parseBody(text);
+                if (!response.ok) {
+                    const message = body?.msg || body?.message || text || response.statusText;
+                    throw new Error(buildMesErrorMessage(path, response.status, message));
+                }
+                if (body && typeof body.code === "number" && body.code !== 0) {
+                    throw new Error(buildMesErrorMessage(path, body.code, body.msg || body.message || `MES code ${body.code}`));
+                }
+                return (body && "data" in body ? body.data : body);
             }
-            if (body && typeof body.code === "number" && body.code !== 0) {
-                throw new Error(buildMesErrorMessage(path, body.code, body.msg || body.message || `MES code ${body.code}`));
+            finally {
+                clearTimeout(timeout);
             }
-            return (body && "data" in body ? body.data : body);
-        }
-        finally {
-            clearTimeout(timeout);
-        }
+        });
     }
     async postApiPath(path, payload) {
         if (/^https?:\/\//i.test(path) || path.includes("..")) {
@@ -82,6 +88,7 @@ export class MesAgentApiClient {
         this.businessActionsPromise = this.fetchBusinessActions()
             .then((actions) => {
             this.businessActionsFetchedAt = new Date();
+            this.businessActionsVersion += 1;
             return actions;
         })
             .catch((error) => {
@@ -111,6 +118,10 @@ export class MesAgentApiClient {
             ? this.businessActionsFetchedAt.toISOString()
             : null;
     }
+    /** 动作目录缓存版本；每次成功刷新递增，用于让下游检索索引失效。 */
+    businessActionsCatalogVersion() {
+        return this.businessActionsVersion;
+    }
     async getBusinessAction(actionCode) {
         const actions = await this.listBusinessActions();
         const cached = actions.find((action) => action.actionCode === actionCode);

package/dist/config.js

@@ -24,6 +24,20 @@ function optionalBooleanEnv(name, fallback) {
         return false;
     throw new Error(`${name} must be a boolean`);
 }
+function positiveIntEnv(name, fallback) {
+    const value = Number(optionalEnv(name, String(fallback)));
+    if (!Number.isInteger(value) || value <= 0) {
+        throw new Error(`${name} must be a positive integer`);
+    }
+    return value;
+}
+function nonNegativeIntEnv(name, fallback) {
+    const value = Number(optionalEnv(name, String(fallback)));
+    if (!Number.isInteger(value) || value < 0) {
+        throw new Error(`${name} must be a non-negative integer`);
+    }
+    return value;
+}
 function actionSearchModeEnv(name, fallback) {
     const value = process.env[name]?.trim().toLowerCase();
     if (!value)
@@ -77,10 +91,9 @@ function assertExpectedTokenValue(label, actual, expected) {
     throw new Error(`${label} mismatch for MES_AGENT_TOKEN: expected ${expected}, got ${actual ?? "<missing>"}`);
 }
 export function loadConfig() {
-    const timeoutMs = Number(optionalEnv("MES_TIMEOUT_MS", "30000"));
-    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
-        throw new Error("MES_TIMEOUT_MS must be a positive number");
-    }
+    const timeoutMs = positiveIntEnv("MES_TIMEOUT_MS", 30000);
+    const maxConcurrentRequests = positiveIntEnv("MES_MAX_CONCURRENT_REQUESTS", 4);
+    const maxQueuedRequests = nonNegativeIntEnv("MES_MAX_QUEUED_REQUESTS", 8);
     const actionCacheTtlMs = Number(optionalEnv("MES_ACTION_CACHE_TTL_MS", "43200000"));
     if (!Number.isFinite(actionCacheTtlMs) || actionCacheTtlMs <= 0) {
         throw new Error("MES_ACTION_CACHE_TTL_MS must be a positive number");
@@ -98,6 +111,8 @@ export function loadConfig() {
         mesApiPrefix: optionalEnv("MES_API_PREFIX", "/api").replace(/\/+$/, ""),
         mesAgentToken,
         timeoutMs,
+        maxConcurrentRequests,
+        maxQueuedRequests,
         registerDynamicTools: optionalBooleanEnv("MES_REGISTER_DYNAMIC_TOOLS", false),
         actionSearchMode: actionSearchModeEnv("MES_ACTION_SEARCH", "lexical"),
         actionCacheTtlMs,

package/dist/discovery/action-search.service.js

@@ -19,16 +19,30 @@ export class ActionSearchService {
             this.client.listBusinessActions(),
             createEmbeddingProvider(this.mode),
         ]);
-        return new ActionSearchIndex(actions, provider);
+        return {
+            index: new ActionSearchIndex(actions, provider),
+            version: this.client.businessActionsCatalogVersion(),
+        };
     }
-    async search(query, options) {
+    async getIndex() {
         if (!this.indexPromise) {
             this.indexPromise = this.buildIndex().catch((error) => {
                 this.indexPromise = undefined;
                 throw error;
             });
         }
-        const index = await this.indexPromise;
+        let indexed = await this.indexPromise;
+        if (indexed.version !== this.client.businessActionsCatalogVersion()) {
+            this.indexPromise = this.buildIndex().catch((error) => {
+                this.indexPromise = undefined;
+                throw error;
+            });
+            indexed = await this.indexPromise;
+        }
+        return indexed.index;
+    }
+    async search(query, options) {
+        const index = await this.getIndex();
         const results = await index.search(query, options);
         return { total: index.size, results };
     }

package/dist/index.js

@@ -28,6 +28,7 @@ function logStartupDiagnostics(config) {
         `[mes-mcp] token username=${config.tokenInfo.username ?? "<unknown>"} apiKeyId=${maskId(config.tokenInfo.apiKeyId)} agentClientId=${config.tokenInfo.agentClientId ?? "<unknown>"} expiresAt=${formatUnixSeconds(config.tokenInfo.expiresAt)}`,
         `[mes-mcp] dynamicTools=${config.registerDynamicTools ? "enabled" : "disabled"} (${config.registerDynamicTools ? "mes.<actionCode> tools will be registered" : "use mes_action.list/detail/execute; set MES_REGISTER_DYNAMIC_TOOLS=true only when the client needs expanded tools"})`,
         `[mes-mcp] actionSearch=${config.actionSearchMode} (mes_action.list 按相关性检索动作目录；hybrid/semantic 需安装可选依赖 @huggingface/transformers，否则自动退化为 lexical)`,
+        `[mes-mcp] requestConcurrency=${config.maxConcurrentRequests} queued=${config.maxQueuedRequests}`,
     ];
     if (config.expectedUsername) {
         lines.push(`[mes-mcp] expected username=${config.expectedUsername}`);

package/dist/tools/register-tools.js

@@ -51,6 +51,11 @@ function errorMessage(error) {
 }
 function errorHints(message) {
     const hints = [];
+    if (message.includes("并发保护") ||
+        message.includes("并发请求已达上限") ||
+        message.includes("写入请求正在执行")) {
+        hints.push("MES/MCP 正在保护数据库并发；不要立即并行重试，稍后再重试或拆分为串行步骤。");
+    }
     if (/pageSize/i.test(message)) {
         hints.push("MES 分页上限是 100；MCP 会对 mes_api.read 和 mes_action.list 自动裁剪 pageSize。");
     }
@@ -148,7 +153,9 @@ function normalizeDynamicArgs(args) {
     return {
         executionMode,
         idempotencyKey,
-        payload: payload ?? rest,
+        // 兼容 MCP 客户端把 DTO 字段放在顶层、同时附带 payload 的调用形态。
+        // payload 中的同名字段优先，避免显式请求体被顶层兼容字段覆盖。
+        payload: { ...rest, ...(payload ?? {}) },
     };
 }
 function buildIdempotencyKey(actionCode) {
@@ -275,6 +282,8 @@ function registerGenericActionTools(server, client, searchService) {
             return formatToolResult({
                 query: keyword || null,
                 ranked: Boolean(keyword),
+                catalogVersion: client.businessActionsCatalogVersion(),
+                refreshedAt: client.businessActionsRefreshedAt(),
                 total,
                 returned: results.length,
                 list: results.map((r) => listActionView(r.action, r.score)),
@@ -334,6 +343,7 @@ function registerGenericActionTools(server, client, searchService) {
             }));
             return formatToolResult({
                 refreshedAt: client.businessActionsRefreshedAt(),
+                catalogVersion: client.businessActionsCatalogVersion(),
                 total: filtered.length,
                 moduleCount: modules.length,
                 filteredModule: moduleFilter ?? null,
@@ -494,7 +504,8 @@ function registerGenericActionTools(server, client, searchService) {
                     (shouldEnsureIdempotencyKey(action, executionMode)
                         ? buildIdempotencyKey(actionCode)
                         : undefined),
-                payload: payload ?? rest,
+                // 与动态工具保持一致：顶层 DTO 字段不能因为存在 payload 而丢失。
+                payload: { ...rest, ...(payload ?? {}) },
             });
             return formatToolResult(result);
         });

package/dist/utils/concurrency-limiter.js

@@ -0,0 +1,49 @@
+export class ConcurrencyLimiter {
+    maxConcurrent;
+    maxQueue;
+    active = 0;
+    queue = [];
+    constructor(maxConcurrent, maxQueue) {
+        this.maxConcurrent = maxConcurrent;
+        this.maxQueue = maxQueue;
+    }
+    async run(task) {
+        await this.acquire();
+        try {
+            return await task();
+        }
+        finally {
+            this.release();
+        }
+    }
+    acquire() {
+        if (this.active < this.maxConcurrent) {
+            this.active += 1;
+            return Promise.resolve();
+        }
+        if (this.queue.length >= this.maxQueue) {
+            return Promise.reject(new Error("MES MCP 并发保护已触发，请稍后重试；请求未发送到 MES"));
+        }
+        return new Promise((resolve, reject) => {
+            this.queue.push({
+                grant: () => {
+                    this.active += 1;
+                    resolve();
+                },
+                reject,
+            });
+        });
+    }
+    release() {
+        this.active = Math.max(0, this.active - 1);
+        const next = this.queue.shift();
+        if (!next)
+            return;
+        try {
+            next.grant();
+        }
+        catch (error) {
+            next.reject(error);
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mes-mcp",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "type": "module",
   "description": "MES MCP adapter for Marvis and AI agents",
   "license": "UNLICENSED",