@seaxlab/archery-mcp 1.1.0 → 1.3.0

package/README.md

@@ -20,11 +20,27 @@
 | `ARCHERY_METADATA_CACHE_ENABLED` | 否 | `true` | 是否启用实例/库元数据缓存 |
 | `ARCHERY_METADATA_CACHE_TTL_SECONDS` | 否 | `604800` | 缓存有效期（秒），默认 7 天 |
 | `ARCHERY_METADATA_CACHE_PATH` | 否 | `~/.cache/archery-mcp/metadata-cache.json` | 缓存文件路径 |
+| `ARCHERY_METADATA_CACHE_EXCLUDE_INSTANCE_NAMES` | 否 | 空 | 不写入缓存的实例名黑名单，多个用英文逗号分隔 |
+| `ARCHERY_METADATA_CACHE_EXCLUDE_INSTANCE_IDS` | 否 | 空 | 不写入缓存的实例 ID 黑名单，多个用英文逗号分隔 |
 
 ## MCP 客户端配置
 
 在客户端的 MCP 配置里为进程设置与上表相同的 `env`。若使用已发布或已安装的包，可按下述配置。
 
+## 元数据缓存
+
+`archery_list_instances` 和 `resource_type=database` 的 `archery_list_resources` 默认使用本地缓存。实例列表会先从 Archery 全量拉取，再在写入本地缓存前按 `ARCHERY_METADATA_CACHE_EXCLUDE_INSTANCE_NAMES` 和 `ARCHERY_METADATA_CACHE_EXCLUDE_INSTANCE_IDS` 排除黑名单实例。
+
+刷新数据库列表缓存时，如果没有显式指定 `instance_id` 或 `instance_name`，也会基于过滤后的实例列表刷新，避免对黑名单实例调用库列表接口。显式指定实例时按入参执行，便于临时排查单个实例。
+
+默认缓存路径：
+
+```text
+~/.cache/archery-mcp/metadata-cache.json
+```
+
+默认缓存有效期为 7 天。需要实时刷新时，可以在工具入参中传 `force_refresh=true`，也可以调用 `archery_refresh_metadata_cache`。
+
 ### 使用已安装的包（推荐）
 
 全局安装或作为项目依赖安装 `@seaxlab/archery-mcp` 后，可用 `npx` 拉起（会使用包内 `bin`）：
@@ -40,10 +56,11 @@
         "ARCHERY_USERNAME": "mcp_service",
         "ARCHERY_PASSWORD": "replace-me",
         "ARCHERY_DEFAULT_LIMIT": "100",
-        "ARCHERY_MAX_LIMIT": "500"
+        "ARCHERY_MAX_LIMIT": "500",
+        "ARCHERY_METADATA_CACHE_EXCLUDE_INSTANCE_NAMES": "instance-a,instance-b",
+        "ARCHERY_METADATA_CACHE_EXCLUDE_INSTANCE_IDS": "1,2"
       }
     }
   }
 }
 ```
-

package/dist/config.d.ts

@@ -8,6 +8,8 @@ declare const envSchema: z.ZodObject<{
     ARCHERY_METADATA_CACHE_ENABLED: z.ZodDefault<z.ZodEffects<z.ZodBoolean, boolean, unknown>>;
     ARCHERY_METADATA_CACHE_TTL_SECONDS: z.ZodDefault<z.ZodNumber>;
     ARCHERY_METADATA_CACHE_PATH: z.ZodEffects<z.ZodOptional<z.ZodString>, string | undefined, string | undefined>;
+    ARCHERY_METADATA_CACHE_EXCLUDE_INSTANCE_NAMES: z.ZodEffects<z.ZodOptional<z.ZodString>, string[], string | undefined>;
+    ARCHERY_METADATA_CACHE_EXCLUDE_INSTANCE_IDS: z.ZodEffects<z.ZodOptional<z.ZodString>, number[], string | undefined>;
 }, "strip", z.ZodTypeAny, {
     ARCHERY_BASE_URL: string;
     ARCHERY_USERNAME: string;
@@ -16,6 +18,8 @@ declare const envSchema: z.ZodObject<{
     ARCHERY_MAX_LIMIT: number;
     ARCHERY_METADATA_CACHE_ENABLED: boolean;
     ARCHERY_METADATA_CACHE_TTL_SECONDS: number;
+    ARCHERY_METADATA_CACHE_EXCLUDE_INSTANCE_NAMES: string[];
+    ARCHERY_METADATA_CACHE_EXCLUDE_INSTANCE_IDS: number[];
     ARCHERY_METADATA_CACHE_PATH?: string | undefined;
 }, {
     ARCHERY_BASE_URL: string;
@@ -26,6 +30,8 @@ declare const envSchema: z.ZodObject<{
     ARCHERY_METADATA_CACHE_ENABLED?: unknown;
     ARCHERY_METADATA_CACHE_TTL_SECONDS?: number | undefined;
     ARCHERY_METADATA_CACHE_PATH?: string | undefined;
+    ARCHERY_METADATA_CACHE_EXCLUDE_INSTANCE_NAMES?: string | undefined;
+    ARCHERY_METADATA_CACHE_EXCLUDE_INSTANCE_IDS?: string | undefined;
 }>;
 export type ArcheryMcpConfig = z.infer<typeof envSchema>;
 export declare function loadConfig(env?: NodeJS.ProcessEnv): ArcheryMcpConfig;

package/dist/config.js

@@ -1 +1 @@
-import{z as n}from"zod";const A=n.preprocess(e=>{if(!(e===void 0||e==="")){if(typeof e=="boolean")return e;if(typeof e=="string"){const r=e.trim().toLowerCase();if(["true","1","yes","y","on"].includes(r))return!0;if(["false","0","no","n","off"].includes(r))return!1}return e}},n.boolean()).default(!0),i=n.string().optional().transform(e=>{const r=e?.trim();return r||void 0}),R=n.object({ARCHERY_BASE_URL:n.string().url(),ARCHERY_USERNAME:n.string().min(1),ARCHERY_PASSWORD:n.string().min(1),ARCHERY_DEFAULT_LIMIT:n.coerce.number().int().positive().default(100),ARCHERY_MAX_LIMIT:n.coerce.number().int().positive().default(500),ARCHERY_METADATA_CACHE_ENABLED:A,ARCHERY_METADATA_CACHE_TTL_SECONDS:n.coerce.number().int().positive().default(604800),ARCHERY_METADATA_CACHE_PATH:i});export function loadConfig(e=process.env){const r=R.safeParse(e);if(!r.success){const s=r.error.issues.map(t=>`${t.path.join(".")}: ${t.message}`).join("; ");throw new Error(`ARCHERY_CONFIG_MISSING: ${s}`)}const o=r.data;if(o.ARCHERY_DEFAULT_LIMIT>o.ARCHERY_MAX_LIMIT)throw new Error("ARCHERY_CONFIG_MISSING: ARCHERY_DEFAULT_LIMIT must be less than or equal to ARCHERY_MAX_LIMIT");return{...o,ARCHERY_BASE_URL:o.ARCHERY_BASE_URL.replace(/\/+$/,"")}}
+import{z as e}from"zod";const i=e.preprocess(n=>{if(!(n===void 0||n==="")){if(typeof n=="boolean")return n;if(typeof n=="string"){const r=n.trim().toLowerCase();if(["true","1","yes","y","on"].includes(r))return!0;if(["false","0","no","n","off"].includes(r))return!1}return n}},e.boolean()).default(!0),E=e.string().optional().transform(n=>{const r=n?.trim();return r||void 0}),A=e.string().optional().transform(n=>(n??"").split(",").map(r=>r.trim()).filter(Boolean)),a=e.string().optional().transform((n,r)=>(n??"").split(",").map(t=>t.trim()).filter(Boolean).map(t=>{if(!/^\d+$/.test(t))return r.addIssue({code:e.ZodIssueCode.custom,message:`Invalid positive integer: ${t}`}),e.NEVER;const o=Number(t);return!Number.isSafeInteger(o)||o<=0?(r.addIssue({code:e.ZodIssueCode.custom,message:`Invalid positive integer: ${t}`}),e.NEVER):o})),_=e.object({ARCHERY_BASE_URL:e.string().url(),ARCHERY_USERNAME:e.string().min(1),ARCHERY_PASSWORD:e.string().min(1),ARCHERY_DEFAULT_LIMIT:e.coerce.number().int().positive().default(100),ARCHERY_MAX_LIMIT:e.coerce.number().int().positive().default(500),ARCHERY_METADATA_CACHE_ENABLED:i,ARCHERY_METADATA_CACHE_TTL_SECONDS:e.coerce.number().int().positive().default(604800),ARCHERY_METADATA_CACHE_PATH:E,ARCHERY_METADATA_CACHE_EXCLUDE_INSTANCE_NAMES:A,ARCHERY_METADATA_CACHE_EXCLUDE_INSTANCE_IDS:a});export function loadConfig(n=process.env){const r=_.safeParse(n);if(!r.success){const o=r.error.issues.map(s=>`${s.path.join(".")}: ${s.message}`).join("; ");throw new Error(`ARCHERY_CONFIG_MISSING: ${o}`)}const t=r.data;if(t.ARCHERY_DEFAULT_LIMIT>t.ARCHERY_MAX_LIMIT)throw new Error("ARCHERY_CONFIG_MISSING: ARCHERY_DEFAULT_LIMIT must be less than or equal to ARCHERY_MAX_LIMIT");return{...t,ARCHERY_BASE_URL:t.ARCHERY_BASE_URL.replace(/\/+$/,"")}}

package/dist/index.js

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-import{Server as c}from"@modelcontextprotocol/sdk/server/index.js";import{StdioServerTransport as i}from"@modelcontextprotocol/sdk/server/stdio.js";import{ArcheryClient as s}from"./archery-client.js";import{loadConfig as m}from"./config.js";import{MetadataCache as p}from"./metadata-cache.js";import{MetadataService as f}from"./metadata-service.js";import{registerTools as l}from"./tools.js";async function d(){const t=m(),e=new s(t),r=new p(t),a=new f(e,r),o=new c({name:"archery-mcp",version:"0.1.0"},{capabilities:{tools:{}}});l(o,e,t,a);const n=new i;await o.connect(n)}d().catch(t=>{const e=t instanceof Error?t.message:String(t);console.error(`archery-mcp failed to start: ${e}`),process.exit(1)});
+import{Server as c}from"@modelcontextprotocol/sdk/server/index.js";import{StdioServerTransport as i}from"@modelcontextprotocol/sdk/server/stdio.js";import{ArcheryClient as s}from"./archery-client.js";import{loadConfig as m}from"./config.js";import{MetadataCache as p}from"./metadata-cache.js";import{MetadataService as f}from"./metadata-service.js";import{registerTools as l}from"./tools.js";async function d(){const t=m(),e=new s(t),r=new p(t),a=new f(e,r,t),o=new c({name:"archery-mcp",version:"0.1.0"},{capabilities:{tools:{}}});l(o,e,t,a);const n=new i;await o.connect(n)}d().catch(t=>{const e=t instanceof Error?t.message:String(t);console.error(`archery-mcp failed to start: ${e}`),process.exit(1)});

package/dist/metadata-service.d.ts

@@ -1,4 +1,5 @@
 import type { ArcheryClient } from "./archery-client.js";
+import type { ArcheryMcpConfig } from "./config.js";
 import type { CacheState, MetadataCache } from "./metadata-cache.js";
 type RefreshScope = "instances" | "databases" | "all";
 export interface CacheOptions {
@@ -33,10 +34,13 @@ export interface RefreshPayload {
 export declare class MetadataService {
     private readonly client;
     private readonly cache;
-    constructor(client: ArcheryClient, cache: MetadataCache);
+    private readonly excludedInstanceNames;
+    private readonly excludedInstanceIds;
+    constructor(client: ArcheryClient, cache: MetadataCache, config: ArcheryMcpConfig);
     listInstances(options?: CacheOptions): Promise<CachedPayload>;
     listDatabases(target: DatabaseTarget, options?: CacheOptions): Promise<CachedPayload>;
     refreshMetadataCache(options?: RefreshOptions): Promise<RefreshPayload>;
     private wrapRealtime;
+    private filterInstances;
 }
 export {};

package/dist/metadata-service.js

@@ -1 +1 @@
-export class MetadataService{client;cache;constructor(e,a){this.client=e,this.cache=a}async listInstances(e={}){if(!this.cache.isEnabled())return this.wrapRealtime(await this.client.listInstances());if(!e.force_refresh){const t=await this.cache.readInstances();if(t)return t}const a=await this.client.listInstances();return this.cache.writeInstances(a)}async listDatabases(e,a={}){const t=o(e);if(!this.cache.isEnabled())return this.wrapRealtime(await this.client.listResources({...e,resource_type:"database"}));if(t&&!a.force_refresh){const s=await this.cache.readDatabases(t);if(s)return s}const n=await this.client.listResources({...e,resource_type:"database"});return t?this.cache.writeDatabases(t,n):this.wrapRealtime(n)}async refreshMetadataCache(e={}){const a=e.scope??"all",t={instances:!1,databases:[]};let n;if((a==="instances"||a==="all")&&(n=await this.client.listInstances(),this.cache.isEnabled()&&await this.cache.writeInstances(n),t.instances=!0),a==="databases"||a==="all"){const s=e.instance_id!==void 0||e.instance_name!==void 0?[{instance_id:e.instance_id,instance_name:e.instance_name}]:f(n??await this.client.listInstances());for(const c of s)try{const r=await this.client.listResources({...c,resource_type:"database"}),d=o(c);this.cache.isEnabled()&&d&&await this.cache.writeDatabases(d,r),t.databases.push({...c,ok:!0})}catch(r){t.databases.push({...c,ok:!1,message:r instanceof Error?r.message:String(r)})}}return{cache:{enabled:this.cache.isEnabled(),path:this.cache.getPath()},refreshed:t}}wrapRealtime(e){return{cache:this.cache.realtimeState(),data:e}}}function o(i){return i.instance_name||i.instance_id}function f(i){const e=new Map;return h(i,e),[...e.values()].sort((a,t)=>{const n=a.instance_name??"",s=t.instance_name??"";return n.localeCompare(s,"zh-Hans-CN")})}function h(i,e){if(Array.isArray(i)){for(const c of i)h(c,e);return}if(!i||typeof i!="object")return;const a=i,t=a.instance_id??a.instanceId??a.id,n=a.instance_name??a.instanceName,s={};if(typeof t=="number"&&Number.isInteger(t)&&t>0&&(s.instance_id=t),typeof t=="string"&&/^\d+$/.test(t)){const c=Number(t);c>0&&(s.instance_id=c)}typeof n=="string"&&n.trim()&&(s.instance_name=n),(s.instance_id!==void 0||s.instance_name!==void 0)&&e.set(s.instance_name??String(s.instance_id),s);for(const c of["data","rows","result","list"])c in a&&h(a[c],e)}
+export class MetadataService{client;cache;excludedInstanceNames;excludedInstanceIds;constructor(e,s,t){this.client=e,this.cache=s,this.excludedInstanceNames=new Set(t.ARCHERY_METADATA_CACHE_EXCLUDE_INSTANCE_NAMES),this.excludedInstanceIds=new Set(t.ARCHERY_METADATA_CACHE_EXCLUDE_INSTANCE_IDS)}async listInstances(e={}){if(!this.cache.isEnabled())return this.wrapRealtime(await this.client.listInstances());if(!e.force_refresh){const t=await this.cache.readInstances();if(t)return t}const s=this.filterInstances(await this.client.listInstances());return this.cache.writeInstances(s)}async listDatabases(e,s={}){const t=h(e);if(!this.cache.isEnabled())return this.wrapRealtime(await this.client.listResources({...e,resource_type:"database"}));if(t&&!s.force_refresh){const a=await this.cache.readDatabases(t);if(a)return a}const i=await this.client.listResources({...e,resource_type:"database"});return t?this.cache.writeDatabases(t,i):this.wrapRealtime(i)}async refreshMetadataCache(e={}){const s=e.scope??"all",t={instances:!1,databases:[]};let i;if((s==="instances"||s==="all")&&(i=this.filterInstances(await this.client.listInstances()),this.cache.isEnabled()&&await this.cache.writeInstances(i),t.instances=!0),s==="databases"||s==="all"){const a=e.instance_id!==void 0||e.instance_name!==void 0?[{instance_id:e.instance_id,instance_name:e.instance_name}]:m(i??this.filterInstances(await this.client.listInstances()));for(const c of a)try{const r=await this.client.listResources({...c,resource_type:"database"}),o=h(c);this.cache.isEnabled()&&o&&await this.cache.writeDatabases(o,r),t.databases.push({...c,ok:!0})}catch(r){t.databases.push({...c,ok:!1,message:r instanceof Error?r.message:String(r)})}}return{cache:{enabled:this.cache.isEnabled(),path:this.cache.getPath()},refreshed:t}}wrapRealtime(e){return{cache:this.cache.realtimeState(),data:e}}filterInstances(e){return this.excludedInstanceNames.size===0&&this.excludedInstanceIds.size===0?e:d(e,this.excludedInstanceNames,this.excludedInstanceIds)}}function d(n,e,s){if(Array.isArray(n))return n.filter(a=>!u(a,e,s)).map(a=>d(a,e,s));if(!n||typeof n!="object")return n;const t=n,i={};for(const[a,c]of Object.entries(t))i[a]=d(c,e,s);return i}function u(n,e,s){if(!n||typeof n!="object")return!1;const t=n,i=t.instance_id??t.instanceId??t.id,a=t.instance_name??t.instanceName;if(typeof a=="string"&&e.has(a.trim()))return!0;const c=l(i);return c!==void 0&&s.has(c)}function l(n){if(typeof n=="number"&&Number.isSafeInteger(n)&&n>0)return n;if(typeof n=="string"&&/^\d+$/.test(n)){const e=Number(n);return Number.isSafeInteger(e)&&e>0?e:void 0}}function h(n){return n.instance_name||n.instance_id}function m(n){const e=new Map;return f(n,e),[...e.values()].sort((s,t)=>{const i=s.instance_name??"",a=t.instance_name??"";return i.localeCompare(a,"zh-Hans-CN")})}function f(n,e){if(Array.isArray(n)){for(const c of n)f(c,e);return}if(!n||typeof n!="object")return;const s=n,t=s.instance_id??s.instanceId??s.id,i=s.instance_name??s.instanceName,a={};if(typeof t=="number"&&Number.isInteger(t)&&t>0&&(a.instance_id=t),typeof t=="string"&&/^\d+$/.test(t)){const c=Number(t);c>0&&(a.instance_id=c)}typeof i=="string"&&i.trim()&&(a.instance_name=i),(a.instance_id!==void 0||a.instance_name!==void 0)&&e.set(a.instance_name??String(a.instance_id),a);for(const c of["data","rows","result","list"])c in s&&f(s[c],e)}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seaxlab/archery-mcp",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "type": "module",
   "description": "Archery MCP server (Node.js, stdio)",
   "main": "dist/index.js",