动态表单 MCP (模型上下文协议)

本文件描述了如何使用 MCP（Model Context Protocol）服务器来管理动态表单。该服务器提供了使用 @dynamicfrm/js 库创建、获取和管理动态表单响应的工具。此服务器设计为与 MCP 客户端一起使用，例如集成在 Visual Studio Code 中的 MCP 检查器。

先决条件

确保你的系统上已安装 Node.js 和 npm（或 yarn）。同时假设你已经安装了 Visual Studio Code 并启用了 MCP 检查器扩展。

安装与构建

1. 克隆或下载此仓库（如果适用）。

2. 在终端中导航到项目目录。

3. 安装必要的依赖项：

   npm install
   # 或者
   yarn add
   

   这将安装服务器使用的主要依赖项：

   • @modelcontextprotocol/sdk/server/mcp.js: 用于创建 MCP 服务器。
   • @modelcontextprotocol/sdk/server/stdio.js: 用于 MCP 服务器的标准输入/输出传输。
   • zod: 用于验证工具的输入数据。
   • uuid: 用于生成表单的唯一 UUID。
   • @dynamicfrm/js: 创建和管理动态表单的主要库。

4. 构建项目：

   npm run build
   

   此命令将在构建目录 (build) 中生成必要的文件，包括服务器主文件 (index.js)。

在 Visual Studio Code 中配置 MCP 检查器

为了让 VS Code 的 MCP 检查器发现并能够与此服务器交互，你需要在 VS Code 设置 (settings.json) 中配置 mcp 部分。一个示例配置如下：

{
  "chat.mcp.discovery.enabled": true,
  "mcp": {
    "inputs": [],
    "servers": {
      "dynamicform": {
        "command": "node",
        "args": [
          "/ruta/absoluta/a/tu/proyecto/build/index.js"
        ]
      }
    }
  }
}

重要： 将 /ruta/absoluta/a/tu/proyecto/build/index.js 替换为你实际的 index.js 文件的绝对路径。

通过 VS Code 的 MCP 检查器运行

配置完成后，VS Code 的 MCP 检查器应能自动检测到 dynamicform 服务。你可以直接从检查器界面与服务器公开的工具进行交互。

要与工具交互，请执行以下步骤：

1. 在 VS Code 中打开 MCP 检查器（通常通过命令面板或侧边栏）。
2. 查找 dynamicform 服务。
3. 选择你要使用的工具（例如 create-form）。
4. 在检查器的输入面板中以 JSON 格式提供所需的输入参数。
5. 执行工具。
6. 服务器的响应将显示在检查器的结果面板中。

可用工具

动态表单 MCP 服务器公开了以下可以通过 MCP 检查器调用的工具：

create-form

描述: 创建一个带有自定义字段的新动态表单。

参数:

{
  title: z.string().min(3).describe('Título del formulario'),
  fields: z
    .array(
      z.object({
        type: z.string().describe('Tipo de campo (e.g., text-field, list-field)'),
        name: z.string().describe('Nombre del campo'),
        label: z.string().optional().describe('Etiqueta para mostrar en el formulario'),
        placeholder: z.string().optional().describe('Texto de marcador de posición'),
        required: z.boolean().optional().describe('Indica si el campo es obligatorio'),
        options: z.array(z.string()).optional().describe('Opciones para campos de lista'),
        url: z.string().optional().describe('URL para campos como qr-field o yt-video'),
        email: z.string().optional().describe('Correo electrónico para email-field'),
        subject: z.string().optional().describe('Asunto para email-field'),
        minLength: z.number().optional().describe('Longitud mínima para campos de texto'),
        maxLength: z.number().optional().describe('Longitud máxima para campos de texto'),
        pattern: z.string().optional().describe('Patrón de validación para campos de texto'),
        defaultValue: z.string().optional().describe('Valor por defecto del campo'),
      })
    )
    .min(1)
    .describe('Lista de campos del formulario'),
}

使用示例（通过 MCP 检查器）:

{
  "title": "Formulario de Contacto",
  "fields": [
    {
      "type": "text-field",
      "name": "nombre",
      "label": "Nombre",
      "required": true
    },
    {
      "type": "email-field",
      "name": "correo",
      "label": "Correo Electrónico",
      "required": true
    },
    {
      "type": "text-area",
      "name": "mensaje",
      "label": "Mensaje"
    }
  ]
}

响应:

如果成功，响应将包含创建的表单的 URL：

{
  "content": [
    {
      "type": "text",
      "text": "Formulario creado exitosamente: <URL_DEL_FORMULARIO>"
    }
  ]
}

如果出错，响应将指示问题所在：

{
  "content": [
    {
      "type": "text",
      "text": "Ha ocurrido un error: <mensaje_de_error>"
    }
  ]
}