技术文档摘要

MCP Server.exe

小知&策展人版 MCP Starter - 适用于策展人&小知

MCP Server.exe 是一个功能强大的可执行服务器，不仅运行标准的 MCP（模型上下文协议）服务，还提供了丰富的高级功能：

• 工具链调用：支持顺序组合多个工具以实现复杂的自动化流程
• 多 MCP 服务组合：能够同时运行和管理多个 MCP 服务，支持 SSE 和 STDio 双模式
• 插件工具系统：支持动态加载和配置自定义工具
• 灵活部署选项：从独立操作到分布式部署，满足各种集成场景
• 自动重载：监听 --mcp-config 和 --mcp-js 的变化，自动重启生效

MCP Server.exe 是一个功能强大的可执行服务器，不仅运行标准的 MCP（模型上下文协议）服务，还提供了丰富的高级功能：

• 工具链执行：支持顺序组合多个工具进行复杂自动化
• 多个 MCP 服务：可以同时运行和管理多个 MCP 服务，支持 SSE 和 stdio 模式
• 插件工具系统：支持动态加载和配置自定义工具
• 灵活部署：从独立操作到分布式部署，满足各种集成场景
• 配置更改自动重载

使用方法

# 推荐：通过 CLI 运行（无需本地构建）
npx mcp_exe --mcp-config ./examples/mcp.json

# 或运行打包后的可执行文件（Windows/macOS）
./executables/mcp_server-win-x64.exe --m

🎯 主要使用场景

1. WebSocket 连接模式

支持通过 WebSocket 连接到其他 MCP 服务，特别适合连接到 xiaozhi.me 和其他接入点。可以通过配置文件轻松地将多个 MCP 服务连接到 xiaozhi.me。

支持通过 WebSocket 连接到其他 MCP 服务，特别是适合连接到启用 WebSocket 的 MCP 服务如 xiaozhi.me。通过配置文件，你可以轻松地将多个 MCP 服务与 xiaozhi.me 整合。

# 使用配置文件连接到 xiaozhi.me / 在 WebSocket 模式下启动
npx mcp_exe --ws wss://api.xiaozhi.me/mcp/?token=...xxx --mcp-config ./examples/mcp-sse.json

配置示例 | 配置示例 (mcp-sse.json):

{
    "mcpServers": {
        "Model Server sse": {
            "url": "http://127.0.0.1:3000"
        }
    },
    "serverInfo": {
        "serverName": "ws-client-mcp-server",
        "version": "1.0.0",
        "description": "WebSocket 客户端的 MCP 服务器实例",
        "author": "shadow"
    }
}

WebSocket 模式特性 | WebSocket 模式特性:

• 支持实时双向通信
• 自动重连机制
• 多服务统一管理
• 兼容标准 MCP 协议

相关项目Visual Xiaozhi MCP Starter

2. 快速启动独立服务

最简单的方式——双击运行，或者通过 npx 启动标准 MCP 服务。

最简单的方式——双击运行，或者通过 npx 启动。

# 双击运行 mcp_server.exe，或通过命令行启动
./executables/mcp_server-win-x64.exe
# 或
npx mcp_exe

默认配置：

• 监听端口：3000（可通过 --port 修改）
• SSE 路由 | SSE 终点：GET / 建立会话，POST /sessions?sessionId=... 发送消息
• 内置基本工具
• 自动重载 --mcp-config 和 --mcp-js

3. 结合多个 MCP 服务

使用与 Cursor 一致的 mcp.json 配置文件，通过配置文件结合多个 MCP 服务，支持同时使用 SSE 和 STDio 传输模式。这允许根据不同的应用场景选择合适的传输方式，提高系统的灵活性和扩展性。

使用相同的 mcp.json 配置文件作为 Cursor 来结合多个 MCP 服务，支持同时使用 SSE 和 stdio 传输模式。

npx mcp_exe --mcp-config ./examples/mcp.json

配置示例 | 配置示例 (mcp.json):

{
  "mcpServers": {
    "Model Server sse": { "url": "http://127.0.0.1:9090" },
    "Model Server - stdio": { "command": "xxx", "args": ["--transport", "stdio"] }
  },
  "serverInfo": { "serverName": "dynamic-mcp-server" },
  "tools": [],
  "namespace": "."
}

• tools：允许工具白名单（空数组表示不进行过滤）
• namespace：组合命名空间分隔符，默认 .（也可以使用） ::）

4. 工具链执行

支持将多个工具组合成工具链以实现复杂的自动化过程。工具链可以灵活配置数据流和结果输出。

支持将多个工具组合成工具链来实现复杂的自动化过程。工具链可以灵活配置数据流和结果输出。

npx mcp_exe --mcp-config ./examples/product-hunt/mcp-tools.json

配置示例 | 配置示例（摘录，可根据需要定制和调整）：

{
  "toolChains": [
    {
      "name": "product_hunt_news",
      "description": "获取产品猎人新闻",
      "steps": [
        { "toolName": "get_product_hunt_url", "args": {} },
        { "toolName": "load_product_hunt_js_code", "args": {} },
        { "toolName": "browser_navigate", "args": {}, "outputMapping": { "url": "content.0.text" }, "fromStep":  0 },
        { "toolName": "browser_execute_javascript", "args": {}, "outputMapping": { "code": "content.0.text" }, "fromStep": 1 },
        { "toolName": "browser_close", "args": {} }
      ],
      "output": { "steps": [3] }
    }
  ]
}

工具链特性：

• 支持多步顺序执行
• 灵活的数据流映射（outputMapping/fromStep）
• 可以从任何步骤获取结果（output.steps）

5. 自定义工具插件机制

通过 JavaScript 配置文件灵活定义工具、资源和提示。

通过 JavaScript 配置文件灵活定义工具、资源和提示。

npx mcp_exe --mcp-js ./examples/custom-mcp-config.js

配置示例 | 配置示例（custom-mcp-config.js）：

module.exports = {
  // 推荐导出名：configureMcp（也兼容 mcpPlugin）
  configureMcp: function(server, ResourceTemplate, z) {
    server.tool('myTool', '自定义工具示例', { /* zod schema */ }, async (args) => ({ content: [{ type: 'text', text: 'ok' }] }))
    server.resource('custom-echo', new ResourceTemplate('custom-echo://{message}', { list: undefined }), async (uri, { message }) => ({ contents: [{ uri: uri.href, text: message }] }))
    server.prompt('custom-prompt', { /* zod */ }, ({ message }) => ({ messages: [{ role: 'user', content: { type: 'text', text: message } }] }))
  }
}

6. 定时任务模式 | Cronjob 模式

使用 --cronjob 定时执行工具。当前支持的操作：listTools、callTool。任务在启动时立即执行，然后按 schedule 定期执行，结果可以通过桌面气泡/邮件/ntfy 推送。

# 示例：结合自定义工具与定时任务
npx mcp_exe --cronjob ./examples/cronjob.json --mcp-js ./examples/product-hunt/custom-mcp-config.js

配置示例 | 配置示例（examples/cronjob.json）：

{
  "tasks": [
    {
      "schedule": "*/30 * * * * *",
      "operations": [
        { "type": "callTool", "name": "get_product_hunt_url", "arguments": {} }
      ],
      "notify": [
        { "type": "desktop", "title": "任务执行结果", "icon": "" }
      ]
    }
  ]
}

通知支持 | 通知：

• 桌面：系统气泡（需要本地桌面环境）
• 邮件：发送邮件（需要） to、subject 等）
• Ntfy：推送到 ntfy（需要提供） url、topic、tags、priority）

注意：定时任务直接调用组合工具（包括远程 SSE/本地 STDio 工具），任务中不指定传输方式。

7. 嵌入式集成 | 嵌入式集成

作为独立进程集成到任何应用程序中。

作为独立进程集成到任何应用程序中。

// Node.js 示例 | Node.js 示例
const { spawn } = require('child_process')

const mcpServer = spawn('./executables/mcp_server-win-x64.exe', [
  '--port', '3000',
  '--transport', 'stdio'
])

mcpServer.stdout.on('data', (data) => {
  // 处理 MCP 服务器的输出
})

mcpServer.stdin.write(JSON.stringify({
  // 发送请求到 MCP 服务器
}))

📚 详细文档

命令行参数

服务器支持以下命令行参数来自定义其行为：服务器支持以下命令行参数：

参数	描述	默认值
--ws <url>	WebSocket 服务器地址，启用 WebSocket 连接模式	无
--mcp-js <路径>	MCP JavaScript 配置文件路径（支持） configureMcp 或 mcpPlugin）	无
--mcp-config <路径/json字符串>	MCP JSON 配置文件路径或 JSON 字符串	无
--server-name <name>	服务器名称	mcp_server_exe

| --port <端口> | 服务器监听端口 | 3000 | | --transport <模式> | 传输模式，支持 sse 或 stdio（非 WS 模式有效） | sse | | --cronjob <路径/json> | 定时任务配置文件路径或 JSON 字符串 | 无 | | --cursor-link | 启动后在光标中快速访问（SSE 模式） | 关闭 | | --log-level <level> | 日志级别：TRACE/DEBUG/INFO/WARN/ERROR/FATAL/OUTPUT | INFO | | --version <version> --description <desc> --author <author> --license <license> --homepage <url> | 元信息 | - |

提示：如果提供了 --ws，优先使用 WebSocket 模式；否则，如果没有明确指定，默认使用 sse。

配置文件格式

服务器支持使用配置文件同时配置服务器参数和 MCP 功能：

module.exports = {
  // MCP 配置函数 | MCP 配置函数
  configureMcp: function(server, ResourceTemplate, z) {
    // 配置资源和工具 | 配置资源和工具
  },
  // 可选：提供额外的 mcp 配置对象
  mcpConfig: { /* mcpServers/tools/toolChains/namespace */ }
}

自动重载

• 监控 --mcp-config 文件变化：自动重新解析并重启服务（包括工具链/命名空间/工具白名单等）
• 监控 --mcp-js 文件变化：自动重新加载自定义文件 configureMcp/mcpPlugin

开发指南 | 开发指南

安装 | 安装

npm install

构建 | 构建

yarn build # 或 npm run build

运行 | 运行

npm start
# 或开发模式（SSE）：
npm run dev
# WebSocket 开发：
npm run dev-ws
# Cronjob 开发：
npm run dev-cronjob

打包 | 打包

# Windows 打包
npm run package-win

# macOS 打包（Intel/Apple Silicon）
npm run package-mac-intel
npm run package-mac-arm

打包后的可执行文件将生成在 executables 目录中。

日志 | 日志

• 通过 --log-level 控制最小输出级别（默认） INFO）
• 控制台带有时间戳/分类/颜色输出；OUTPUT 级别用于工具解析的原样输出

作为库 | 库 API

从 v0.11.x 版本开始，提供稳定的导出：McpRouterServer。

// CommonJS
const { McpRouterServer } = require('mcp_exe');

(async () => {
  const server = new McpRouterServer({ name: 'my-app' }, { transportType: 'sse', port: 3000 });
  await server.importMcpConfig(require('./mcp.json'), null);
  await server.start();
})();

// TypeScript / ESM
import { McpRouterServer } from 'mcp_exe';

const server = new McpRouterServer({ name: 'my-app' }, { transportType: 'stdio' });
await server.importMcpConfig(mcpJson, null);
await server.start();

• 类型声明输出在 dist/index.d.ts，通过 types/exports 自动暴露。
• CLI 仍然通过 bin/cli.js 提供，库和 CLI 可以并行使用。

📝 许可证 | 许可证

MIT