@xuanling-rs/xuanling-mcp 0.6.0 → 0.7.0

package/README-ZH.md

@@ -2,20 +2,64 @@
 
 [English](README.md) | 简体中文
 
-`@xuanling-rs/xuanling-mcp` 是面向编码 Agent 的跨平台本地 Model Context Protocol 服务器。它通过
-stdio 提供 42 个类型化工具，覆盖文件系统操作、进程执行、项目探测、Artifact、Session 和
-proposal-first SQLite Memory。
+`@xuanling-rs/xuanling-mcp` 是面向编码 Agent 的本地跨平台 Model Context Protocol
+（MCP）服务器。它通过 stdio 提供 43 个类型化工具，覆盖文件系统操作、进程与项目执行、
+Artifact、Session 和 proposal-first 的 Memory v2，并提供确定性 schema、结构化失败和显式
+文件系统边界。
+
+## 这是什么、为什么用它
+
+XuanLing 让 MCP Host 获得一个本地、可预测的统一工具面，而不必为每个平台维护一套脚本。
+它的主要特点：
+
+- **43 个类型化工具，可按 profile 组合。** Host 可以暴露完整 catalog，也可以只暴露需要
+  的工具族；未暴露的工具无法按名称调用。
+- **文件操作带显式安全前置条件。** 修改类工具支持 SHA-256 preimage 校验；支持窗口输出
+  的读取和搜索返回类型化 cursor，而不是静默截断；路径访问由显式 capability root 控制。
+- **proposal-first 的 Memory v2。** Memory 写入先停留在 pending proposal，只有显式
+  `memory_review` 决策才会推进不可变 canonical record，Agent 无法静默改写持久化 Memory。
+- **直接的进程与项目执行。** 命令以 program + argv 形式运行，不经过隐式 shell；取消操作
+  会作用于整个子进程树。
+- **原生 npm 分发。** 安装过程不运行 `postinstall`、不编译 Rust、不从远程 URL 下载
+  binary；启动器会校验平台 package metadata 和原生 binary 的 SHA-256。
+
+**该用哪个？** 当 MCP Host 可以直接启动 stdio 服务器时，使用
+`@xuanling-rs/xuanling-mcp`。使用 DeepSeek Harness 时，请安装对应 bundle：推荐用
+`@xuanling-rs/xuanling-dsh-memory` 获得 Memory v2 profile；需要增量挂载完整 catalog 用
+`@xuanling-rs/xuanling-dsh-tools`；需要替换 DSH 文件系统工具用
+`@xuanling-rs/xuanling-dsh-tools-replace`。`@xuanling-rs/xuanling-dsh-skills` 只增加
+工作流 Skill，不挂载 MCP 工具。[DeepSeek Harness 集成 README](https://github.com/umbrella22/xuanling/blob/main/integrations/deepseek-harness/README-ZH.md)
+说明了 bundle 的选择与安装。
+
+## 环境要求
+
+- Node.js 18.17 或更高版本。
+- 支持 stdio 的 MCP Host。
+- 受支持平台之一：
 
-## 安装
+| 操作系统 | 架构 | 运行时要求 |
+| --- | --- | --- |
+| macOS | Apple Silicon（`arm64`） | 原生二进制 |
+| Linux | `x64` | glibc 2.35 或更高版本 |
+| Windows | `x64` | MSVC runtime |
+
+不需要 Rust 工具链或编译器。不支持的 OS、CPU 或 libc 组合会由启动器返回明确错误。
 
-启动器要求 Node.js 18.17 或更高版本。
+## 安装
 
 ```sh
-npm install --global @xuanling-rs/xuanling-mcp@0.6.0
+npm install --global @xuanling-rs/xuanling-mcp@0.7.0
 xuanling-mcp --version
 ```
 
-MCP Client 也可以使用 `npx` 固定版本：
+频繁启动服务器时，全局安装或项目内安装可以省去 package 解析步骤。偏好按需执行的 Host
+可以使用[快速开始](#快速开始)中的固定版本 `npx` 配置。
+
+固定精确版本可以让活动项目发现的 MCP 合同保持稳定。已发布的 npm 版本不可变。
+
+## 快速开始
+
+把服务器加入 MCP Client 配置：
 
 ```json
 {
@@ -24,88 +68,139 @@ MCP Client 也可以使用 `npx` 固定版本：
       "command": "npx",
       "args": [
         "-y",
-        "@xuanling-rs/xuanling-mcp@0.6.0",
+        "@xuanling-rs/xuanling-mcp@0.7.0",
         "--workspace-root",
-        "/absolute/path/to/project",
-        "--tool-profile",
-        "core",
-        "--tool-profile",
-        "fs",
-        "--tool-profile",
-        "memory"
+        "/absolute/path/to/project"
       ]
     }
   }
 }
 ```
 
-固定版本可以保持活动项目发现的 MCP 合同稳定。频繁启动服务器时，全局安装或项目内安装可以
-省去 package 解析过程。
+重启 Host，让它启动服务器并完成 MCP `initialize`。初始化 metadata 会发布所选 catalog
+的 `xuanling.tool_count` 和模型可见定义的 `xuanling.catalog_sha256`。重复添加
+`--tool-profile` 可以让服务器只暴露 Host 需要的工具族；见[工具 Profile](#工具-profile)。
 
-## 支持平台
+## 使用与配置
 
-| 操作系统 | 架构 | 运行时要求 |
-| --- | --- | --- |
-| macOS | Apple Silicon (`arm64`) | 原生二进制 |
-| Linux | `x64` | glibc 2.35 或更高版本 |
-| Windows | `x64` | MSVC runtime |
-
-不支持的 OS、CPU 或 libc 组合会返回明确错误。安装过程不编译 Rust、不运行 `postinstall`，
-也不下载可执行文件。启动器会在启动前校验 package metadata 和所选原生 binary 的 SHA-256。
+### 工具 Profile
 
-## 工具 Profile
-
-默认 catalog 暴露全部 42 个工具。重复使用 `--tool-profile` 可以组合多个较小的工具组：
+默认 catalog 暴露全部 43 个工具。重复使用 `--tool-profile` 可以组合较小的工具组：
 
 | Profile | 工具数 | 能力族 |
 | --- | ---: | --- |
 | `core` | 3 | 系统信息与可移植路径检查 |
-| `fs` | 16 | 文件读取、搜索、预览与修改 |
+| `fs` | 17 | 文件读取、搜索、预览与修改 |
 | `process` | 5 | 直接进程执行与项目探测/执行 |
 | `memory` | 9 | Memory v2 提案、评审、召回与反馈 |
 | `advanced` | 9 | Artifact、ChangeSet、Pipeline 与 Session |
-| `all` | 42 | 完整 catalog 和默认选择 |
+| `all` | 43 | 完整 catalog 和默认选择 |
+
+`all` 与其他 profile 同时出现时优先。发现与调用使用同一份选择，未暴露的工具无法按名称
+调用。修改 profile 后需要重启服务器进程。
 
-## 文件系统能力
+### 文件系统边界
 
 - `--workspace-root <PATH>` 可重复，允许读取、写入、删除，并允许在该 root 内设置子进程
   工作目录。
 - `--read-root <PATH>` 可重复，只允许读取、列出、搜索和计算 hash；拒绝写入、删除和设置
   子进程工作目录。
-- 两个 flag 都未提供时，XuanLing 文件系统访问不受限制。仅提供 `--read-root` 时为只读部署。
+- 两个 flag 都未提供时，XuanLing 文件系统访问不受限制。仅提供 `--read-root` 时为只读
+  部署。
+- 在配置了 capability root 的部署中，`--base-dir` 默认取第一个 `--workspace-root`；
+  `--base-dir` 只是相对路径解析上下文，不是 sandbox。
 
 修改类工具支持 SHA-256 preimage 校验。支持窗口输出的工具可以设置显式 byte budget，并返回
 类型化 cursor 或 resume token，不会静默截断结果。
 
 路径能力不是子进程的 OS sandbox。工具审批和恶意进程隔离由 MCP Host 与执行环境负责。
 
-## Memory v2
+### Memory v2
+
+Memory v2 把提案（proposal）与 canonical record 分开：
 
-Create、replace 和 archive 调用只产生 pending proposal。只有显式 `memory_review` 决策才能
-原子推进不可变的 canonical record。严格的 `global`、`project` 和 `workspace` scope 防止
-sibling project 之间发生召回泄漏。
+1. `memory_search` 与 `memory_get` 检查 active record。
+2. `memory_candidate_create`、`memory_candidate_replace` 和
+   `memory_candidate_archive` 产生 pending proposal。
+3. `memory_review` 接受或拒绝特定 proposal revision；只有 review 被接受才会原子推进
+   canonical record head。
+4. 不可变版本、终态 review 和 append-only feedback 保留审计与恢复所需的历史。
+
+`global`、`project` 和 `workspace` scope 严格执行；sibling project 之间不会互相
+召回。召回使用 SQLite FTS5 上的确定性词法查询计划，不要求也不下载 embedding 模型。默认
+数据库为 `~/.xuanling/memory.db`；可用 `--memory-db <PATH>` 覆盖。服务器在第一次有效
+Memory 工具调用时才惰性打开数据库，因此启动、discovery 和非 Memory 工具不会创建或迁移它。
+
+canonical 数据可以导出、导入空数据库，并用于重建派生搜索投影：
+
+```sh
+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
+```
 
-召回使用确定性 SQLite FTS5 query plan 和稳定词法重排，不要求或下载 embedding 模型。默认
-数据库路径为 `~/.xuanling/memory.db`；使用 `--memory-db <PATH>` 可以覆盖该路径。
+导出会写入带版本的 JSONL；导入会先完整校验，再以单个事务写入；`rebuild-index` 不会改变
+canonical row。
 
-## Server 选项
+### 服务器选项
 
 ```text
---base-dir <PATH>                  相对路径解析上下文
---workspace-root <PATH>            可重复的读写 capability root
+--base-dir <PATH>                  相对工具路径的解析上下文（不是 sandbox）
+--workspace-root <PATH>            可重复的读写删除 capability root
 --read-root <PATH>                 可重复的只读 capability root
---memory-db <PATH>                 共享 SQLite Memory 数据库
---default-namespace <VALUE>        默认 Memory namespace
+--memory-db <PATH>                 共享 SQLite Memory 数据库（默认：~/.xuanling/memory.db）
+--default-namespace <VALUE>        Memory 请求省略 namespace 时使用的默认值
 --sqlite-busy-timeout-ms <NUMBER>  SQLite busy timeout（默认 5000）
 --tool-profile <PROFILE>           可重复工具组；默认 all
---compat-lenient-object-params     受影响 Host 的可选兼容模式
+--compat-lenient-object-params     面向会把 object 参数转成字符串的 Host 的可选兼容模式
 ```
 
-## 源码与文档
+`xuanling-mcp memory export|import|rebuild-index` 是维护子命令，不会启动 stdio 服务器
+会话。
+
+## 工作原理
+
+- npm package 是 Node.js 启动器：解析平台原生 package，校验版本 metadata 与 binary
+  SHA-256，然后把 argv、stdio、signal 和退出状态透传给原生服务器。
+- 原生服务器只通过 stdin/stdout 承载 MCP，不监听网络端口，也不发起远程调用。
+- 工具 catalog 在服务器进程生命周期内保持不变。`tools/list` 使用不透明 cursor 分页，
+  Host 必须持续跟随 `nextCursor` 直到其消失。
+- Memory 是本地 SQLite 数据库，惰性打开；召回过程不访问网络。
+
+## 兼容性与限制
+
+- 受支持的 npm 目标为 macOS Apple Silicon、glibc 2.35 或更高版本的 Linux x64，以及
+  Windows x64 MSVC。Intel macOS、ARM Linux、glibc 2.34 及更早版本、musl Linux 和
+  ARM Windows 不在发布范围内。
+- 支持的 MCP 协议版本为 `2024-11-05`、`2025-03-26`、`2025-06-18` 和
+  `2025-11-25`。
+- 0.7.0 的原生 binary 没有 Developer ID 或 Authenticode 签名；package 完整性合同由
+  npm provenance 和启动器的 SHA-256 校验保证。
+- 文件系统 capability 不是 XuanLing 工具所启动进程的 OS sandbox。
+- catalog 在服务器进程内不变，服务器不会声明 `tools.listChanged`。修改 profile 或
+  catalog 配置后需要重启服务器。
+- Memory 在每个服务器进程中使用单个本地 SQLite 数据库，需要可写的数据库路径，或可解析的
+  `HOME`/`USERPROFILE`。
+- 服务器只使用 stdio transport，不提供 HTTP 或远程模式。
+
+## 故障排查
+
+| 现象 | 原因与处理 |
+| --- | --- |
+| `Unsupported platform: <os>/<arch>` | 该目标未发布。请使用 macOS Apple Silicon、glibc 2.35 或更高版本的 Linux x64，或 Windows x64。 |
+| `Unsupported Linux libc` 或 `Unsupported Linux glibc` | XuanLing 只发布 glibc 构建，并要求 glibc 2.35 或更高版本。 |
+| `Missing optional dependency` 或 `Native binary checksum mismatch` | 重新安装固定版本，例如 `npm install --global @xuanling-rs/xuanling-mcp@0.7.0`。已发布的 npm 版本不可变。 |
+| Memory 工具报告 `memory store unavailable` 或 `cannot resolve the default memory DB path` | 传入可写的 `--memory-db <PATH>`，或设置 `HOME`/`USERPROFILE` 以便解析默认的 `~/.xuanling/memory.db`。非 Memory 工具仍可正常使用。 |
+| Host 看到的工具比预期少 | 当前启用了 `--tool-profile` 选择。组合多个 profile 或使用 `--tool-profile all`，然后重启服务器进程。 |
+| Host 在 `initialize` 前退出 | 检查 Node.js 版本（18.17 或更高）以及 Host 的 stdio 启动配置。 |
+
+## 链接
 
 - 源码：<https://github.com/umbrella22/xuanling>
-- 集成指南：<https://github.com/umbrella22/xuanling/blob/main/docs/guides/xuanling-mcp-integration.md>
-- DeepSeek Harness 集成：<https://github.com/umbrella22/xuanling/tree/main/integrations/deepseek-harness>
+- 产品文档：<https://github.com/umbrella22/xuanling/blob/main/README-ZH.md>
+- DeepSeek Harness 集成：<https://github.com/umbrella22/xuanling/blob/main/integrations/deepseek-harness/README-ZH.md>
+- Changelog：<https://github.com/umbrella22/xuanling/blob/main/CHANGELOG.md>
 - Issues：<https://github.com/umbrella22/xuanling/issues>
+- npm package：<https://www.npmjs.com/package/@xuanling-rs/xuanling-mcp>
 
 本项目采用 [MIT License](LICENSE)。

package/README.md

@@ -2,21 +2,75 @@
 
 English | [Simplified Chinese](README-ZH.md)
 
-`@xuanling-rs/xuanling-mcp` is a cross-platform local Model Context Protocol server for
-coding agents. It exposes 42 typed tools over stdio for filesystem work,
-process execution, project discovery, artifacts, sessions, and proposal-first
-SQLite memory.
+`@xuanling-rs/xuanling-mcp` is a local, cross-platform Model Context Protocol
+(MCP) server for coding agents. It exposes 43 typed tools over stdio for
+filesystem work, process and project execution, artifacts, sessions, and
+proposal-first Memory v2, with deterministic schemas, structured failures, and
+explicit filesystem boundaries.
+
+## What and Why
+
+XuanLing gives an MCP host one local, predictable tool surface instead of a
+collection of OS-specific scripts. Its main properties are:
+
+- **43 typed tools with combinable profiles.** A host can expose the complete
+  catalog or only the families it needs, and a hidden tool cannot be called by
+  name.
+- **Filesystem work with explicit safety preconditions.** Mutations support
+  SHA-256 preimage checks, window-capable reads and searches return typed
+  cursors instead of silently truncating, and path access is controlled by
+  explicit capability roots.
+- **Proposal-first Memory v2.** Memory writes stay pending until an explicit
+  `memory_review` decision advances an immutable canonical record, so an agent
+  cannot silently rewrite persistent memory.
+- **Direct process and project execution.** Commands run as program + argv
+  without an implicit shell, and cancellation applies to the descendant process
+  tree.
+- **Native npm distribution.** Installation runs no `postinstall`, compiles no
+  Rust, and downloads no binary from a remote URL; the launcher verifies the
+  platform package metadata and the native binary's SHA-256.
+
+**Which package do I need?** Use `@xuanling-rs/xuanling-mcp` when an MCP host can
+launch a stdio server directly. For DeepSeek Harness, install a bundle instead:
+`@xuanling-rs/xuanling-dsh-memory` for the recommended Memory v2 profile,
+`@xuanling-rs/xuanling-dsh-tools` for the additive full catalog, or
+`@xuanling-rs/xuanling-dsh-tools-replace` to replace DSH filesystem tools.
+`@xuanling-rs/xuanling-dsh-skills` adds workflow Skills and no MCP tools. The
+[DeepSeek Harness integration README](https://github.com/umbrella22/xuanling/blob/main/integrations/deepseek-harness/README.md)
+covers bundle selection and setup.
+
+## Requirements
+
+- Node.js 18.17 or newer.
+- An MCP host that can start a stdio server.
+- One of the supported platforms:
 
-## Install
+| Operating system | Architecture | Runtime requirement |
+| --- | --- | --- |
+| macOS | Apple Silicon (`arm64`) | native binary |
+| Linux | `x64` | glibc 2.35 or newer |
+| Windows | `x64` | MSVC runtime |
 
-The launcher requires Node.js 18.17 or newer.
+No Rust toolchain or compiler is required. Unsupported OS, CPU, or libc
+combinations fail with an explicit launcher error.
+
+## Install
 
 ```sh
-npm install --global @xuanling-rs/xuanling-mcp@0.6.0
+npm install --global @xuanling-rs/xuanling-mcp@0.7.0
 xuanling-mcp --version
 ```
 
-MCP clients can also pin the version with `npx`:
+A global or project-local installation avoids the package resolution step when
+the host starts the server frequently. Hosts that prefer on-demand execution can
+use the pinned `npx` configuration in [Quickstart](#quickstart).
+
+Pinning the exact version keeps the discovered MCP contract stable for an
+active project. Published npm versions are immutable.
+
+## Quickstart
+
+Add the server to the MCP client configuration:
 
 ```json
 {
@@ -25,98 +79,157 @@ MCP clients can also pin the version with `npx`:
       "command": "npx",
       "args": [
         "-y",
-        "@xuanling-rs/xuanling-mcp@0.6.0",
+        "@xuanling-rs/xuanling-mcp@0.7.0",
         "--workspace-root",
-        "/absolute/path/to/project",
-        "--tool-profile",
-        "core",
-        "--tool-profile",
-        "fs",
-        "--tool-profile",
-        "memory"
+        "/absolute/path/to/project"
       ]
     }
   }
 }
 ```
 
-Pinning the version keeps the discovered MCP contract stable for an active
-project. A global or project-local installation avoids the package resolution
-step when the host starts the server frequently.
+Restart the host so it launches the server and completes MCP `initialize`.
+Initialization metadata publishes `xuanling.tool_count` for the selected catalog
+and `xuanling.catalog_sha256` for the model-visible definitions. Add repeatable
+`--tool-profile` entries to expose only the families the host needs; see
+[Tool profiles](#tool-profiles).
 
-## Supported Platforms
+## Usage and Configuration
 
-| Operating system | Architecture | Runtime requirement |
-| --- | --- | --- |
-| macOS | Apple Silicon (`arm64`) | native binary |
-| Linux | `x64` | glibc 2.35 or newer |
-| Windows | `x64` | MSVC runtime |
+### Tool profiles
 
-Unsupported OS, CPU, and libc combinations fail with an explicit error. The
-package does not compile Rust, run a `postinstall` script, or download
-executables. The launcher validates package metadata and the selected native
-binary's SHA-256 before startup.
-
-## Tool Profiles
-
-The default catalog exposes all 42 tools. Repeat `--tool-profile` to combine
+The default catalog contains all 43 tools. Repeat `--tool-profile` to combine
 smaller groups:
 
 | Profile | Tools | Capability family |
 | --- | ---: | --- |
 | `core` | 3 | system and portable path inspection |
-| `fs` | 16 | filesystem read, search, preview, and mutation |
+| `fs` | 17 | filesystem read, search, preview, and mutation |
 | `process` | 5 | direct processes and project detection/execution |
 | `memory` | 9 | Memory v2 proposal, review, recall, and feedback |
 | `advanced` | 9 | artifacts, ChangeSets, pipelines, and sessions |
-| `all` | 42 | complete catalog and default selection |
+| `all` | 43 | complete catalog and default selection |
+
+`all` takes precedence when combined with another profile. Discovery and
+dispatch use the same selection, so a hidden tool cannot be called by name.
+Changing profiles requires restarting the server process.
 
-## Filesystem Capabilities
+### Filesystem boundaries
 
 - `--workspace-root <PATH>` is repeatable and grants read/write/delete access
   plus child-process working-directory admission inside the root.
 - `--read-root <PATH>` is repeatable and grants read/list/search/hash access
   while rejecting writes, deletion, and child-process working directories.
-- With neither flag, XuanLing filesystem access is unrestricted. With only
-  `--read-root`, the deployment is read-only.
+- With neither flag, XuanLing filesystem access is unrestricted. Supplying only
+  `--read-root` creates a read-only deployment.
+- In a contained deployment, `--base-dir` defaults to the first
+  `--workspace-root`; `--base-dir` is a relative-path context, not a sandbox.
 
-Mutating tools support SHA-256 preimage checks. Window-capable tools support
+Mutating tools support SHA-256 preimage checks. Window-capable tools accept
 explicit byte budgets and return typed cursors or resume tokens instead of
 silently truncating results.
 
-The pathname capability is not an OS sandbox for child programs. Tool
-approval and hostile process isolation belong to the MCP host and execution
-environment.
+The pathname capability is not an OS sandbox for child programs. Tool approval
+and hostile process isolation belong to the MCP host and execution environment.
 
-## Memory v2
+### Memory v2
 
-Create, replace, and archive calls produce pending proposals. Only an explicit
-`memory_review` decision can atomically advance an immutable canonical record.
-Strict `global`, `project`, and `workspace` scopes prevent sibling-project
-recall.
+Memory v2 separates proposals from canonical records:
+
+1. `memory_search` and `memory_get` inspect active records.
+2. `memory_candidate_create`, `memory_candidate_replace`, and
+   `memory_candidate_archive` produce pending proposals.
+3. `memory_review` accepts or rejects a specific proposal revision. Only an
+   accepted review atomically advances the canonical record head.
+4. Immutable versions, terminal reviews, and append-only feedback keep the
+   history needed for audit and recovery.
+
+`global`, `project`, and `workspace` scopes are strict; sibling projects are
+never searched. Recall uses a deterministic lexical query plan over SQLite FTS5
+and does not require or download an embedding model. The default database is
+`~/.xuanling/memory.db`; override it with `--memory-db <PATH>`. The server opens
+the database lazily on the first valid Memory tool call, so startup, discovery,
+and non-memory tools never create or migrate it.
+
+Canonical data can be exported, imported into an empty database, and used to
+rebuild the derived search projection:
+
+```sh
+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
+```
 
-Recall uses deterministic SQLite FTS5 query planning and stable lexical
-reranking. It does not require or download an embedding model. The default
-database is `~/.xuanling/memory.db`; use `--memory-db <PATH>` to override it.
+Export writes a versioned JSONL stream, import validates the complete stream
+before one transactional write, and `rebuild-index` never changes canonical
+rows.
 
-## Server Options
+### Server options
 
 ```text
---base-dir <PATH>                  Relative-path resolution context
---workspace-root <PATH>            Repeatable read/write capability root
+--base-dir <PATH>                  Base directory for relative tool paths (not a sandbox)
+--workspace-root <PATH>            Repeatable read/write/delete capability root
 --read-root <PATH>                 Repeatable read-only capability root
---memory-db <PATH>                 Shared SQLite memory database
---default-namespace <VALUE>        Default memory namespace
+--memory-db <PATH>                 Shared SQLite memory database (default: ~/.xuanling/memory.db)
+--default-namespace <VALUE>        Namespace used when a memory request omits one
 --sqlite-busy-timeout-ms <NUMBER>  SQLite busy timeout (default: 5000)
 --tool-profile <PROFILE>           Repeatable tool group; default: all
---compat-lenient-object-params     Opt-in compatibility for affected hosts
+--compat-lenient-object-params     Opt-in compatibility for hosts that stringify object parameters
 ```
 
-## Source and Documentation
+`xuanling-mcp memory export|import|rebuild-index` are maintenance subcommands;
+they do not start a stdio server session.
+
+## How it works
+
+- The npm package is a Node.js launcher. It resolves the platform-specific
+  native package, validates its version metadata and binary SHA-256, then
+  forwards argv, stdio, signals, and exit status to the native server.
+- The native server speaks MCP over stdin/stdout only. It opens no network
+  listener and makes no remote calls.
+- The tool catalog is static for the lifetime of the server process.
+  `tools/list` is paginated with opaque cursors, and the host must follow
+  `nextCursor` until it is absent.
+- Memory is a local SQLite database. It is opened lazily, and recall performs no
+  network access.
+
+## Compatibility and limits
+
+- Supported npm targets are macOS Apple Silicon, Linux x64 with glibc 2.35 or
+  newer, and Windows x64 MSVC. Intel macOS, ARM Linux, glibc 2.34 or older,
+  musl Linux, and ARM Windows are not published.
+- Supported MCP protocol revisions are `2024-11-05`, `2025-03-26`,
+  `2025-06-18`, and `2025-11-25`.
+- The native binaries in 0.7.0 are not Developer ID or Authenticode signed.
+  npm provenance and the launcher's SHA-256 check provide the package integrity
+  contract.
+- The filesystem capability is not an OS sandbox for processes started by
+  XuanLing tools.
+- The catalog does not change during a server process, and the server does not
+  advertise `tools.listChanged`. Restart the server to change profiles or
+  catalog configuration.
+- Memory is a single local SQLite database per server process. It requires a
+  writable database path or a resolvable `HOME`/`USERPROFILE`.
+- The server uses stdio transport only; there is no HTTP or remote mode.
+
+## Troubleshooting
+
+| Symptom | Cause and fix |
+| --- | --- |
+| `Unsupported platform: <os>/<arch>` | The target is not published. Use macOS Apple Silicon, Linux x64 with glibc 2.35 or newer, or Windows x64. |
+| `Unsupported Linux libc` or `Unsupported Linux glibc` | XuanLing publishes a glibc build only and requires glibc 2.35 or newer. |
+| `Missing optional dependency` or `Native binary checksum mismatch` | Reinstall the pinned version, for example `npm install --global @xuanling-rs/xuanling-mcp@0.7.0`. Published npm versions are immutable. |
+| Memory tools report `memory store unavailable` or `cannot resolve the default memory DB path` | Pass an explicit writable `--memory-db <PATH>`, or set `HOME`/`USERPROFILE` so the default `~/.xuanling/memory.db` can be resolved. Non-memory tools keep working. |
+| The host sees fewer tools than expected | A `--tool-profile` selection is active. Combine profiles or use `--tool-profile all`, then restart the server process. |
+| The host exits before `initialize` | Check the Node.js version (18.17 or newer) and the host's stdio launch configuration. |
+
+## Links
 
 - Source: <https://github.com/umbrella22/xuanling>
-- Integration guide: <https://github.com/umbrella22/xuanling/blob/main/docs/guides/xuanling-mcp-integration.md>
-- DeepSeek Harness integration: <https://github.com/umbrella22/xuanling/tree/main/integrations/deepseek-harness>
+- Product documentation: <https://github.com/umbrella22/xuanling/blob/main/README.md>
+- DeepSeek Harness integration: <https://github.com/umbrella22/xuanling/blob/main/integrations/deepseek-harness/README.md>
+- Changelog: <https://github.com/umbrella22/xuanling/blob/main/CHANGELOG.md>
 - Issues: <https://github.com/umbrella22/xuanling/issues>
+- npm package: <https://www.npmjs.com/package/@xuanling-rs/xuanling-mcp>
 
 Licensed under the [MIT License](LICENSE).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xuanling-rs/xuanling-mcp",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Cross-platform stdio MCP server for XuanLing typed filesystem, process, project, artifact, session, and memory tools.",
   "license": "MIT",
   "author": "umbrella22 and XuanLing contributors",
@@ -35,9 +35,9 @@
     "directory": "npm/packages/xuanling-mcp"
   },
   "optionalDependencies": {
-    "xuanling-mcp-darwin-arm64": "npm:@xuanling-rs/xuanling-mcp-darwin-arm64@0.6.0-darwin-arm64",
-    "xuanling-mcp-linux-x64-gnu": "npm:@xuanling-rs/xuanling-mcp-linux-x64-gnu@0.6.0-linux-x64-gnu",
-    "xuanling-mcp-win32-x64-msvc": "npm:@xuanling-rs/xuanling-mcp-win32-x64-msvc@0.6.0-win32-x64-msvc"
+    "xuanling-mcp-darwin-arm64": "npm:@xuanling-rs/xuanling-mcp-darwin-arm64@0.7.0-darwin-arm64",
+    "xuanling-mcp-linux-x64-gnu": "npm:@xuanling-rs/xuanling-mcp-linux-x64-gnu@0.7.0-linux-x64-gnu",
+    "xuanling-mcp-win32-x64-msvc": "npm:@xuanling-rs/xuanling-mcp-win32-x64-msvc@0.7.0-win32-x64-msvc"
   },
   "publishConfig": {
     "access": "public",
@@ -45,6 +45,6 @@
     "registry": "https://registry.npmjs.org"
   },
   "xuanlingRelease": {
-    "sourceCommit": "1aecd89c696404d6d4c0e9e6e0ad92ad94f33efe"
+    "sourceCommit": "c95f1e8fa6b744b479a6ffc48839ff90151389f5"
   }
 }