Skip to main content
Glama
zhouruoye

archery-mcp

by zhouruoye
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
TypeScript

archery-mcp

通过 Archery 网关安全查询 MySQL / Redis / MongoDB 的 MCP Server，支持性能诊断。

数据访问路径

MCP Client (Trae/Cursor/Claude Code) -> archery-mcp (HTTP /mcp) -> Archery Web -> Database

本项目不直连数据库，所有查询都通过 Archery 的 /query/ 接口执行。

功能特性

  • 支持 MySQL / Redis / MongoDB 三种数据库查询

  • 只读安全策略：MySQL 仅允许 SELECT/SHOW/EXPLAIN，阻塞写、DDL、多语句、会话操作和文件导出

  • 自动补 LIMIT：缺 LIMIT 的 SELECT 自动追加

  • 预定义性能诊断集：MySQL 8 项 / Redis 9 项 / MongoDB 7 项

  • 模拟登录：自动处理 CSRF + Cookie，session 缓存 1 小时，失效自动重登

  • HTTP /mcp 接口：支持多会话隔离（Mcp-Session-Id），可选 Bearer 鉴权

  • 错误信息脱敏：含 password/cookie/csrf/session/token 的消息自动替换

环境要求

  • Node.js >= 20

  • npm

  • 可访问目标 Archery 网关

安装与运行

git clone <repo-url> archery-mcp
cd archery-mcp
npm install
npm run build

支持两种传输模式：stdio（默认，推荐）和 HTTP。

stdio 模式（默认）

客户端（Trae/Cursor/Claude Code）自动拉起子进程，所有配置写在 mcpServers 里，无需单独启动 server。

node dist/cli.js --archery-url https://archery.example.com --username your-user --password your-password

或用环境变量：

export ARCHERY_BASE_URL=https://archery.example.com
export ARCHERY_LOGIN_USERNAME=your-user
export ARCHERY_LOGIN_PASSWORD=your-password
node dist/cli.js

stdio 模式下凭证不暴露在进程列表（ps aux）里，相对安全。

HTTP 模式

适合多客户端共享同一个 server，需要单独启动：

export ARCHERY_LOGIN_USERNAME="your-archery-user"
export ARCHERY_LOGIN_PASSWORD="your-archery-password"
node dist/cli.js --transport http --port 8080

默认监听 127.0.0.1:8080。如需开放给内网，显式指定 host：

node dist/cli.js --transport http --host 0.0.0.0 --port 8080

环境变量

变量

必需

默认值

说明

ARCHERY_BASE_URL

是

-

Archery 网关地址

ARCHERY_LOGIN_USERNAME

是

-

Archery 登录用户名

ARCHERY_LOGIN_PASSWORD

是

-

Archery 登录密码

ARCHERY_QUERY_PATH

否

/query/

Archery 查询接口路径

ARCHERY_QUERY_DEFAULT_LIMIT

否

100

缺省 LIMIT

ARCHERY_QUERY_MAX_LIMIT

否

500

最大 LIMIT

ARCHERY_QUERY_ALLOWED_INSTANCES

否

空

实例白名单，逗号分隔

ARCHERY_QUERY_ALLOWED_DATABASES

否

空

数据库白名单

ARCHERY_QUERY_BLOCKED_TABLES

否

空

阻塞表名片段

ARCHERY_MCP_HTTP_HOST

否

127.0.0.1

HTTP 监听地址（HTTP 模式）

ARCHERY_MCP_HTTP_PORT

否

8080

HTTP 监听端口（HTTP 模式）

ARCHERY_MCP_HTTP_API_KEY

否

空

/mcp Bearer 鉴权 token（HTTP 模式）

ARCHERY_BLOCKED_URLS

否

空

黑名单：禁止访问的 Archery 地址，逗号分隔

ARCHERY_BLOCKED_USERNAMES

否

空

黑名单：禁止使用的 Archery 用户名，逗号分隔

ARCHERY_BLACKLIST_FILE

否

空

黑名单：JSON 文件路径，未设置时自动查找 ./blacklist.json

CLI 参数会覆盖同名环境变量。完整参数列表见 node dist/cli.js --help。

黑名单配置

用于禁止特定 Archery 地址或用户名访问本服务。启动时会校验，命中黑名单则拒绝启动：

# 禁止访问生产环境 Archery
export ARCHERY_BLOCKED_URLS="https://archery-prod.example.com,https://archery-prod2.example.com"

# 禁止某些用户名
export ARCHERY_BLOCKED_USERNAMES="admin,root,sa"

# 然后正常启动
node dist/cli.js

从文件读取（推荐用于较长黑名单）

当黑名单条目较多时，可改用 JSON 文件维护。文件查找优先级：

  1. CLI 参数 --blacklist-file <path>（最高）

  2. 环境变量 ARCHERY_BLACKLIST_FILE

  3. 自动发现：当前工作目录（项目根）下的 ./blacklist.json（最低）

// blacklist.json
{
  "urls": [
    "https://archery-prod.example.com",
    "https://archery-prod2.example.com/"
  ],
  "usernames": ["admin", "root", "sa"]
}
# 方式一：在项目根放置 blacklist.json，自动发现（无需任何参数）
node dist/cli.js

# 方式二：环境变量指定路径
export ARCHERY_BLACKLIST_FILE="/path/to/blacklist.json"
node dist/cli.js

# 方式三：CLI 参数（覆盖环境变量与自动发现）
node dist/cli.js --blacklist-file /path/to/blacklist.json

说明：

  • urls 与 usernames 均为可选字段，缺失视为空数组；文件中未知字段会被忽略。

  • 自动发现的 ./blacklist.json 是可选的：不存在则忽略（不报错），存在则必须为合法 JSON，否则启动失败（fail-fast）。

  • 显式指定的路径（CLI/env）必须存在，否则启动失败。

  • 文件与 ARCHERY_BLOCKED_URLS / ARCHERY_BLOCKED_USERNAMES 环境变量会合并去重（非互斥）。典型用法：文件维护长期黑名单，环境变量临时追加屏蔽项。

  • 下方「匹配规则」对两种来源都生效。

  • 文件读取/解析失败会直接拒绝启动（fail-fast），错误信息会包含文件路径。

匹配规则：

  • URL：不区分大小写，自动忽略末尾 /，精确匹配

  • 用户名：不区分大小写，精确匹配

  • 两者命中任一即拒绝

客户端配置示例

stdio 模式（推荐）

Trae / Cursor / Claude Code

{
  "mcpServers": {
    "archery": {
      "command": "node",
      "args": [
        "/absolute/path/to/archery-mcp/dist/cli.js"
      ],
      "env": {
        "ARCHERY_BASE_URL": "https://archery.example.com",
        "ARCHERY_LOGIN_USERNAME": "your-archery-user",
        "ARCHERY_LOGIN_PASSWORD": "your-archery-password"
      }
    }
  }
}

或用 CLI 参数传凭证（更直观，但密码会出现在进程列表）：

{
  "mcpServers": {
    "archery": {
      "command": "node",
      "args": [
        "/absolute/path/to/archery-mcp/dist/cli.js",
        "--archery-url", "https://archery.example.com",
        "--username", "your-archery-user",
        "--password", "your-archery-password"
      ]
    }
  }
}

stdio 模式不需要 --transport 参数（默认就是 stdio）。凭证只在该子进程内可见，不会污染全局环境。

HTTP 模式

Trae / Cursor

{
  "mcpServers": {
    "archery": {
      "type": "http",
      "url": "http://localhost:8080/mcp",
      "headers": {
        "Authorization": "Bearer your-api-key"
      }
    }
  }
}

若未配置 ARCHERY_MCP_HTTP_API_KEY，可省略 headers。

curl 调试

# 1. initialize
curl -i -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'

# 从响应头取 mcp-session-id
SID="..."

# 2. notifications/initialized
curl -X POST http://localhost:8080/mcp \
  -H "mcp-session-id: $SID" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'

# 3. tools/list
curl -X POST http://localhost:8080/mcp \
  -H "mcp-session-id: $SID" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# 4. tools/call
curl -X POST http://localhost:8080/mcp \
  -H "mcp-session-id: $SID" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"archery_run_diagnostic","arguments":{"instanceName":"prod-mysql","dbName":"mydb","diagnosticKey":"processlist"}}}'

MCP 工具

工具

说明

archery_list_instances

列出 Archery 注册的实例，可选 dbType 过滤

archery_list_databases

列出某实例下的所有数据库

archery_execute_query

执行只读 SQL（MySQL）或诊断命令（Redis/MongoDB），自动校验和补 LIMIT

archery_describe_table

读取表结构元数据

archery_query_history

搜索查询历史摘要

archery_run_diagnostic

运行预定义性能诊断命令

archery_execute_query

{
  "instanceName": "prod-mysql",
  "dbName": "mydb",
  "sql": "SELECT * FROM users WHERE created_at > '2026-01-01'",
  "limitNum": 100
}

archery_run_diagnostic

{
  "instanceName": "prod-redis",
  "dbName": "0",
  "diagnosticKey": "slowlog"
}

带额外参数（MongoDB 集合诊断）：

{
  "instanceName": "prod-mongo",
  "dbName": "mydb",
  "diagnosticKey": "collection_stats",
  "extraParams": { "collectionName": "users" }
}

支持的诊断命令

MySQL

key

说明

processlist

当前所有连接和正在执行的 SQL

status

全局状态计数器

variables

全局变量（配置）

innodb_status

InnoDB 引擎状态（锁、死锁、事务）

slow_queries

最近 50 条慢查询

table_sizes

按 data_length 排序的前 50 大表

index_usage

按 read 次数排序的前 50 个索引

long_running

运行超过 60 秒的查询

locks

当前 InnoDB 行锁和等待事务

Redis

注意：Archery 的 Redis 引擎有 safe_cmd 白名单，只允许查询类命令。SLOWLOG、CLIENT LIST、CONFIG GET 等性能诊断命令会被 Archery 拒绝（返回"禁止执行该命令！"）。因此 Redis 诊断以 key 查询为主。

key

说明

需要参数

info

Redis INFO 输出（部分 Archery 版本可能禁用）

-

scan

扫描当前 DB 的 key（前 100 个）

-

key_type

查看指定 key 的类型

keyName

key_ttl

查看指定 key 的 TTL（秒）

keyName

key_exists

检查 key 是否存在

keyName

string_get

获取 string 类型 key 的值

keyName

string_strlen

获取 string 类型 key 的值长度

keyName

hash_getall

获取 hash key 的所有字段和值

keyName

hash_len

获取 hash key 的字段数量

keyName

list_len

获取 list key 的长度

keyName

list_range

获取 list key 的前 50 个元素

keyName

set_members

获取 set key 的所有成员

keyName

set_scard

获取 set key 的成员数量

keyName

zset_range

获取 zset key 的前 50 个成员（带 score）

keyName

zset_zcard

获取 zset key 的成员数量

keyName

MongoDB

key

说明

server_status

服务器状态概览

current_ops

当前活跃操作

slow_queries

system.profile 中最近 50 条慢查询

connections

连接统计

collection_stats

指定 collection 的统计（需 extraParams.collectionName）

index_stats

指定 collection 的索引使用统计（需 extraParams.collectionName）

db_stats

数据库级别统计

安全说明

  • 只读：MySQL 仅允许 SELECT/SHOW/EXPLAIN，Redis 阻塞 CONFIG SET，MongoDB 阻塞 insert/update/remove/drop 等写操作

  • 凭证安全：username/password 只从环境变量读取，不写日志、不返回给 AI

  • 错误脱敏：含敏感关键词的 Archery 错误消息会被替换为通用提示

  • 会话隔离：HTTP /mcp 每个 Mcp-Session-Id 独立，session cookie 进程内存缓存 1 小时

  • 默认本机：HTTP 默认监听 127.0.0.1，仅当显式 --host 0.0.0.0 时开放外网；建议配合 ARCHERY_MCP_HTTP_API_KEY 使用

开发

npm run typecheck     # 类型检查
npm run build         # 构建
npm test              # 运行单元测试
npm run start:http    # 启动 HTTP 服务

目录结构：

src/
├── archeryClient.ts       # Archery HTTP 客户端
├── archeryForms.ts        # 表单构造
├── archeryHttpSupport.ts  # CookieJar、CSRF 提取
├── archeryMappers.ts      # 响应映射
├── archerySession.ts      # 模拟登录
├── cli.ts                 # CLI 入口
├── config.ts              # 环境变量加载
├── diagnostics.ts         # 诊断命令集
├── httpServer.ts          # HTTP /mcp 服务
├── mcpServer.ts           # MCP 工具注册
├── policy.ts              # 只读 SQL 策略
├── services.ts           # 依赖容器
└── tools.ts               # 工具 schema + 分发

License

MIT