@dezhouzhang/archery-query-mcp

用于通过 Archery 网关安全查询数据库的 MCP Server。支持 stdio 和 HTTP 两种运行模式，适合接入 OpenCode、Codex 等支持 MCP 的客户端。

数据访问路径始终是：

MCP Client -> archery-query-mcp -> Archery Web Gateway -> Database

本项目不直连数据库。

功能特性

• 只允许只读 SQL：SELECT、SHOW、EXPLAIN。
• 阻止写入、DDL、多语句、会话切换和文件导出类操作。
• 对缺少 LIMIT 的 SELECT 自动追加限制。
• 日常低风险只读查询支持单次调用；高风险或显式审阅场景保留 prepare / execute 两阶段流程。
• 支持表结构读取和查询历史检索。
• 支持 hangzhou、beijing、huawei 三个 Archery 云别名。
• 支持业务组 scope 解析、绑定、切换、查看、清除和临时覆盖。
• 支持按 companyId 路由到共享库、公司库、schema 映射或混合路由。
• 支持 stdio 本地子进程模式和 HTTP /mcp 模式。

环境要求

• Node.js >= 20
• npm
• 当前网络能访问目标 Archery 网关

安装

推荐全局安装：

npm install -g @dezhouzhang/archery-query-mcp

验证命令是否可用：

archery-query-mcp --help

也可以不安装，直接用 npm exec 临时运行：

npm exec --yes --package=@dezhouzhang/archery-query-mcp -- archery-query-mcp --help

查看版本：

archery-query-mcp -v

检查当前进程能否看到 Node、CLI 入口和必需环境变量：

archery-query-mcp doctor

doctor 只报告 MCP_ARCHERY_LOGIN_USERNAME / MCP_ARCHERY_LOGIN_PASSWORD 是否存在，不会输出账号或密码值。路径字段会把当前用户 home 目录显示为 ~。

从源码目录本地安装时，不要直接对未构建的源码目录执行 npm install -g .；先安装开发依赖并构建：

npm ci
npm run build
npm install -g .

升级到最新版本：

archery-query-mcp upgrade

凭证配置

Archery 登录账号密码只从运行时环境变量读取：

MCP_ARCHERY_LOGIN_USERNAME=your-user
MCP_ARCHERY_LOGIN_PASSWORD=your-password

不要把密码、Cookie、CSRF、session、SQL API token、数据库凭证写入仓库或共享配置文件。

macOS / Linux

export MCP_ARCHERY_LOGIN_USERNAME="your-user"
export MCP_ARCHERY_LOGIN_PASSWORD="your-password"

Windows PowerShell

当前终端临时生效：

$env:MCP_ARCHERY_LOGIN_USERNAME="your-user"
$env:MCP_ARCHERY_LOGIN_PASSWORD="your-password"

写入当前 Windows 用户环境变量：

setx MCP_ARCHERY_LOGIN_USERNAME "your-user"
setx MCP_ARCHERY_LOGIN_PASSWORD "your-password"

使用 setx 后，需要重新打开终端或重启客户端进程。

运行方式

stdio 模式

stdio 模式适合 OpenCode、Codex 等客户端自动拉起 MCP 子进程：

archery-query-mcp --transport stdio

HTTP 模式

HTTP 模式适合多个客户端共享同一个 MCP 服务：

archery-query-mcp --transport http --port 8080

HTTP 默认绑定 127.0.0.1，不会监听所有网卡。如果确实要开放给内网网关或容器网络，可以显式指定：

archery-query-mcp --transport http --host 0.0.0.0 --port 8080

HTTP endpoints：

POST   /mcp   MCP JSON-RPC（tools/call 等）
GET    /mcp   可选的 SSE 通知流
DELETE /mcp   结束一个 MCP 会话
GET    /health

/mcp 走标准的 MCP Streamable HTTP 协议：客户端先 POST initialize，服务端在响应里返回 Mcp-Session-Id 头，后续所有请求都要带上这个头，属于同一个会话。会话内多次调用的 scope 绑定会复用；不同 Mcp-Session-Id 之间互相隔离。请求还需带 Accept: application/json, text/event-stream。DELETE /mcp（带会话头）用于显式结束会话。

共享 HTTP 部署建议配置 API Key：

export ARCHERY_MCP_HTTP_API_KEY="replace-with-a-long-random-token"
archery-query-mcp --transport http --port 8080

客户端请求 /mcp 时需带：

Authorization: Bearer replace-with-a-long-random-token

/health 用于健康检查，不要求 Bearer token。不要把 HTTP API Key 写进仓库；如果未配置 ARCHERY_MCP_HTTP_API_KEY，请只在本机、可信内网或受可信网关保护的环境中使用，不要直接暴露到公网。

OpenCode stdio 配置

先全局安装：

npm install -g @dezhouzhang/archery-query-mcp

在启动 OpenCode 前，确保 MCP_ARCHERY_LOGIN_USERNAME 和 MCP_ARCHERY_LOGIN_PASSWORD 已经在 OpenCode 进程环境中可见。

在 ~/.config/opencode/opencode.json 中添加：

{
  "mcp": {
    "archery_query": {
      "type": "local",
      "command": ["archery-query-mcp", "--transport", "stdio"],
      "enabled": true,
      "timeout": 30000
    }
  }
}

stdio 模式下，每个 OpenCode 进程通常会启动一个独立的 MCP 子进程，不会跨 OpenCode 实例复用。若希望多个 OpenCode 共享同一个 MCP，请使用 HTTP 模式并配置 remote MCP。

Codex stdio 配置

先全局安装：

npm install -g @dezhouzhang/archery-query-mcp

在启动 Codex 前，确保环境变量已设置：

export MCP_ARCHERY_LOGIN_USERNAME="your-user"
export MCP_ARCHERY_LOGIN_PASSWORD="your-password"

在 ~/.codex/config.toml 中添加：

[mcp_servers.archery_query]
command = "archery-query-mcp"
args = ["--transport", "stdio"]
enabled = true
startup_timeout_sec = 30
tool_timeout_sec = 120
env_vars = ["MCP_ARCHERY_LOGIN_USERNAME", "MCP_ARCHERY_LOGIN_PASSWORD"]

macOS 上如果 Codex 从 GUI 启动后找不到命令，先在终端执行 command -v archery-query-mcp，再把 command 改成输出的绝对路径。

如果不想全局安装，也可以使用 npm exec：

[mcp_servers.archery_query]
command = "npm"
args = ["exec", "--yes", "--package=@dezhouzhang/archery-query-mcp", "--", "archery-query-mcp", "--transport", "stdio"]
enabled = true
startup_timeout_sec = 30
tool_timeout_sec = 120
env_vars = ["MCP_ARCHERY_LOGIN_USERNAME", "MCP_ARCHERY_LOGIN_PASSWORD"]

修改 config.toml 后需要重启 Codex。

Archery 认证模式

默认认证模式是 simulated-login：

archery-query-mcp --archery-auth-mode simulated-login

该模式会使用运行时环境变量 MCP_ARCHERY_LOGIN_USERNAME / MCP_ARCHERY_LOGIN_PASSWORD 登录 Archery。huawei 目前使用 HTTP base URL，但仍可走 simulated-login；只是请确保它运行在可信内网或可信网关后面，不要直接暴露给公网。

支持的云

| cloudName | 别名 | 说明 | | --- | --- | --- | | hangzhou | hz、杭州云 | 杭州 Archery | | beijing | bj、北京云 | 北京 Archery | | huawei | hw、华为云 | 华为 Archery，默认登录模式受 HTTP 限制 |

查询 scope 可以显式传入物理 Archery 目标，也可以通过业务组和 companyId 解析，也可以复用当前 session 绑定。

Scope 工作流

scope 的目标是先确定当前查询属于哪个业务组，再根据公司路由规则得到安全的物理 Archery 目标。本服务仍然只通过 Archery 网关访问数据库，不会直连数据库。

解析优先级

普通查询工具会按以下顺序解析 scope：

1. 本次调用显式传入 cloudName、instanceName、dbName。
2. 本次调用显式传入 businessGroupId，必要时再传 companyId。company-db 业务复用公司路由规则，schema-map 业务必须落到公司真实存在的业务库。
3. 本次调用只传入 companyId 时，archery_query_readonly / archery_prepare_query 会先用 bugContext / sql / 路径字符串的强业务意图解析，并和公司真实 availableBusinesses 校验。
4. 当前 bindingDomainId 下有效的临时覆盖。
5. 当前 bindingDomainId 下有效的 session 绑定。
6. 无法安全确定时返回候选或拒绝结果，让用户选择。

显式物理 scope 只对本次调用生效，不会写入持久绑定。显式物理 scope 必须一次性提供完整的 cloudName、instanceName、dbName；只提供其中一部分会返回结构化的 needs_user_input，不会让客户端猜测缺失字段。普通的 prepare、describe、history 工具不会自动改写 session scope。

ScopeRequestContext 字段

scope 相关工具和普通查询工具都可以携带这些上下文字段：

| 字段 | 说明 | | --- | --- | | sessionId | 调用方的会话标识。HTTP 下取自 MCP 会话（initialize 握手返回的 Mcp-Session-Id 头），由服务端权威设定并注入到每个工具，不接受工具参数覆盖；stdio 未传时由服务进程生成默认会话。 | | userSubject | 当前 MCP 用户标识，未传时使用服务启动参数中的用户。 | | workspaceRoot | 当前工作区根目录。用于计算绑定域；普通查询和 archery_resolve_scope 不会因为它自动扫描工作区配置。 | | activeFilePath | 当前正在处理的文件路径。用于计算最近模块绑定域，也可作为轻量 codeContext 文本证据。 | | activeModuleRoot | 当前模块根目录。用于绑定域，也可作为轻量 codeContext 文本证据。 | | businessGroupId | 显式业务组。与 companyId 一起用于公司路由；共享库业务组可不传 companyId。 | | companyId | 公司 ID。和显式 businessGroupId 一起用于公司路由；没有业务组时，先与 bugContext / sql / 路径字符串的业务意图求交集，没有强意图就返回公司真实可选业务让用户选择。 | | cloudName、instanceName、dbName | 显式物理 Archery scope，优先级最高，只用于本次调用。 | | allowMultiScope | 只影响路由层是否返回多目标候选。普通 prepare 仍只支持一个物理目标。默认不允许。 |

服务会用 sessionId、规范化后的 workspaceRoot 和最近模块根目录计算 bindingDomainId。同一个用户在不同仓库、不同模块或不同会话中的绑定不会互相覆盖。没有 workspaceRoot 时，只能创建 session 本地的手动域，后续复用需要显式 bind 或 switch。

业务组注册表和 companyId 路由

业务组来自显式注册表，不从测试、表名或单个样例 SQL 猜测。注册表为每个业务组维护：

• businessGroupId 和显示名称。
• 路由模式：shared-db、company-db、schema-map 或 hybrid。
• Archery cloudName、instanceName，以及可选默认 dbName。
• 可识别的数据源别名、数据库名模式、schema 名模式。
• 支持的业务类型，以及可选公司 schema 映射键或公司库命名模式。

路由模式含义：

| 模式 | 行为 | | --- | --- | | shared-db | 业务组固定到一个共享数据库，通常不需要 companyId。 | | company-db | companyId 参与数据库名解析。 | | schema-map | 先解析公司位置，再从公司映射中选择业务 schema。 | | hybrid | 可能同时涉及共享库和公司映射。若得到多个物理目标，默认返回 ambiguous；设置 allowMultiScope 只允许路由层返回多目标候选，不表示普通 prepare 可以执行多目标查询。 |

archery_query_readonly 是推荐的 AI 查询入口：优先传 companyId、bugContext、sql、maxRows 和必要的工作区上下文。它在内部复用 prepare/execute；普通低风险只读查询会直接执行，需要确认时只返回 prepared query 和下一步指引。archery_prepare_query 保留给需要先审阅 SQL、显式分阶段执行或兼容旧客户端的场景。

自动选择规则：

• 显式 businessGroupId 且公司路由能得到唯一物理目标：允许 prepare。company-db 业务通过公司库命名规则解析；schema-map 业务必须存在于 availableBusinesses 且具备 instanceName。
• 没有显式业务组，但 bugContext / sql 有唯一强业务意图且该业务存在并且 query-ready：允许 prepare。
• 杭州 company_schema_lookup 返回的 RDS ID / RDS 名称只作为实例匹配证据；服务会再用 user_all_instances 结果匹配真正的 Archery instanceName。如果匹配不到实例，该业务会以 queryReady: false 暴露给调用方，但不会自动 prepare。
• bugContext / sql 没有强业务意图时，不会扫描 workspace 配置兜底；有 companyId 时返回公司真实可选业务，让用户选择 businessGroupId。
• activeFilePath、activeModuleRoot、nearestModuleRoot 只作为 codeContext 文本证据；不希望路径启发式时不要传这些字段。
• 多个候选、弱证据或没有业务意图：返回 needs_user_input，并给出 availableBusinesses / candidates。
• 业务意图明确但公司没有该业务库：返回 business_not_available。
• 公司云、实例或映射不确定：返回 needs_user_input，不会 fuzzy 绑定实例。

旧的 archery_resolve_company_location 仍可单独根据 companyId 查看公司品牌、云和业务 schema 映射。archery_resolve_scope、archery_bind_business_group 和 archery_switch_business_group 保留用于人工预检和显式绑定，但 AI 默认不需要先调用它们来猜 scope。

绑定、切换、查看和清除

常用用户流程：

1. 调用 archery_resolve_scope 查看当前上下文能解析到什么。该工具不修改绑定。
2. 若返回唯一可信业务组，或用户已知道业务组，调用 archery_bind_business_group 绑定当前 bindingDomainId。
3. 如果要切换到另一个业务组，调用 archery_switch_business_group。切换只影响当前绑定域。
4. 调用 archery_show_scope 查看当前持久绑定和临时覆盖。
5. 调用 archery_clear_scope 清除当前绑定域的持久绑定和临时覆盖。
6. 需要一次性跨业务查询时，调用 archery_set_temporary_scope 设置临时覆盖。

archery_bind_business_group 和 archery_switch_business_group 会根据 businessGroupId 和可选 companyId 路由到物理 scope，然后把结果绑定到当前域。共享库业务组可以只传 businessGroupId；公司库、schema 映射和混合业务通常需要同时传 companyId。

临时覆盖

archery_set_temporary_scope 可设置一次性或限时覆盖，适合临时跨业务、临时跨公司或手动指定物理库的查询。参数可以是：

• businessGroupId，可选 companyId。
• 或显式 cloudName、instanceName、dbName。
• mode: one_query 或 time_boxed。
• expiresInSeconds: time_boxed 时的有效秒数，未传时使用默认有效期。

临时覆盖优先于 session 绑定，但低于本次调用显式传入的物理 scope 或业务组路由。one_query 覆盖在一次安全查询解析后消费，过期覆盖不会继续生效，也不会变成默认绑定。

工作区上下文

workspaceRoot、activeFilePath 和 activeModuleRoot 仍可传给工具，用于隔离不同会话、仓库和模块的绑定域。普通查询和 archery_resolve_scope 不会因为传入 workspaceRoot 就扫描本地配置文件，也不会用本地 datasource 配置自动选择线上业务组。

路径字段的使用边界：

• workspaceRoot 参与 bindingDomainId 计算，避免一个 session 在不同项目或模块间复用错误绑定。
• activeFilePath、activeModuleRoot、nearestModuleRoot 可作为轻量 codeContext 文本证据，例如路径中包含 attendance 或 payroll。
• 路径证据只用于业务组意图打分，不会生成 dbName 或 instanceName。
• 无法从用户问题、SQL 或路径字符串得到唯一强业务意图时，系统会直接返回 needs_user_input / missing_scope，让用户选择业务组或显式物理 scope。

安全查询解析

archery_query_readonly、archery_prepare_query、archery_describe_table 和 archery_query_history 都会先解析安全物理 scope，再访问 Archery。以下情况会在访问 Archery 前拒绝：

• scope 缺失。
• 当前 session 绑定属于另一个 bindingDomainId。
• 业务组不支持或公司路由缺少必要数据。
• 混合路由得到多个目标且本次调用没有设置 allowMultiScope。
• 混合路由得到多个目标且本次调用设置了 allowMultiScope：普通 prepare 仍会返回 multi_target_execution_unsupported。

archery_execute_query 不会重新检测工作区，也不会改写 scope。它只执行 prepare 阶段已经捕获的物理 scope。

普通 prepare 当前只捕获并执行一个物理 Archery 目标。多目标 hybrid 查询的 fan-out、结果合并、确认 token 和失败语义尚未定义，因此故意不支持可执行的多目标 prepare；在显式 fan-out 语义实现前，allowMultiScope 仅用于路由层发现候选。

当系统能给出候选但不能安全选择时，会返回候选列表和 rejected 或 ambiguous 状态，用户应调用 archery_bind_business_group、archery_switch_business_group 或 archery_set_temporary_scope 明确选择后再查询。

查询前必须得到 query-ready scope：cloudName + instanceName + dbName。该 scope 只能来自安全解析结果，或来自用户明确输入的完整物理 scope。客户端不应从代码、JDBC URL、DataGrip、表名或历史样例中猜测 Archery instanceName / dbName。

查询策略配置

可以通过环境变量调整查询策略：

| 环境变量 | 默认值 | 说明 | | --- | --- | --- | | ARCHERY_QUERY_DEFAULT_LIMIT | 100 | 未传 limitNum 或传入小于等于 0 时使用的默认 LIMIT | | ARCHERY_QUERY_MAX_LIMIT | 500 | 最大允许 LIMIT | | ARCHERY_QUERY_REQUIRE_CONFIRMATION | true | staged execute 是否强制提供确认 token，保留旧客户端默认安全语义 | | ARCHERY_QUERY_AUTO_EXECUTE_LOW_RISK | true | archery_query_readonly 是否在当前调用内自动执行低风险只读查询 | | ARCHERY_QUERY_ALLOWED_INSTANCES | 空 | 逗号分隔的实例白名单，空表示不限制 | | ARCHERY_QUERY_ALLOWED_DATABASES | 空 | 逗号分隔的数据库白名单，空表示不限制 | | ARCHERY_QUERY_BLOCKED_TABLES | 空 | 逗号分隔的禁止访问表名或限定表名，按 SQL identifier 精确匹配 | | ARCHERY_MCP_HTTP_API_KEY | 空 | HTTP /mcp Bearer token，空表示不启用内置 HTTP 鉴权 |

示例：

export ARCHERY_QUERY_DEFAULT_LIMIT=50
export ARCHERY_QUERY_MAX_LIMIT=200
export ARCHERY_QUERY_REQUIRE_CONFIRMATION=true
export ARCHERY_QUERY_AUTO_EXECUTE_LOW_RISK=true

MCP 工具

除 archery_execute_query 外，查询和 scope 工具都可携带 ScopeRequestContext 字段，例如 workspaceRoot、activeFilePath、activeModuleRoot、businessGroupId、companyId 和 allowMultiScope。sessionId / userSubject 仅用于无 transport 的兼容调用；HTTP/stdio 下始终以 MCP transport session 和服务端认证用户为准。普通查询工具也继续接受显式 cloudName、instanceName、dbName，用于本次调用的最高优先级物理 scope。

archery_query_readonly

日常 AI 查数主入口。输入 companyId、bugContext、sql 和可选的统一 maxRows，内部完整复用 scope 解析、SQL policy、LIMIT、prepare store 和 execute；省略 maxRows 时使用 ARCHERY_QUERY_DEFAULT_LIMIT。

• riskLevel=low 且启用 ARCHERY_QUERY_AUTO_EXECUTE_LOW_RISK 时，在一次工具调用内执行，顶层直接返回 status、rows、columns、durationMs 等执行结果。
• 查询被阻止或 scope 不明确时，返回与 prepare 相同的结构化错误。
• 查询为 medium risk、关闭自动执行或需要确认时不执行，保留 prepareId 并返回 nextAction: "archery_execute_query"。
• 直接执行完成后清理内部 prepared query，避免长期积累。

archery_prepare_query

先解析安全物理 scope，再校验只读 SQL，补齐 LIMIT，计算 SQL hash，并返回 prepareId 和确认 token 提示。

成功时返回 status: "ok"，并包含：

• prepareId
• normalizedSql
• riskLevel
• requiresConfirmation
• policyFindings
• confirmationToken
• sqlHash
• scope: 本次 prepare 捕获的 query-ready scope，包含 cloudName、instanceName、dbName
• businessGroupId: 通过 TargetResolver 自动解析时返回的业务组
• target: 通过 TargetResolver 自动解析时返回的 query-ready scope
• evidence: 自动解析证据，例如用户文本命中的业务词和 availableBusinesses 中的真实库名
• confirmationSummary

companyId + 业务意图自动解析成功示例：

{
  "status": "ok",
  "businessGroupId": "attendance",
  "target": {
    "cloudName": "beijing",
    "instanceName": "schysc_四川宏远上城超市有限公司",
    "dbName": "schysc_attendance_amazon"
  },
  "evidence": [
    { "source": "userText", "value": "考勤", "confidence": 0.9 },
    { "source": "availableBusiness", "value": "schysc_attendance_amazon", "confidence": 1 }
  ],
  "confirmationToken": "CONFIRM:..."
}

如果 scope 解析失败，archery_prepare_query 不会访问 Archery，也不会抛出传输层错误；它会返回 status: "needs_user_input"、prepareId: null、requiresConfirmation: false 和结构化 scopeError：

{
  "code": "missing_schema_mapping",
  "message": "...",
  "known": { "companyId": "...", "businessGroupId": "..." },
  "missing": ["cloudName", "instanceName", "dbName"],
  "availableBusinesses": [
    { "businessGroupId": "attendance", "dbName": "schysc_attendance_amazon" },
    {
      "businessGroupId": "workflow",
      "dbName": "prod_workflow_region1023",
      "source": "company_schema_lookup",
      "rdsId": "rm-bp11266408d5u32i7",
      "rdsName": "考勤新分区库-4",
      "queryReady": false,
      "missing": ["instanceName"]
    },
    { "businessGroupId": "payroll", "dbName": "schysc_payroll_amazon" }
  ],
  "candidates": [
    { "businessGroupId": "attendance", "confidence": 0.9 }
  ],
  "nextAction": "ask_user",
  "userPrompt": "请提供查询所需的 cloudName / instanceName / dbName，不要从代码、JDBC 或 DataGrip 猜测 Archery scope。"
}

调用方应把 scopeError.userPrompt 或等价问题展示给用户。缺少完整物理 scope 时，missing 只列出未提供的物理字段；公司/业务组路由能列出真实业务库但不能安全自动选择时，missing 会要求 businessGroupId 并返回 availableBusinesses。不要从候选外生成 dbName。

常见参数：

• bugContext
• sessionId
• workspaceRoot
• activeFilePath
• activeModuleRoot
• businessGroupId
• companyId
• allowMultiScope
• cloudName
• instanceName
• dbName
• sql
• limitNum

archery_execute_query

执行已 prepare 的查询。中风险查询或启用全局强制确认时需要传入 confirmationToken。

常见参数：

• prepareId
• confirmationToken
• maxRows

archery_describe_table

先解析安全物理 scope，再通过 Archery 读取表结构元数据。

常见参数：

• sessionId
• workspaceRoot
• activeFilePath
• activeModuleRoot
• businessGroupId
• companyId
• cloudName
• instanceName
• dbName
• schemaName
• tableName

archery_query_history

先解析安全物理 scope，再搜索 Archery 查询历史摘要，不返回历史结果数据。

常见参数：

• search
• sessionId
• workspaceRoot
• activeFilePath
• activeModuleRoot
• businessGroupId
• companyId
• cloudName
• instanceName
• dbName
• limit

archery_resolve_scope

解析当前 scope 状态或显式业务组/company 路由，不修改持久绑定。适合在出现 scope 拒绝时查看已有绑定、预演显式业务组路由，或在只有 companyId 时获取公司真实可选业务。传入 businessGroupId 时，它会预演与 archery_prepare_query 相同的业务组/company 路由路径，避免预检结果和实际 prepare 不一致。

常见参数：

• sessionId
• workspaceRoot
• activeFilePath
• activeModuleRoot
• businessGroupId
• companyId

可能返回：

• resolved: 已有显式、临时或 session scope 可用。
• rejected: 存在过期、跨域或不安全状态。
• needs_user_input: 已知上下文不足，返回 scopeError，调用方应询问用户补齐字段。

archery_bind_business_group

把当前 bindingDomainId 绑定到一个业务组路由。绑定成功后，同一 session 和工作区模块内的普通查询可以复用该 scope。

常见参数：

• businessGroupId
• companyId
• sessionId
• workspaceRoot
• activeFilePath
• activeModuleRoot

archery_switch_business_group

把当前 bindingDomainId 切换到另一个业务组路由。它和 bind 一样显式写入当前域，但语义上用于用户主动切换。

常见参数：

• businessGroupId
• companyId
• sessionId
• workspaceRoot
• activeFilePath
• activeModuleRoot

archery_show_scope

查看当前 bindingDomainId 下的 session 绑定和临时覆盖。

常见参数：

• sessionId
• workspaceRoot
• activeFilePath
• activeModuleRoot

archery_clear_scope

清除当前 bindingDomainId 下的 session 绑定和临时覆盖，并让下一次查询重新解析 scope。

常见参数：

• sessionId
• workspaceRoot
• activeFilePath
• activeModuleRoot

archery_set_temporary_scope

设置一次性或限时临时覆盖。适合用户明确知道本次要跨业务或跨公司查询，但不希望改写默认绑定。

常见参数：

• businessGroupId
• companyId
• cloudName
• instanceName
• dbName
• mode
• expiresInSeconds
• sessionId
• workspaceRoot
• activeFilePath
• activeModuleRoot

archery_resolve_company_location

根据 auth center 的 companyId 解析公司品牌、Archery 云和业务库映射。

常见参数：

• companyId

返回示例：

{
  "status": "ok",
  "companyId": "...",
  "brand": "prod",
  "cloudName": "hangzhou",
  "mappings": [
    {
      "businessType": "kpi",
      "schemaName": "prod_kpi_region1017",
      "isValid": true
    }
  ],
  "message": "Company cloud and schema mappings resolved"
}

archery_runtime_diagnostics

查看 MCP 进程实际看到的运行环境，适合排查 macOS GUI 启动后 PATH 或环境变量不一致的问题。该工具不会返回账号或密码原文，只返回 present: true/false；路径字段会把当前用户 home 目录显示为 ~。

常见返回字段：

• status: ok 或 warning，聚合所有 checks
• runtime.nodeVersion
• runtime.platform
• runtime.argvEntry
• environment.MCP_ARCHERY_LOGIN_USERNAME.present
• environment.MCP_ARCHERY_LOGIN_PASSWORD.present

推荐查询流程

1. 日常 AI 查询优先直接调用 archery_query_readonly，传入 companyId、bugContext、sql、maxRows；可传 activeFilePath / activeModuleRoot 作为轻量路径证据。
2. 如果返回 needs_user_input 且包含 availableBusinesses，让用户选择 businessGroupId，不要从 workspace 配置猜测。
3. 如果要建立当前会话的默认业务域，调用 archery_bind_business_group 绑定用户确认的业务组。若系统返回多个候选，先让用户选择，再 bind 或 switch。
4. 如果只是临时跨业务或跨公司查询，调用 archery_set_temporary_scope，不要改写默认绑定。
5. archery_query_readonly 和 archery_prepare_query 都可以在本次调用中直接传完整的 cloudName、instanceName、dbName，或传 businessGroupId 和 companyId。
6. 检查返回的 normalizedSql、riskLevel、policyFindings。若顶层包含 executionId，则查询已经执行，顶层 status 是 Archery 执行状态。
7. 如果返回 status: "needs_user_input"，按 scopeError.missing / scopeError.userPrompt 询问用户补齐，不要猜测 Archery scope。
8. 如返回 nextAction: "archery_execute_query"，由用户审阅 SQL 后再使用确认 token。
9. 调用 archery_execute_query 并传入确认 token。
10. 查看 columns、rows、rowCount、effectiveMaxRows、truncated、durationMs、archeryMessage。

truncated 表示返回行数达到本次执行上限，语义是“可能还有更多行”。普通字段内容不会默认截断。

CLI 参数

--transport <transport>       stdio 或 http，默认 stdio
--host <host>                 HTTP 监听地址，默认 127.0.0.1
--port <port>                 HTTP 端口，默认 8080
--archery-auth-mode <mode>    simulated-login 或 personal-session
--archery-client-mode <mode>  http-query 或 stub
--query-path <path>           Archery 查询接口路径，默认 /query/
--user <subject>              MCP 用户标识

常见问题

找不到 archery-query-mcp 命令

确认已全局安装，并且 npm 全局 bin 目录在 PATH 中：

npm install -g @dezhouzhang/archery-query-mcp
command -v archery-query-mcp
archery-query-mcp --help

macOS GUI 应用可能不继承终端里的 PATH。如果 OpenCode / Codex 从桌面启动后找不到命令，请在 MCP 配置里使用 command -v archery-query-mcp 输出的绝对路径，或改用上面的 npm exec 配置。

OpenCode / Codex 配置后不生效

修改 MCP 配置后需要重启 OpenCode / Codex。stdio MCP 是由客户端启动的子进程，旧进程不会自动读取新配置。

凭证未生效

确认启动客户端的进程能读取到：

MCP_ARCHERY_LOGIN_USERNAME
MCP_ARCHERY_LOGIN_PASSWORD

Windows 使用 setx 后，需要重新打开终端或重启客户端。

华为云登录失败

huawei 当前是 HTTP URL，但 npm 版已允许 simulated-login 直接走该地址；请确保只在可信内网或可信网关后使用。

维护者发布流程

发布前检查：

npm test
npm run typecheck
npm run build
npx biome check .
npm publish --dry-run --access public

发布：

npm publish --access public

如果版本已发布，需要先更新 package.json 中的 version。