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

面向 Agent 平台和终端用户的接入适配器。当前提供无状态 MCP 服务和 kbox CLI， 把调用方的 Bearer API Key 原样透传给 K-Box，统一使用非结构化知识检索和结构化 数据洞察能力。适配层不复制查询编排逻辑。

设计基线：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 与应用能力服务。
• 完整数据洞察：调用应用侧统一工作流完成语义召回、SQL 生成校验、执行和回答， Agent 不需要也不能直接选择数据主题、模型凭据或数据源。

工具清单

工具	说明
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 外部源链接）
list_data_insight_apps	发现当前 Key 绑定的数据洞察应用，不知道 app_code 时先调用
query_data_insight	通过完整数据洞察工作流查询企业结构化数据，支持请求内多轮上下文和澄清回答

快速开始（本地开发）

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 权限保存，并为该 Key 可访问的每个数据洞察应用生成一个独立 Skill。公网生产环境应使用 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 的租户"

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

浏览器登录会根据当前 API Key 可访问的应用生成独立 Skill，例如 kbox-insight-etjpssdc。应用授权变化后可以重新同步：

kbox skills sync

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 不允许覆盖同版本制品；代码发生变化后必须先提升版本号再发布。

Agent 平台接入

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

所有请求需携带 Authorization: Bearer sk-xxx（k-box 租户 API Key）。 该 Key 还必须绑定目标数据洞察应用；调用方通过 list_data_insight_apps 获取可用的 app_code，再调用 query_data_insight。多轮追问可携带最近的成功问答作为 conversation，第一阶段不在 MCP 服务内保存会话。

query_data_insight 返回具备明确 outputSchema 的 kbox.data-insight.result/v1 结构。Agent 应优先使用 answer，按需展示 data.rows，并把 presentation 作为展示建议。完整 Trace、候选表和治理上下文不会 进入 MCP 结果，避免占用 Agent 上下文或泄露内部诊断信息。

以 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 秒）。