k-box-connectors — K-Box Agent 接入适配器

面向 Agent 平台和终端用户的接入适配器。当前提供无状态 MCP 服务和 kbox CLI， 把调用方的 Bearer API Key 原样透传给 K-Box，MCP 服务提供非结构化知识检索； 结构化数据洞察通过 CLI 与独立 Skill 使用。

设计基线：k-box-docs/TECH_SPEC_MCP_KNOWLEDGE_SUPPLIER.md（v2 透传包装器版）。

特性

• MCP 零密钥托管：MCP 服务不落盘、不存储、不解析 API Key，仅同请求内透传；
• CLI 本地配置：交互配置将服务地址和 API Key 分文件保存，目录权限 0700、 凭证文件权限 0600；环境变量可以无状态覆盖本地配置；
• 连接期预检：首次出现的 Key 调 GET /tenant/kb/whoami 校验并缓存（TTL 可配）， 无效 Key 在 MCP 握手阶段即被拒绝；
• 多租户天然支持：身份即 Key，k-box-api 侧按 Key 注入租户上下文并校验端点归属；
• 按需部署：无数据库/中间件依赖，只需网络可达 K-Box API。

工具清单

工具	说明
list_endpoints	发现当前 Key 可用的检索端点（原样返回），不知道 endpoint_code 时先调用
search_knowledge	知识分段检索，支持接口全部参数（searchMode/scoreThreshold/unionId/docIds/tags/tagStrict），响应含 chunks/graphs 完整字段
get_chunk_context	扩展某个检索分段的前后上下文（window ≤ 10，无需端点编码）
search_documents	按文件名发现文档（limit ≤ 20，原样返回）
get_doc_detail	获取文档基础信息与访问链接（docLink 预签名 60 分钟有效，sourceLink 外部源链接）

快速开始（本地开发）

cp .env.example .env        # 可选：配置 KBOX_API_BASE_URL 等（缺省指向 localhost:8080）
./start.sh                  # 后台启动（幂等：自动停旧进程），日志在 logs/server.log
./start.sh --foreground     # 前台启动（Ctrl+C 退出）
./start.sh --port 9000 \
  --base-url http://192.168.1.10:8080/api \
  --app-base-url http://192.168.1.10:8091/kbapp/api

或手动启动：

uv sync --all-groups
uv run python -m kbox_connectors.server

服务监听 0.0.0.0:8082，MCP 端点 /mcp（Streamable HTTP，stateless），健康检查 /health。

测试

uv run pytest -q                    # 单元测试（mock httpx，无外部依赖）
uv run python scripts/smoke_local.py  # 冒烟（内置假 k-box-api，全协议链路）

CLI

CLI 直接调用 K-Box 应用能力 API，不经过 MCP 服务。正式版本从公共 PyPI 安装：

uv tool install --force k-box-connectors
kbox --version

仓库开发环境可直接使用 uv run kbox ...，无需安装全局命令。

首次使用推荐通过浏览器登录。--server 是 K-Box 对外入口，支持域名或公网可访问的 IP:端口；CLI 默认从同一入口访问 /api 和 /kbapp/api：

kbox auth login --server https://kbox.example.com
kbox auth status
kbox doctor

例如测试环境可以使用：

kbox auth login --server http://203.0.113.10:32120

浏览器登录后选择当前账号已有的 Bearer API Key。Key 通过 Redis 短时一次性授权请求 直接交给等待中的 CLI，不进入浏览器 URL；CLI 将凭证以 0600 权限保存。Skill 需要 从 K-BOX 应用列表下载后手动安装。公网生产环境应使用 HTTPS。

拆分部署时，可单独指定应用能力 API：

kbox auth login \
  --server https://console.kbox.example.com \
  --base-url https://agent-api.kbox.example.com/kbapp/api

保留手工配置作为无人值守环境的后备方式：

kbox config init

也可以完全使用环境变量，不在本地保存凭证：

export KBOX_API_KEY=sk-xxx
export KBOX_APP_API_BASE_URL=http://localhost:8091/kbapp/api

发现当前 Key 可以访问的数据洞察应用：

uv run kbox insight apps
uv run kbox insight apps --json

执行查询时默认使用 SSE：执行进度写入 stderr，回答增量写入 stdout。

uv run kbox insight query --app etjpssdc "分段数量 TOP10 的租户"

检索端点 Skill 使用最小的同步检索命令，端点自身已保存知识库范围和检索配置：

uv run kbox kb search --base-url https://kbox.example.com/api \
  --endpoint abcd1234 "公司的差旅报销标准"
uv run kbox kb search --base-url https://kbox.example.com/api \
  --endpoint abcd1234 --json "公司的差旅报销标准"

--json 适合 Agent 和自动化程序，输出端点检索接口返回的 data 对象；普通模式展示 命中片段、相关度和来源链接。知识检索使用管理 API 的 /api 地址，不要传入数据洞察的 /kbapp/api 地址；从检索端点页面下载的 Skill 已包含正确参数。

Agent、脚本和自动化应使用 --json。该模式关闭流式展示，stdout 只输出一个 kbox.data-insight.result/v1 JSON 对象：

uv run kbox insight query --app etjpssdc \
  "分段数量 TOP10 的租户" --json

也可从标准输入读取长问题，并用重复参数补充澄清信息：

cat question.txt | uv run kbox insight query --app etjpssdc - \
  --clarification time_range=2025年

Agent Skill

在 K-BOX 应用列表中选择“下载成 Skill”，再将对应 ZIP 安装到目标 Agent 的 Skill 目录。应用编码为 etjpssdc 时，Skill 名称为 kbox-insight-etjpssdc。 凭证过期或更换后，可以重新执行授权：

kbox auth login --server https://kbox.example.com

CLI 也保留通用的 kbox-data-insight Skill。安装到 Codex 默认 Skill 目录：

kbox skills list
kbox skills install

安装到其他支持 Agent Skills 的平台：

kbox skills install --dir <agent-skills-directory>

Skill 已有文件默认跳过，升级时显式使用 --force。面向 Agent 的完整安装步骤位于 K-Box 在线文档 product-docs/integration/kbox-cli-installation-guide.md。部署文档站点后， 用户只需把该页面 URL 交给 Codex、WorkBuddy 等具备终端能力的 Agent。

Docker 部署

docker build -t kbox-connectors:latest .
docker run -d --name kbox-connectors \
  -p 8082:8082 \
  -e KBOX_API_BASE_URL=http://kbox-api:8080/api \
  -e KBOX_APP_API_BASE_URL=http://kbox-app-api:8000/kbapp/api \
  kbox-connectors:latest

手动发布 PyPI

发布前同时更新 pyproject.toml 与 kbox_connectors/__init__.py 中的版本号，并在本地 安全配置 UV_PUBLISH_TOKEN。构建和发布 wheel：

uv build --wheel
uv publish --check-url https://pypi.org/simple dist/*

PyPI 不允许覆盖同版本制品；代码发生变化后必须先提升版本号再发布。

也可以使用仓库内的快捷脚本。首次使用时将 PyPI Token 写入本地 .env 的 UV_PUBLISH_TOKEN，然后执行：

./publish.sh --dry-run
./publish.sh

脚本会自动构建 wheel 和 sdist，并使用 https://pypi.org/simple 检查重复版本。

Agent 平台接入

面向接入方的完整指南（前置准备、各客户端配置示例、错误码、安全须知）见 K-Box 在线文档： 管理后台「API 文档」页 → Open API → MCP 集成 → MCP 接入指南（product-docs/integration/mcp-integration.md）。

所有请求需携带 Authorization: Bearer sk-xxx（k-box 租户 API Key）。 该 Key 用于知识库检索端点。结构化数据洞察请安装对应的 Data Insight Skill，并通过 本机 kbox insight query 调用。

以 Agno 为例：

from agno.tools.mcp import MCPTools

tools = MCPTools(
    url="http://<kbox-connectors-host>:8082/mcp",
    transport="streamable-http",
    headers={"Authorization": "Bearer sk-xxx"},
)

安全约束

• 仅支持 Bearer 模式 Key（HMAC 签名模式不适用于 MCP 通道）；
• 默认部署形态为同内网 HTTP；暴露公网时必须前置 TLS；
• Key 吊销延迟上限 = WHOAMI_CACHE_TTL（默认 300 秒）。