Metadata-Version: 2.5
Name: k-box-connectors
Version: 1.3.1
Summary: K-Box Agent 接入适配器：MCP 与 CLI
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.12
Requires-Dist: fastmcp>=2.14
Requires-Dist: httpx>=0.27.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: uvicorn[standard]>=0.30.0
Description-Content-Type: text/markdown

# 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 外部源链接） |

## 快速开始（本地开发）

```bash
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
```

或手动启动：

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

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

## 测试

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

## CLI

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

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

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

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

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

例如测试环境可以使用：

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

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

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

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

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

```bash
kbox config init
```

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

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

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

```bash
uv run kbox insight apps
uv run kbox insight apps --json
```

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

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

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

```bash
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 对象：

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

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

```bash
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`。
凭证过期或更换后，可以重新执行授权：

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

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

```bash
kbox skills list
kbox skills install
```

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

```bash
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 部署

```bash
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：

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

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

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

```bash
./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 为例：

```python
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 秒）。
