universal-mcp-sdk

跨 Agent 的 MCP Server 开发套件。一次实现，多端接入。

已实测接通：

• Claude Code / Cursor — stdio 传输
• Mavis — streamable-http 传输
• OpenAI / ChatGPT — remote MCP（streamable-http，需公网 HTTPS /mcp 或 Secure MCP Tunnel）
• 任何 HTTP-based AI Agent — streamable-http 传输

OpenAI Responses API 与 ChatGPT Apps 侧接入时，server_url 必须是外部可访问的 HTTPS /mcp 端点；本机 127.0.0.1 只适合本地客户端或通过 Secure MCP Tunnel / ngrok / Cloudflare Tunnel 暴露。

---

安装

npm install universal-mcp-sdk
# 或直接复制本目录到你的项目

---

快速开始

const { createServer, tool, textContent } = require('universal-mcp-sdk');

const server = createServer({
    name: 'my-first-mcp',
    version: '1.0.0',
    tools: [
        tool('hello', '打招呼', { name: { type: 'string' } },
            async ({ name }) => textContent(`Hello, ${name}!`)),
        tool('add', '两数相加', { a: { type: 'number' }, b: { type: 'number' } },
            async ({ a, b }) => textContent(String(a + b))),
    ],
    resources: [
        {
            uri: 'hello://greeting',
            name: 'Default Greeting',
            description: '默认问候语',
            mimeType: 'text/plain',
            read: async () => 'Hello World',
        },
    ],
});

server.start();

直接 node your-server.js 启动时，SDK 会自动检测运行环境：

• TTY 终端（交互式启动）→ stdio 模式
• 非 TTY / 后台服务（默认）→ HTTP 模式，监听 http://127.0.0.1:8080/mcp

需要强制指定模式时：

node your-server.js --stdio          # 强制 stdio（Claude Code / Cursor 子进程）
node your-server.js --http           # 强制 HTTP
node your-server.js --http --port 9000  # HTTP + 指定端口

---

完整示例

const {
    createServer,
    tool,
    command,
    staticResource,
    dynamicResource,
    textContent,
    errorContent,
    imageContentFromFile,
} = require('universal-mcp-sdk');

const server = createServer({
    name: 'my-mcp-server',
    version: '2.0.0',
    tools: [
        tool('scene_query_node', '查询场景节点',
            { uuid: { type: 'string' } },
            async ({ uuid }) => {
                const data = await queryNode(uuid);
                return textContent(JSON.stringify(data, null, 2));
            }
        ),
        tool('preview_screenshot', '截图预览页面',
            { path: { type: 'string' } },
            async ({ path }) => {
                const absPath = await captureScreenshot(path);
                return textContent(absPath);
            }
        ),
        command('preview_refresh', '刷新预览', async () => {
            await doRefresh();
            return textContent('ok');
        }),
    ],
    resources: [
        staticResource('project://info', 'Project Info',
            JSON.stringify({ name: 'MyGame', version: '1.0.0' })
        ),
        dynamicResource('scene://tree', 'Current Scene Tree', '当前场景节点树',
            async () => await querySceneTree()
        ),
    ],
});

server.start();

---

启动模式