铁路-MCP-测试

作者：AgentArtel0 星标更新：2025-11-23

项目介绍

统一的Lovable MCP服务器

一个托管在Railway上的中心化模型上下文协议（MCP）服务器，结合了多个MCP提供商。包括Magic UI、Shadcn UI、Aceternity UI、8bitcn、品牌系统（设计API）、AI路由器和自定义组件——易于扩展以添加更多！

🎯 目的

这是一个统一的MCP服务器，托管多个MCP提供商，提供单一端点来访问所有组件库、设计令牌和AI工具。非常适合Lovable开发，其中你需要一致地访问：

组件库：Magic UI（68个），Shadcn UI（59个），Aceternity UI（96个），8bitcn（55个）——总共278个组件
设计系统API：完整的品牌系统，包含设计令牌、主题和验证
AI操作：通过n8n网络钩子解耦的AI路由器
自定义组件：你自己的组件库

为什么统一？

单次连接：只需一次连接到Lovable，即可访问所有MCP服务器
简单管理：所有MCP服务器在一个代码库中
可扩展性：使用模块化架构轻松添加新的MCP提供商
始终可用：Railway确保其全天候运行

🚀 快速开始

本地开发

安装依赖项：

npm install

启动服务器：

npm start

服务器将在http://localhost:4001上运行（或由PORT环境变量指定的端口）。

部署到Railway

将你的GitHub仓库连接到Railway：
- 转到Railway.app
- 点击“新建项目”
- 选择“从GitHub仓库部署”
- 选择这个仓库
Railway会自动执行以下操作：
- 检测Node.js项目
- 安装依赖项
- 使用npm start启动服务器
- 分配公共URL
获取你的服务器URL：
- Railway会提供一个公共URL（例如，https://your-app.railway.app）
- 复制此URL用于连接到Lovable

🔌 连接到Lovable

步骤配置

获取你的Railway服务器URL
- 你的URL：https://design-api-mcp-production.up.railway.app
在Lovable中，转到MCP/外部服务：
- 导航到你的Lovable项目
- 前往设置→MCP服务器或外部服务
- 点击添加MCP服务器或添加外部服务
填写连接详情：

基本设置：
- 服务器名称：设计API MCP服务器（或你喜欢的任何名称）
- 服务器URL：https://design-api-mcp-production.up.railway.app
- 连接类型：选择HTTP或MCP
MCP端点（如果单独提示）：
- 初始化：/mcp/initialize
- 列出工具：/mcp/tools/list
- 调用工具：/mcp/tools/call
- 列出资源：/mcp/resources/list
- 读取资源：/mcp/resources/read
OAuth2设置（如果需要）：
- OAuth客户端ID：lovable-client（或任何值——我们的服务器接受任何值）
- OAuth客户端密钥：lovable-secret（或任何值——我们的服务器接受任何值）
- 授权URL：https://design-api-mcp-production.up.railway.app/oauth2/authorize
- 令牌URL：https://design-api-mcp-production.up.railway.app/oauth2/token
- 范围：mcp:read mcp:write（或留空）
保存并测试：
- 点击保存或连接
- Lovable现在应该连接到你的MCP服务器
- 你应该能看到所有35个工具

快速测试

手动测试连接：

# 健康检查
curl https://design-api-mcp-production.up.railway.app/health

# 应返回：{"status":"ok","service":"mcp-server"}

故障排除

如果你仍然遇到OAuth错误：

在Railway重新部署后等待2-3分钟
检查Railway日志，确保服务器正在运行
尝试发现端点：https://design-api-mcp-production.up.railway.app/.well-known/oauth-authorization-server
验证端点是否可访问（没有404错误）

📡 API端点

MCP协议端点

POST /mcp/initialize - 初始化MCP连接
POST /mcp/tools/list - 列出可用工具
POST /mcp/tools/call - 执行工具
POST /mcp/resources/list - 列出可用资源
POST /mcp/resources/read - 读取特定资源

实用端点

GET /health - 健康检查端点
GET / - 服务器信息

🛠️ 可用工具

组件库工具

Magic UI（68个组件）

magicui_get_component - 根据名称获取组件
magicui_list_components - 列出所有组件（按类别过滤）
magicui_search_components - 关键词搜索组件
magicui_get_component_context - 获取详细上下文、用例和示例

Shadcn UI（59个组件）

shadcn_get_component - 根据名称获取组件
shadcn_list_components - 列出所有组件（按类别过滤）
shadcn_search_components - 关键词搜索组件
shadcn_get_component_code - 获取完整源代码
shadcn_get_installation_command - 获取CLI安装命令
shadcn_get_component_context - 获取详细上下文、用例和示例

Aceternity UI（96个组件）

aceternity_get_component - 根据名称获取组件
aceternity_list_components - 列出所有组件
aceternity_search_components - 关键词搜索组件
aceternity_get_component_context - 获取详细上下文、用例和示例

8bitcn（55个组件）

eightbit_get_component - 根据名称获取组件
eightbit_list_components - 列出所有组件
eightbit_search_components - 关键词搜索组件
eightbit_get_component_context - 获取详细上下文、用例和示例

品牌系统（设计API）工具

品牌系统提供了完整的Design System API，具有嵌套属性访问、验证和有用的错误消息。

颜色工具

brand_get_color - 获取颜色值（支持嵌套：“primary.500”或简单：“success”）
- 参数：colorName（字符串），theme（可选，默认：“default”）
- 示例："primary.500"，"secondary.600"，"success"
- 功能：嵌套访问、验证、错误建议
brand_list_colors - 列出主题的所有可用颜色
- 参数：theme（可选）

间距工具

brand_get_spacing - 获取间距值（支持scale.4或semantic.md）
- 参数：size（字符串），theme（可选）
- 功能：检查比例、语义和直接访问
brand_list_spacing - 列出所有间距值

字体工具

brand_get_typography - 获取字体值（支持嵌套：“fontSizes.base”）
- 参数：property（字符串），theme（可选）
- 示例："fontSizes.base"，"fontFamilies.sans"，"fontWeights.bold"
- 功能：嵌套访问、验证
brand_list_typography - 列出所有字体值

其他设计令牌

brand_get_radius - 获取边框半径值
brand_get_shadow - 获取阴影值
brand_get_theme - 获取完整的主题配置
brand_list_tokens - 列出主题的所有设计令牌

品牌系统功能：

✅ 嵌套属性访问（primary.500，fontSizes.base）
✅ 令牌验证（颜色格式、CSS值）
✅ 有用的错误消息和建议
✅ 多主题支持（default，rpg_8bit）
✅ 自动令牌发现

AI路由器工具

所有AI操作都通过n8n网络钩子路由（解耦架构）：

ai_call - 通过n8n的通用AI操作
ai_summarize - 通过n8n总结内容
ai_extract - 通过n8n提取数据
ai_generate - 通过n8n生成内容

注意：这些工具POST到n8n网络钩子——AI逻辑在下游处理，而不是直接在Lovable中处理。

自定义组件工具

get_component - 获取自定义组件
list_components - 列出自定义组件
create_component - 创建新的自定义组件

📦 可用资源

组件库资源

所有组件库提供的资源格式如下：

magicui://<component-name> - Magic UI组件（68个可用）
shadcn://<component-name> - Shadcn UI组件（59个可用）
aceternity://<component-name> - Aceternity UI组件（96个可用）
8bit://<component-name> - 8bitcn组件（55个可用）
component://<component-name> - 自定义组件

品牌系统资源（设计API）

brand://colors - 完整的颜色调色板（支持嵌套访问）
brand://spacing - 间距比例（比例+语义值）
brand://typography - 字体系统（字体、大小、权重、行高）
brand://radii - 边框半径值
brand://shadows - 阴影值
brand://themes - 完整的主题配置

示例用法：

// 获取嵌套颜色
brand_get_color({ colorName: "primary.500", theme: "default" })
// 返回：{ color: "#0ea5e9", valid: true }

// 获取字体
brand_get_typography({ property: "fontSizes.base", theme: "default" })
// 返回：{ value: "1rem", valid: true }

🔧 自定义

添加新的MCP提供商

服务器使用模块化架构，使得添加新的MCP提供商变得容易：

在mcp-providers/中创建一个新的提供商文件：

// mcp-providers/my-provider.mjs
export const myProviderTools = [/* 工具定义 */];
export const myProviderResources = [/* 资源定义 */];
export async function handleMyProviderTool(name, args) { /* ... */ }
export async function handleMyProviderResource(uri) { /* ... */ }

在server.mjs中导入并注册：

import { myProviderTools, ... } from "./mcp-providers/my-provider.mjs";

合并到统一的端点：
- 将工具添加到/mcp/tools/list中的allTools数组
- 将资源添加到/mcp/resources/list中的allResources数组
- 在/mcp/tools/call中路由工具调用
- 在/mcp/resources/read中路由资源读取

自定义现有提供商

组件库提供商

Magic UI：mcp-providers/magic-ui.mjs - 68个组件，带有完整的上下文元数据
Shadcn UI：mcp-providers/shadcn.mjs - 59个组件，带有完整的上下文元数据
Aceternity UI：mcp-providers/aceternity-ui.mjs - 96个组件，带有完整的上下文元数据
8bitcn：mcp-providers/eightbit.mjs - 55个组件，带有完整的上下文元数据

所有组件提供商包括：

组件上下文元数据（用例、模式、示例）
元数据跨搜索功能
get_component_context工具提供详细信息

品牌系统提供商

文件：mcp-providers/brand-system.mjs
令牌文件：design-tokens/*.json
功能：嵌套属性访问、验证、错误处理
主题：default，rpg_8bit
状态：✅ 完成，所有功能已实现

AI路由器提供商

文件：mcp-providers/ai-router.mjs
目的：将AI操作路由到n8n网络钩子
配置：设置N8N_WEBHOOK_URL环境变量
状态：⏳ 构架完成，需要配置n8n网络钩子URL

自定义组件提供商

文件：mcp-providers/custom-components.mjs
状态：⏳ 占位符——实现实际存储（数据库、文件系统等）

环境变量

PORT - 服务器端口（默认：4001，Railway自动设置）

🏗️ 项目结构

railway-mcp-test/
├── server.mjs                    # 主统一MCP服务器
├── mcp-providers/                # 模块化MCP提供商模块
│   ├── magic-ui.mjs             # Magic UI提供商（68个组件）
│   ├── shadcn.mjs               # Shadcn UI提供商（59个组件）
│   ├── aceternity-ui.mjs        # Aceternity UI提供商（96个组件）
│   ├── eightbit.mjs             # 8bitcn提供商（55个组件）
│   ├── brand-system.mjs         # 品牌系统/设计API提供商
│   ├── ai-router.mjs            # AI路由器提供商（n8n网络钩子）
│   └── custom-components.mjs    # 自定义组件提供商
├── design-tokens/                # 设计令牌JSON文件
│   ├── colors.json              # 颜色调色板（default，rpg_8bit）
│   ├── spacing.json             # 间距比例
│   ├── typography.json          # 字体系统
│   ├── radii.json               # 边框半径
│   ├── shadows.json             # 阴影值
│   └── themes.json              # 主题配置
├── package.json                 # 依赖项和脚本
├── railway.json                 # Railway部署配置
├── .gitignore                   # Git忽略规则
└── README.md                    # 本文档

架构

服务器使用模块化提供商架构和解耦AI：

提供商模式：

每个MCP服务器都是mcp-providers/中的独立模块
主服务器（server.mjs）合并所有提供商
所有提供商的工具和资源被统一到单一端点
不修改核心服务器代码即可轻松添加新提供商

解耦AI架构：

所有AI操作通过n8n网络钩子路由
Lovable → 边缘函数 → n8n网络钩子 → LLM + 工具 → 返回
Lovable不直接调用LLM API
中央化的AI编排和成本控制

组件上下文增强：

所有278个组件包括丰富的元数据：
- useCases - 常见用例
- commonPatterns - 使用模式
- whenToUse / whenNotToUse - 指导
- examples - 代码示例
- relatedComponents - 相关组件
搜索功能搜索所有元数据字段
get_component_context工具提供详细的组件信息

设计系统API：

完整的品牌系统，具有嵌套属性访问
多主题支持（default，rpg_8bit）
令牌验证和有用的错误消息
自动令牌发现和建议

🔒 安全注意事项

CORS目前设置为允许所有来源（*）
对于生产环境，考虑限制CORS到特定域
如果需要，为敏感操作添加身份验证
考虑对公共端点进行速率限制

✨ 功能

组件库

✅ 总计278个组件，跨越4个库
✅ 所有组件的丰富上下文元数据（用例、模式、示例）
✅ 增强搜索跨元数据字段
✅ 组件上下文工具提供详细的组件信息

设计系统API（品牌系统）

✅ 嵌套属性访问 - primary.500，fontSizes.base
✅ 令牌验证 - 验证颜色格式和CSS值
✅ 有用的错误消息 - 错误时建议相似的令牌
✅ 多主题支持 - default和rpg_8bit主题