AI导哈

RAML生成器

一个基于Node.js和React的应用程序，利用AI从数据库模式生成RAML（RESTful API建模语言）规范。

  • by sasibhumaraju
  • JavaScript
  • 本地部署
  • 更新于
在 GitHub 查看 sasibhumaraju/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

  2. 定义您的架构:

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

  3. 生成RAML:

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

  4. 验证并修复:

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

  5. 下载:

    • 点击“下载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": "<!DOCTYPE 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）

许可证

麻省理工学院

相关 MCP