面向 AI Agent 的 OpenAPI 文档知识库与混合检索服务。
Tool Index 把多个系统中分散的 OpenAPI 文档整理成一个统一的 API 知识库。AI Agent 不需要一次加载全部工具定义，只需要先搜索，再按需取得目标 API 的完整文档。
你提供 OpenAPI 文档源，Tool Index 负责采集、结构化、建立索引并提供检索接口；Agent 负责搜索 API、阅读完整文档，并在确认参数后调用真实业务系统。
OpenAPI 文档 → Tool Index 建立知识库 → Agent 搜索并获取 API 文档 → Agent 调用业务 API
Tool Index 的职责到“发现 API 和返回文档”为止，不会代替 Agent 执行业务 API。
一次完整使用通常分为两个阶段：
- 建立索引：Tool Index 从一个或多个 OpenAPI 文档源拉取数据，统一整理 API 名称、路径、参数、请求体、响应、示例等信息，并写入 SQLite 知识库。
- Agent 检索：Agent 通过 MCP 或 HTTP 提交自然语言问题，先用
search_tools找到候选 API 和证据片段，再用get_api_doc获取选中 API 的完整结构化文档。
例如，当用户提出“查询某个用户最近 30 天的订单”时：
- Agent 调用
search_tools搜索与用户订单相关的 API。 - Tool Index 综合向量检索和 BM25，返回最相关的候选 API。
- Agent 调用
get_api_doc获取目标 API 的路径、参数、鉴权和响应结构。 - Agent 根据文档调用真实订单系统；这一步不经过 Tool Index。
当 Agent 可使用的 API 从几十个增长到几百甚至几千个时，把全部工具定义直接塞进上下文会带来明显问题：
- 上下文快速膨胀，推理成本增加。
- 相似 API 难以区分，工具选择准确率下降。
- API 文档更新后，客户端配置容易失效。
- 多个系统的接口文档缺少统一发现入口。
Tool Index 把“预先加载所有工具”转换为“按需检索工具”：
用户意图 → 搜索候选 API → 获取完整文档 → Agent 调用真实 API
- 多知识库管理：通过一个 TOML 文件管理多个具名 OpenAPI 文档源。
- 结构化索引：提取 operation、请求、响应、示例和层级元数据。
- 混合检索：融合文档向量、可选章节向量和 SQLite FTS5 BM25。
- 跨库全局排序：候选在统一空间内融合，Query Embedding 只计算一次。
- 证据片段：返回命中的文档章节，便于 Agent 判断相关性。
- 完整文档回查：通过 operation_id 获取结构化 API 文档。
- MCP 与 HTTP：支持 MCP stdio、MCP Streamable HTTP 和 REST。
- 异步索引重建：按单个知识库或全部知识库触发重建并查询状态。
- 本地优先存储：使用 SQLite 保存文档、向量和全文索引。
架构图中的两条链路分别对应：
- 索引构建链路：OpenAPI 文档源 → 采集与标准化 → 结构化索引 → SQLite 知识库。
- Agent 检索链路：用户意图 → MCP / HTTP → 混合检索 → 候选 API 与证据 → 完整 API 文档。
更完整的组件边界、异常路径和 Mermaid 源码见 架构文档。
-
Python 3.12
-
git clone https://github.com/fei121/tool_index.git cd tool_index uv sync cp .env.example .env
编辑 tool-index.toml。当前文档源协议是：向配置的 URL 发送 JSON POST 请求，并接收 OpenAPI JSON 对象。
[storage]
db_path = ".runtime/tool_index/tools.db"
[service]
require_writer_auth = true
[retrieval]
default_scope = "global"
[knowledge_bases.example_api]
name = "Example API"
url = "https://your-api-doc-service.example.com/openapi/export"
extractor = "standard"
body = { type = "openapi", version = "3.0" }
知识库 key 必须使用小写字母、数字和下划线，并以字母开头。
默认示例使用本地 Embedding。首次运行会下载模型：
TOOL_INDEX_EMBED_BACKEND=local
TOOL_INDEX_EMBED_MODEL=BAAI/bge-base-zh-v1.5
TOOL_INDEX_EMBED_DIM=768
TOOL_INDEX_SERVICE_ROLE=writer
TOOL_INDEX_AUTH_TOKEN=replace-with-a-strong-token
使用 OpenAI-compatible Embedding 服务时：
TOOL_INDEX_EMBED_BACKEND=openai_compatible
TOOL_INDEX_EMBED_API_BASE_URL=http://127.0.0.1:8001
TOOL_INDEX_EMBED_API_KEY=your-api-key
TOOL_INDEX_EMBED_API_MODEL=your-embedding-model
TOOL_INDEX_EMBED_DIM=1024
模型实际输出维度必须与 TOOL_INDEX_EMBED_DIM 一致。
scripts/tool-index start --entry http-service
触发异步重建：
curl -X POST "http://127.0.0.1:8090/v1/index/rebuild?knowledge_base=example_api" \
-H "Authorization: Bearer replace-with-a-strong-token"
接口返回 job_id 后查询状态：
curl "http://127.0.0.1:8090/v1/jobs/<job_id>" \
-H "Authorization: Bearer replace-with-a-strong-token"
curl -X POST "http://127.0.0.1:8090/v1/search/tools" \
-H "Content-Type: application/json" \
-d '{"query":"查询用户订单","top_k":5}'
指定知识库时，在请求体中增加：
"knowledge_base": "example_api"
客户端配置示例：
{
"mcpServers": {
"tool-index": {
"command": "/absolute/path/to/tool_index/scripts/tool-index",
"args": ["--entry", "mcp-stdio"]
}
}
}
scripts/tool-index start --entry mcp-streamable-http
MCP 地址：
http://127.0.0.1:8090/mcp
| 工具 | 作用 | 权限 |
|---|---|---|
| list_knowledge_bases | 列出可用知识库 | 读取 |
| search_tools | 根据自然语言搜索 API | 读取 |
| get_api_doc | 按 operation_id 获取完整文档 | 读取 |
| index_rebuild | 异步重建单库或全部索引 | Writer |
| get_job | 查询异步任务状态 | Writer |
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /v1/health | 存活检查 |
| GET | /v1/ready | 就绪状态与服务角色 |
| POST | /v1/search/tools | 搜索 API |
| GET | /v1/api-docs/{operation_id} | 获取完整 API 文档 |
| POST | /v1/index/rebuild | 触发异步索引重建 |
| GET | /v1/jobs/{job_id} | 查询重建任务 |
完整 HTTP 契约位于 OpenAPI 文件。
默认启用两条路线：
- Route B — 文档向量：先召回 operation 文档；可选章节二次排序。
- Route C — BM25：利用 API 名称、参数和描述中的精确关键词。
Route A 章节向量可通过环境变量启用。多个活跃路线通过加权 RRF 融合；全局搜索会先汇总所有知识库候选，再生成统一 Top K。
TOOL_INDEX_ENABLE_ROUTE_A=false
TOOL_INDEX_ENABLE_ROUTE_B=true
TOOL_INDEX_ENABLE_ROUTE_B_SECTION_RERANK=false
TOOL_INDEX_ENABLE_ROUTE_C=true
TOOL_INDEX_INCLUDE_DEBUG=false
uv run --project apps/python pytest -q
bash scripts/ci/check_contracts.sh
bash -n scripts/tool-index
贡献前请阅读 CONTRIBUTING.md。
- OpenAPI 文档源目前需要支持 JSON POST 请求。
- 异步任务状态保存在进程内存中，服务重启后不会保留。
- SQLite 适合单机和中等规模知识库；大规模部署需要替换存储适配器。
- Tool Index 负责发现与文档回查，不直接执行检索到的业务 API。
- 支持 OpenAPI GET URL 与本地文件。
- 增量索引与文档变更检测。
- 可持久化任务队列。
- 检索评测集与 Recall@K / MRR 报告。
- 更多存储与向量数据库适配器。
Writer 接口默认要求 Bearer Token。不要将真实密钥提交到仓库；安全问题请按照 SECURITY.md 私下报告。
本项目采用 Apache License 2.0。