MCP Integration

MCP Integration / MCP 接入

← Wiki home / 手册首页 · English · 中文 · Troubleshooting / 故障排查

Use this page when / 适用情况： choosing an MCP release package, connecting a client to Caelune-MCP.exe, or checking what the read-only MCP server can and cannot do.
选择 MCP 发布包、让客户端连接 Caelune-MCP.exe，或确认只读 MCP Server 的能力边界。

English

What the MCP server is

Caelune-MCP.exe is a read-only headless interface over the same retrieval core used by the desktop app. It does not create a second database.

The desktop app remains responsible for:

• configuring data roots and source directories
• installing Runtime and models
• full and incremental builds
• live watch
• deleting app-owned index/state

The MCP server exposes:

• omniclip.status — reports readiness, selected environment, and full/degraded retrieval state
• omniclip.search — returns source-labelled search results

Choose a package

• Use the MCP ZIP when manually pointing a client at Caelune-MCP.exe.
• Use .mcpb when the client supports the MCP Registry or MCPB installation.
• Use the WIN-EXE package for normal desktop configuration and indexing.

Always build at least one knowledge base with the desktop app first.

Local stdio configuration

A compatible client needs:

• transport: stdio
• command: the absolute path to Caelune-MCP.exe
• arguments: empty unless a documented option is required
• environment: empty unless intentionally overriding the data root or Runtime root

Example shape:

{
  "mcpServers": {
    "caelune": {
      "command": "D:\\Apps\\Caelune\\Caelune-MCP.exe",
      "args": []
    }
  }
}

Merge only the server entry into an existing client configuration. Do not overwrite unrelated servers.

Client limitations

Not every product that advertises MCP supports launching a local stdio process. Check the client’s current transport documentation before adding a proxy. Current OpenClaw releases manage command-based stdio servers under mcp.servers; see OpenClaw MCP 配置错误 for the current CLI-based setup and notes about older configuration errors.

Safe operation

The MCP server is read-only at the Caelune layer, but retrieved text is delivered to the connected client. The client's storage, logging, network, and model-provider policies still apply.

Use omniclip.status before search when diagnosing:

• missing or unbuilt indexes
• lexical-only degradation
• incomplete Runtime or models
• active data-root mismatch

Technical reference

See MCP_SETUP.md and the examples under examples/mcp.

中文

MCP Server 是什么

Caelune-MCP.exe 是桌面版检索内核之上的只读无界面入口，不会建立第二套数据库。

桌面版仍负责：

• 配置数据目录和来源目录
• 安装 Runtime 与模型
• 全量和增量建库
• 热监听
• 删除软件拥有的索引和状态

MCP Server 只开放：

• omniclip.status：报告环境、就绪状态和完整/降级检索模式
• omniclip.search：返回带来源标签的检索结果

选择发布包

• 手动把客户端指向 Caelune-MCP.exe 时使用 MCP ZIP。
• 客户端支持 MCP Registry 或 MCPB 安装时使用 .mcpb。
• 普通桌面配置和建库使用 WIN-EXE。

必须先通过桌面版建立至少一个知识库。

本地 stdio 配置

兼容客户端需要：

• 传输方式：stdio
• 命令：Caelune-MCP.exe 的绝对路径
• 参数：没有文档要求时留空
• 环境变量：没有主动覆盖数据目录或 Runtime 目录时留空

配置结构示例：

{
  "mcpServers": {
    "caelune": {
      "command": "D:\\Apps\\Caelune\\Caelune-MCP.exe",
      "args": []
    }
  }
}

只把这个 Server 条目合并到已有客户端配置，不要覆盖其他 Server。

客户端限制

并不是所有宣称支持 MCP 的产品都能直接启动本地 stdio 进程。引入代理之前，应先确认客户端当前版本的传输文档。当前 OpenClaw 已经可以在 mcp.servers 下管理命令型 stdio Server；最新 CLI 配置和旧版错误说明见：OpenClaw MCP 配置错误。

安全边界

MCP Server 在星野这一层是只读的，但检索文字会传给所连接的客户端。客户端自身的存储、日志、网络和模型服务商政策仍然适用。

排查以下问题时，先调用 omniclip.status：

• 索引缺失或尚未建库
• 当前只有字面检索
• Runtime 或模型不完整
• 客户端和桌面版使用的数据目录不一致

技术参考

请看 MCP_SETUP.md 和 examples/mcp 中的配置示例。

---

Previous / 上一篇： ← PDF and Tika / PDF 与 Tika · Next / 下一篇： Troubleshooting / 故障排查 →