Metadata-Version: 2.5
Name: k-box-connectors
Version: 1.1.0
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，统一使用非结构化知识检索和结构化
数据洞察能力。适配层不复制查询编排逻辑。

> 设计基线：`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` | 通过完整数据洞察工作流查询企业结构化数据，支持请求内多轮上下文和澄清回答 |

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

```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 ...`，无需安装全局命令。

首次使用执行交互式配置和验证：

```bash
kbox config init
kbox auth status
kbox doctor
```

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

```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 的租户"
```

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

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

## 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 为例：

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