Raml MCP Server

RAML生成器

一个完整的Node.js+Rreact应用程序，用于使用AI从数据库模式生成RAML（RESTful API建模语言）规范。该应用程序通过Ollama（默认）或OpenAI使用Qwen2.5作为后备。

特性

• 模式编辑器：用于定义数据库表、字段和数据类型的交互式UI
• 人工智能发电：使用Qwen2.5（通过Ollama）或OpenAI生成RAML规范
• RAML编辑器：摩纳哥编辑器，用于查看和编辑生成的RAML
• HTML预览：以HTML格式并排预览生成的RAML
• 验证：内置RAML验证和错误报告
• 自动修正：针对无效RAML的AI纠错

先决条件

• Node.js 18+和npm
• Ollama（用于默认Qwen2.5型号）或OpenAI API密钥

设置

1.安装Ollama（推荐）

下载并安装Ollama https://ollama.ai

拉动Qwen2.5型号：

ollama pull qwen2.5

启动Ollama（它应该自动运行，但如果不是）：

ollama serve

2.安装依赖项

从项目根：

npm run install:all

这将安装服务器和客户端的依赖关系。

3.配置环境

复制 .env.example 到 .env:

cp .env.example .env

编辑 .env 如果需要：

• USE_OLLAMA=true -使用Ollama（默认）或设置为 false OpenAI
• OLLAMA_URL=http://127.0.0.1:11434 -Ollama服务器URL
• MODEL_NAME=qwen2.5 -Ollama的型号名称
• OPENAI_API_KEY= -您的OpenAI API密钥（如果使用OpenAI回退）
• PORT=3001 -服务器端口

运行应用程序

选项1：单独运行（建议用于开发）

终端1-启动服务器：

npm run dev:server
# or
npm start

终端2-启动客户端：

npm run dev:client

服务器将在上运行 http://localhost:3001 客户在 http://localhost:3000.

选项2：使用流程管理器

您可以使用以下流程管理器 concurrently 或 pm2 一起跑步。添加到root package.json:

"dev": "concurrently \"npm run dev:server\" \"npm run dev:client\""

然后运行：

npm run dev

用法

1. 打开应用程序 在浏览器中 http://localhost:3000

1. 定义您的架构:

- 单击“添加表”以创建新表 - 输入表名 - 单击“添加字段”将字段添加到表中 - 从下拉列表中选择字段类型（varchar、text、integer、bigint、decimal、boolean、timestamp、date、float）

1. 生成RAML:

- 点击“生成RAML”按钮 - 该系统将： - 使用AI从模式中提取实体图 - 生成RAML规范 - 验证RAML - 如果验证失败，尝试更正 - 在RAML编辑器和HTML预览中显示结果

1. 验证并修复:

- 点击“验证”查看当前RAML - 如果发现错误，请单击“修复错误”尝试自动更正 - 错误将显示在底部的错误面板中

1. 下载:

- 点击“下载RAML”保存生成的RAML文件

示例架构

以下是您可以在UI中创建的示例模式：

用户表：

• id（整数）
• 名称（varchar）
• 电子邮件（varchar）
• created_at（时间戳）

职位表：

• id（整数）
• 标题（varchar）
• 内容（文本）
• user_id（整数）
• created_at（时间戳）

这将生成一个RAML规范，其中包括：

• 用户和帖子的类型定义
• CRUD操作的RESTful端点
• 请求/响应模式

项目结构

raml-generator-cursor/
├── package.json              # Root package.json
├── .env.example              # Environment variables template
├── .gitignore
├── README.md
├── server/
│   ├── index.js              # Express server with /generate, /validate, /fix endpoints
│   ├── modelClient.js        # Ollama/OpenAI client abstraction
│   └── ramlFormatter.js      # RAML generation and HTML conversion
└── client/
    ├── package.json
    ├── vite.config.js        # Vite configuration with proxy
    ├── index.html
    └── src/
        ├── main.jsx          # React entry point
        ├── App.jsx           # Main app component
        ├── styles.css        # Global styles
        └── components/
            ├── SchemaEditor.jsx   # Table/field editor UI
            ├── RamlEditor.jsx     # Monaco editor for RAML
            └── HtmlPreview.jsx    # HTML preview iframe

API终点

POST/生成

从模式数据生成RAML。

请求：

{
  "uiData": {
    "tables": [
      {
        "name": "User",
        "fields": [
          { "name": "id", "type": "integer" },
          { "name": "name", "type": "varchar" }
        ]
      }
    ],
    "relations": []
  },
  "maxRetries": 3
}

答复：

{
  "success": true,
  "raml": "#%RAML 1.0\n...",
  "html": "..."
}

POST/验证

验证RAML内容。

请求：

{
  "raml": "#%RAML 1.0\n..."
}

答复：

{
  "valid": true,
  "errors": []
}

POST/修复

尝试使用AI修复RAML错误。

请求：

{
  "raml": "#%RAML 1.0\n...",
  "errors": [...],
  "maxRetries": 3
}

答复：

{
  "success": true,
  "raml": "#%RAML 1.0\n...",
  "errors": []
}

故障排除

Ollama连接问题

如果您看到“无法连接到Ollama”错误：

1. 确保Olama正在运行： ollama serve
2. 检查模型是否已拉动： ollama list
3. 验证中的URL .env 匹配您的Ollama实例
4. 集 USE_OLLAMA=false 并提供 OPENAI_API_KEY 改用OpenAI

端口已在使用中

如果端口3001或3000已在使用中：

• 改变 PORT 在 .env 对于服务器
• 改变 port 在 client/vite.config.js 为客户

模型响应问题

如果模型返回无效的JSON或RAML：

• 系统将自动尝试重试
• 检查控制台日志以获取详细的错误消息
• 尝试降低架构复杂性或拆分为更小的表

开发说明

• 服务器使用 raml-1-parser 用于验证
• 温度设置为0.0以进行确定性生成
• 该系统使用两步方法：提取实体图，然后格式化为RAML
• 纠错循环高达 maxRetries 次数（默认值：3）

许可证

麻省理工学院