@xuanling-rs/xuanling-mcp 0.2.2 → 0.2.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 umbrella22 and XuanLing contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README-ZH.md

@@ -0,0 +1,111 @@
+# XuanLing MCP
+
+[English](README.md) | 简体中文
+
+`@xuanling-rs/xuanling-mcp` 是面向编码 Agent 的跨平台本地 Model Context Protocol 服务器。它通过
+stdio 提供 42 个类型化工具，覆盖文件系统操作、进程执行、项目探测、Artifact、Session 和
+proposal-first SQLite Memory。
+
+## 安装
+
+启动器要求 Node.js 18.17 或更高版本。
+
+```sh
+npm install --global @xuanling-rs/xuanling-mcp@0.2.3
+xuanling-mcp --version
+```
+
+MCP Client 也可以使用 `npx` 固定版本：
+
+```json
+{
+  "mcpServers": {
+    "xuanling": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@xuanling-rs/xuanling-mcp@0.2.3",
+        "--workspace-root",
+        "/absolute/path/to/project",
+        "--tool-profile",
+        "core",
+        "--tool-profile",
+        "fs",
+        "--tool-profile",
+        "memory"
+      ]
+    }
+  }
+}
+```
+
+固定版本可以保持活动项目发现的 MCP 合同稳定。频繁启动服务器时，全局安装或项目内安装可以
+省去 package 解析过程。
+
+## 支持平台
+
+| 操作系统 | 架构 | 运行时要求 |
+| --- | --- | --- |
+| macOS | Apple Silicon (`arm64`) | 原生二进制 |
+| Linux | `x64` | glibc 2.35 或更高版本 |
+| Windows | `x64` | MSVC runtime |
+
+不支持的 OS、CPU 或 libc 组合会返回明确错误。安装过程不编译 Rust、不运行 `postinstall`，
+也不下载可执行文件。启动器会在启动前校验 package metadata 和所选原生 binary 的 SHA-256。
+
+## 工具 Profile
+
+默认 catalog 暴露全部 42 个工具。重复使用 `--tool-profile` 可以组合多个较小的工具组：
+
+| Profile | 工具数 | 能力族 |
+| --- | ---: | --- |
+| `core` | 3 | 系统信息与可移植路径检查 |
+| `fs` | 16 | 文件读取、搜索、预览与修改 |
+| `process` | 5 | 直接进程执行与项目探测/执行 |
+| `memory` | 9 | Memory v2 提案、评审、召回与反馈 |
+| `advanced` | 9 | Artifact、ChangeSet、Pipeline 与 Session |
+| `all` | 42 | 完整 catalog 和默认选择 |
+
+## 文件系统能力
+
+- `--workspace-root <PATH>` 可重复，允许读取、写入、删除，并允许在该 root 内设置子进程
+  工作目录。
+- `--read-root <PATH>` 可重复，只允许读取、列出、搜索和计算 hash；拒绝写入、删除和设置
+  子进程工作目录。
+- 两个 flag 都未提供时，XuanLing 文件系统访问不受限制。仅提供 `--read-root` 时为只读部署。
+
+修改类工具支持 SHA-256 preimage 校验。支持窗口输出的工具可以设置显式 byte budget，并返回
+类型化 cursor 或 resume token，不会静默截断结果。
+
+路径能力不是子进程的 OS sandbox。工具审批和恶意进程隔离由 MCP Host 与执行环境负责。
+
+## Memory v2
+
+Create、replace 和 archive 调用只产生 pending proposal。只有显式 `memory_review` 决策才能
+原子推进不可变的 canonical record。严格的 `global`、`project` 和 `workspace` scope 防止
+sibling project 之间发生召回泄漏。
+
+召回使用确定性 SQLite FTS5 query plan 和稳定词法重排，不要求或下载 embedding 模型。默认
+数据库路径为 `~/.xuanling/memory.db`；使用 `--memory-db <PATH>` 可以覆盖该路径。
+
+## Server 选项
+
+```text
+--base-dir <PATH>                  相对路径解析上下文
+--workspace-root <PATH>            可重复的读写 capability root
+--read-root <PATH>                 可重复的只读 capability root
+--memory-db <PATH>                 共享 SQLite Memory 数据库
+--default-namespace <VALUE>        默认 Memory namespace
+--sqlite-busy-timeout-ms <NUMBER>  SQLite busy timeout（默认 5000）
+--tool-profile <PROFILE>           可重复工具组；默认 all
+--compat-lenient-object-params     受影响 Host 的可选兼容模式
+```
+
+## 源码与文档
+
+- 源码：<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>
+- Issues：<https://github.com/umbrella22/xuanling/issues>
+
+本项目采用 [MIT License](LICENSE)。

package/README.md

@@ -0,0 +1,122 @@
+# XuanLing MCP
+
+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.
+
+## Install
+
+The launcher requires Node.js 18.17 or newer.
+
+```sh
+npm install --global @xuanling-rs/xuanling-mcp@0.2.3
+xuanling-mcp --version
+```
+
+MCP clients can also pin the version with `npx`:
+
+```json
+{
+  "mcpServers": {
+    "xuanling": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@xuanling-rs/xuanling-mcp@0.2.3",
+        "--workspace-root",
+        "/absolute/path/to/project",
+        "--tool-profile",
+        "core",
+        "--tool-profile",
+        "fs",
+        "--tool-profile",
+        "memory"
+      ]
+    }
+  }
+}
+```
+
+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.
+
+## Supported Platforms
+
+| Operating system | Architecture | Runtime requirement |
+| --- | --- | --- |
+| macOS | Apple Silicon (`arm64`) | native binary |
+| Linux | `x64` | glibc 2.35 or newer |
+| Windows | `x64` | MSVC runtime |
+
+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
+smaller groups:
+
+| Profile | Tools | Capability family |
+| --- | ---: | --- |
+| `core` | 3 | system and portable path inspection |
+| `fs` | 16 | 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 |
+
+## Filesystem Capabilities
+
+- `--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.
+
+Mutating tools support SHA-256 preimage checks. Window-capable tools support
+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.
+
+## 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.
+
+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.
+
+## Server Options
+
+```text
+--base-dir <PATH>                  Relative-path resolution context
+--workspace-root <PATH>            Repeatable read/write capability root
+--read-root <PATH>                 Repeatable read-only capability root
+--memory-db <PATH>                 Shared SQLite memory database
+--default-namespace <VALUE>        Default memory namespace
+--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
+```
+
+## Source and Documentation
+
+- 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>
+- Issues: <https://github.com/umbrella22/xuanling/issues>
+
+Licensed under the [MIT License](LICENSE).

package/bin/xuanling-mcp.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+
+import { launch } from "../lib/launcher.js";
+
+launch().catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(`xuanling-mcp: ${message}`);
+  process.exit(1);
+});

package/lib/launcher.js

@@ -0,0 +1,120 @@
+import { spawn as nodeSpawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync as nodeExistsSync, readFileSync as nodeReadFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { constants as osConstants } from "node:os";
+import path from "node:path";
+
+import { detectTarget } from "./targets.js";
+
+const require = createRequire(import.meta.url);
+
+export function resolveNativeBinary(
+  target,
+  {
+    existsSync = nodeExistsSync,
+    readFileSync = nodeReadFileSync,
+    resolvePackageJson = (specifier) => require.resolve(specifier),
+  } = {},
+) {
+  let packageJsonPath;
+  try {
+    packageJsonPath = resolvePackageJson(`${target.alias}/package.json`);
+  } catch {
+    throw new Error(
+      `Missing optional dependency ${target.alias}. Reinstall the current xuanling-mcp package before retrying`,
+    );
+  }
+
+  const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+  const metadata = packageJson.xuanlingBinary;
+  if (
+    metadata?.target !== target.rustTarget ||
+    metadata?.binary !== target.binary ||
+    !/^[0-9a-f]{64}$/.test(metadata?.sha256 ?? "")
+  ) {
+    throw new Error(
+      `Installed package ${target.alias} does not match target ${target.rustTarget}`,
+    );
+  }
+
+  const binaryPath = path.join(path.dirname(packageJsonPath), metadata.binary);
+  if (!existsSync(binaryPath)) {
+    throw new Error(
+      `Native binary is missing from ${target.alias}. Reinstall the current xuanling-mcp package before retrying`,
+    );
+  }
+  const actualSha256 = createHash("sha256")
+    .update(readFileSync(binaryPath))
+    .digest("hex");
+  if (actualSha256 !== metadata.sha256) {
+    throw new Error(
+      `Native binary checksum mismatch in ${target.alias}. Reinstall the current xuanling-mcp package before retrying`,
+    );
+  }
+  return binaryPath;
+}
+
+function exitCodeForSignal(signal) {
+  const number = osConstants.signals?.[signal];
+  return typeof number === "number" ? 128 + number : 1;
+}
+
+export async function launch({
+  argv = process.argv.slice(2),
+  env = process.env,
+  runtime = process,
+  spawn = nodeSpawn,
+  target = detectTarget(),
+  binaryPath = resolveNativeBinary(target),
+} = {}) {
+  const child = spawn(binaryPath, argv, {
+    env,
+    stdio: "inherit",
+    windowsHide: true,
+  });
+
+  const signalHandlers = new Map();
+  for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+    const handler = () => {
+      if (!child.killed) {
+        try {
+          child.kill(signal);
+        } catch {
+          // A concurrent child exit can make signal forwarding fail.
+        }
+      }
+    };
+    signalHandlers.set(signal, handler);
+    runtime.on(signal, handler);
+  }
+
+  let result;
+  try {
+    result = await new Promise((resolve, reject) => {
+      child.once("error", reject);
+      child.once("exit", (code, signal) => {
+        resolve(signal ? { signal } : { code: code ?? 1 });
+      });
+    });
+  } catch (error) {
+    for (const [signal, handler] of signalHandlers) {
+      runtime.removeListener(signal, handler);
+    }
+    throw error;
+  }
+
+  for (const [signal, handler] of signalHandlers) {
+    runtime.removeListener(signal, handler);
+  }
+
+  if (result.signal) {
+    if (runtime.platform === "win32") {
+      runtime.exit(exitCodeForSignal(result.signal));
+      return;
+    }
+    runtime.kill(runtime.pid, result.signal);
+    return;
+  }
+  runtime.exit(result.code);
+}

package/lib/targets.js

@@ -0,0 +1,130 @@
+export const NPM_SCOPE = "@xuanling-rs";
+export const PACKAGE_BASENAME = "xuanling-mcp";
+export const PACKAGE_NAME = `${NPM_SCOPE}/${PACKAGE_BASENAME}`;
+
+export const DSH_BUNDLES = Object.freeze([
+  Object.freeze({ id: "xuanling-dsh-memory", packageName: `${NPM_SCOPE}/xuanling-dsh-memory` }),
+  Object.freeze({ id: "xuanling-dsh-skills", packageName: `${NPM_SCOPE}/xuanling-dsh-skills` }),
+  Object.freeze({ id: "xuanling-dsh-tools", packageName: `${NPM_SCOPE}/xuanling-dsh-tools` }),
+  Object.freeze({
+    id: "xuanling-dsh-tools-replace",
+    packageName: `${NPM_SCOPE}/xuanling-dsh-tools-replace`,
+  }),
+]);
+
+export const TARGETS = Object.freeze({
+  "darwin-arm64": Object.freeze({
+    id: "darwin-arm64",
+    alias: "xuanling-mcp-darwin-arm64",
+    packageName: `${NPM_SCOPE}/xuanling-mcp-darwin-arm64`,
+    binary: "bin/xuanling-mcp",
+    cpu: "arm64",
+    os: "darwin",
+    rustTarget: "aarch64-apple-darwin",
+    distTag: "platform-darwin-arm64",
+  }),
+  "linux-x64-gnu": Object.freeze({
+    id: "linux-x64-gnu",
+    alias: "xuanling-mcp-linux-x64-gnu",
+    packageName: `${NPM_SCOPE}/xuanling-mcp-linux-x64-gnu`,
+    binary: "bin/xuanling-mcp",
+    cpu: "x64",
+    libc: "glibc",
+    os: "linux",
+    rustTarget: "x86_64-unknown-linux-gnu",
+    distTag: "platform-linux-x64-gnu",
+  }),
+  "win32-x64-msvc": Object.freeze({
+    id: "win32-x64-msvc",
+    alias: "xuanling-mcp-win32-x64-msvc",
+    packageName: `${NPM_SCOPE}/xuanling-mcp-win32-x64-msvc`,
+    binary: "bin/xuanling-mcp.exe",
+    cpu: "x64",
+    os: "win32",
+    rustTarget: "x86_64-pc-windows-msvc",
+    distTag: "platform-win32-x64-msvc",
+  }),
+});
+
+export function platformVersion(releaseVersion, targetId) {
+  if (!/^\d+\.\d+\.\d+$/.test(releaseVersion)) {
+    throw new Error(
+      `XuanLing npm releases require a stable semver version, received ${JSON.stringify(releaseVersion)}`,
+    );
+  }
+  if (!Object.hasOwn(TARGETS, targetId)) {
+    throw new Error(`Unknown XuanLing npm target: ${targetId}`);
+  }
+  return `${releaseVersion}-${targetId}`;
+}
+
+export function expectedOptionalDependencies(releaseVersion) {
+  return Object.fromEntries(
+    Object.values(TARGETS)
+      .sort((left, right) => left.alias.localeCompare(right.alias))
+      .map((target) => [
+        target.alias,
+        `npm:${target.packageName}@${platformVersion(releaseVersion, target.id)}`,
+      ]),
+  );
+}
+
+const MINIMUM_GLIBC = Object.freeze({ major: 2, minor: 35 });
+
+function runtimeGlibcVersion(report) {
+  try {
+    const header = report?.getReport?.()?.header;
+    return typeof header?.glibcVersionRuntime === "string"
+      ? header.glibcVersionRuntime
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function supportsMinimumGlibc(version) {
+  const match = /^(\d+)\.(\d+)/.exec(version);
+  if (!match) {
+    return false;
+  }
+  const major = Number(match[1]);
+  const minor = Number(match[2]);
+  return (
+    major > MINIMUM_GLIBC.major ||
+    (major === MINIMUM_GLIBC.major && minor >= MINIMUM_GLIBC.minor)
+  );
+}
+
+export function detectTarget({
+  platform = process.platform,
+  arch = process.arch,
+  report = process.report,
+} = {}) {
+  if (platform === "darwin" && arch === "arm64") {
+    return TARGETS["darwin-arm64"];
+  }
+  if (platform === "win32" && arch === "x64") {
+    return TARGETS["win32-x64-msvc"];
+  }
+  if (platform === "linux" && arch === "x64") {
+    const glibcVersion = runtimeGlibcVersion(report);
+    if (!glibcVersion) {
+      throw new Error(
+        "Unsupported Linux libc: xuanling-mcp currently publishes an x64 glibc binary, not musl",
+      );
+    }
+    if (!supportsMinimumGlibc(glibcVersion)) {
+      throw new Error(
+        `Unsupported Linux glibc ${glibcVersion}: xuanling-mcp requires glibc 2.35 or newer`,
+      );
+    }
+    return TARGETS["linux-x64-gnu"];
+  }
+
+  const supported = Object.values(TARGETS)
+    .map((target) => `${target.os}/${target.cpu}${target.libc ? `/${target.libc}` : ""}`)
+    .join(", ");
+  throw new Error(
+    `Unsupported platform: ${platform}/${arch}. Published targets: ${supported}`,
+  );
+}

package/package.json

@@ -1,10 +1,20 @@
 {
   "name": "@xuanling-rs/xuanling-mcp",
-  "version": "0.2.2",
-  "description": "XuanLing bootstrap placeholder; replaced by the verified 0.2.3 release.",
+  "version": "0.2.3",
+  "description": "Cross-platform stdio MCP server for XuanLing typed filesystem, process, project, artifact, session, and memory tools.",
   "license": "MIT",
   "author": "umbrella22 and XuanLing contributors",
   "type": "module",
+  "bin": {
+    "xuanling-mcp": "bin/xuanling-mcp.js"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "LICENSE",
+    "README.md",
+    "README-ZH.md"
+  ],
   "engines": {
     "node": ">=18.17.0"
   },
@@ -24,9 +34,17 @@
     "url": "git+https://github.com/umbrella22/xuanling.git",
     "directory": "npm/packages/xuanling-mcp"
   },
+  "optionalDependencies": {
+    "xuanling-mcp-darwin-arm64": "npm:@xuanling-rs/xuanling-mcp-darwin-arm64@0.2.3-darwin-arm64",
+    "xuanling-mcp-linux-x64-gnu": "npm:@xuanling-rs/xuanling-mcp-linux-x64-gnu@0.2.3-linux-x64-gnu",
+    "xuanling-mcp-win32-x64-msvc": "npm:@xuanling-rs/xuanling-mcp-win32-x64-msvc@0.2.3-win32-x64-msvc"
+  },
   "publishConfig": {
     "access": "public",
+    "provenance": true,
     "registry": "https://registry.npmjs.org"
   },
-  "private": false
+  "xuanlingRelease": {
+    "sourceCommit": "eec429d009481e193295678b9aa244d44c5d52a2"
+  }
 }