canpoint-knowledge-mcp 0.1.0__tar.gz

canpoint_knowledge_mcp-0.1.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

canpoint_knowledge_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,208 @@
+Metadata-Version: 2.4
+Name: canpoint-knowledge-mcp
+Version: 0.1.0
+Summary: KB2 产品知识库的查询/同步 MCP 服务：项目绑定的混合检索、大纲、文档、章节与引用边跳转；同步 MCP 经环境变量绑定项目，是唯一写侧入口。
+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
+
+# KB2 产品知识库
+
+本仓库提供一个面向多个业务项目的 Markdown 知识库服务：AI 在业务项目发布后调用
+同步 MCP，把 `docs/` 完整清单发送到共享 HTTP 服务；PostgreSQL 保存文档、章节、层级和
+引用边，Milvus `kb2_chunks` 保存混合检索所需的向量与原文。查询 MCP 绑定单个
+`project_key`，同步 MCP 是唯一受支持的写侧入口。
+
+## 架构
+
+```text
+业务仓库 docs/**/*.md
+        │
+        └─ AI 发布流程 → sync_now(project_root)
+                         │ 同步 MCP（清单、哈希、变更正文）
+                         │
+                         ▼
+                  FastAPI /kb/sync
+                    │          │
+              PostgreSQL     Milvus
+             结构化事实      kb2_chunks
+```
+
+同一项目的同步按顺序执行，清单可重复提交。Markdown 的 `docs/` 一级子目录是
+版本/分组标签；平铺文件归入 `default`，路径中名为 `prototype` 的目录不入库。
+更深层目录保留在相对路径中，中文路径按 UTF-8 处理。
+
+## 安装与配置
+
+需要 Python 3.12、可访问的 PostgreSQL 和 Milvus/Zilliz Cloud。
+
+```powershell
+cd C:\path\to\canpoint-mcp
+.\.venv\Scripts\python.exe -m pip install -r requirements.txt
+```
+
+复制 `.env.example` 为本机 `.env`，填写 `PG_HOST`、`PG_PORT`、`PG_USER`、
+`PG_PASSWORD`、`PG_DATABASE`、`MILVUS_URI`、`MILVUS_TOKEN` 以及 embedding
+配置。真实密码、API key 只允许存在于本机环境或密钥管理器，不能提交到 Git 或
+写入文档。初始化 PostgreSQL 表和 KB2 collection：
+
+```powershell
+.\.venv\Scripts\python.exe scripts\init_kb2.py
+```
+
+启动共享 HTTP 服务：
+
+```powershell
+.\.venv\Scripts\python.exe -m uvicorn app.main:app --host 0.0.0.0 --port 8001
+```
+
+## HTTP 接口
+
+| 方法与路径 | 用途 |
+| --- | --- |
+| `POST /kb/sync` | 提交项目完整 Markdown 清单 |
+| `GET /kb/sync/{job_id}` | 查询同步和图谱任务进度 |
+| `GET /kb/outline` | 按项目和可选版本读取标题树 |
+| `POST /kb/search` | 项目范围内混合检索，返回父章节和行号 |
+| `GET /kb/document` | 按相对路径读取全文 |
+| `GET /kb/chunk/{chunk_id}` | 读取章节块、父块和子块 |
+| `POST /kb/hop` | 沿项目引用边跳转相邻文档 |
+| `GET /health` | 检查 PostgreSQL 与 KB2 Milvus |
+
+所有查询请求都必须带 `project_key`。服务端会在 PostgreSQL 和 Milvus 两侧同时
+校验项目范围，避免跨项目返回内容。
+
+## MCP 入口
+
+查询 MCP 是只读、项目绑定的 HTTP 客户端，提供 `get_outline`、`search`、
+`get_document`、`get_section`、`hop`。同步 MCP 提供
+`sync_now(project_root, project_key?)` 和 `sync_status(job_id)`；两个进程都只需绑定
+共享服务地址与项目标识。
+
+本地源码的完整 MCP 客户端配置如下；把路径与 `project_key` 换成实际值：
+
+```json
+{
+  "mcpServers": {
+    "kb2-query-member-prototype": {
+      "type": "stdio",
+      "command": "C:\\path\\to\\canpoint-mcp\\.venv\\Scripts\\python.exe",
+      "args": ["C:\\path\\to\\canpoint-mcp\\query_mcp.py"],
+      "env": {
+        "KB_SERVER_URL": "http://127.0.0.1:8001",
+        "KB_PROJECT_KEY": "member-prototype"
+      }
+    },
+    "kb2-sync-member-prototype": {
+      "type": "stdio",
+      "command": "C:\\path\\to\\canpoint-mcp\\.venv\\Scripts\\python.exe",
+      "args": ["C:\\path\\to\\canpoint-mcp\\server.py"],
+      "env": {
+        "KB_SERVER_URL": "http://127.0.0.1:8001",
+        "KB_PROJECT_KEY": "member-prototype"
+      }
+    }
+  }
+}
+```
+
+调用 `sync_now` 时，AI 必须传入当前业务项目的绝对 Git 根目录。工具要求该路径存在、
+就是 Git 顶层目录，且目录名与 MCP 绑定的 `project_key` 大小写不敏感地相等；随后固定
+扫描 `<project_root>/docs/**/*.md`。`docs/` 必须存在，空目录表示有意提交空的完整清单。
+可选 `project_key` 参数只作绑定断言，不能切换项目。同步不依赖业务仓库内的配置文件，
+也不提供独立命令或 Git hook 触发方式；复用的扫描与哈希代码仅是 MCP 内部实现。详见
+[`clients/sync/README.md`](https://github.com/mjwyr/canpoint-mcp/blob/main/clients/sync/README.md)。
+
+`sync_now(project_root=...)` 只等待本地扫描、上传以及服务端持久化受理，拿到 `job_id`
+后即可继续发布；
+解析、向量化和图谱在 FastAPI 后台进行。`job_id` 表示已受理而非同步完成，只有在
+知识库必须作为发布门禁时才需要调用 `sync_status(job_id)`，其终态为 `done` 或
+`failed`。
+
+业务项目的 `AGENTS.md` 使用以下发布规则：
+
+```text
+发布成功后调用同步 MCP 的 sync_now(project_root="<current absolute project root>");
+取得并汇报已受理的 job_id 后继续发布流程;除非知识库索引完成是发布门禁,否则不要等待或轮询 sync_status。
+```
+
+两个 MCP 入口都通过共享 HTTP 服务工作，不在 MCP 进程中直接打开数据库或向量库。
+
+## 已发布包（PyPI / npm）
+
+查询与同步两个 MCP 以 `canpoint-knowledge-mcp` 为名发布（作者：若清风）。两个
+进程都通过 `KB_SERVER_URL` 与 `KB_PROJECT_KEY` 环境变量绑定共享服务地址和项目，
+不在本机打开数据库或向量库；同步 MCP 的 `sync_now(project_root)` 由 AI 传入业务
+项目的绝对 Git 根目录，固定同步 `<project_root>/docs/**/*.md`。
+
+- **PyPI**：`pip install canpoint-knowledge-mcp` 或
+  `uvx canpoint-knowledge-mcp`，提供命令行入口 `kb2-query-mcp` 与
+  `kb2-sync-mcp`
+- **npm**：`npx -y canpoint-knowledge-mcp`（查询）或
+  `npx -y --package canpoint-knowledge-mcp kb2-sync-mcp`（同步）；
+  uvx 包装器，需要先安装 [uv](https://docs.astral.sh/uv/)，用法见
+  [npm/README.md](https://github.com/mjwyr/canpoint-mcp/blob/main/npm/README.md)
+
+使用前提是可访问的 KB2 共享 HTTP 服务；服务端（FastAPI/PostgreSQL/Milvus）
+不在发布包内，仍需在本仓库中部署。
+
+维护者一键发布（版本号以 `pyproject.toml` 为准，自动同步到 `npm/package.json`）：
+
+```powershell
+# 试跑（只构建，不发布）
+.\.venv\Scripts\python.exe scripts\publish.py --dry-run
+
+# 升补丁版本并发布双平台（凭据走环境变量）
+$env:PYPI_TOKEN = "<pypi token>"; $env:NPM_TOKEN = "<npm token>"
+.\.venv\Scripts\python.exe scripts\publish.py --bump patch
+```
+
+`--platform pypi|npm|all` 可选平台，`--set-version X.Y.Z` 指定版本。
+
+## 图谱与版本
+
+显式 Markdown 相对链接在同步阶段生成 `md_link` 边；LLM 抽取的业务边在后台异步
+补齐。抽取失败只记录在 `sync_jobs`，不影响文档入库和检索，服务重启后会恢复未完
+成的图谱任务。文档更新按 `project_key + rel_path` 覆盖，删除文档会级联删除其
+章节和边；版本标签来自目录，不额外维护版本快照。
+
+图谱抽取按块缓存并批量请求 LLM。默认每次最多 8 个块、12,000 个正文字符，并在
+全服务范围最多并发 4 个请求；可通过 `GRAPH_EXTRACT_BATCH_SIZE`、
+`GRAPH_EXTRACT_BATCH_MAX_CHARS` 和 `GRAPH_EXTRACT_CONCURRENCY` 调整。修改模型、
+提示契约或 `GRAPH_EXTRACT_CACHE_VERSION` 会自动使旧缓存失效。DeepSeek V4 默认以
+`LLM_ENABLE_THINKING=false` 关闭思考模式，降低结构化抽取延迟。
+
+新增、更新或删除文档都会在后台重新解析全项目的关系目标，但只有新增或失效的块
+会请求 LLM；缓存完整的热运行不会产生模型调用。热运行一次读取项目级缓存，复用
+预计算的文档匹配索引，并在校验目录和缓存快照后用单事务批量替换完整文档的 LLM
+边，避免关系数增长时重复扫描正文或逐边写库。`GET /kb/sync/{job_id}` 的
+`graph_chunks_total`、`graph_chunks_done`、`graph_cache_hits` 和
+`graph_provider_calls` 可用于查看实际进度。`/health` 只有在 PostgreSQL 迁移完成且
+Milvus collection 可用时返回健康。
+
+## 开发检查
+
+```powershell
+.\.venv\Scripts\python.exe -m unittest discover -s tests -v
+.\.venv\Scripts\python.exe -m compileall -q app clients config controller service
+```
+
+`frontend-next/` 是冻结的既有可视化前端，本阶段不修改其任何文件。

canpoint_knowledge_mcp-0.1.0/README.md

@@ -0,0 +1,182 @@
+# KB2 产品知识库
+
+本仓库提供一个面向多个业务项目的 Markdown 知识库服务：AI 在业务项目发布后调用
+同步 MCP，把 `docs/` 完整清单发送到共享 HTTP 服务；PostgreSQL 保存文档、章节、层级和
+引用边，Milvus `kb2_chunks` 保存混合检索所需的向量与原文。查询 MCP 绑定单个
+`project_key`，同步 MCP 是唯一受支持的写侧入口。
+
+## 架构
+
+```text
+业务仓库 docs/**/*.md
+        │
+        └─ AI 发布流程 → sync_now(project_root)
+                         │ 同步 MCP（清单、哈希、变更正文）
+                         │
+                         ▼
+                  FastAPI /kb/sync
+                    │          │
+              PostgreSQL     Milvus
+             结构化事实      kb2_chunks
+```
+
+同一项目的同步按顺序执行，清单可重复提交。Markdown 的 `docs/` 一级子目录是
+版本/分组标签；平铺文件归入 `default`，路径中名为 `prototype` 的目录不入库。
+更深层目录保留在相对路径中，中文路径按 UTF-8 处理。
+
+## 安装与配置
+
+需要 Python 3.12、可访问的 PostgreSQL 和 Milvus/Zilliz Cloud。
+
+```powershell
+cd C:\path\to\canpoint-mcp
+.\.venv\Scripts\python.exe -m pip install -r requirements.txt
+```
+
+复制 `.env.example` 为本机 `.env`，填写 `PG_HOST`、`PG_PORT`、`PG_USER`、
+`PG_PASSWORD`、`PG_DATABASE`、`MILVUS_URI`、`MILVUS_TOKEN` 以及 embedding
+配置。真实密码、API key 只允许存在于本机环境或密钥管理器，不能提交到 Git 或
+写入文档。初始化 PostgreSQL 表和 KB2 collection：
+
+```powershell
+.\.venv\Scripts\python.exe scripts\init_kb2.py
+```
+
+启动共享 HTTP 服务：
+
+```powershell
+.\.venv\Scripts\python.exe -m uvicorn app.main:app --host 0.0.0.0 --port 8001
+```
+
+## HTTP 接口
+
+| 方法与路径 | 用途 |
+| --- | --- |
+| `POST /kb/sync` | 提交项目完整 Markdown 清单 |
+| `GET /kb/sync/{job_id}` | 查询同步和图谱任务进度 |
+| `GET /kb/outline` | 按项目和可选版本读取标题树 |
+| `POST /kb/search` | 项目范围内混合检索，返回父章节和行号 |
+| `GET /kb/document` | 按相对路径读取全文 |
+| `GET /kb/chunk/{chunk_id}` | 读取章节块、父块和子块 |
+| `POST /kb/hop` | 沿项目引用边跳转相邻文档 |
+| `GET /health` | 检查 PostgreSQL 与 KB2 Milvus |
+
+所有查询请求都必须带 `project_key`。服务端会在 PostgreSQL 和 Milvus 两侧同时
+校验项目范围，避免跨项目返回内容。
+
+## MCP 入口
+
+查询 MCP 是只读、项目绑定的 HTTP 客户端，提供 `get_outline`、`search`、
+`get_document`、`get_section`、`hop`。同步 MCP 提供
+`sync_now(project_root, project_key?)` 和 `sync_status(job_id)`；两个进程都只需绑定
+共享服务地址与项目标识。
+
+本地源码的完整 MCP 客户端配置如下；把路径与 `project_key` 换成实际值：
+
+```json
+{
+  "mcpServers": {
+    "kb2-query-member-prototype": {
+      "type": "stdio",
+      "command": "C:\\path\\to\\canpoint-mcp\\.venv\\Scripts\\python.exe",
+      "args": ["C:\\path\\to\\canpoint-mcp\\query_mcp.py"],
+      "env": {
+        "KB_SERVER_URL": "http://127.0.0.1:8001",
+        "KB_PROJECT_KEY": "member-prototype"
+      }
+    },
+    "kb2-sync-member-prototype": {
+      "type": "stdio",
+      "command": "C:\\path\\to\\canpoint-mcp\\.venv\\Scripts\\python.exe",
+      "args": ["C:\\path\\to\\canpoint-mcp\\server.py"],
+      "env": {
+        "KB_SERVER_URL": "http://127.0.0.1:8001",
+        "KB_PROJECT_KEY": "member-prototype"
+      }
+    }
+  }
+}
+```
+
+调用 `sync_now` 时，AI 必须传入当前业务项目的绝对 Git 根目录。工具要求该路径存在、
+就是 Git 顶层目录，且目录名与 MCP 绑定的 `project_key` 大小写不敏感地相等；随后固定
+扫描 `<project_root>/docs/**/*.md`。`docs/` 必须存在，空目录表示有意提交空的完整清单。
+可选 `project_key` 参数只作绑定断言，不能切换项目。同步不依赖业务仓库内的配置文件，
+也不提供独立命令或 Git hook 触发方式；复用的扫描与哈希代码仅是 MCP 内部实现。详见
+[`clients/sync/README.md`](https://github.com/mjwyr/canpoint-mcp/blob/main/clients/sync/README.md)。
+
+`sync_now(project_root=...)` 只等待本地扫描、上传以及服务端持久化受理，拿到 `job_id`
+后即可继续发布；
+解析、向量化和图谱在 FastAPI 后台进行。`job_id` 表示已受理而非同步完成，只有在
+知识库必须作为发布门禁时才需要调用 `sync_status(job_id)`，其终态为 `done` 或
+`failed`。
+
+业务项目的 `AGENTS.md` 使用以下发布规则：
+
+```text
+发布成功后调用同步 MCP 的 sync_now(project_root="<current absolute project root>");
+取得并汇报已受理的 job_id 后继续发布流程;除非知识库索引完成是发布门禁,否则不要等待或轮询 sync_status。
+```
+
+两个 MCP 入口都通过共享 HTTP 服务工作，不在 MCP 进程中直接打开数据库或向量库。
+
+## 已发布包（PyPI / npm）
+
+查询与同步两个 MCP 以 `canpoint-knowledge-mcp` 为名发布（作者：若清风）。两个
+进程都通过 `KB_SERVER_URL` 与 `KB_PROJECT_KEY` 环境变量绑定共享服务地址和项目，
+不在本机打开数据库或向量库；同步 MCP 的 `sync_now(project_root)` 由 AI 传入业务
+项目的绝对 Git 根目录，固定同步 `<project_root>/docs/**/*.md`。
+
+- **PyPI**：`pip install canpoint-knowledge-mcp` 或
+  `uvx canpoint-knowledge-mcp`，提供命令行入口 `kb2-query-mcp` 与
+  `kb2-sync-mcp`
+- **npm**：`npx -y canpoint-knowledge-mcp`（查询）或
+  `npx -y --package canpoint-knowledge-mcp kb2-sync-mcp`（同步）；
+  uvx 包装器，需要先安装 [uv](https://docs.astral.sh/uv/)，用法见
+  [npm/README.md](https://github.com/mjwyr/canpoint-mcp/blob/main/npm/README.md)
+
+使用前提是可访问的 KB2 共享 HTTP 服务；服务端（FastAPI/PostgreSQL/Milvus）
+不在发布包内，仍需在本仓库中部署。
+
+维护者一键发布（版本号以 `pyproject.toml` 为准，自动同步到 `npm/package.json`）：
+
+```powershell
+# 试跑（只构建，不发布）
+.\.venv\Scripts\python.exe scripts\publish.py --dry-run
+
+# 升补丁版本并发布双平台（凭据走环境变量）
+$env:PYPI_TOKEN = "<pypi token>"; $env:NPM_TOKEN = "<npm token>"
+.\.venv\Scripts\python.exe scripts\publish.py --bump patch
+```
+
+`--platform pypi|npm|all` 可选平台，`--set-version X.Y.Z` 指定版本。
+
+## 图谱与版本
+
+显式 Markdown 相对链接在同步阶段生成 `md_link` 边；LLM 抽取的业务边在后台异步
+补齐。抽取失败只记录在 `sync_jobs`，不影响文档入库和检索，服务重启后会恢复未完
+成的图谱任务。文档更新按 `project_key + rel_path` 覆盖，删除文档会级联删除其
+章节和边；版本标签来自目录，不额外维护版本快照。
+
+图谱抽取按块缓存并批量请求 LLM。默认每次最多 8 个块、12,000 个正文字符，并在
+全服务范围最多并发 4 个请求；可通过 `GRAPH_EXTRACT_BATCH_SIZE`、
+`GRAPH_EXTRACT_BATCH_MAX_CHARS` 和 `GRAPH_EXTRACT_CONCURRENCY` 调整。修改模型、
+提示契约或 `GRAPH_EXTRACT_CACHE_VERSION` 会自动使旧缓存失效。DeepSeek V4 默认以
+`LLM_ENABLE_THINKING=false` 关闭思考模式，降低结构化抽取延迟。
+
+新增、更新或删除文档都会在后台重新解析全项目的关系目标，但只有新增或失效的块
+会请求 LLM；缓存完整的热运行不会产生模型调用。热运行一次读取项目级缓存，复用
+预计算的文档匹配索引，并在校验目录和缓存快照后用单事务批量替换完整文档的 LLM
+边，避免关系数增长时重复扫描正文或逐边写库。`GET /kb/sync/{job_id}` 的
+`graph_chunks_total`、`graph_chunks_done`、`graph_cache_hits` 和
+`graph_provider_calls` 可用于查看实际进度。`/health` 只有在 PostgreSQL 迁移完成且
+Milvus collection 可用时返回健康。
+
+## 开发检查
+
+```powershell
+.\.venv\Scripts\python.exe -m unittest discover -s tests -v
+.\.venv\Scripts\python.exe -m compileall -q app clients config controller service
+```
+
+`frontend-next/` 是冻结的既有可视化前端，本阶段不修改其任何文件。