# @empyria/mcp 中文文档

规范地址：https://npmcn.com/package/%40empyria/mcp/

版本：0\.1\.29
npm 元数据更新时间：2026-10-31T23:34:32.479Z
中文译文更新时间：2026-11-01T02:41:37.075Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40empyria/mcp
原文对照：https://npmcn.com/package/%40empyria/mcp/?lang=original
项目主页：https://github.com/empyria-nano/guard-mcp#readme
源码仓库：https://github.com/empyria-nano/guard-mcp

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：65.6 kB，20 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=26
- 运行依赖：4 个
- 首次发布：2026-08-16T15:37:12.175Z
- 最新版本发布：2026-10-31T23:34:32.259Z
- 已发布版本数：30（近 12 个月 30 个）

## 中文简介

用于Empyria纳米服务框架的MCP（模型上下文协议）助手

## 安装

```sh
npm install @empyria/mcp
```

也可以使用：`pnpm add @empyria/mcp`、`yarn add @empyria/mcp`、`bun add @empyria/mcp`

## README

# @empyria / mcp

[模型上下文协议](https://modelcontextprotocol.io/) 助手的 **Empyria**,一个 主要构建在Bun上的纳米服务框架：发布一个分子型服务列表 MCP工具，通过JSON模式输入验证 `@empyria/common`的 `createValidator` - - - - - - 没有Zod，没有Ajv，在我们自己的代码里。

## 要求

-   包子 `>=1.4.0` 或node . js `>=26`
-   简单的ESM，没有构建步骤，没有TypeScript

这两个要求都来自 [@empyria /分类](https://github.com/imrefazekas/empyria-classification) 和 [@empyria /常见](https://github.com/imrefazekas/empyria-common)这个包裹 取决于和哪个使用本机 `Temporal` 全局用于所有日期/时间处理。

## 安装

```bash
bun add @empyria/mcp
```

## 使用

```js
import { createMcpServer } from '@empyria/mcp'
import { string, number } from '@empyria/common'
import { StdioServerTransport } from '@modelcontextprotocol/server/stdio'

const WeatherService = {
    name: 'Weather',
    actions: {
        getForecast: {
            description: 'Get the weather forecast for a city',
            params: { city: string(), days: number(3) },
            handler: async ({ city, days }) => ({ city, days, forecast: 'sunny' }),
        },
        // bare functions work too — no params schema, no description
        ping: async () => 'pong',
    },
}

const server = createMcpServer({
    name: 'my-mcp-server',
    version: '1.0.0',
    services: [WeatherService],
})

await server.connect(new StdioServerTransport())
```

每个动作都成为一个名为 `"<service.name>.<actionName>"` - - - - - - `Weather.getForecast`， `Weather.ping` 上面镜像分子自己的 `service.action` 命名。 `params` 是JSON 使用构建的架构属性定义 `@empyria/common`的模式辅助程序(`string()`， `number()`， `bool()`， `enumType()`,……);传入的工具调用之前会根据它们进行验证 处理程序运行，验证失败将作为正常情况报告回MCP客户端 工具调用错误(`isError: true`) -处理程序永远不会看到无效输入。处理程序的返回 value可以是字符串，任何json可序列化的值，或者已经形成mcp的值 `{ content: [...] }` 结果;抛出的错误也作为工具调用错误报告回来 自动。

`createMcpServer` 只构建和注册-连接到传输（stdio， HTTP，…）是 由你决定。关于工作室，请参见 `@modelcontextprotocol/server/stdio`的 `StdioServerTransport`/ `serveStdio`． 对于HTTP，这个包有它自己的helper：

```js
import { serveMcpHttp } from '@empyria/mcp'

serveMcpHttp(
    { name: 'my-mcp-server', version: '1.0.0', services: [WeatherService] },
    { port: 3000 },
)
```

`serveMcpHttp` 为MCP服务 `Bun.serve` 直接-不需要web框架。MCP的官方 `createMcpHandler` 生成一个简单的web标准 `{ fetch: (Request) => Promise<Response>, close }` 处理程序（可用于任何Fetch-API服务器，包括Bun）； `@modelcontextprotocol/hono` 在几个可选适配器中只有一个用于将处理程序连接到Hono，不是吗 一个要求。如果你需要裸 `{fetch, close}` 处理程序，而不是已经运行的Bun 服务器(例如安装在您自己的 `Bun.serve`，或另一个基于fetch的运行时)，使用 `createMcpHttpHandler(options)` 代替。

### 使用令牌保护服务

服务可以通过添加令牌来要求令牌 `resolveToken` 函数- mcp端等效的 `empyria-guard-moleculer`的 `MetaGuard.middleware.js`，重复使用与它相同的形状 `getUser(ctx, action)`：

```js
const SecretsService = {
    name: 'Secrets',
    async resolveToken(tokenKey, { service, action }) {
        // look the token up however you like — call another service, hit a DB, etc.
        // return the resolved user/session, or a falsy value to reject the call
        return lookupUser(tokenKey)
    },
    actions: {
        reveal: {
            params: { id: string() },
            handler: async ({ id }, extra) => `secret for ${extra.user.name}`,
        },
    },
}
```

令牌从 `Authorization` 头文件（可选） `Bearer` 前缀被剥离)， 或自定义标题via `guard: { tokenHeader: 'x-token-key' }` 传递给 `createMcpServer`/ `serveMcpHttp`． 缺少令牌或未解析令牌的调用将作为正常的工具调用被拒绝 错误，并将解析的值附加到处理程序的 `extra.user`是分子的镜像 `ctx.meta.user`. **这只适用于HTTP** -令牌作为请求头传播，工作室有 没有一个;一个 `resolveToken`通过studio调用的受保护服务总是被拒绝。服务,而不 `resolveToken` 不受影响（公开）-它完全是选择加入，每个服务。

### 作为客户机连接

```js
import { connectStdioClient, connectHttpClient } from '@empyria/mcp'

const stdioClient = await connectStdioClient({
    name: 'my-client',
    version: '1.0.0',
    command: 'node',
    args: ['./my-server.js'],
})

const httpClient = await connectHttpClient({
    name: 'my-client',
    version: '1.0.0',
    url: 'http://localhost:3000',
    token: 'my-token', // sends Authorization: Bearer my-token
})

const { tools } = await httpClient.listTools()
await httpClient.callTool({ name: 'Weather.getForecast', arguments: { city: 'Zurich' } })
```

### 将多个MCP服务器聚合为一个（网关）

如果您有多个MCP服务器，并希望将它们作为一个代理主机公开 连接-更少的配置项，一个地方应用 `lib/Guard.js`等-连接到每个as 一个客户，然后交给他们 `createMcpGateway`：

```js
import { connectStdioClient, connectHttpClient, createMcpGateway } from '@empyria/mcp'
import { StdioServerTransport } from '@modelcontextprotocol/server/stdio'

const weather = await connectStdioClient({
    name: 'gw',
    version: '1.0.0',
    command: 'node',
    args: ['./weather-server.js'],
})
const search = await connectHttpClient({
    name: 'gw',
    version: '1.0.0',
    url: 'http://localhost:4000',
})

const gateway = await createMcpGateway({
    name: 'my-gateway',
    version: '1.0.0',
    upstreams: [
        { name: 'Weather', client: weather },
        { name: 'Search', client: search },
    ],
})

await gateway.connect(new StdioServerTransport())
```

每个上游的工具都在前面列出一次，并作为 `"<upstream.name>.<toolName>"`;调用被转发到所属的上游及其结果 直接通过，第二次未验证-上游已经验证过了。 建立一个网关确实有用 `listTools()` 每个上游)，因此构建一次并重用 相同的实例——包括as `createMcpHandler`HTTP的per-request factory，例如inside `serveMcpHttp`的 `bunOptions.fetch` -而不是每次请求都重新连接上游。

## 模块

| 模块 | 目的 |
| --- | --- |
| [lib / Server.js](https://npmcn.com/package/%40empyria/mcp/lib/Server.js) | `createMcpServer` -发布了一个分子型的列表 `{ name, actions }` 服务作为MCP工具。 |
| [lib / Http.js](https://npmcn.com/package/%40empyria/mcp/lib/Http.js) | `createMcpHttpHandler` （运行时无关的web标准处理程序）和 `serveMcpHttp` (只有面包方便，包装 `Bun.serve`）。 |
| [lib / Guard.js](https://npmcn.com/package/%40empyria/mcp/lib/Guard.js) | `withMetaGuard` -可选的每个服务令牌保护；见上图。 |
| [lib / Client.js](https://npmcn.com/package/%40empyria/mcp/lib/Client.js) | `createMcpClient`， `connectStdioClient`， `connectHttpClient` -客户端助手。 |
| [lib / Gateway.js](https://npmcn.com/package/%40empyria/mcp/lib/Gateway.js) | `createMcpGateway` -将多个已连接的上游MCP客户端聚合到一个服务器上。 |
| [lib / Validator.js](https://npmcn.com/package/%40empyria/mcp/lib/Validator.js) | `empyriaJsonSchemaValidator` -适应 `@empyria/common`的 `createValidator` 到MCP SDK的可插拔JSON模式验证器接口，相同的扩展点是它自己的 `ajv`/`cf-worker` 供应商使用。 |

没有官方的JSON-Schema-only便利API `@modelcontextprotocol/server` ——它的 `registerTool()` 仍然需要一个“标准模式”（Zod生成的）。什么 _是_ 官方和 Zod-free是 `fromJsonSchema(schema, validatorProvider)`，它包装了一个普通的JSON Schema对象 转换为给定验证器提供程序的标准模式——就是这样 `lib/Server.js` 用途，由 `lib/Validator.js` 而不是SDK自己的 `ajv`/`cf-worker` 提供者。

每个导出的函数都直接用JSDoc记录在其源文件中——悬停 VSCode或Zed中的函数显示其参数和返回类型，不需要任何额外的内容 工具，因为两个编辑器都从plain读取JSDoc `.js` 自动文件。

测试在 [测试/](https://npmcn.com/package/%40empyria/mcp/test/)，每个模块一个文件。他们开着真正的 `@modelcontextprotocol/client` `Client` 反对服务器over `InMemoryTransport` 而不是 嘲弄协议。

## 脚本

```bash
bun run format       # check formatting (oxfmt)
bun run format:fix   # apply formatting
bun run lint         # lint (oxlint)
bun run lint:fix     # lint and fix
bun run test         # run tests with coverage
```

## 许可证

MIT©Imre Fazekas

## 常见问题

### @empyria/mcp 是什么？

用于Empyria纳米服务框架的MCP（模型上下文协议）助手

### 如何安装 @empyria/mcp？

在项目目录运行 npm install @empyria/mcp，或使用 pnpm add / yarn add / bun add。

### @empyria/mcp 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/empyria\_\_mcp 是否存在。

### @empyria/mcp 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @empyria/mcp 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=26。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @empyria/mcp 可以商用吗？

@empyria/mcp 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @empyria/mcp 还在维护吗？

最新版本 0\.1\.29 发布于 2026/11/01（2 天前）；至今共发布 30 个版本，其中过去 12 个月发布了 30 个；首次发布于 2026/08/16。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。