jaggernaut007/nexus-mcp

# Nexus-MCP [](https://pypi.org/project/nexus-mcp-ci/) [](https://pypi.org/project/nexus-mcp-ci/) [](LICENSE) [](https://github.com/jaggernaut007/Nexus-MCP/actions/workflows/publish.yml) [](https://glama.ai/mcp/servers/jaggernaut007/Nexus-MCP) **在一个本地 MCP server 中集成混合搜索 + 代码图 + 语义记忆 —— 内存占用不到 350 MB。** Nexus-MCP 是一个为 [Model Context Protocol](https://modelcontextprotocol.io) 设计的代码智能 server。它让 AI agent 能够在不依赖云服务的情况下，获取关于你代码库的精确且节省 token 的回答：无需 API key，无需数据传出，无需订阅。 ``` pip install nexus-mcp-ci claude mcp add nexus-mcp-ci -- nexus-mcp-ci ``` ## 它解决的问题 默认情况下，AI 编程 agent 使用 token 的效率很低。一个试图理解 `verify_credentials()` 的 agent 通常需要： 1. `Glob("src/**/*.py")` → 返回 120 个文件，agent 阅读最可能的 8 个 → **约 12,000 tokens** 2. `Grep("verify_credentials")` → 3 个匹配项，agent 阅读上下文 → **约 4,000 tokens** 3. `Read("auth/middleware.py")` → 读取 400 行的完整文件以理解调用者 → **约 3,000 tokens** **总计：约 19,000 tokens，3 次以上的工具调用，且没有图关系。** 使用 Nexus-MCP： 1. `explain("verify_credentials")` → 符号定义 + 所有调用者 + 所有被调用者 + 复杂度指标 → **约 1,500 tokens，1 次工具调用** 或者用于代码发现： 1. `search("credential verification flow")` → 整个代码库中语义最相关的前 10 个片段 → **约 2,000 tokens，1 次工具调用** **预计节省：每次编程会话可减少 30–60% 的 token。** 具体数字取决于代码库的大小和任务类型 —— 请参阅下方的 [基准测试表](#token-efficiency)。 ## 快速开始（60 秒） ``` # 1. 安装 pip install nexus-mcp-ci # 2. 注册到 Claude Code claude mcp add nexus-mcp-ci -- nexus-mcp-ci # 3. 验证（在任意 Claude Code 会话中） # 当 CLAUDE.md 指示时，Claude 将自动使用 nexus-mcp-ci 工具 ``` 然后在你的项目根目录下创建一个 `CLAUDE.md` 文件： ``` ## 代码导航 Use nexus-mcp-ci tools before built-in file tools: - Start sessions with `mcp__nexus-mcp__status`; run `index` if needed - `search` before `Read/Grep` - `explain` instead of reading a file to understand a symbol - `impact` before any refactor ``` 就这样。Claude 会在首次使用时为你的项目建立索引，并自动使用 Nexus-MCP 工具。 ## 工作原理 ### 索引流水线（8个步骤） ``` Source files │ ├─ Step 1: Discover ──────── walk tree, filter by ext/size/.gitignore │ ├─ Step 2: Parse symbols ─── tree-sitter (parallel ThreadPool) │ extracts: functions, classes, methods │ captures: name, signature, docstring, line_start/end, language │ ├─ Step 3: Parse graph ────── ast-grep (sequential for consistency) │ extracts: call edges, import edges, inheritance edges │ output: UniversalGraph(nodes=[], edges=[]) │ ├─ Step 4: Transfer graph ── populate rustworkx PyDiGraph │ O(1) node lookup by name, Rust-backed traversal │ ├─ Step 5: Chunk ──────────── Symbol → CodeChunk │ deterministic IDs: SHA256(file_path + symbol_name + line) │ avoids duplicate inserts on incremental reindex │ ├─ Step 6: Embed ──────────── bge-small-en: 384-dim (default) or jina-code: 768-dim via ONNX │ lazy-loaded, unloaded after indexing (try/finally) │ GPU/MPS auto-detected; falls back to CPU │ ├─ Step 7: Store ──────────── write to LanceDB `chunks` table (12-col PyArrow schema) │ rebuild native FTS (Tantivy) index after write │ └─ Step 8: Cleanup ────────── unload model, persist metadata (mtimes for incremental) save rustworkx graph to SQLite (warm-start recovery) ``` **增量重建索引：** 基于 mtime —— 仅重新处理更改过的文件。损坏的索引检测会触发自动的全面重建。 ### 搜索流水线 ``` search("how does auth work") │ ├─► vector_engine.search(query, n=30) ← cosine similarity on 768-dim embeddings │ "auth" finds "verify_credentials", "token_check" │ ├─► bm25_engine.search(query, n=30) ← Tantivy FTS on same LanceDB table │ fast exact-keyword matching │ ├─► graph_engine.boost(query, n=30) ← structural relevance score │ hub symbols (high in/out degree) boosted │ └─► fusion.merge(v_results, b_results, g_results) │ │ Reciprocal Rank Fusion: score = Σ weight_i / (k + rank_i) │ default weights: vector=0.5, bm25=0.3, graph=0.2 │ ├─► reranker.rerank(top_20) ← FlashRank (optional, 4MB ONNX model, <10ms) │ └─► token_budget.truncate() ← summary / detailed / full │ └─► Top-N chunks, scored, formatted ``` ### 技术栈 | 层级 | 技术 | 决策理由 | |-------|-----------|-------------------| | **向量存储** | LanceDB | mmap 磁盘备份 → 相比 ChromaDB 的内存模型，仅有约 20–50 MB 的开销。原生的 Tantivy FTS 意味着只需一个存储即可同时用于向量和 BM25。([ADR-002](docs/adr/ADR-002-lancedb-over-chromadb.md)) | | **Embeddings** | bge-small-en (默认) 或 ONNX Runtime + jina-code | bge-small-en 非常轻量（384维，无需 trust_remote_code）。jina-code 专为代码设计（161M 参数，8192 序列长度），在 ONNX 上运行（约 50 MB，而 PyTorch 大约需要 500 MB）。懒加载/卸载使内存在索引建立后保持平稳。([ADR-003](docs/adr/ADR-003-onnx-runtime-over-pytorch.md)) | | **图引擎** | rustworkx PyDiGraph | Rust 底层，O(1) 节点查找，PageRank + 中心性算法。通过 RLock 实现线程安全。([ADR-006](docs/adr/ADR-006-rustworkx-graph-engine.md)) | | **符号解析器** | tree-sitter 0.21.3 | 支持 25+ 种语言，增量解析，带有元数据的 AST 级别符号提取。通过 ThreadPool 实现并行。([ADR-005](docs/adr/ADR-005-dual-parser-strategy.md)) | | **图解析器** | ast-grep | 用于调用/导入/继承边的结构化模式匹配。顺序运行以确保图的一致性。([ADR-005](docs/adr/ADR-005-dual-parser-strategy.md)) | | **分块** | 基于符号 | 每个函数/类对应一个块。确定性的 SHA256 ID 可防止重复插入。([ADR-008](docs/adr/ADR-008-code-chunk-strategy.md)) | | **重排器** | FlashRank (可选) | 4 MB 的 ONNX 交叉编码器，在 CPU 上处理 top-20 仅需不到 10 ms。如果未安装则平滑透传。 | | **持久化** | SQLite + LanceDB | 图存储在 SQLite 中（热启动恢复），向量 + FTS 存储在 LanceDB 中，mtime 存储在 JSON 中。零配置。 | | **MCP 框架** | FastMCP 2.0 | Stdio 传输，自动工具注册，schema 生成。 | ## Token 效率 在约 10,000 行的 Python 代码库上，与等效的 agentic 文件浏览工作流进行对比测量： | 任务 | 不使用 Nexus-MCP | 使用 Nexus-MCP | 减少 | |------|:-----------------:|:--------------:|:---------:| | 查找相关代码 (agent 阅读 5–10 个文件) | 5,000–15,000 tokens | 500–2,000 tokens | **70–90%** | | 理解一个符号 (grep + read + 追踪调用者) | 3,000–8,000 tokens，3–5 次调用 | 800–2,000 tokens，1 次调用 | **60–75%** | | 评估变更影响 (手动传递追踪) | 10,000–20,000 tokens | 1,000–3,000 tokens | **80–85%** | | 上下文中的工具描述 (2 个 MCP server) | 约 1,700 tokens (17 个工具) | 约 700 tokens (10 个工具) | **约 60%** | | 搜索精度 (仅限关键词需要重试) | 2–3 次搜索 × 2,000 tokens | 1 次混合搜索 × 1,500 tokens | **60–75%** | **典型的会话节省：** 与文件浏览 agent 相比，节省 **15,000–40,000 tokens (30–60%)**。 ### 三个详细级别 每个工具都支持 `verbosity` 参数 —— agent 可以根据需要准确请求相应的详细程度： | 级别 | Token 预算 | 包含内容 | |-------|:-----------:|-----------------| | `summary` | 约 500 tokens | 仅计数、得分、文件:行号指针 | | `detailed` | 约 2,000 tokens | 函数签名、类型、行范围、docstrings | | `full` | 约 8,000 tokens | 完整代码片段、所有关系、元数据 | ## 10 个工具 **v2.0.0 破坏性变更：** `find_callers`/`find_callees`/`impact` 已合并入 `graph`，`overview`/`architecture` 已合并入 `map`，且 `remember`/`recall`/`forget` 已合并入 `memory` —— 有关旧→新的映射，请参阅 [CHANGELOG](CHANGELOG.md)； 有关原因请参阅 [ADR-017](docs/adr/ADR-017-tool-consolidation.md)。在 MCP Tool Search 下，与众多单一功能的工具相比，数量更少、功能更丰富的工具能实现更好的路由。 ### 发现与索引 | 工具 | 适用场景 | |------|----------| | `index(path)` | 任何会话中的首个操作。支持逗号分隔的多文件夹路径。默认增量索引，运行时报告进度，并在完成时启动一个防抖动的自动重新索引监视器 (`NEXUS_AUTO_WATCH`)。 | | `status()` | 检查索引健康度：符号数量、代码块数量、内存使用情况、引擎可用性，以及如果自上次索引以来文件发生更改时提供的一对 `stale`/`staleness_warning` 值。 | | `health()` | 存活探测 —— 运行时间，以及哪些引擎已准备就绪。 | | `map(detail)` | **替代 `ls` + 手动浏览。** `detail="summary"` (文件/语言/质量/顶层模块，原为 `overview()`)，`"architecture"` (层级/依赖/类/入口点/枢纽符号，原为 `architecture()`)，或 `"full"` 获取两者。 | ### 搜索 | 工具 | 适用场景 | |------|----------| | `search(query, mode, language, type, n)` | 主要的代码发现方式。`mode`：`hybrid` (默认)、`vector` 或 `bm25`。如果结果稀少，则回退到实时的 grep。如果索引看起来已过期，则返回非空的 `warning`（后台会自动触发重建索引；结果仍会立即返回）。 | ### 图分析 | 工具 | 适用场景 | |------|----------| | `find_symbol(name, exact)` | 查找特定符号。`exact=False` 用于模糊匹配。 | | `graph(symbol, direction, transitive, max_depth)` | `direction="callers"` (谁调用了它，原为 `find_callers`) 或 `"callees"` (它调用了什么，原为 `find_callees`)。**`transitive=True` —— 必须在任何重构之前运行** (原为 `impact()`)：整个图中完整的传递性变更影响范围。 | | `explain(symbol)` | **替代 `Read` 以理解代码。** 一次调用中获取图关系 + 语义上下文 + 质量指标。 | | `analyze(path)` | 代码质量：循环复杂度、认知复杂度、代码坏味道、依赖指标。 | ### 记忆 | 工具 | 适用场景 | |------|----------| | `memory(action, ...)` | `action="store"` (原为 `remember`) 用于跨会话持久化保存决策/笔记 (类型：`note`, `decision`, `conversation`, `status`, `preference`, `doc`；TTL：`permanent`, `month`, `week`, `day`, `session`)；`"search"` (原为 `recall`) 用于语义检索；`"delete"` (原为 `forget`) 通过 ID、tag 或 type 删除。 | ## 安装 ### 从 PyPI 安装（推荐） ``` pip install nexus-mcp-ci # GPU (CUDA) 支持 — 添加 ONNX CUDA execution provider pip install nexus-mcp-ci[gpu] # FlashRank reranker — 添加约 4MB 的 cross-encoder 以提升搜索质量 pip install nexus-mcp-ci[reranker] # 两者 pip install nexus-mcp-ci[gpu,reranker] ``` ### 从源码安装 ``` git clone https://github.com/jaggernaut007/Nexus-MCP.git cd Nexus-MCP ./setup.sh # creates venv, installs, verifies # 或 pip install -e ".[dev]" ``` **需要 Python 3.10–3.13。** 可选：`rg` (ripgrep)，用于在未索引文件上提供 100% 搜索覆盖率回退。 ## MCP Client 设置 ### Claude Code ``` # 最小化 claude mcp add nexus-mcp-ci -- nexus-mcp-ci # 使用代码专用的 embedding model（需要 trust_remote_code） claude mcp add nexus-mcp-ci -e NEXUS_EMBEDDING_MODEL=jina-code -- nexus-mcp-ci # GPU embeddings claude mcp add nexus-mcp-ci -e NEXUS_EMBEDDING_DEVICE=cuda -- nexus-mcp-ci # Virtualenv 安装 — 传递完整的二进制路径 claude mcp add nexus-mcp-ci -- /path/to/.venv/bin/nexus-mcp-ci ``` ### Claude Desktop `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS): ``` { "mcpServers": { "nexus-mcp-ci": { "command": "nexus-mcp-ci", "args": [], "env": { "NEXUS_EMBEDDING_MODEL": "jina-code" } } } } ``` ### Cursor / Windsurf / Cline / 任何 MCP Client ``` { "nexus-mcp-ci": { "command": "nexus-mcp-ci", "transport": "stdio" } } ``` ## Agent 集成模式 ### CLAUDE.md 样板文件（放入项目根目录） ``` ## 代码智能 — nexus-mcp-ci Every code task in this project MUST follow this workflow: 1. **Session start**: `mcp__nexus-mcp__status` → if not indexed, `mcp__nexus-mcp__index` 2. **Before any file read**: `mcp__nexus-mcp__search` to locate relevant code 3. **To understand a symbol**: `mcp__nexus-mcp__explain` (not Read) 4. **Before refactoring**: `mcp__nexus-mcp__impact` to assess blast radius 5. **For project orientation**: `mcp__nexus-mcp__overview` or `mcp__nexus-mcp__architecture` ``` ### 典型的 agent 工具调用序列 ``` # 会话开始 status() → "indexed: True, 8,412 chunks, 1,203 symbols, 87 MB" # 代码发现 search("JWT token validation", mode="hybrid", n=10) → auth/jwt.py:42 validate_token() score=0.94 → auth/middleware.py:18 require_auth() score=0.87 → tests/test_auth.py:91 test_valid_jwt() score=0.81 # 深度符号理解 explain("validate_token") → definition, docstring, params, complexity → callers: [require_auth, login_required, api_key_check] → callees: [decode_jwt, check_expiry, verify_signature] → quality: complexity=6, smells=[], maintainability=A # 重构前安全检查 impact("validate_token") → direct callers: 3 symbols → transitive impact: 12 symbols across 4 files → high-risk: auth/middleware.py (5 dependents) ``` ### 多文件夹 monorepo 索引 ``` # 在一次调用中索引多个 roots — 按顺序处理，共享 engines index(path="packages/api/src,packages/shared/src,packages/cli/src") # 或使用 paths 参数来添加额外的 roots index(path="packages/api/src", paths="packages/shared/src,packages/cli/src") ``` ## 配置 所有设置均通过 `NEXUS_` 环境变量进行： | 变量 | 默认值 | 描述 | |----------|---------|-------------| | `NEXUS_EMBEDDING_MODEL` | `bge-small-en` | `bge-small-en` (384维，轻量级) 或 `jina-code` (768维，针对代码优化) | | `NEXUS_EMBEDDING_DEVICE` | `auto` | `auto` (CUDA → MPS → CPU), `cuda`, `mps`, `cpu` | | `NEXUS_STORAGE_DIR` | `.nexus` | 索引存储目录 | | `NEXUS_AUTO_WATCH` | `true` | 在 `index()` 之后启动防抖动监视器，在文件更改时自动重新索引 | | `NEXUS_STALENESS_CHECK_INTERVAL` | `15` | `status()`/`search()` 之间进行过期检查的间隔秒数（有节流限制，非每次调用都检查） | | `NEXUS_MAX_FILE_SIZE_MB` | `10` | 跳过大于此大小的文件 | | `NEXUS_CHUNK_MAX_CHARS` | `4000` | 每个代码块的最大字符数 | | `NEXUS_MAX_MEMORY_MB` | `350` | 内存预算目标 | | `NEXUS_SEARCH_MODE` | `hybrid` | `hybrid`, `vector 或 `bm25` | | `NEXUS_FUSION_WEIGHT_VECTOR` | `0.5` | RRF 中的向量得分权重 | | `NEXUS_FUSION_WEIGHT_BM25` | `0.3` | RRF 中的 BM25 得分权重 | | `NEXUS_FUSION_WEIGHT_GRAPH` | `0.2` | RRF 中的图得分权重 | | `NEXUS_PERMISSION_LEVEL` | `full` | `full`, `read`, 或 `restricted` | | `NEXUS_RATE_LIMIT_ENABLED` | `false` | 启用基于每个工具的令牌桶速率限制 | | `NEXUS_AUDIT_ENABLED` | `true` | 带有相关性 ID 的结构化审计日志 | | `NEXUS_TRUST_REMOTE_CODE` | `true` | jina-code 必需；使用 bge-small-en 时设置为 `false` | | `NEXUS_LOG_LEVEL` | `INFO` | 日志级别 | | `NEXUS_LOG_FORMAT` | `text` | `text` 或 `json` | ### Embedding 模型 | 模型 | Key | 维度 | 最大序列 | 后端 | `trust_remote_code` | |-------|-----|:----:|:-------:|---------|:-------------------:| | BGE Small EN v1.5 (默认) | `bge-small-en` | 384 | 512 | PyTorch | 否 | | Jina Embeddings v2 Code | `jina-code` | 768 | 8,192 | ONNX | 是 | **更改模型后，请重新建立索引。** 不同模型的 Embedding 互不兼容。 ## 对比 ### 与其他 MCP Server 对比 | 功能 | Nexus-MCP | Sourcegraph MCP | Greptile MCP | GitHub MCP | tree-sitter MCP | |---------|:---:|:---:|:---:|:---:|:---:| | 完全本地/私有 | ✅ | ❌ 需要基础设施 | ❌ 云端 | ❌ 云端 | ✅ | | 语义（向量）搜索 | ✅ | ❌ 仅限关键词 | ✅ 基于 LLM | ❌ | ❌ | | 关键词 (BM25) 搜索 | ✅ | ✅ | — | ✅ | ❌ | | 混合融合 (RRF) | ✅ | ❌ | ❌ | ❌ | ❌ | | 代码图 (调用/导入) | ✅ rustworkx | ✅ SCIP | ❌ | ❌ | ❌ | | 重排 | ✅ FlashRank | ❌ | — | ❌ | ❌ | | 语义记忆（持久化） | ✅ 6 种类型 | ❌ | ❌ | ❌ | ❌ | | 变更影响分析 | ✅ | 部分 | ❌ | ❌ | ❌ | | 基于 Token 预算的响应 | ✅ 3 个级别 | ❌ | ❌ | ❌ | ❌ | | 语言 | 25+ | 30+ | 多种 | 多种 | 多种 | | 成本 | **免费** | $$$ | $40/月 | $10–39/月 | 免费 | | 需要 API Key | **否** | 是 | 是 | 是 | 否 | ### 与 AI 代码工具对比 | 能力 | Nexus-MCP | Cursor | Copilot @workspace | Cody | Continue.dev | Aider | |---|:---:|:---:|:---:|:---:|:---:|:---:| | 与 IDE 无关 | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ | | MCP 原生 | ✅ | 部分 | ❌ | ❌ | ✅ client | ❌ | | 完全本地 | ✅ | 部分 | ❌ | 部分 | ✅ | ✅ | | 混合搜索 | ✅ | 未知 | 未知 | 关键词 | 是 | ❌ | | 代码图 | ✅ | 未知 | 未知 | ✅ SCIP | 基础 | ❌ | | 语义记忆 | ✅ 持久化 | ❌ | ❌ | ❌ | ❌ | ❌ | | 基于 Token 预算的输出 | ✅ | — | — | — | — | — | | 开源 | ✅ MIT | ❌ | ❌ | 部分 | ✅ | ✅ | | 成本 | **免费** | $20–40/月 | $10–39/月 | $0–49/月 | 免费 | 免费 | ## 开发 ``` git clone https://github.com/jaggernaut007/Nexus-MCP.git cd Nexus-MCP pip install -e ".[dev]" pytest -v # 441 tests pytest -m "not slow" # skip performance benchmarks pytest tests/test_search.py # single module ruff check . # lint ``` ### 项目结构 ``` src/nexus_mcp/ ├── server.py # FastMCP entrypoint — 10 tools, input validation, graceful shutdown ├── config.py # Settings (NEXUS_ env prefix) ├── state.py # Global singleton SessionState ├── core/ │ ├── models.py # Symbol, ParsedFile, CodebaseIndex, Memory │ ├── graph_models.py # UniversalNode, Relationship │ ├── interfaces.py # IParser, IEngine protocols │ └── exceptions.py # NexusException hierarchy ├── parsing/ │ ├── treesitter_parser.py # Symbol extraction (parallel) │ ├── astgrep_parser.py # Structural graph extraction (sequential) │ ├── language_registry.py # 25+ language definitions │ └── file_watcher.py # Debounced watchdog for live reindex ├── engines/ │ ├── vector_engine.py # LanceDB cosine similarity search │ ├── bm25_engine.py # LanceDB native FTS (Tantivy) │ ├── graph_engine.py # rustworkx PyDiGraph with RLock │ ├── fusion.py # Reciprocal Rank Fusion │ └── reranker.py # FlashRank (optional, graceful degradation) ├── indexing/ │ ├── pipeline.py # 8-step indexing pipeline │ ├── embedding_service.py # ONNX Runtime, GPU/MPS auto-detect │ ├── parallel_indexer.py # ThreadPool over files │ └── chunker.py # Symbol → CodeChunk with deterministic IDs ├── memory/ │ └── memory_store.py # LanceDB-backed memory, TTL, 6 types ├── analysis/ │ └── code_analyzer.py # Cyclomatic/cognitive complexity, smells ├── security/ │ ├── permissions.py # READ/MUTATE/WRITE tool categories │ └── rate_limiter.py # Token-bucket, per-tool, thread-safe └── middleware/ └── audit.py # Structured audit logs, correlation IDs, field redaction ``` ### 添加新工具 1. 在 `server.py` 中添加带有 `@mcp.tool()` 装饰器的处理函数 2. 为任何新输入添加内联验证（`server.py` 中的 `_validate_*` 辅助函数） 3. 在 `security/permissions.py` 中添加权限类别 4. 在 `tests/` 中编写测试 5. 更新 `self_test/demo_mcp.py` 以测试该工具 ### 添加新语言 1. 在 `parsing/language_registry.py` 中添加带有 tree-sitter 语法的条目 2. 在 `parsing/astgrep_parser.py` 中添加用于调用/导入提取的结构化模式 3. 在 `tests/fixtures/` 中添加测试夹具 ## 自测 验证你的安装是否端到端地测试了所有 10 个工具： ``` python self_test/demo_mcp.py # built-in sample project python self_test/demo_mcp.py /path/to/project # your own codebase ``` 预期输出：所有 10 个工具均被执行，并显示每个工具的通过/失败情况及摘要。 ## 已知限制 - **顺序图解析：** ast-grep 顺序运行（而非并行），以保持调用图的一致性。这是大型代码库上的主要索引瓶颈。 - **bge-small-en 使用 PyTorch：** 轻量级模型使用的是 PyTorch 而非 ONNX，因此它无法像 jina-code 那样享受到约 50 MB 内存占用的优势。 - **无增量图更新：** 增量重建索引时图会被完整重建（在代码块级别，仅向量/BM25 是增量的）。 - **无 SSE 传输：** 目前仅支持 stdio 传输。 - **语言覆盖率：** 支持 25+ 种语言，但对于 Python、TypeScript、JavaScript、Go 和 Rust，结构化关系提取（调用者/被调用者）最为准确。其他语言可能存在图边缺失的情况。 - **仅限静态调用图：** `find_callers`/`find_callees`/`impact` 是通过静态解析构建的，而非运行时追踪 —— 动态分发、猴子补丁以及通过回调/闭包/反射进行的调用不会显示为边。在高度动态的代码中，请将 `impact` 视为影响范围的下限。 - **自动重新索引存在检测延迟：** 启用文件监视器（默认）的情况下，编辑操作会在短暂的防抖动后被捕获，并且 `status()`/`search()` 会运行一个有节流限制的过期检查作为兜底保障 —— 并非实时的、基于每次调用的新鲜度保证。 ## 架构决策记录 关键决策已记录在 [docs/adr/](docs/adr/) 中： | ADR | 决策 | |-----|----------| | [ADR-001](docs/adr/ADR-001-single-mcp-consolidation.md) | 将两个 MCP server 合并为一个 | | [ADR-002](docs/adr/ADR-002-lancedb-over-chromadb.md) | 选择 LanceDB 而非 ChromaDB | | [ADR-003](docs/adr/ADR-003-onnx-runtime-over-pytorch.md) | Embeddings 选择 ONNX Runtime 而非 PyTorch | | [ADR-004](docs/adr/ADR-004-bge-small-default-model.md) | bge-small-en 作为默认 embedding 模型 | | [ADR-005](docs/adr/ADR-005-dual-parser-strategy.md) | 双解析器：tree-sitter + ast-grep | | [ADR-006](docs/adr/ADR-006-rustworkx-graph-engine.md) | 使用 rustworkx 进行图算法处理 | | [ADR-007](docs/adr/ADR-007-lancedb-schema-design.md) | LanceDB 的 12 列 PyArrow schema | | [ADR-008](docs/adr/ADR-008-code-chunk-strategy.md) | 带有确定性 ID 的基于符号的分块 | | [ADR-009](docs/adr/ADR-009-indexing-pipeline-architecture.md) | 8 步索引流水线 | | [ADR-010](docs/adr/ADR-010-graph-tools-api-design.md) | 图工具 API：序列化、歧义处理 | | [ADR-011](docs/adr/ADR-011-hardening-decisions.md) | 优雅关闭、损坏恢复、JSON 日志记录 | | [ADR-012](docs/adr/ADR-012-tool-permission-model.md) | READ/MUTATE/WRITE 权限类别 | | ~~[ADR-013](docs/adr/ADR-013-pydantic-schemas.md)~~ | Pydantic v2 I/O schema —— 被 ADR-016 取代（从未接入，已删除） | | [ADR-014](docs/adr/ADR-014-rate-limiting.md) | 令牌桶速率限制（默认关闭） | | [ADR-015](docs/adr/ADR-015-auto-watch-and-staleness-detection.md) | 自动监视 + 有节流限制的过期检测 | | [ADR-016](docs/adr/ADR-016-remove-unused-pydantic-schemas.md) | 移除未使用的 Pydantic schema（取代 ADR-013） | | [ADR-017](docs/adr/ADR-017-tool-consolidation.md) | 工具整合 15→10，动作感知的权限类别 | ## 文档 - [安装指南](docs/INSTALLATION.md) — 前置条件、特定客户端的设置、故障排除 - [架构](docs/ARCHITECTURE.md) — 数据流、组件设计、内存预算分析 - [使用指南](docs/USAGE_GUIDE.md) — 带有示例的完整工具参考 - [开发者指南](docs/DEVELOPER_GUIDE.md) — 贡献、添加工具/引擎/语言 - [研究笔记](docs/RESEARCH.md) — 库评估和技术深入分析 ## 致谢 Nexus-MCP 整合了两个早期的开源项目： - **[CodeGrok MCP](https://github.com/shreyasjagannath/CodeGrok_mcp)** 作者 [rdondeti](https://github.com/rdondeti) (Ravitez Dondeti, MIT) — 贡献了符号提取流水线、embedding 服务、并行索引器、核心数据模型和记忆检索系统。 - **[code-graph-mcp](https://github.com/entrepeneur4lyf/code-graph-mcp)** 作者 [entrepeneur4lyf](https://github.com/entrepeneur4lyf) — 贡献了 ast-grep 结构化解析器、rustworkx 图引擎、复杂度分析和关系提取。 源文件在其模块的 docstrings 中保留了“Ported from”的署名。有关合并的理由，请参阅 [ADR-001](docs/adr/ADR-001-single-mcp-consolidation.md)。 ## 许可证 MIT — 详情请参阅 [LICENSE](LICENSE)。

标签：AI编程助手, MCP服务, Python, 代码图谱, 代码智能, 无后门, 本地部署, 语义搜索, 逆向工具