使用说明

MCP服务器启动模板

一个用于构建的全面初始模板 模型上下文协议（MCP）服务器专为UI库和组件注册表设计。此模板为创建MCP服务器提供了坚实的基础，这些服务器能够获取、分类并向像Claude这样的AI助手提供组件信息。

🌎 现实世界的例子？

查看一下 stackzero-labs/mcp 翻译为中文是：“stackzero实验室/MCP（或‘多播通信协议’，具体含义需根据上下文确定）”。不过，通常在没有特定上下文的情况下，“MCP”可能是一个项目、协议或特定技术的名称，因此直接翻译可能不够准确。如果“MCP”在stackzero-labs中有特定的含义或项目名称，建议查找相关资料以获取更准确的翻译。在这里，我给出了一个较为通用的翻译，即“stackzero实验室/MCP（多播通信协议）”，但实际使用时可能需要根据具体情况调整。该模板用于向AI模型暴露其UI组件和模块。您也可以查看引用的UI项目 stackzero/ui 翻译为中文是“零栈/用户界面”。不过，这里的“stackzero”可能是一个特定项目或公司的名称，如果它有官方的中文译名，那么应该使用那个译名。在没有官方译名的情况下，“零栈”是一个较为直译的翻译，但具体含义还需结合上下文来理解

🚀 特性

即开即用的MCP服务器 支持TypeScript
组件注册表集成 用于UI库
分类组件组织 具有灵活的分类系统
Zod模式验证 为了类型安全
开发工具 包括热重载和检查器
示例实现 使用真实项目URL进行演示
可扩展架构 用于自定义组件类型和类别

📋 前提条件

Node.js 18 或更高版本
pnpm（推荐）或 npm
对TypeScript和MCP的基本了解

🤝 预期使用场景

这个模板是专门为遵循（某种标准或规范的）图书馆设计的 registry 格式（如 shadcn/ui)，使其非常适合：

用户界面组件库
设计系统
需要通过AI助手访问的组件注册表
需要以结构化方式将UI组件暴露给AI模型的工具、实用程序和框架

在此了解更多关于如 shadcn/ui 这样的组件注册表的信息组件注册表。

不过，通过一些定制化调整，它也可以适应其他类型的MCP服务器。

🛠️ 安装

克隆或下载此模板：

git clone https://github.com/mnove/mcp-starter.git
cd mcp-starter

安装依赖项：

pnpm install

构建项目：

pnpm run build

⚙️ 配置

1. 更新项目配置

编辑 src/lib/config.ts 指向您自己的组件注册表：

export const mcpConfig = {
  projectName: "your-project-name",
  // Replace with your actual project URL
  baseUrl: "https://your-ui-library.com",
  registryUrl: "https://your-ui-library.com/r",
  registryFileUrl: "https://your-ui-library.com/registry.json",
};

注这个模板目前使用的是 https://ui.stackzero.co 作为演示URL。你可以必须在生产环境中，请将此替换为您的实际项目URL。

2. 定义组件类别

定制化 src/lib/categories.ts 以匹配您的组件结构：

export const componentCategories = {
  Buttons: ["button-primary", "button-secondary", "button-ghost"],
  Forms: ["input-text", "input-email", "textarea"],
  // Add your categories here
};

3. 更新服务器元数据

修改 src/server.ts 自定义您的服务器信息：

const server = new McpServer({
  name: "your-mcp-server-name",
  version: "1.0.0",
});

🏃‍♂️ 开发

启动开发服务器

pnpm run dev

为生产构建（或准备生产环境）

pnpm run build

检查MCP服务器

pnpm run inspect

这将打开MCP检查器，以便您交互式地测试您的服务器工具。确保你的授权令牌（auth token）出现在检查器（inspector）的URL中，否则连接将会失败。

📚 可用工具

MCP服务器提供以下工具：

`getUIComponents`

从您的注册表中返回所有用户界面组件的完整列表。

特定类别的工具

为每个定义的类别创建动态工具 componentCategories：

getButtons - 获取所有按钮组件
getForms - 获取所有表单组件
等等。

每个类别工具提供：

组件实现细节
使用示例
安装说明
相关组件

🏗️ 项目结构

mcp-starter/
├── src/
│   ├── server.ts              # Main MCP server implementation
│   ├── lib/
│   │   ├── config.ts          # Configuration settings
│   │   └── categories.ts      # Component categories
│   └── utils/
│       ├── api.ts             # API fetching utilities
│       ├── formatters.ts      # Data formatting helpers
│       ├── schemas.ts         # Zod validation schemas
│       └── index.ts           # Utility exports
├── dist/                      # Built files
├── package.json
└── README.md

🔧 定制化

添加新的组件类型

更新模式（或架构） 在 src/utils/schemas.ts：

export const CustomComponentSchema = z.object({
  name: z.string(),
  category: z.string(),
  // Add your fields
});

添加API函数 在 src/utils/api.ts：

export async function fetchCustomComponents() {
  // Your implementation
}

注册新工具 在 src/server.ts：

server.tool("getCustomComponents" /*...*/);

扩展类别

只需添加新类别到 src/lib/categories.ts：

export const componentCategories = {
  // Existing categories...
  Navigation: ["navbar", "sidebar", "breadcrumbs"],
  DataDisplay: ["table", "card", "badge"],
};

服务器将自动为新类别创建工具。

为什么要分类？

分类有助于逻辑地组织组件，从而使AI助手能够更容易地查找并基于此建议相关组件。此外，一些模型和集成开发环境（IDE）对它们能处理的工具数量有限制，因此对工具进行分类有助于保持工具数量在可控范围内。

您可以根据自己的需求随意定制类别，具体取决于您的具体情况。如果您没有很多工具，那么您也可以考虑完全不使用类别。

📖 注册表格式

您的组件注册表应遵循以下结构：

注册表文件（`registry.json`)

{
  "registry": [
    {
      "name": "button-primary",
      "type": "registry:component",
      "description": "Primary button component"
    }
  ]
}

组件详情（`/r/{component-name}.json`）

{
  "name": "button-primary",
  "type": "registry:component",
  "files": [
    {
      "content": "// Component implementation"
    }
  ]
}

🚀 部署

作为本地MCP服务器

构建项目：

pnpm run build

在您的MCP客户端（例如，Claude桌面版）中进行配置：

{
  "mcpServers": {
    "your-mcp-server": {
      "command": "node",
      "args": ["/path/to/mcp-starter/dist/server.js"]
    }
  }
}

作为一个NPM包

你也可以将此模板发布为一个NPM包，以便在其他项目中轻松安装。

更新 package.json 附上您的详细信息
构建并发布：

pnpm run build
npm publish

🤝 贡献

见 `CONTRIBUTING.md` 翻译为中文是：`贡献指南.md` 或 `如何贡献.md`（根据具体语境，也可简化为“贡献说明.md”等）。这个文件通常用于说明如何向某个项目或组织做出贡献，包括贡献的流程、规范、要求等有关如何为该项目做出贡献的详细信息。

📄 许可证

这个项目采用MIT许可证授权——详见许可证文件中有详细信息。

🤝 联系方式

马塞洛 - @mnove（这个用户名或标签在中文中通常保持不变，直接翻译为“@mnove”即可）

🙏 致谢

用……建造模型上下文协议软件开发工具包（SDK）
最初灵感来源于magic-ui MCP服务器
受更好地集成AI组件的需求启发
感谢MCP社区的贡献

⚠️ 重要记得更换 https://ui.stackzero.co 在生产环境中使用此模板之前，请替换为您的实际项目URL！