百炼知识库 MCP（仅检索）

通过 stdio 调用阿里云百炼 OpenAPI Retrieve（2023-12-29）。文档上传、解析、建库请在百炼控制台完成；本 MCP 只负责对已就绪的知识库做运行时检索。

从 npm 用 npx 运行（发布后）

公共包名：bailian-knowledge-base-mcp。安装后提供可执行命令 bailian-knowledge-base-mcp。

• 仅用 mcpServers.env 配置时：args 为 ["-y", "bailian-knowledge-base-mcp"]（或 scoped 包名）即可，见下文 Cursor 方式 A。
• 用 --env-file 时（密钥不进 MCP JSON）：npx -y bailian-knowledge-base-mcp --env-file /绝对路径/你的.env（不要把 .env 打进 npm 包）。

npx -y bailian-knowledge-base-mcp --env-file /绝对路径/你的百炼.env

配置方式二选一（或混用）：

• mcpServers.env：与 .env 相同的键名写入即可，进程启动时已进 process.env，无需改代码。适合发布后 npx + 全量在 env 里配置（注意勿把含密钥的 JSON 提交到 Git）。
• --env-file / CLI 标志：见下文。若同时使用：已出现在 process.env 的键不会被 --env-file 覆盖；CLI 标志仍会覆盖对应键。

工具

| 名称 | 说明 | |------|------| | bailian_retrieve | 参数：query（必填）、index_id（可选，缺省读 BAILIAN_INDEX_ID）、dense_similarity_top_k、sparse_similarity_top_k、rerank_top_n、enable_reranking、enable_rewrite、rerank_min_score。返回 JSON：{ success, data, source, summary, error }，data.body 为百炼响应体（含切片 nodes 等）。 |

配置方式

1）推荐：--env-file（与 .env 键名一致）

启动参数里增加 --env-file 与 .env 的绝对路径（内容格式与 .env.example 相同：KEY=value，# 注释）。文件中每一行仅在 process.env 尚未设置该键 时写入，便于本机已 export 的变量优先生效。

随后仍可用下面 CLI 标志覆盖个别键。

2）CLI 标志（可选，覆盖对应环境变量）

| 参数 | 写入的环境变量 | |------|----------------| | --workspace-id / --workspace-id=… | WORKSPACE_ID | | --access-key-id | ALIBABA_CLOUD_ACCESS_KEY_ID | | --access-key-secret | ALIBABA_CLOUD_ACCESS_KEY_SECRET | | --bailian-index-id | BAILIAN_INDEX_ID | | --endpoint | BAILIAN_ENDPOINT | | --security-token | ALIBABA_CLOUD_SECURITY_TOKEN |

把密钥写在命令行会被 ps 等看到，优先用 --env-file；标志适合临时覆盖或 CI。

环境变量（与 .env 一致）

| 变量 | 必填 | 含义 | |------|------|------| | ALIBABA_CLOUD_ACCESS_KEY_ID | 是 | AccessKey Id | | ALIBABA_CLOUD_ACCESS_KEY_SECRET | 是 | AccessKey Secret | | WORKSPACE_ID | 是 | 百炼业务空间 ID | | BAILIAN_INDEX_ID | 建议默认检索场景 | 知识库 ID；也可每次在工具参数中传 index_id | | BAILIAN_ENDPOINT | 否 | 默认 bailian.cn-beijing.aliyuncs.com | | ALIBABA_CLOUD_SECURITY_TOKEN | 否 | STS 时使用 |

日志与诊断信息请打在 stderr，勿向 stdout 打印，以免破坏 MCP JSON-RPC。

本地构建

cd mcp/bailian-knowledge-base
npm ci
npm run build

开发：npm run dev -- --env-file ./.env（按需改路径）。

Cursor 配置示例

方式 A：npx + env（与 .env 键名一致，发布后常用）

Cursor 会把 env 注入子进程环境变量，与本仓库 .env / .env.example 的变量名一致 即可，不需要 --env-file，也不需要改 MCP 代码。

• 无 scope 包名与 npx 参数一致时：

{
  "mcpServers": {
    "bailian-knowledge-base": {
      "command": "npx",
      "args": ["-y", "bailian-knowledge-base-mcp"],
      "env": {
        "ALIBABA_CLOUD_ACCESS_KEY_ID": "你的AccessKeyId",
        "ALIBABA_CLOUD_ACCESS_KEY_SECRET": "你的AccessKeySecret",
        "WORKSPACE_ID": "你的业务空间ID",
        "BAILIAN_INDEX_ID": "你的知识库索引ID"
      }
    }
  }
}

• scoped 包（@组织名/bailian-knowledge-base-mcp）：args 里第二个字符串必须与 package.json 的 name 字段完全一致；发布 scoped 公开包需在 package.json 中配置 "publishConfig": { "access": "public" } 后执行 npm publish。

"args": ["-y", "@你的组织/bailian-knowledge-base-mcp"]

可选：在 env 中增加 BAILIAN_ENDPOINT、ALIBABA_CLOUD_SECURITY_TOKEN（STS），键名与 .env.example 相同。

方式 B：npx + --env-file（密钥不进 MCP JSON）

将 .env 路径 换成你本机绝对路径：

{
  "mcpServers": {
    "bailian-knowledge-base": {
      "command": "npx",
      "args": [
        "-y",
        "bailian-knowledge-base-mcp",
        "--env-file",
        "/Users/你的用户名/.config/bailian-mcp.env"
      ]
    }
  }
}

方式 C：克隆仓库本地 node

将路径换成本机 CyberCrew 仓库下的绝对路径：

{
  "mcpServers": {
    "bailian-knowledge-base": {
      "command": "node",
      "args": [
        "/Users/你的用户名/Alibaba/CyberCrew/mcp/bailian-knowledge-base/dist/index.js",
        "--env-file",
        "/Users/你的用户名/Alibaba/CyberCrew/mcp/bailian-knowledge-base/.env"
      ]
    }
  }
}

开发本包（未 build）可用 npx tsx 指向本仓库 src/index.ts（需在本目录 npm ci）：

{
  "mcpServers": {
    "bailian-knowledge-base": {
      "command": "npx",
      "args": [
        "tsx",
        "/Users/你的用户名/Alibaba/CyberCrew/mcp/bailian-knowledge-base/src/index.ts",
        "--env-file",
        "/Users/你的用户名/Alibaba/CyberCrew/mcp/bailian-knowledge-base/.env"
      ]
    }
  }
}

可在 args 末尾追加 CLI 标志覆盖 .env 中的单项，例如 "--endpoint", "bailian.cn-hangzhou.aliyuncs.com"。

发布到 npm（维护者）

在 mcp/bailian-knowledge-base 目录：

1. 注册/登录 npm：npm login（或使用 access token / npm whoami 确认已登录）。
2. 若使用 scoped 包名（如 @你的组织/bailian-knowledge-base-mcp），将 package.json 的 name 改为与 npx 参数一致；本仓库已含 publishConfig.access: public，发布公开 scoped 包时一般执行 npm publish 即可（无 scope 时亦可 npm publish --access public）。
3. 更新 package.json 的 version（semver，如 1.0.1）。
4. 执行：

npm publish

prepublishOnly 会在发布前自动执行 npm run build，打进的文件由 files 字段限定（dist、README.md、LICENSE），不会包含本机 .env。

校验 tarball（不实际上传）：

npm publish --dry-run

与本地 wuying-docs MCP 的关系

mcp/wuying-docs 为离线 PDF + MiniSearch；本服务为云端百炼检索，环境变量相互独立，可按合规与成本选择其一或并存。