Create Dzx

二氮嗪

Dzx是在Dwizi上构建MCP服务器的开放框架。它规范了Node和Deno的仓库结构、工具/资源/提示发现和运行时配置。

运行时间要求： Node.js 24+（ESM优先）。

入门指南

刚到dzx？ 从 入门指南 全面介绍：

• 为什么选择dzx以及何时使用它
• 快速入门教程
• 了解构建模式、开发模式和运行时模式
• 项目结构和常见问题

快速脚手架：

npx @dwizi/create-dzx@latest

create-dzx 是的别名 dzx init （脚手架模式），因此整个设置都来自同一个代码库。

回购布局

.
├─ mcp.json
├─ tools/
│  └─ *.ts
├─ resources/
│  └─ *.md
├─ prompts/
│  └─ *.md
└─ src/
   └─ server.ts

运行时和CLI架构

• 共享核心：清单解析、发现和捆绑逻辑。
• 节点CLI： @dwizi/dzx （开发/检查/验证/构建）。
• Deno CLI： @dwizi/dzx-deno （相同的命令，Deno运行时）。

封装结构（dzx）

packages/dzx/
  src/        core + runtime + CLI
  templates/  create-dzx templates
  scripts/    build + smoke test
  mcp.schema.json
  tool-manifest.schema.json

开发日志和环境加载

dzx dev 默认情况下打印请求+工具日志。使用 --quiet 尽量减少输出或 --verbose 包括RPC+结构化输出日志。

环境文件按以下顺序加载：

1. .env
2. .env.local
3. .env.
4. .env..local

mode 是 development 默认情况下（或 NODE_ENV / DZX_ENV).现有的 process.env 值会覆盖文件值。

开发人员仪表板：

• 访问 http://localhost:3333/ 查看带有端点和工具/资源/提示列表的简单本地仪表板。

超时：

• DZX_TOOL_TIMEOUT_MS 设置工具执行超时（默认值：30000ms）。

mcp.json

清单定义了运行时、入口点和权限。看 mcp.schema.json 对于完整的模式。

最小示例：

{
  "name": "weather-tools",
  "version": "0.1.0",
  "runtime": "node",
  "entry": "src/server.ts",
  "toolsDir": "tools",
  "resourcesDir": "resources",
  "promptsDir": "prompts",
  "permissions": {
    "network": false,
    "filesystem": { "read": ["./resources", "./prompts"], "write": [] }
  }
}

验证规则（摘要）

• name, version, runtime，以及 entry 是必需的。
• runtime 必须 node 或 deno.
• entry 必须是仓库中的相对路径。
• toolsDir, resourcesDir, promptsDir 必须是相对路径。
• permissions.filesystem.read/write 是路径异教徒；默认设置为无写访问权限。
• build.command 是可选的；如果存在， build.output 必须提供。

工具发现

工具是从以下位置发现的 tools/ 作为 默认导出工具名称来自文件路径（例如， tools/smart-hello.ts → smart-hello).

构建输出

dzx build 生产：

• dist/tools/* 捆绑工具文件（每个工具或捆绑）
• dist/resources/* 复制的资源
• dist/prompts/* 复制提示
• dist/tool-manifest.json dwizi导入流使用的清单

开发人员监视模式

如果您的系统达到文件描述符限制，请启用轮询：

dzx dev --poll

无插座开发模式（EPERM）

一些沙盒环境会阻止TCP侦听器并引发 EPERM在dev中，dzx 回退到Unix套接字（默认值： /tmp/dzx-.sock).如果插座 它也被阻止，它在不监听的情况下保持进程活动，并打印警告。

您可以通过以下方式控制套接字路径：

DZX_SOCKET=/tmp/dzx.sock dzx dev

协议版本

如果您的MCP客户端需要特定的协议版本，请将其设置为 mcp.json:

{
  "protocolVersion": "2025-11-25"
}

可选MCP方法

您可以在中选择加入其他MCP方法 mcp.json:

{
  "mcp": {
    "methods": {
      "resourcesTemplatesList": true,
      "completionComplete": true,
      "notificationsComplete": true
    }
  }
}

客户端兼容性

dzx接受斜线和点划线方法名，并支持SSE流。

支持的方法：

• initialize （返回工具/资源/提示和 protocolVersion)
• notifications/initialized
• tools/list, tools/call （也 tools.list, tools.call)
• resources/list, resources/read, resources/subscribe, resources/unsubscribe
• prompts/list, prompts/get
• logging/setLevel, notifications/cancelled, notifications/canceled
• 可选： resources/templates/list
• 可选： completion/complete
• 可选： notifications/complete, notifications/completed

流动：

• 添加 ?stream=1 或 Accept: text/event-stream 获得SSE(event: message).

推荐（Zod优先）

在MCP仓库中安装Zod：

pnpm add zod

import { z } from "zod";
import { defineSchema } from "@dwizi/dzx/schema";

/**
 * Adds two numbers.
 */
export default async function add(input: { a: number; b: number }) {
  return { sum: input.a + input.b };
}

export const schema = {
  input: defineSchema(z.object({
    a: z.number(),
    b: z.number()
  })),
  output: defineSchema(z.object({
    sum: z.number()
  }))
};

标准（JSON模式）

/**
 * Adds two numbers.
 */
export default async function add(input: { a: number; b: number }) {
  return { sum: input.a + input.b };
}

export const schema = {
  input: {
    type: "object",
    properties: { a: { type: "number" }, b: { type: "number" } },
    required: ["a", "b"]
  },
  output: {
    type: "object",
    properties: { sum: { type: "number" } }
  }
};

自动模式推理（JSDoc）

如果不导出模式， dzx 从JSDoc推断出来 @param 标签。

/**
 * Multiply two numbers.
 * @param {object} input
 * @param {number} input.a
 * @param {number} [input.b] Optional multiplier
 */
export default async function multiply(input) {
  // ...
}

这将生成一个JSON模式 a （必填）以及 b （可选）。

架构要求

始终为工具清单和运行时验证生成模式。

• 如果你出口 schema，它将被直接使用。
• 否则，dzx将从JSDoc推断模式(@param, @returns).
• 如果缺少JSDoc，dzx将根据函数签名（键入的参数或破坏的参数）进行推断。
• 如果推理没有发现任何结果，dzx将退回到许可模式：

- 输入： { type: "object", properties: {}, additionalProperties: true } - 输出： { type: "object", properties: {}, additionalProperties: true }

自定义验证器（Joi/Yup/等）

dzx 与图书馆无关。如果您的模式对象实现 .parse() 或 .validate()，运行时验证将使用它。如果它也实现了 .toJSONSchema()，发现和工具将把它暴露给LLM。

上下文中间件

您可以将请求范围的上下文（例如身份验证、数据库连接）注入到所有工具中。

1. 创建 src/context.ts （或 .js):

   import type { IncomingMessage } from "http";

   export default function createContext(req: IncomingMessage) {
     return {
       user: req.headers["x-user-id"],
       db: process.env.DB_URL
     };
   }

1. 在工具中访问上下文（第二个参数）：

   export default async function myTool(args, context) {
     console.log(context.user); // Access injected context
   }

测试SDK

dzx 提供了一个测试SDK，用于在进程中验证您的工具和上下文（无需启动完整的HTTP服务器）。

import { createTestServer } from "@dwizi/dzx/testing";
import assert from "node:assert";

// 1. Initialize server
const client = await createTestServer({ cwd: process.cwd() });

// 2. Call tool with arguments and optional mock context
const result = await client.callTool("myTool", { a: 1 }, { user: "TestUser" });

assert.equal(result.sum, 2);

资源

资源是Markdown文件 resources/文件名是默认的资源名称。

可选正面：

---
name: getting-started
description: Quick start guide
---
# Getting Started
...

提示

提示是Markdown文件 prompts/ 带有可选的前盖。

---
name: summarize
description: Summarize text in 3 bullets
inputs:
  - name: text
    type: string
---
Summarize the following:
{{text}}

计划CLI

• dzx dev 本地MCP服务器
• dzx inspect 列出工具/资源/提示
• dzx validate 验证 mcp.json
• dzx build 生成可部署的捆绑包

创建dzx

使用模板构建新的MCP回购。

例子：

npx @dwizi/create-dzx@latest --template basic

默认情况下，它会安装依赖项。使用 --no-install 跳过。

对于现有目录中的手动设置：

dzx init --template basic --force

发布（清单）

在发布到npm之前 @dwizi/dzx:

• pnpm --filter @dwizi/dzx test
• pnpm --filter @dwizi/dzx build
• pnpm -C packages/dzx publish --dry-run
• pnpm -C packages/dzx publish --access public

附加文档

• docs/getting-started.md — 在这里开始：全面的入门指南
• docs/README.md --文件索引
• CLI.md --命令和标志矩阵
• ARCHITECTURE.md --设计+流程概述
• CORE.md --共享核心布局
• tool-manifest.schema.json --构建输出模式
• examples/tool-manifest.json --示例清单

许可证

麻省理工学院（见根 LICENSE).