umbrella22/xuanling

XuanLing MCP

XuanLing MCP 是一个面向编码代理的跨平台本地 Model Context Protocol 服务器。它通过 stdio 暴露 42 个类型化工具，用于文件系统操作、进程执行、项目发现、持久化记忆、工件以及长时间运行的会话。

该服务器专为需要确定性 schema、结构化失败、显式文件系统能力以及不会静默成为规范状态的记忆写入的主机而设计。

亮点

- 类型化文件系统操作，支持严格编辑、SHA-256 前置条件、分页搜索、可恢复读取以及显式输出预算。
- 提案优先的 Memory v2，具有不可变记录版本、显式审查、项目/工作区作用域隔离以及确定性词法召回。
- 直接进程执行，使用程序 + argv 且不经过隐式 shell，取消操作会应用于后代进程树。
- 选择性工具配置文件，使每个主机仅暴露其所需的能力族。
- 原生 npm 分发，适用于 macOS、Linux 和 Windows，无需 postinstall 编译或远程二进制下载。
- 稳定的 MCP 契约，由协议、黄金、持久化、重启以及跨平台测试套件提供支持。

安装

npm 启动器需要 Node.js 18.17 或更高版本，并会为当前平台安装匹配的原生二进制文件。

npm install --global @xuanling-rs/xuanling-mcp@0.4.0
xuanling-mcp --version

MCP 客户端可以在不进行全局安装的情况下固定同一版本：

{
"mcpServers": {
"xuanling": {
"command": "npx",
"args": [
"-y",
"@xuanling-rs/xuanling-mcp@0.4.0",
"--workspace-root",
"/absolute/path/to/project",
"--tool-profile",
"core",
"--tool-profile",
"fs",
"--tool-profile",
"memory"
]
}
}
}

固定包版本可使已发现的 MCP schema 在活动项目中保持稳定。当主机频繁启动服务器时，全局或项目本地安装可避免包解析步骤。

支持的平台

| 操作系统 | 架构 | 运行时要求 |
| --- | --- | --- |
| macOS | Apple Silicon (arm64) | 原生二进制文件 |
| Linux | x64 | glibc 2.35 或更高版本 |
| Windows | x64 | MSVC 运行时 |

不受支持的操作系统、CPU 和 libc 组合会以显式的启动器错误失败。该包在安装期间不会编译 Rust 或下载可执行文件。启动器会在启动服务器之前验证包元数据和原生二进制文件的 SHA-256。

从源码构建

源码构建需要 Rust 1.98。

cargo build --locked --release -p xuanling-mcp
./target/release/xuanling-mcp --workspace-root /absolute/path/to/project

工具配置文件

默认目录包含全部 42 个工具。重复使用 --tool-profile 可组合更小、更稳定的分组：

| 配置文件 | 工具 | 能力族 |
| --- | ---: | --- |
| core | 3 | 系统和可移植路径检查 |
| fs | 16 | 文件系统读取、搜索、预览和变更 |
| process | 5 | 直接进程以及项目检测/执行 |
| memory | 9 | Memory v2 提案、审查、召回和反馈 |
| advanced | 9 | 工件、ChangeSet、流水线和会话 |
| all | 42 | 完整目录；在未提供配置文件时也是默认值 |

当 all 与其他配置文件组合时，all 优先。发现和调度使用相同的选择，因此隐藏工具无法按名称调用。

目录传输

tools/list 以每页八个工具的方式返回选定的静态目录。跟随不透明的 nextCursor，直到它不存在为止；格式错误、过期或跨目录的游标会以 JSON-RPC -32602 和 data.reason: "invalid_cursor" 失败，而不是从第一页重新开始。初始化元数据发布 xuanling.tool_count 以表示完整的过滤后目录，并发布 xuanling.catalog_sha256 作为每个模型可见定义的稳定摘要。

目录在服务器进程期间不会发生变化，因此 XuanLing 有意不声明 tools.listChanged。分页限制了 MCP 传输帧；完整目录是否进入模型上下文仍由 Host 投影决定。

文件系统安全

当两个能力标志都未提供时，文件系统访问不受限制。生产主机配置应至少声明一个根：

- --workspace-root  可重复，授予根内的读/写/删除访问权限以及子进程工作目录准入。
- --read-root  可重复，授予读/列出/搜索/哈希访问权限，同时拒绝写入、删除和子进程工作目录。
- 仅提供 --read-root 会创建只读部署。

变更工具支持显式的前像检查。对于整文件替换和精确编辑，使用 expected_sha256；对于 fs_patch，使用 expected_preimage_sha256。如果文件在读取后发生变化，会在写入前报告冲突。

支持窗口的工具接受显式输出选择器，例如 {"mode":"bounded","max_bytes":65536}。被截断的读取和搜索会返回类型化游标或恢复令牌；它们不会静默丢弃剩余结果。

文件系统能力控制 XuanLing 打开的路径。它不是针对任意子程序的 OS 沙箱：主机批准和进程隔离仍是 MCP 主机及其执行环境的责任。

Memory v2

Memory v2 将提案与规范记录分离：

1. memory_search 和 memory_get 检查活动记录。
2. memory_candidate_create、memory_candidate_replace 或 memory_candidate_archive 创建待处理提案。
3. memory_review 接受或拒绝特定提案修订。只有被接受的审查才会原子性地推进规范记录头。
4. 不可变版本、终态审查和仅追加反馈保留
用于审计和确定性恢复的历史记录。

作用域对 global、project 和 workspace 使用严格的标记值。
祖先搜索仅在请求时遵循 workspace -> project -> global；
永远不会搜索同级项目。

召回在 SQLite FTS5（unicode61
和 trigram）上使用确定性的词法查询计划、多通道融合、可见性过滤和稳定的重排序。
默认版本不需要也不下载嵌入模型，并且
不会为召回执行网络访问。

默认数据库为 ~/.xuanling/memory.db。使用
--memory-db  覆盖它，并可选择提供 --default-namespace 。
stdio 服务器仅在首次调用有效的
Memory 工具时解析并打开该数据库；初始化、发现、非 memory 工具以及格式错误的
Memory 请求不会创建或迁移它。Memory 初始化失败
不会禁用非 memory 工具；memory 调用会返回结构化的不可用
错误。

维护

规范数据可以导出、导入到空数据库，并用于
重建派生的搜索投影：

xuanling-mcp --memory-db /path/to/memory.db memory export --output backup.jsonl
xuanling-mcp --memory-db /path/to/empty.db memory import --input backup.jsonl
xuanling-mcp --memory-db /path/to/memory.db memory rebuild-index

导出会写入带版本号的 JSONL 流，其中包含计数和 SHA-256 尾部。
导入会在一次事务性写入之前验证完整流，并且
rebuild-index 永远不会更改规范行。

DeepSeek Harness

从仓库 URL 进行对话式安装

将 https://github.com/umbrella22/xuanling 复制到 DeepSeek Harness (DSH)
聊天中，并要求它安装 XuanLing DSH 集成。DSH 将读取
仓库自有的
安装器 Skill，询问要使用哪个
配置文件和预设，显示确切的冻结 npm 版本和包
变更以供确认，然后通过 dsh plugin 安装并验证它们。

这是一个由模型编排的工作流：DSH 本身不会安装任意
URL。在需要时，agent 会在新的
临时检出中获取固定的仓库 ref，仅将其用于有界的文档发现，并在提出第一个问题之前
移除该检出。路径发现可能会列出已跟踪的
路径，或运行一个其模型可见输出仅为路径名的定位器；源
代码和清单正文永远不会进入模型上下文。唯一加载的内容是
允许列表中的根 README、安装器 Skill，以及可选的 DSH
集成指南。agent 永远不会执行仓库代码或从
检出安装；配置文件包仍然仅来自公共 npm registry。
当交互式
问题或仓库访问不可用时，下面的手动集成指南仍然是后备方案。

integrations/deepseek-harness 包含
针对附加式 Memory 工具、附加式或替换式文件系统工具、schema 投影、严格覆盖策略以及两个按需工作流 Skill 的宿主专属 bundle。该集成保持在 Rust 工具契约之外，使 DeepSeek Harness 专属的路由与策略能够演进，而无需更改面向其他宿主的 MCP 目录。

随附的 DSH 运行时 bundle 使用宿主侧惰性投影：它们缓存每个 MCP 目录页，但初始仅暴露 mcp_catalog__xuanling。模型搜索该紧凑控制项，并在普通 mcp__xuanling__* 调用之前激活确切的原始名称。这降低了初始 schema 成本，而不会将 MCP 分页或 list_changed 视为能力选择。

有关 bundle 选择、安装和运行时配置，请参阅
DeepSeek Harness 集成指南。

仓库布局

| 路径 | 用途 |
| --- | --- |
| crates/xuanling-toolkit | 跨平台文件系统、进程、项目、会话和工件实现。 |
| crates/xuanling-memory | Memory v2 生命周期、SQLite 持久化、词法检索和 JSONL 维护。 |
| crates/xuanling-mcp | stdio MCP 服务器、类型化处理器、配置文件和协议契约。 |
| integrations | 可安装的宿主专属适配器、策略和 Skill。 |
| npm | Node 启动器、原生包暂存、完整性检查和发布自动化。 |
| test | 仅限仓库的测试夹具、探针、评估覆盖层和验收报告。 |
| docs | 已接受的决策、架构、集成契约和执行记录。 |

当前文档索引位于
docs/README.md。仓库来源和分离工作区边界记录在
docs/repository-boundary.md。

开发

仓库开发需要 Rust 1.98、Node.js 22.14 或更高版本，以及 npm
11.5.1 或更高版本。

cargo fmt -p xuanling-toolkit -p xuanling-memory -p xuanling-mcp -- --check
cargo check -p xuanling-toolkit -p xuanling-memory -p xuanling-mcp --all-targets
cargo clippy -p xuanling-toolkit -p xuanling-memory -p xuanling-mcp --all-targets -- -D warnings

cargo test -p xuanling-toolkit --features test-fixtures --test contract
cargo test -p xuanling-memory --test contract
cargo test -p xuanling-mcp --test protocol
cargo test -p xuanling-mcp --test golden

npm --prefix npm run check
npm --prefix npm run check:docs
npm --prefix npm test

Non-gating, single-process benchmark for the complete paginated catalog.
cargo build --locked --release -p xuanling-mcp
npm --prefix npm run benchmark:catalog -- --binary target/release/xuanling-mcp

完整的宿主契约和错误映射记录在
MCP 集成指南中。npm 包
组装和发布记录在 npm/README.md中。

许可证

根据 MIT 许可证授权。