@omni/mcp

OmniAPI 的 MCP Adapter：把 Procedure 自动暴露为 Model Context Protocol 工具，所有 Agent 平台（Claude Desktop / Cursor / Codebuddy / Cline / 自研 Agent）一次接入。

安装

pnpm add @omni/mcp @omni/core zod

快速使用

本地 stdio（最常见）

给 Claude Desktop / Cursor / Codebuddy 等本机 IDE 用：

// src/mcp.ts
import { Registry, defineProcedure } from '@omni/core';
import { startMcpStdio } from '@omni/mcp';
import { z } from 'zod';

const registry = new Registry();
registry.register(
  defineProcedure({
    name: 'order.create',
    description: '创建订单。当用户表达"购买/下单"意图时调用。',
    input: z.object({ sku: z.string(), qty: z.number().int().positive() }),
    output: z.object({ id: z.string() }),
    meta: { mcp: { dangerLevel: 'write', requireConfirmation: true } },
    handler: ({ input }) => ({ id: 'O_' + input.sku }),
  }),
);

await startMcpStdio({ registry, name: 'myapp', version: '1.0.0' });

Claude Desktop 配置（~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "myapp": {
      "command": "node",
      "args": ["/path/to/dist/mcp.js"],
      "env": { "OMNI_TOKEN": "..." }
    }
  }
}

远程 Streamable HTTP

import { startMcpHttp } from '@omni/mcp';

await startMcpHttp({ registry, port: 4000, path: '/mcp' });

客户端连接：http://host:4000/mcp + Authorization: Bearer <token>。

设计要点

| 设计 | 说明 | |---|---| | 统一执行心脏 | 所有 tool 调用都走 runByName，与 HTTP 完全一致；中间件、限流、鉴权都共享 | | 业务错误用 isError 返回 | 不抛 JSON-RPC error，让 LLM 看到结构化错误并自我修正（MCP 推荐做法） | | description 自动增强 | 危险等级 / 别名 / 示例 自动拼接到 tool description，提升 LLM 召回与谨慎度 | | namespace 拆分 | 一个项目可启多个 MCP server（按 namespace），让 Client 选择性安装 | | transport 两选一 | stdio（本地 IDE）/ Streamable HTTP（云端） |

API

• createMcpServer(options) - 创建未连接 transport 的 McpServer
• startMcpStdio(options) - 启动 stdio Server
• startMcpHttp(options) - 启动 HTTP Server
• countExposed(registry, opts?) - 列出会被暴露的 procedure 数量（debug 用）
• buildMcpToolDescription(p) - 构造增强 description（高级用法）

name 转换规则

MCP tool name 不允许 .，所以 order.create → order_create。客户端调用时使用转换后的名字。

鉴权

• stdio: 默认从 process.env.OMNI_TOKEN 取 token，传给 authenticate(authInfo)
• HTTP: 从 Authorization: Bearer <token> header 取 token
• 业务方可自定义 authenticate(authInfo) 转 UserPrincipal，业务层用 ctx.user 即可