Metadata-Version: 2.4
Name: canpoint-knowledge-mcp
Version: 0.1.8
Summary: 业务项目知识库 MCP：AI 可检索项目文档大纲、混合搜索、阅读正文与章节、跳转引用关系，并在项目发布后把最新文档同步进知识库。
Author: 若清风
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/mjwyr/canpoint-mcp
Project-URL: Repository, https://github.com/mjwyr/canpoint-mcp.git
Project-URL: Issues, https://github.com/mjwyr/canpoint-mcp/issues
Keywords: mcp,model-context-protocol,knowledge-base,rag,search
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp<2,>=1.6.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic-settings>=2.5.0
Dynamic: license-file

# canpoint-knowledge-mcp

面向业务项目的知识库 MCP。安装后，AI 助手可以直接检索和阅读你项目的知识库
文档：查大纲、混合检索、读全文与章节、沿文档引用关系跳转；项目发布后，
还能一键把最新的 `docs/` 同步进知识库。

## 能做什么

**查询 MCP**（只读，绑定一个项目）：

| 工具 | 能力 |
| --- | --- |
| `get_outline` | 查看项目知识库的文档大纲（可按版本/分组过滤） |
| `search` | 在项目范围内混合检索，命中结果带标题路径、父章节与行号 |
| `get_document` | 按文档路径读取全文 |
| `get_section` | 读取章节块及其父块、子块 |
| `hop` | 沿文档之间的引用边跳转相邻内容 |

**同步 MCP**（发布后更新知识库）：

| 工具 | 能力 |
| --- | --- |
| `sync_now(project_root)` | 把业务项目 `docs/` 下的最新文档提交到知识库，返回受理任务号；`project_root` 传业务项目的绝对根目录 |
| `sync_status(job_id)` | 查询同步任务进度，`done` / `failed` 为终态 |

## 怎么用

前提：

- 一个可访问的 KB2 知识库服务（通常由团队统一部署，向管理员要地址）
- 通过 npm 使用时需要先安装 [uv](https://docs.astral.sh/uv/)

启动前设置两个环境变量，把 MCP 绑定到服务和项目：

```bash
KB_SERVER_URL=http://your-kb-service:8001
KB_PROJECT_KEY=your-project
```

Claude Code 配置示例（`.mcp.json`）：

```json
{
  "mcpServers": {
    "kb2-query": {
      "command": "npx",
      "args": ["-y", "canpoint-knowledge-mcp"],
      "env": {
        "KB_SERVER_URL": "http://your-kb-service:8001",
        "KB_PROJECT_KEY": "your-project"
      }
    },
    "kb2-sync": {
      "command": "npx",
      "args": ["-y", "--package", "canpoint-knowledge-mcp", "kb2-sync-mcp"],
      "env": {
        "KB_SERVER_URL": "http://your-kb-service:8001",
        "KB_PROJECT_KEY": "your-project"
      }
    }
  }
}
```

也可以用 Python 方式安装运行：

```bash
pip install canpoint-knowledge-mcp   # 提供 kb2-query-mcp / kb2-sync-mcp 命令
uvx canpoint-knowledge-mcp            # 免安装直接运行查询 MCP
```

Codex 配置示例（`~/.codex/config.toml`）：

```toml
[mcp_servers.kb2-query]
type = "stdio"
command = "npx"
args = ["-y", "canpoint-knowledge-mcp"]

[mcp_servers.kb2-query.env]
KB_SERVER_URL = "http://your-kb-service:8001"
KB_PROJECT_KEY = "your-project"

[mcp_servers.kb2-sync]
type = "stdio"
command = "npx"
args = ["-y", "--package", "canpoint-knowledge-mcp", "kb2-sync-mcp"]

[mcp_servers.kb2-sync.env]
KB_SERVER_URL = "http://your-kb-service:8001"
KB_PROJECT_KEY = "your-project"
```

Windows 下若 `npx` 启动失败，可把 `command` 改为 `cmd`、`args` 改为
`["/c", "npx", "-y", "canpoint-knowledge-mcp"]`（env 表不变）。

推荐的发布规则（写入业务项目的 `AGENTS.md`）：

```text
发布成功后调用同步 MCP 的 sync_now(project_root="<当前项目绝对根目录>")；
取得并汇报已受理的 job_id 后继续发布流程；除非知识库索引完成是发布门禁，
否则不要等待或轮询 sync_status。
```

## 项目

- 仓库与完整文档：<https://github.com/mjwyr/canpoint-mcp>
- 作者：若清风
- 协议：Apache-2.0
