xtc-app-knowledge-mcp 0.1.0__tar.gz

xtc_app_knowledge_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: xtc-app-knowledge-mcp
+Version: 0.1.0
+Summary: Local MCP aggregator that merges local + cloud knowledge search. 聚合 MCP 本地网关。
+Requires-Python: >=3.11
+Requires-Dist: fastmcp>=0.1.0
+Requires-Dist: fastembed>=0.5.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pyyaml>=6.0

xtc_app_knowledge_mcp-0.1.0/README.md

@@ -0,0 +1,279 @@
+# app-knowledge-mcp — 聚合 MCP
+
+聚合云端知识库与本地 `local_knowledge/` 的统一 MCP 网关。云端能力全部平替 [xtc_knowledge_engine](http://172.28.1.116:9999/App/xtc_knowledge_engine)，同时新增本地语义检索。
+
+## 与云端 MCP 的异同
+
+| 维度 | 云端 MCP (xtc_knowledge_engine) | 聚合 MCP (本项目) |
+|------|-------------------------------|-------------------|
+| 架构 | Gateway → 3 微服务 (retrieval/rule/skill) | FastMCP stdio 本地进程 |
+| 知识检索 | FTS5 + 同义词扩展，直连 retrieval:18001 | 并行直连 retrieval + skill，逻辑完全一致 |
+| Skill 检索 | triggers 打分，直连 skill:18003 | 同上 |
+| 规则校验 | K2 关键词匹配，直连 rule:18002 | 代理云端 MCP |
+| 知识同步 | profile 匹配，直连 retrieval:18001 | 代理云端 MCP |
+| 本地检索 | ❌ 无 | ✅ 词法 OR + bge-small-zh-v1.5 语义 embedding |
+| 内置模型 | ❌ 无 | ✅ 90MB ONNX，零下载 |
+| 工具数量 | 4 个（search/skill_get/rule_check/knowledge_sync） | 9 个（+ cloud_search/local_search/knowledge_get/local_read 等） |
+| 获取全文 | 脚本 `fetch_doc.py` → 读缓存 | MCP 工具 `knowledge_get(doc_id)` 直接返回 |
+| Skill 文件 | `fetch_doc.py --skill-id` 两步 | `skill_get(include_prompt=True)` 一步并行 |
+| 平台命令 | 无 | `/k-search` 双检索命令（OpenCode / Claude Code / Cursor） |
+| 安装方式 | 脚本拷贝 → pip install | `python3 knowledge-mcp.py` 跨平台，pip install -e 可编辑模式 |
+| 传输方式 | streamable-http (:18000) | stdio 本地进程 |
+| 安装模式 | — | `pip install -e` 可编辑模式，改源码即时生效，无需重装 |
+
+**在线时效果一致**，聚合 MCP 的云端能力完全平替云端 MCP。离线时聚合 MCP 保留本地检索。
+
+## 工具清单
+
+### 云端工具（5 个）
+
+| 工具 | 触发时机 | 说明 |
+|------|---------|------|
+| `cloud_search` | 每次知识检索必须调用 | 并行直连 retrieval + skill，返回知识文档 + Skill 候选 |
+| `skill_get` | search 返回 skill_id 后 | 获取 Skill 详情，include_prompt 时并行拉取全量文件 |
+| `rule_check` | 每次代码修改完成后 | 对 diff 进行 K2/K5/K7 编码规范校验 |
+| `knowledge_sync` | 本地缓存缺失或过期时 | 按 profile 批量同步云端知识文档 |
+| `knowledge_get` | search 返回云端 doc_id 后 | 获取云端知识文档全文 |
+
+### 本地工具（4 个）
+
+| 工具 | 触发时机 | 说明 |
+|------|---------|------|
+| `local_search` | 每次知识检索必须调用 | 词法 OR + bge-small-zh-v1.5 语义混合检索 |
+| `local_read` | local_search 返回 file_path 后 | 读取本地文件全文 |
+| `local_list_domains` | 了解本地域覆盖时 | 列出 `local_knowledge/` 下所有业务域及概览 |
+| `local_list_files` | 浏览本地文件时 | 列出所有知识文件路径 |
+
+## 调用规则
+
+**每次知识检索必须同时调用 `cloud_search` + `local_search`**。LLM 通过 `instructions` 和 `/k-search` 命令双重保障。
+
+```
+cloud_search(query, ...) + local_search(query)
+  → 查看元信息 → 判断相关性
+  → knowledge_get(doc_id) 获取云端全文
+  → local_read(path) 获取本地全文
+  → skill_get → rule_check → 重复直到 passed
+```
+
+## 架构
+
+```mermaid
+flowchart TB
+    subgraph USER["用户 / LLM"]
+        CMD["/k-search 命令"]
+        INS["instructions（云端+本地描述）"]
+        TOOLS["tools/list（9 个工具）"]
+        CMD --> LLM["LLM 触发"]
+        INS --> LLM
+        TOOLS --> LLM
+    end
+
+    subgraph GATEWAY["knowledge-gateway · FastMCP stdio"]
+        MW["LoggingMiddleware"]
+        MW --> LOG["→ .knowledge/logs/mcp-calls.log"]
+
+        subgraph CLOUD_TOOLS["云端工具（5 个）"]
+            CS["cloud_search(query, platform, domain, ...)"]
+            SG["skill_get(skill_id, include_prompt)"]
+            RC["rule_check(content, rule_types)"]
+            KS["knowledge_sync(repo_id, profile)"]
+            KG["knowledge_get(doc_id)"]
+        end
+
+        subgraph LOCAL_TOOLS["本地工具（4 个）"]
+            LS["local_search(query, query_domains?)"]
+            LR["local_read(path)"]
+            LD["local_list_domains()"]
+            LF["local_list_files()"]
+        end
+
+        subgraph RESOURCES["资源（4 个）"]
+            R1["knowledge://local/files"]
+            R2["knowledge://local/domains"]
+            R3["knowledge://local/meta/{path*}"]
+            R4["knowledge://local/{path*}"]
+        end
+    end
+
+    subgraph CLOUD["云端后端"]
+        RET["retrieval :18001/search\nFTS5 · 同义词扩展 · bm25 排序\nmetadata 过滤 · LIKE 兜底"]
+        SKL["skill :18003/search\ntriggers 多维打分\nkeywords · filePatterns · changeTypes"]
+        DOC["retrieval :18001/doc\nSQLite → GitLab fallback"]
+        RUL["rule :18002/check\nK2 关键词匹配"]
+        SYNC["retrieval :18001/sync-profile-docs\nprofile 展开 · diff 比对"]
+    end
+
+    subgraph LOCAL["本地 local_knowledge/"]
+        LEX["词法 OR 召回\nfm 4x · body 1x"]
+        SEM["语义召回\nbge-small-zh-v1.5 embedding\ncosine similarity"]
+        MERGE["blend 排序\n40% 词法 + 60% 语义\nsem-only ×0.7 discount"]
+    end
+
+    LLM -->|"每次必调"| CS
+    LLM -->|"每次必调"| LS
+    LLM --> SG
+    LLM --> RC
+    LLM --> KS
+    LLM --> KG
+    LLM --> LR
+    LLM --> LD
+    LLM --> LF
+    LLM --> R1
+    LLM --> R2
+    LLM --> R3
+    LLM --> R4
+
+    CS -->|"asyncio.gather 并行"| RET
+    CS -->|"return_exceptions=True"| SKL
+    KG --> DOC
+    RC --> RUL
+    KS --> SYNC
+    SG -->|"MCP 代理"| SKL
+
+    LS --> LEX --> MERGE
+    LS --> SEM --> MERGE
+
+    MW --> CS
+    MW --> LS
+    MW --> KG
+    MW --> SG
+    MW --> RC
+    MW --> KS
+    MW --> LR
+    MW --> LD
+    MW --> LF
+```
+
+### 安装/卸载流程
+
+```mermaid
+flowchart LR
+    subgraph INSTALL["安装 · python3 knowledge-mcp.py /path/to/project"]
+        I1["clone/pull → ~/app-knowledge-mcp-repo/"] --> I2["pip install -e"]
+        I2 --> I3["平台检测\nflutter/android/ios/harmonyos"]
+        I3 --> I4["创建 .knowledge/profile.yaml"]
+        I4 --> I5["部署 dev-toolkit 模板\nlocal_knowledge/dev-toolkit/"]
+        I5 --> I6["创建 .opencode/agents/ 软链接"]
+        I6 --> I7["创建 .opencode/skills/ 软链接"]
+        I7 --> I8["写入 opencode.json"]
+        I8 --> I9["写入 .mcp.json"]
+        I9 --> I10["写入 .opencode/commands/k-search.md"]
+        I10 --> I11["写入 .claude/commands/k-search.md"]
+        I11 --> I12["写入 .cursor/rules/mcp-rules.mdc"]
+    end
+
+    subgraph UNINSTALL["卸载 · python3 knowledge-mcp.py --uninstall"]
+        U1["pip uninstall app-knowledge-mcp"] --> U2["移除 opencode.json 配置"]
+        U2 --> U3["移除 .mcp.json 配置"]
+        U3 --> U4["删除 .knowledge/"]
+        U4 --> U5["清理 .opencode/agents/ 软链接"]
+        U5 --> U6["清理 .opencode/skills/ 软链接"]
+        U6 --> U7["删除 .opencode/commands/k-search.md"]
+        U7 --> U8["删除 .claude/commands/k-search.md"]
+        U8 --> U9["删除 .cursor/rules/mcp-rules.mdc"]
+        U9 --> U10["删除 local_knowledge/dev-toolkit/"]
+        U10 --> U11["❗ local_knowledge/ 其余内容保留不动"]
+    end
+```
+
+### 本地语义检索管线
+
+```mermaid
+flowchart TD
+    Q["query: '摔倒 SOS'"] --> T["分词: ['摔倒', 'sos']"]
+    T --> LEX["词法召回\n扫描 local_knowledge/ 所有 .md"]
+    T --> SEM_EMB["语义 embedding\nbge-small-zh-v1.5 → 512d"]
+    
+    LEX --> LEX_MATCH{"关键词命中?"}
+    LEX_MATCH -->|"有候选"| CAND["候选列表\nfile_path · name · relevance"]
+    LEX_MATCH -->|"无候选"| CAND_EMPTY["candidates = []"]
+    
+    SEM_EMB --> SEM_ALL["全量 cosine similarity\n遍历所有文件"]
+    SEM_ALL --> SEM_SCORE["{file_path: similarity}"]
+
+    CAND --> BLEND["blend 融合\n40% lex_norm + 60% sem"]
+    CAND_EMPTY --> SEM_ONLY["纯语义构建\nsem ≥ 0.2 阈值"]
+    SEM_SCORE --> BLEND
+    SEM_SCORE --> SEM_ONLY
+
+    BLEND --> SORT["sort by relevance"]
+    SEM_ONLY --> SORT
+    SORT --> TOPK["top_k 截断 → results"]
+```
+
+
+## 快速接入
+
+```bash
+# 一键安装
+python3 knowledge-mcp.py /path/to/your-project
+
+# 卸载
+python3 knowledge-mcp.py --uninstall /path/to/your-project
+```
+
+脚本自动完成：
+1. 从远程克隆/更新仓库到 `~/app-knowledge-mcp-repo/`
+2. `pip install -e` 安装（含 90MB 内置模型）
+3. 检测项目平台（flutter/android/ios/harmonyos）
+4. 创建 `.knowledge/` + `profile.yaml`
+5. 部署 dev-toolkit 模板（Agent + Skill 定义）
+6. 创建 `.opencode/skills/` 软链接 → `local_knowledge/dev-toolkit/skills/<name>/`
+7. 创建 `.opencode/agents/` 软链接 → `.opencode/agents/<name>.yaml`
+8. 写入 OpenCode / Claude Code / Cursor 三平台 MCP 配置
+9. 创建 `/k-search` 命令
+10. 服务启动时预加载 embedding 模型，首次搜索无冷启动延迟
+
+## 性能特性
+
+- **异步日志**：`_log_call` 通过 `asyncio.Queue` 推送，后台 worker 批量写文件，工具调用不阻塞
+- **文件缓存**：`local_search` 按 mtime+size 缓存文件内容，同会话重复搜索不读盘
+- **语义模型预热**：服务启动时加载 bge-small-zh-v1.5 ONNX 模型，首次搜索免等待
+- **manifest 缓存**：`.knowledge/manifest.json` 带 mtime 校验，避免每次搜索读磁盘
+
+## 手动配置
+
+`opencode.json`:
+
+```json
+{
+  "mcp": {
+    "knowledge-gateway": {
+      "type": "local",
+      "command": ["python3", "-m", "app_knowledge_mcp.server"],
+      "enabled": true
+    }
+  }
+}
+```
+
+## 项目结构
+
+```
+app-knowledge-mcp-repo/
+├── app_knowledge_mcp/
+│   ├── __init__.py
+│   ├── server.py              # FastMCP 入口，9 工具 + 4 资源 + 异步日志 + _return_timed
+│   ├── cloud_client.py        # 云端直连（retrieval+skill 并行 REST）
+│   ├── local_search.py        # 词法 OR + 语义 embedding 混合检索（带文件内容缓存）
+│   ├── local_embedding.py     # fastembed 封装，bge-small-zh-v1.5（启动预热）
+│   ├── frontmatter.py         # YAML frontmatter 解析
+│   ├── models/                # 90MB 内置 ONNX 模型
+│   └── templates/
+│       └── dev-toolkit/       # 部署到项目的 dev-toolkit 模板
+│           ├── agents/        # Agent 定义（lee, kai, nio 等）
+│           └── skills/        # Skill 定义（ai-concept-crafter 等）
+├── knowledge-mcp.py           # 安装/卸载脚本（纯 Python 跨平台）
+├── knowledge-mcp-setup.sh     # Shell 入口（legacy）
+├── knowledge-mcp-setup.ps1    # PowerShell 入口（legacy）
+└── pyproject.toml             # 依赖：fastmcp + fastembed + httpx + pyyaml
+```
+
+## 依赖
+
+- Python >= 3.11
+- fastmcp >= 0.1.0
+- fastembed >= （hard dependency，内置模型无需下载）
+- httpx >= 0.27.0
+- pyyaml >= 6.0

xtc_app_knowledge_mcp-0.1.0/app_knowledge_mcp/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

xtc_app_knowledge_mcp-0.1.0/app_knowledge_mcp/cli.py

@@ -0,0 +1,50 @@
+"""CLI 入口：app-knowledge-mcp init / enable / disable"""
+
+import argparse
+import sys
+from pathlib import Path
+
+from .installer import (
+    init_project,
+    enable_global,
+    disable_global,
+    log,
+)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="app-knowledge-mcp — 聚合 MCP 本地网关")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    init_p = sub.add_parser("init", help="为项目安装 MCP 能力")
+    init_p.add_argument("project_dir", nargs="?", default=".",
+                        help="业务仓库目录（默认当前目录）")
+    init_p.add_argument("--project", default=None,
+                        help="平台 project 标识（如 callwatch）")
+
+    sub.add_parser("enable", help="注册到全局 opencode config")
+    sub.add_parser("disable", help="从全局 opencode config 移除")
+
+    args = parser.parse_args()
+
+    if args.command == "init":
+        project_dir = Path(args.project_dir).resolve()
+        if not project_dir.is_dir():
+            log(f"目录不存在: {project_dir}", "ERROR")
+            return 1
+        init_project(project_dir, args.project)
+        return 0
+
+    if args.command == "enable":
+        enable_global()
+        return 0
+
+    if args.command == "disable":
+        disable_global()
+        return 0
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())