@seaxlab/archery-mcp 1.0.0

package/README.md

@@ -0,0 +1,49 @@
+# Archery MCP
+
+基于 MCP stdio、通过 Archery HTTP 接口访问内部 Archery。
+
+## 前置条件
+
+- Node.js 18+；运行环境能访问 `ARCHERY_BASE_URL`。
+
+## 环境变量
+
+通过进程环境变量注入（不要把真实密码写入仓库，可参考仓库内 `.env.example`）：
+
+| 变量 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `ARCHERY_BASE_URL` | 是 | 无 | Archery 地址，会自动去掉末尾 `/` |
+| `ARCHERY_USERNAME` | 是 | 无 | 服务账号用户名 |
+| `ARCHERY_PASSWORD` | 是 | 无 | 服务账号密码 |
+| `ARCHERY_DEFAULT_LIMIT` | 否 | `100` | 查询默认返回条数上限 |
+| `ARCHERY_MAX_LIMIT` | 否 | `500` | MCP 侧允许的最大返回条数 |
+| `ARCHERY_METADATA_CACHE_ENABLED` | 否 | `true` | 是否启用实例/库元数据缓存 |
+| `ARCHERY_METADATA_CACHE_TTL_SECONDS` | 否 | `604800` | 缓存有效期（秒），默认 7 天 |
+| `ARCHERY_METADATA_CACHE_PATH` | 否 | `~/.cache/archery-mcp/metadata-cache.json` | 缓存文件路径 |
+
+## MCP 客户端配置
+
+在客户端的 MCP 配置里为进程设置与上表相同的 `env`。若使用已发布或已安装的包，可按下述配置。
+
+### 使用已安装的包（推荐）
+
+全局安装或作为项目依赖安装 `@seaxlab/archery-mcp` 后，可用 `npx` 拉起（会使用包内 `bin`）：
+
+```json
+{
+  "mcpServers": {
+    "archery": {
+      "command": "npx",
+      "args": ["-y", "@seaxlab/archery-mcp"],
+      "env": {
+        "ARCHERY_BASE_URL": "http://archery.internal",
+        "ARCHERY_USERNAME": "mcp_service",
+        "ARCHERY_PASSWORD": "replace-me",
+        "ARCHERY_DEFAULT_LIMIT": "100",
+        "ARCHERY_MAX_LIMIT": "500"
+      }
+    }
+  }
+}
+```
+

package/dist/archery-client.d.ts

@@ -0,0 +1,40 @@
+import type { ArcheryMcpConfig } from "./config.js";
+export type ArcheryJson = Record<string, unknown>;
+export interface QueryInput {
+    instance_name: string;
+    db_name: string;
+    sql_content: string;
+    limit_num: number;
+    schema_name?: string;
+    tb_name?: string;
+}
+export interface ResourceInput {
+    instance_id: number;
+    resource_type: "database" | "schema" | "table" | "column";
+    db_name?: string;
+    schema_name?: string;
+    tb_name?: string;
+}
+export declare class ArcheryClient {
+    private readonly config;
+    private readonly jar;
+    private authenticated;
+    constructor(config: ArcheryMcpConfig);
+    ping(): Promise<{
+        ok: true;
+        baseUrl: string;
+        authenticated: boolean;
+    }>;
+    listInstances(): Promise<unknown>;
+    listResources(input: ResourceInput): Promise<unknown>;
+    query(input: QueryInput): Promise<unknown>;
+    queryLogs(params: Record<string, string | number | undefined>): Promise<unknown>;
+    private ensureAuthenticated;
+    private login;
+    private requestJson;
+    private rawRequest;
+    private parseSuccessfulJson;
+    private looksUnauthenticated;
+    private headers;
+    private url;
+}

package/dist/archery-client.js

@@ -0,0 +1 @@
+import{CookieJar as h}from"./cookie-jar.js";import{ArcheryMcpError as n}from"./errors.js";export class ArcheryClient{config;jar=new h;authenticated=!1;constructor(t){this.config=t}async ping(){return await this.ensureAuthenticated(),{ok:!0,baseUrl:this.config.ARCHERY_BASE_URL,authenticated:this.authenticated}}async listInstances(){return this.requestJson("/api/v1/instance/",{method:"GET"})}async listResources(t){return this.requestJson("/api/v1/instance/resource/",{method:"POST",form:{instance_id:String(t.instance_id),resource_type:t.resource_type,db_name:t.db_name??"",schema_name:t.schema_name??"",tb_name:t.tb_name??""}})}async query(t){return this.requestJson("/query/",{method:"POST",form:{instance_name:t.instance_name,db_name:t.db_name,sql_content:t.sql_content,limit_num:String(t.limit_num),schema_name:t.schema_name??"",tb_name:t.tb_name??""}})}async queryLogs(t){const e=new URLSearchParams;for(const[s,a]of Object.entries(t))a!==void 0&&e.set(s,String(a));const r=e.size>0?`?${e.toString()}`:"";return this.requestJson(`/query/querylog/${r}`,{method:"GET"})}async ensureAuthenticated(){this.authenticated&&this.jar.hasSession()||await this.login()}async login(){this.authenticated=!1,this.jar.clearSession();const t=await fetch(this.url("/login/"),{method:"GET",redirect:"manual"});this.jar.setFromHeaders(t.headers);const e=this.jar.get("csrftoken");if(!e)throw new n("ARCHERY_AUTH_FAILED","\u65E0\u6CD5\u4ECE Archery \u767B\u5F55\u9875\u83B7\u53D6 csrftoken",t.status);const r=new URLSearchParams({username:this.config.ARCHERY_USERNAME,password:this.config.ARCHERY_PASSWORD}),s=await fetch(this.url("/authenticate/"),{method:"POST",headers:this.headers({"Content-Type":"application/x-www-form-urlencoded","X-CSRFToken":e}),body:r.toString(),redirect:"manual"});this.jar.setFromHeaders(s.headers);const a=await u(s);if(!s.ok||a.status!==0)throw new n("ARCHERY_AUTH_FAILED",typeof a.msg=="string"?a.msg:"Archery \u8D26\u53F7\u5BC6\u7801\u767B\u5F55\u5931\u8D25",s.status);if(a.data)throw new n("ARCHERY_AUTH_FAILED","Archery \u8FD4\u56DE 2FA \u4F1A\u8BDD\uFF0C\u4F46\u8BE5 MCP \u65B9\u6848\u8981\u6C42\u670D\u52A1\u8D26\u53F7\u5173\u95ED 2FA",s.status);if(!this.jar.hasSession())throw new n("ARCHERY_AUTH_FAILED","Archery \u767B\u5F55\u6210\u529F\u4F46\u672A\u8FD4\u56DE sessionid",s.status);this.authenticated=!0}async requestJson(t,e){await this.ensureAuthenticated();const r=await this.rawRequest(t,e);if(this.looksUnauthenticated(r.response,r.text)){await this.login();const s=await this.rawRequest(t,e);return this.parseSuccessfulJson(s.response,s.text)}return this.parseSuccessfulJson(r.response,r.text)}async rawRequest(t,e){const r=this.jar.get("csrftoken")??"",s={};let a;e.method==="POST"&&(s["Content-Type"]="application/x-www-form-urlencoded",s["X-CSRFToken"]=r,a=new URLSearchParams(e.form??{}).toString());const o=await fetch(this.url(t),{method:e.method,headers:this.headers(s),body:a,redirect:"manual"});this.jar.setFromHeaders(o.headers);const c=await o.text();return{response:o,text:c}}parseSuccessfulJson(t,e){if(t.status===403)throw new n("ARCHERY_PERMISSION_DENIED","Archery \u62D2\u7EDD\u8BBF\u95EE\uFF0C\u8BF7\u68C0\u67E5\u670D\u52A1\u8D26\u53F7\u6743\u9650",t.status);if(!t.ok)throw new n("ARCHERY_HTTP_ERROR",`Archery HTTP ${t.status}: ${e.slice(0,200)}`,t.status);try{return JSON.parse(e)}catch{throw new n("ARCHERY_RESPONSE_PARSE_ERROR",`Archery \u8FD4\u56DE\u975E JSON \u5185\u5BB9: ${e.slice(0,200)}`,t.status)}}looksUnauthenticated(t,e){return t.status===401?!0:t.status>=300&&t.status<400?(t.headers.get("location")??"").includes("/login"):t.status===200&&e.includes("Login To Archery")}headers(t){const e=new Headers(t),r=this.jar.header();return r&&e.set("Cookie",r),e.set("Accept","application/json, text/plain, */*"),e}url(t){if(t.startsWith("http://")||t.startsWith("https://"))return t;const e=t.startsWith("/")?t:`/${t}`;return`${this.config.ARCHERY_BASE_URL}${e}`}}async function u(i){const t=await i.text();try{return JSON.parse(t)}catch{throw new n("ARCHERY_RESPONSE_PARSE_ERROR",`Archery \u8FD4\u56DE\u975E JSON \u5185\u5BB9: ${t.slice(0,200)}`,i.status)}}

package/dist/config.d.ts

@@ -0,0 +1,32 @@
+import { z } from "zod";
+declare const envSchema: z.ZodObject<{
+    ARCHERY_BASE_URL: z.ZodString;
+    ARCHERY_USERNAME: z.ZodString;
+    ARCHERY_PASSWORD: z.ZodString;
+    ARCHERY_DEFAULT_LIMIT: z.ZodDefault<z.ZodNumber>;
+    ARCHERY_MAX_LIMIT: z.ZodDefault<z.ZodNumber>;
+    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>;
+}, "strip", z.ZodTypeAny, {
+    ARCHERY_BASE_URL: string;
+    ARCHERY_USERNAME: string;
+    ARCHERY_PASSWORD: string;
+    ARCHERY_DEFAULT_LIMIT: number;
+    ARCHERY_MAX_LIMIT: number;
+    ARCHERY_METADATA_CACHE_ENABLED: boolean;
+    ARCHERY_METADATA_CACHE_TTL_SECONDS: number;
+    ARCHERY_METADATA_CACHE_PATH?: string | undefined;
+}, {
+    ARCHERY_BASE_URL: string;
+    ARCHERY_USERNAME: string;
+    ARCHERY_PASSWORD: string;
+    ARCHERY_DEFAULT_LIMIT?: number | undefined;
+    ARCHERY_MAX_LIMIT?: number | undefined;
+    ARCHERY_METADATA_CACHE_ENABLED?: unknown;
+    ARCHERY_METADATA_CACHE_TTL_SECONDS?: number | undefined;
+    ARCHERY_METADATA_CACHE_PATH?: string | undefined;
+}>;
+export type ArcheryMcpConfig = z.infer<typeof envSchema>;
+export declare function loadConfig(env?: NodeJS.ProcessEnv): ArcheryMcpConfig;
+export {};

package/dist/config.js

@@ -0,0 +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(/\/+$/,"")}}

package/dist/cookie-jar.d.ts

@@ -0,0 +1,8 @@
+export declare class CookieJar {
+    private readonly cookies;
+    setFromHeaders(headers: Headers): void;
+    get(name: string): string | undefined;
+    header(): string;
+    clearSession(): void;
+    hasSession(): boolean;
+}

package/dist/cookie-jar.js

@@ -0,0 +1 @@
+export class CookieJar{cookies=new Map;setFromHeaders(e){const o=a(e);for(const c of o){const s=c.split(";")[0],i=s.indexOf("=");if(i<=0)continue;const n=s.slice(0,i).trim(),r=s.slice(i+1).trim();n&&r&&this.cookies.set(n,r)}}get(e){return this.cookies.get(e)}header(){return[...this.cookies.entries()].map(([e,o])=>`${e}=${o}`).join("; ")}clearSession(){this.cookies.delete("sessionid")}hasSession(){return!!this.cookies.get("sessionid")}}function a(t){const e=t;if(typeof e.getSetCookie=="function")return e.getSetCookie();const o=t.get("set-cookie");return o?l(o):[]}function l(t){return t.split(/,(?=\s*[^;,=\s]+=[^;,]+)/g).map(e=>e.trim()).filter(Boolean)}

package/dist/errors.d.ts

@@ -0,0 +1,13 @@
+export type ArcheryErrorCode = "ARCHERY_CONFIG_MISSING" | "ARCHERY_AUTH_FAILED" | "ARCHERY_SESSION_EXPIRED" | "ARCHERY_PERMISSION_DENIED" | "ARCHERY_QUERY_REJECTED" | "ARCHERY_HTTP_ERROR" | "ARCHERY_RESPONSE_PARSE_ERROR";
+export declare class ArcheryMcpError extends Error {
+    readonly code: ArcheryErrorCode;
+    readonly status?: number;
+    constructor(code: ArcheryErrorCode, message: string, status?: number);
+}
+export declare function toErrorPayload(error: unknown): {
+    ok: false;
+    error: {
+        code: ArcheryErrorCode;
+        message: string;
+    };
+};

package/dist/errors.js

@@ -0,0 +1 @@
+export class ArcheryMcpError extends Error{code;status;constructor(s,r,o){super(r),this.name="ArcheryMcpError",this.code=s,this.status=o}}export function toErrorPayload(e){return e instanceof ArcheryMcpError?{ok:!1,error:{code:e.code,message:e.message}}:e instanceof Error&&e.message.startsWith("ARCHERY_CONFIG_MISSING:")?{ok:!1,error:{code:"ARCHERY_CONFIG_MISSING",message:e.message.replace(/^ARCHERY_CONFIG_MISSING:\s*/,"")}}:{ok:!1,error:{code:"ARCHERY_HTTP_ERROR",message:e instanceof Error?e.message:"Unknown Archery MCP error"}}}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +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)});

package/dist/metadata-cache.d.ts

@@ -0,0 +1,33 @@
+import type { ArcheryMcpConfig } from "./config.js";
+export interface CacheState {
+    enabled: boolean;
+    hit: boolean;
+    stale: boolean;
+    cached_at?: string;
+    expires_at?: string;
+}
+export interface CacheReadResult {
+    data: unknown;
+    cache: CacheState;
+}
+export declare class MetadataCache {
+    private readonly enabled;
+    private readonly ttlSeconds;
+    private readonly baseUrl;
+    private readonly cachePath;
+    constructor(config: ArcheryMcpConfig);
+    isEnabled(): boolean;
+    getPath(): string;
+    readInstances(): Promise<CacheReadResult | undefined>;
+    writeInstances(data: unknown): Promise<CacheReadResult>;
+    readDatabases(instanceId: number): Promise<CacheReadResult | undefined>;
+    writeDatabases(instanceId: number, data: unknown): Promise<CacheReadResult>;
+    realtimeState(): CacheState;
+    private toReadResult;
+    private toCacheState;
+    private isStale;
+    private createEntry;
+    private readFile;
+    private writeFile;
+    private emptyFile;
+}

package/dist/metadata-cache.js

@@ -0,0 +1 @@
+import{mkdir as n,readFile as c,writeFile as h}from"node:fs/promises";import{dirname as l,join as d,resolve as o}from"node:path";import{homedir as u}from"node:os";const i=1;export class MetadataCache{enabled;ttlSeconds;baseUrl;cachePath;constructor(e){this.enabled=e.ARCHERY_METADATA_CACHE_ENABLED,this.ttlSeconds=e.ARCHERY_METADATA_CACHE_TTL_SECONDS,this.baseUrl=e.ARCHERY_BASE_URL,this.cachePath=A(e.ARCHERY_METADATA_CACHE_PATH)}isEnabled(){return this.enabled}getPath(){return this.cachePath}async readInstances(){const t=(await this.readFile()).instances;return this.toReadResult(t)}async writeInstances(e){const t=await this.readFile(),a=this.createEntry(e);return t.instances=a,await this.writeFile(t),{data:e,cache:this.toCacheState(a,!1)}}async readDatabases(e){const a=(await this.readFile()).databasesByInstanceId?.[String(e)];return this.toReadResult(a)}async writeDatabases(e,t){const a=await this.readFile(),s=this.createEntry(t);return a.databasesByInstanceId={...a.databasesByInstanceId??{},[String(e)]:s},await this.writeFile(a),{data:t,cache:this.toCacheState(s,!1)}}realtimeState(){return{enabled:this.enabled,hit:!1,stale:!1}}toReadResult(e){if(!(!e||this.isStale(e)))return{data:e.data,cache:this.toCacheState(e,!0)}}toCacheState(e,t){const a=Date.parse(e.cachedAt),s=new Date(a+this.ttlSeconds*1e3).toISOString();return{enabled:this.enabled,hit:t,stale:!1,cached_at:e.cachedAt,expires_at:s}}isStale(e){const t=Date.parse(e.cachedAt);return Number.isNaN(t)?!0:Date.now()-t>=this.ttlSeconds*1e3}createEntry(e){return{cachedAt:new Date().toISOString(),data:e}}async readFile(){try{const e=await c(this.cachePath,"utf8"),t=JSON.parse(e);return t.version!==i||t.baseUrl!==this.baseUrl?this.emptyFile():{...t,databasesByInstanceId:t.databasesByInstanceId??{}}}catch(e){if(e instanceof Error&&"code"in e&&e.code==="ENOENT")return this.emptyFile();if(e instanceof SyntaxError)return this.emptyFile();throw e}}async writeFile(e){await n(l(this.cachePath),{recursive:!0}),await h(this.cachePath,JSON.stringify(e,null,2),"utf8")}emptyFile(){return{version:i,baseUrl:this.baseUrl,databasesByInstanceId:{}}}}function A(r){return r?o(r):d(u(),".cache","archery-mcp","metadata-cache.json")}

package/dist/metadata-service.d.ts

@@ -0,0 +1,38 @@
+import type { ArcheryClient } from "./archery-client.js";
+import type { CacheState, MetadataCache } from "./metadata-cache.js";
+type RefreshScope = "instances" | "databases" | "all";
+export interface CacheOptions {
+    force_refresh?: boolean;
+}
+export interface RefreshOptions {
+    scope?: RefreshScope;
+    instance_id?: number;
+}
+export interface CachedPayload {
+    cache: CacheState;
+    data: unknown;
+}
+export interface RefreshPayload {
+    cache: {
+        enabled: boolean;
+        path: string;
+    };
+    refreshed: {
+        instances: boolean;
+        databases: Array<{
+            instance_id: number;
+            ok: boolean;
+            message?: string;
+        }>;
+    };
+}
+export declare class MetadataService {
+    private readonly client;
+    private readonly cache;
+    constructor(client: ArcheryClient, cache: MetadataCache);
+    listInstances(options?: CacheOptions): Promise<CachedPayload>;
+    listDatabases(instanceId: number, options?: CacheOptions): Promise<CachedPayload>;
+    refreshMetadataCache(options?: RefreshOptions): Promise<RefreshPayload>;
+    private wrapRealtime;
+}
+export {};

package/dist/metadata-service.js

@@ -0,0 +1 @@
+export class MetadataService{client;cache;constructor(t,a){this.client=t,this.cache=a}async listInstances(t={}){if(!this.cache.isEnabled())return this.wrapRealtime(await this.client.listInstances());if(!t.force_refresh){const e=await this.cache.readInstances();if(e)return e}const a=await this.client.listInstances();return this.cache.writeInstances(a)}async listDatabases(t,a={}){if(!this.cache.isEnabled())return this.wrapRealtime(await this.client.listResources({instance_id:t,resource_type:"database"}));if(!a.force_refresh){const s=await this.cache.readDatabases(t);if(s)return s}const e=await this.client.listResources({instance_id:t,resource_type:"database"});return this.cache.writeDatabases(t,e)}async refreshMetadataCache(t={}){const a=t.scope??"all",e={instances:!1,databases:[]};let s;if((a==="instances"||a==="all")&&(s=await this.client.listInstances(),this.cache.isEnabled()&&await this.cache.writeInstances(s),e.instances=!0),a==="databases"||a==="all"){const h=t.instance_id===void 0?d(s??await this.client.listInstances()):[t.instance_id];for(const n of h)try{const i=await this.client.listResources({instance_id:n,resource_type:"database"});this.cache.isEnabled()&&await this.cache.writeDatabases(n,i),e.databases.push({instance_id:n,ok:!0})}catch(i){e.databases.push({instance_id:n,ok:!1,message:i instanceof Error?i.message:String(i)})}}return{cache:{enabled:this.cache.isEnabled(),path:this.cache.getPath()},refreshed:e}}wrapRealtime(t){return{cache:this.cache.realtimeState(),data:t}}}function d(c){const t=new Set;return r(c,t),[...t].sort((a,e)=>a-e)}function r(c,t){if(Array.isArray(c)){for(const s of c)r(s,t);return}if(!c||typeof c!="object")return;const a=c,e=a.instance_id??a.instanceId??a.id;if(typeof e=="number"&&Number.isInteger(e)&&e>0&&t.add(e),typeof e=="string"&&/^\d+$/.test(e)){const s=Number(e);s>0&&t.add(s)}for(const s of["data","rows","result","list"])s in a&&r(a[s],t)}

package/dist/smoke.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/smoke.js

@@ -0,0 +1 @@
+import{ArcheryClient as t}from"./archery-client.js";import{loadConfig as c}from"./config.js";async function e(){const n=c(),o=new t(n),s=await o.ping();console.log(JSON.stringify(s,null,2));const i=await o.listInstances();console.log(JSON.stringify(i,null,2))}e().catch(n=>{const o=n instanceof Error?n.message:String(n);console.error(o),process.exit(1)});

package/dist/sql-guard.d.ts

@@ -0,0 +1,2 @@
+export declare function assertReadOnlySql(sql: string): void;
+export declare function normalizeLimit(inputLimit: number | undefined, defaultLimit: number, maxLimit: number): number;

package/dist/sql-guard.js

@@ -0,0 +1 @@
+import{ArcheryMcpError as o}from"./errors.js";const i=["select","show","desc","describe","explain","with"],a=["insert","update","delete","drop","alter","truncate","create","replace","grant","revoke","merge","call","execute"];export function assertReadOnlySql(t){const e=c(t).trim().toLowerCase();if(!e)throw new o("ARCHERY_QUERY_REJECTED","SQL \u4E0D\u80FD\u4E3A\u7A7A");if(s(e))throw new o("ARCHERY_QUERY_REJECTED","MCP \u4FA7\u62D2\u7EDD\u591A\u8BED\u53E5 SQL");const r=e.match(/^[a-z]+/)?.[0]??"";if(!i.includes(r))throw new o("ARCHERY_QUERY_REJECTED",`MCP \u4FA7\u53EA\u5141\u8BB8\u53EA\u8BFB SQL\uFF0C\u5F53\u524D\u8BED\u53E5\u4EE5 ${r||"\u672A\u77E5\u5185\u5BB9"} \u5F00\u5934`);for(const n of a)if(new RegExp(`\\b${n}\\b`,"i").test(e))throw new o("ARCHERY_QUERY_REJECTED",`MCP \u4FA7\u62D2\u7EDD\u5305\u542B ${n.toUpperCase()} \u7684 SQL`)}export function normalizeLimit(t,e,r){if(t===void 0||Number.isNaN(t))return e;const n=Math.floor(t);return n<=0?e:Math.min(n,r)}function c(t){let e=t.trimStart(),r="";for(;e!==r;)r=e,e=e.replace(/^--.*(?:\n|$)/,"").trimStart(),e=e.replace(/^\/\*[\s\S]*?\*\//,"").trimStart();return e}function s(t){return t.replace(/;\s*$/,"").includes(";")}

package/dist/tools.d.ts

@@ -0,0 +1,5 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { ArcheryClient } from "./archery-client.js";
+import type { ArcheryMcpConfig } from "./config.js";
+import type { MetadataService } from "./metadata-service.js";
+export declare function registerTools(server: Server, client: ArcheryClient, config: ArcheryMcpConfig, metadataService: MetadataService): void;

package/dist/tools.js

@@ -0,0 +1 @@
+import{CallToolRequestSchema as _,ListToolsRequestSchema as h}from"@modelcontextprotocol/sdk/types.js";import{z as e}from"zod";import{toErrorPayload as y}from"./errors.js";import{assertReadOnlySql as d,normalizeLimit as l}from"./sql-guard.js";const b=e.object({instance_id:e.number().int().positive(),resource_type:e.enum(["database","schema","table","column"]),db_name:e.string().optional(),schema_name:e.string().optional(),tb_name:e.string().optional(),force_refresh:e.boolean().optional()}),f=e.object({force_refresh:e.boolean().optional()}),g=e.object({scope:e.enum(["instances","databases","all"]).optional(),instance_id:e.number().int().positive().optional()}),R=e.object({instance_name:e.string().min(1),db_name:e.string().min(1),sql_content:e.string().min(1),limit_num:e.number().int().positive().optional(),schema_name:e.string().optional(),tb_name:e.string().optional()}),q=e.object({page:e.number().int().positive().optional(),limit:e.number().int().positive().optional(),instance_name:e.string().optional(),db_name:e.string().optional(),username:e.string().optional()});export function registerTools(i,a,o,m){i.setRequestHandler(h,async()=>({tools:[{name:"archery_ping",description:"Check Archery MCP configuration, reachability, and login state.",inputSchema:{type:"object",properties:{},additionalProperties:!1}},{name:"archery_list_instances",description:"List Archery instances. Uses local metadata cache by default and refreshes when force_refresh is true or cache is expired.",inputSchema:{type:"object",properties:{force_refresh:{type:"boolean"}},additionalProperties:!1}},{name:"archery_list_resources",description:"List databases, schemas, tables, or columns for an Archery instance. Database discovery uses local metadata cache by default.",inputSchema:{type:"object",required:["instance_id","resource_type"],properties:{instance_id:{type:"number",minimum:1},resource_type:{type:"string",enum:["database","schema","table","column"]},db_name:{type:"string"},schema_name:{type:"string"},tb_name:{type:"string"},force_refresh:{type:"boolean"}},additionalProperties:!1}},{name:"archery_query",description:"Execute read-only SQL through Archery. Archery still enforces permissions, masking, limits, and audit logs.",inputSchema:{type:"object",required:["instance_name","db_name","sql_content"],properties:{instance_name:{type:"string",minLength:1},db_name:{type:"string",minLength:1},sql_content:{type:"string",minLength:1},limit_num:{type:"number",minimum:1},schema_name:{type:"string"},tb_name:{type:"string"}},additionalProperties:!1}},{name:"archery_query_logs",description:"Fetch Archery query logs visible to the service account.",inputSchema:{type:"object",properties:{page:{type:"number",minimum:1},limit:{type:"number",minimum:1},instance_name:{type:"string"},db_name:{type:"string"},username:{type:"string"}},additionalProperties:!1}},{name:"archery_refresh_metadata_cache",description:"Refresh local Archery metadata cache for instances and database lists.",inputSchema:{type:"object",properties:{scope:{type:"string",enum:["instances","databases","all"]},instance_id:{type:"number",minimum:1}},additionalProperties:!1}}]})),i.setRequestHandler(_,async p=>{const r=p.params.name,s=p.params.arguments??{};try{if(r==="archery_ping")return n(await a.ping());if(r==="archery_list_instances"){const t=f.parse(s);return n(await m.listInstances(t))}if(r==="archery_list_resources"){const t=b.parse(s);if(t.resource_type==="database")return n(await m.listDatabases(t.instance_id,{force_refresh:t.force_refresh}));const{force_refresh:c,...u}=t;return n(await a.listResources(u))}if(r==="archery_query"){const t=R.parse(s);d(t.sql_content);const c=l(t.limit_num,o.ARCHERY_DEFAULT_LIMIT,o.ARCHERY_MAX_LIMIT);return n(await a.query({...t,limit_num:c}))}if(r==="archery_query_logs"){const t=q.parse(s),c=t.limit===void 0?void 0:l(t.limit,o.ARCHERY_DEFAULT_LIMIT,o.ARCHERY_MAX_LIMIT);return n(await a.queryLogs({...t,limit:c}))}if(r==="archery_refresh_metadata_cache"){const t=g.parse(s);return n(await m.refreshMetadataCache(t))}return n({ok:!1,error:{code:"ARCHERY_HTTP_ERROR",message:`Unknown tool: ${r}`}},!0)}catch(t){return n(y(t),!0)}})}function n(i,a=!1){return{content:[{type:"text",text:JSON.stringify(i,null,2)}],...a?{isError:!0}:{}}}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@seaxlab/archery-mcp",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Archery MCP server (Node.js, stdio)",
+  "main": "dist/index.js",
+  "bin": {
+    "archery-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "node scripts/clean-dist.mjs && tsc -p tsconfig.json",
+    "build:release": "node scripts/clean-dist.mjs && tsc -p tsconfig.json && node scripts/minify-dist.mjs",
+    "prepublishOnly": "npm run build:release",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "start": "node dist/index.js",
+    "smoke": "node dist/smoke.js",
+    "dev": "tsx watch src/index.ts",
+    "dev:once": "tsx src/index.ts",
+    "inspector": "bash scripts/mcp-inspector.sh"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "esbuild": "^0.25.12",
+    "tsx": "^4.19.0",
+    "typescript": "^5.8.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}