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 | 缓存文件路径 | | 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，也会基于过滤后的实例列表刷新，避免对黑名单实例调用库列表接口。显式指定实例时按入参执行，便于临时排查单个实例。

默认缓存路径：

~/.cache/archery-mcp/metadata-cache.json

默认缓存有效期为 7 天。需要实时刷新时，可以在工具入参中传 force_refresh=true，也可以调用 archery_refresh_metadata_cache。

使用已安装的包（推荐）

全局安装或作为项目依赖安装 @seaxlab/archery-mcp 后，可用 npx 拉起（会使用包内 bin）：

{
  "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",
        "ARCHERY_METADATA_CACHE_EXCLUDE_INSTANCE_NAMES": "instance-a,instance-b",
        "ARCHERY_METADATA_CACHE_EXCLUDE_INSTANCE_IDS": "1,2"
      }
    }
  }
}