Lingshu Gate

独立、可自托管的 MCP Gateway 与控制平面。

Lingshu MCP Nexus 是 Lingshu AgentOS 的 MCP Tool Layer / MCP 控制平面工程实现。

运行版本以 src/lingshu_mcp_nexus/_version.py 为唯一来源，可执行 python -m lingshu_mcp_nexus.cli --version 或访问健康接口查看。

版本摘要

详细路线规划见：docs/roadmap.md。

Build + Deploy 操作说明见：docs/build-deploy-guide.md。

跨平台兼容说明见：docs/cross-platform-compatibility.md。

HTTP MCP、InfraMCP 伴生控制台与独立 Origin 安全代理接入说明见：docs/http-companion-apps.md。

版本规则见：docs/versioning.md。

Related MCP server: Peta Core

当前能力

• Web Console：/console。

• OpenAPI 文档：/docs。

• MCP Config 在线管理。

• MCP Runtime 管理。

• MCP Server Detail。

• 外部/受管 Streamable HTTP MCP 与伴生网页入口。

• 聚合 MCP Gateway：POST /mcp，暴露 Registry 中的托管 MCP、已发布 Skill、内置工具和只读 nexus_system_debug。

• ZIP Upload / Project Analyzer。

• Skill ZIP 上传与自动发现：递归识别一个或多个 SKILL.md，校验后进入 Skill Catalog。

• Skill 在线 API：支持发布/停用、AI Provider/Model 单次调用和持久会话。

• 嵌套 ZIP 项目根目录识别：例如 project/package.json。

• Build + Deploy Pipeline P1。

• Build Preflight：/v1/builds/preflight。

• Build 创建支持 runtime / runtime_override 和 project_root。

• Build 深链接：#/builds/{build_id}。

• 上传页创建 Build 后自动跳转到对应构建详情。

• 上传结果 JSON / Manifest / Analysis 视图切换和复制。

• Async Build Jobs。

• Build Detail 组件化和 Build Timeline。

• Failure Hints 前端本地化。

• Build Logs：/v1/builds/{build_id}/logs。

• Build Logs live tail：/v1/builds/{build_id}/logs/stream。

• Build 日志快速筛选、关键词搜索、自动滚动和复制操作。

• Docker / Unraid 部署。

• Windows / macOS / Linux 本地脚本启动。

认证与默认管理员

认证现已默认开启。如果数据库中还没有任何用户，Nexus 会在首次初始化时创建一次性随机管理员凭据。用户名仍为 admin，随机密码只写入数据目录中的本地文件：

/data/initial-admin-credentials.json

该文件不通过 HTTP API 或日志输出密码，在支持 POSIX 权限的平台上以 0600 创建。首次改密后文件会自动删除。初始管理员登录后只能访问当前用户信息、修改密码和退出接口；必须先把密码修改为至少 8 位的新密码，重新登录后才可进入 Console、创建个人 Token 或调用 MCP Tool。

生产部署建议配置 LINGSHU_MCP_NEXUS_ADMIN_USERNAME 与 LINGSHU_MCP_NEXUS_BOOTSTRAP_PASSWORD_FILE，让秘密管理系统以只读文件注入一次性密码； compose.prod.yaml 已通过 Docker secret 使用这一方式，密码值不会进入容器环境。 文件变量与兼容用的 LINGSHU_MCP_NEXUS_ADMIN_PASSWORD 明文变量互斥。 无论采用哪种方式，初始管理员都必须首次改密；已有用户的数据库不会重复创建或覆盖管理员。

通过 HTTPS 反向代理或任何共享网络提供 Console 时，必须设置 LINGSHU_MCP_NEXUS_AUTH_COOKIE_SECURE=true，使会话 Cookie 带 Secure; HttpOnly; SameSite=Lax。仅本机 HTTP 开发环境可保留默认的 false。

仅限受信任的本地调试环境，可显式设置 LINGSHU_MCP_NEXUS_AUTH_ENABLED=false 关闭认证；关闭后请求会使用拥有完整权限的兼容系统身份，不得暴露到共享网络。

用户下游 MCP 凭据

Nexus 区分三类凭据：

• 个人 API Token：用于登录和调用 Nexus，本身受用户权限、资源授权与 scope 限制。

• 系统共享凭据：由管理员通过 CredentialStore 配置，用于 MCP 启动、共享 Header 或 AI Provider。

• 用户下游凭据：用户自己的 PAT、API Key 等，用于以该用户身份访问下游 MCP。

Streamable HTTP Manifest 可声明不含秘密的 user_credentials 槽位：

id: github
launch:
  type: external
transport:
  type: streamable_http
  endpoint: https://mcp.example.com/mcp
user_credentials:
  - id: github_pat
    name: GitHub PAT
    required: true
    injection:
      type: http_header
      name: Authorization
      template: Bearer {value}

用户在 Console“我的下游凭据”页面绑定自己的值。调用时 Nexus 创建独立的用户 HTTP MCP Session 并注入请求头，不复用共享 Session，也不把秘密写回 Manifest、日志或审计。当前共享 stdio 进程无法安全隔离不同用户的环境变量，因此 v1.13.0 对 stdio 用户凭据失败关闭。

共享 Runtime 仍负责 initialize、健康检查和 tools/list。如果下游 MCP 连工具发现都要求鉴权，需要在 transport.headers 中配置权限最小化的系统共享“发现凭据”；用户凭据只在用户实际调用时注入，不能替代共享发现凭据。

也可以在 Console 的 Manifest JSON 中临时增加一次性的值：

{
  "id": "github",
  "launch": { "type": "external" },
  "transport": {
    "type": "streamable_http",
    "endpoint": "https://mcp.example.com/mcp"
  },
  "user_credentials": [
    {
      "id": "github_pat",
      "name": "GitHub PAT",
      "required": true,
      "injection": {
        "type": "http_header",
        "name": "Authorization",
        "template": "Bearer {value}"
      }
    }
  ],
  "user_credential_values": {
    "github_pat": "仅在本次保存请求中使用"
  }
}

Console 保存前会把 user_credential_values 从 Manifest 中抽离，后端将其写入当前用户的独立加密库，保存成功或失败后编辑器都不再保留该字段。直接调用配置 API 时，user_credential_values 与 manifest 是请求体的同级字段。

个人秘密不得通过明文 HTTP 提交。远程 Console 必须启用 HTTPS；如果秘密必须始终留在用户电脑，则需要后续本地 Connector 解析本地引用，服务端 Runtime 无法直接读取用户设备。

跨平台说明

Nexus 控制面能力支持 Linux、macOS 和 Windows 本地运行；Docker 镜像主要面向 Linux / Unraid，也可在 Docker Desktop 环境验证。

需要注意：被管理的 MCP Server 是否跨平台，取决于 Manifest 中的命令、路径、依赖包和本机运行时。Node Build 需要 node/npm/npx，Python Build 需要 python/pip。

v1.0.9 的 Build Preflight 会在创建 Build 前检查本机工具链，并针对 Windows、macOS、Linux 给出修复建议。

Docker 构建

默认构建安全的 Core 镜像：以 UID/GID 10001 运行，不包含 Node.js、npm、npx 或 Docker CLI。

docker build --target core -t lingshu-gate:dev .

Lite Compose 默认只绑定 127.0.0.1，不会把首次管理入口直接暴露到局域网或公网：

mkdir -p runtime/workspace
docker compose up -d --build core

runner target 用于验证未来独立 Runtime Worker 的工具链与安全守卫；当前 Worker API 尚未交付，容器会以退出码 78 失败关闭，不能作为可用服务发布。需要保留旧版一体化 行为时只能显式使用迁移用 legacy target，且不能作为新部署默认值：

docker build --target runner -t lingshu-gate-runner:dev .
docker build --target legacy -t lingshu-gate-legacy:dev .

部署矩阵、生产配置、健康探针、升级与回滚见 docs/deployment.md。Docker-out-of-Docker 的新安全边界见 docs/managed-container-dood.md。

聚合 MCP Gateway

MCP Client 可连接 http://<MCP-Nexus-Host>:8000/mcp，发现并调用当前 Tool Registry 中的托管 MCP、已发布 Skill 和内置工具。网关工具名由稳定 Registry id 转换，例如 mcp.knowledge-mcp.winning_get_parameter 会暴露为 mcp__knowledge-mcp__winning_get_parameter。

nexus_system_debug 继续提供 overview、server_detail、logs、events、diagnostics 五种只读诊断 action。v1.13.0 起，tools/list 和 tools/call 统一按已发布的 Tool 读写分类、用户/角色资源授权以及 API Token scope 判定；未发布或已失效的分类对普通用户默认拒绝。

Tool 分类流程为：优先读取 MCP annotations，再执行 Nexus 内部规则，可选调用已配置的 AI Provider 给出复核建议，最终由管理员人工确认并发布。annotations、规则或 AI 只提供建议，不能直接获得调用权限。

{
  "action": "server_detail",
  "server_id": "wiki-mcp",
  "limit": 50
}

聚合网关与系统调试工具均默认开启，可分别通过 Docker 参数关闭：

LINGSHU_MCP_NEXUS_MCP_GATEWAY_ENABLED=false docker compose up -d mcp-nexus
LINGSHU_MCP_NEXUS_SYSTEM_DEBUG_MCP_ENABLED=false docker compose up -d mcp-nexus

关闭 SYSTEM_DEBUG_MCP_ENABLED 只会移除 nexus_system_debug，不会影响业务工具网关；关闭 MCP_GATEWAY_ENABLED 才会关闭整个 /mcp 入口。

系统调试工具读取 Nexus 持久化日志以及托管 MCP 进程/容器被捕获的 stdout、stderr，不执行任意 Shell，也不调用 docker logs 或要求 Docker Socket。生产环境建议同时设置 LINGSHU_MCP_NEXUS_AUTH_ENABLED=true，为用户或角色分配对应 MCP Server/Tool 的只读或读写权限，并让个人 Token scope 进一步收敛可调用范围。

项目自动交付 MCP 工具

v1.18.0 在同一 /mcp 网关注册首批 13 个原子管理工具，v1.22.0 增加显式工具刷新后共 14 个；v1.23.0 另增 4 个分类治理工具：

nexus_project_upload_begin   nexus_project_upload_chunk
nexus_project_upload_commit  nexus_project_upload_abort
nexus_build_preflight        nexus_build_plan
nexus_build_create           nexus_build_status
nexus_build_cancel           nexus_deploy_build
nexus_deployment_status      nexus_server_start
nexus_server_status          nexus_server_refresh_tools

分类治理工具：

nexus_tool_classification_list       nexus_tool_classification_analyze
nexus_tool_classification_review     nexus_tool_classification_publish

上传采用最大 512 KiB 的 base64 分块，每块和完整 ZIP 都校验 SHA-256；提交后继续复用 REST 上传已有的 50 MiB、3000 文件、200 MiB 展开大小和 Zip Slip 防护。构建创建必须回传 source_sha256 与 plan_fingerprint，且不开放 custom_steps。nexus_deploy_build 默认 overwrite=false、start=false；覆盖部署绑定 expected_previous_config_digest，存在旧凭据时还需绑定脱敏 expected_credential_binding_digest，服务端只继承受管引用和用户 Slot 声明。独立启动和 nexus_server_refresh_tools 绑定 expected_config_digest；工具快照完整校验后按 Server 原子替换，分类变化收紧为待审核且不自动扩大权限。REST 兼容接口的既有默认值不在此处改变。

所有写工具使用调用者级持久化 idempotency_key，同键同请求返回原结果，同键不同请求返回 idempotency_conflict。分类治理写工具另要求 classifications.manage，审核只把分类置为待发布，发布必须指定 server_id 或工具 ID 范围；普通业务调用者还必须同时具备已发布工具分类、资源 grant、Token scope、tools.invoke 和 operations.manage。首次注册后的待判定工具不会自动向非 Admin 发布。业务失败以 MCP isError=true 与 structuredContent.error 返回稳定错误码。

部署和配置应用使用目标 Server 粒度的 Runtime apply；更新 A 不会全量停止 B、C。显式 POST /v1/mcp/configs/reload 仍保留全量重载语义。

自动交付只接受用户明确指定且信任的项目。安全 Core/Runner 角色会在共享服务层拒绝 build、deploy 和 rollback，不读取上传内容后再偷偷提交本地 executor；Core 的 preflight 只做文件与工具路径分析，不启动项目或工具链子进程。现有构建执行仅保留在本地开发模式 与显式 legacy 兼容镜像：子进程使用最小环境变量白名单与 build 级 HOME/TMP/npm/pip cache，不继承 Nexus Token、数据库、Provider 或代理环境变量，但仍以 Nexus OS 身份执行项目代码，没有独立用户/容器、默认断网或文件系统沙箱，因此不能用于 不可信多租户构建。

Build API

GET  /v1/builds
POST /v1/builds/preflight
POST /v1/builds/plan
POST /v1/builds
GET  /v1/builds/{build_id}
GET  /v1/builds/{build_id}/logs?limit=200
GET  /v1/builds/{build_id}/logs/stream
POST /v1/builds/{build_id}/deploy

v1.0.10 起，POST /v1/builds 在创建前执行 preflight 门禁：unknown/ambiguous/docker 运行时或预检错误会以 HTTP 422 直接拒绝，并要求手动选择 runtime=node/python，不再落 unsupported/failed 死记录。

Skill API

POST /v1/skills/uploads
GET  /v1/skills/uploads
GET  /v1/skills
GET  /v1/skills/{skill_id}
POST /v1/skills/{skill_id}/publish
POST /v1/skills/{skill_id}/disable
POST /v1/skills/{skill_id}/invoke
GET  /v1/skill-runs
GET  /v1/skill-sessions
POST /v1/skill-sessions
GET  /v1/skill-sessions/{session_id}
POST /v1/skill-sessions/{session_id}/messages
POST /v1/skill-sessions/{session_id}/close

Skill MVP 固定使用 prompt 执行模式。上传包中的脚本只进入风险清单，Nexus 不会安装依赖或执行脚本；只有管理员发布后的 Skill 才能通过调用和会话接口使用。

启动 smoke test

cd services/mcp-nexus
PYTHONPATH=src python -m unittest tests/test_startup_smoke.py

本地开发 Console

cd services/mcp-nexus/web
npm install
npm run dev

构建 Console：

cd services/mcp-nexus/web
npm run build

安全边界

• /config/mcp.d 需要可写，但建议只挂载专用配置目录。

• /data 保存运行时系统数据、上传项目和构建产物，需要持久化并限制访问。

• 上传项目在 Build 阶段可能执行项目内安装和构建命令，只应构建可信来源项目。

• Skill 上传与项目 Build 是两条独立链路：Skill 链路不会执行 ZIP 中的 Python、JavaScript、PowerShell、Shell 或批处理文件。

• Skill 指令和参考资料按不可信输入处理，不能覆盖 Nexus 的鉴权、审计和安全前缀。

• 系统调试 MCP 默认开启但保持只读；生产环境应开启 Nexus 鉴权，或通过 LINGSHU_MCP_NEXUS_SYSTEM_DEBUG_MCP_ENABLED=false 关闭入口。

• 宿主进程模式仍可使用本机 Docker 运行 managed_container；容器模式的 Core 镜像不含 Docker CLI，也绝不挂载 Docker socket。

• 原始 Docker socket 等同宿主机 root 权限。新的 Runner 镜像提供命令守卫、镜像/目录/网络白名单与资源上限，但独立 Runtime Worker API 尚未交付，因此 Managed Compose 默认 fail-closed；迁移边界见 docs/managed-container-dood.md。