Stellify MCP

🚀 Stellify MCP Server

Stellify MCP Server 是专为 Stellify 这一 AI 原生代码生成平台打造的 Model Context Protocol (MCP) 服务器。它能让 AI 助手（如 Claude Desktop）与你的 Stellify 项目进行交互，逐步构建 Laravel 和 Vue.js 应用程序。

🚀 快速开始

前提条件

• Node.js 18 或更高版本
• Stellify 账户 - 可在 stellisoft.com 上注册
• Claude Desktop（或其他支持 MCP 的 AI 客户端）

安装

通过 npm 全局安装：

npm install -g @stellisoft/stellify-mcp

配置

1. 获取 Stellify API 令牌：

   • 登录 Stellify
   • 导航至“设置”→“API 令牌”
   • 点击“创建新令牌”
   • 复制你的令牌

2. 配置 Claude Desktop： 编辑 Claude Desktop 配置文件：

   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json
   • Linux：~/.config/claude/claude_desktop_config.json 添加 Stellify MCP 服务器：

   {
     "mcpServers": {
       "stellify": {
         "command": "stellify-mcp",
         "env": {
           "STELLIFY_API_URL": "https://api.stellisoft.com/v1",
           "STELLIFY_API_TOKEN": "your-token-here"
         }
       }
     }
   }
   

3. 重启 Claude Desktop

完成以上步骤后，Stellify 工具应可在 Claude Desktop 中使用。

✨ 主要特性

• 允许 AI 助手与 Stellify 项目交互，逐步构建 Laravel 和 Vue.js 应用程序。
• 支持创建文件结构、添加方法签名、解析代码为结构化 JSON、将 HTML 转换为 Stellify 元素等操作。
• 提供丰富的工具，涵盖项目与目录、文件、方法、语句、路由、元素、全局库和模块等方面。
• 采用结构化 JSON 存储代码，实现精准修改、代码查询、即时重构、版本控制和自动依赖解析等功能。

📦 安装指南

通过 npm 全局安装：

npm install -g @stellisoft/stellify-mcp

💻 使用示例

基础用法

配置完成后，你可以自然地与 Claude 对话来构建应用程序，以下是一些示例对话：

• 创建新控制器：

"Create a UserController in my Stellify project"

• 添加方法：

"Add a method called 'store' that takes a Request parameter and returns a JsonResponse"

• 实现方法逻辑：

"Add this implementation to the store method:
$user = User::create($request->validated());
return response()->json($user, 201);"

• 构建 Vue 组件：

"Create a Counter component with an increment button"

• 将 HTML 转换为元素：

"Convert this HTML to Stellify elements:
<div class='container'><h1>Hello</h1><button>Click me</button></div>"

• 搜索代码库：

"Search for all controller files in my project"
"Find methods related to authentication"

📚 详细文档

可用工具

项目与目录工具

• get_project：获取经过身份验证的用户的活动 Stellify 项目。在进行其他操作之前，首先调用此方法。
  • 参数：无
  • 返回值：
    • uuid：项目 UUID（大多数操作需要）
    • name：项目名称
    • directories：现有目录的 {uuid, name} 数组
• get_directory：通过 UUID 获取目录以查看其内容。
  • 参数：
    • uuid（必填）：目录的 UUID
• create_directory：创建一个新目录用于组织文件。
  • 参数：
    • name（必填）：目录名称（例如，"js"、"css"、"components"）

文件工具

• create_file：在 Stellify 项目中创建一个新文件。这将创建一个空的文件外壳，没有方法、语句或模板。
  • 参数：
    • directory（必填）：目录的 UUID（从 get_project 的目录数组中获取）
    • name（必填）：文件名（不带扩展名，例如，"Counter"、"UserController"）
    • type（必填）：文件类型 - "class"、"model"、"controller"、"middleware" 或 "js"
    • extension（可选）：文件扩展名。对于 Vue 组件，使用 "vue"。
    • namespace（可选）：PHP 命名空间（例如，"App\Services\"）。仅适用于 PHP 文件。
    • includes（可选）：要导入的完全限定类名数组（例如，["App\\Models\\User", "Illuminate\\Http\\Request"]）。Stellify 将解析这些类名到文件 UUID，如果需要，从 Laravel API 或供应商目录中获取。
  • 目录选择：根据文件的用途选择目录。如果目录不存在，请先使用 create_directory 创建它。 | 文件类型 | 目录 | 命名空间 | |-----------|-----------|-----------| | 控制器 | controllers | App\Http\Controllers\ | | 模型 | models | App\Models\ | | 服务 | services | App\Services\ | | 中间件 | middleware | App\Http\Middleware\ | | Vue/JS | js | 无 |
  • 示例工作流程：
    1. create_file → 创建空外壳，返回文件 UUID
    2. create_statement + add_statement_code → 添加变量/导入
    3. create_method + add_method_body → 添加函数
    4. html_to_elements → 创建模板元素（对于 Vue）
    5. save_file → 使用所有 UUID 完成文件配置
  • 自动依赖创建（当 auto_create_dependencies: true 时）： 当你创建包含以下代码的文件时：

    <?php
    namespace App\Http\Controllers;
    
    use App\Models\User;
    use Illuminate\Http\Request;
    
    class UserController extends Controller
    {
        public function store(Request $request)
        {
            $user = User::create($request->validated());
            return response()->json($user);
        }
    }
    

    Stellify 将：
    1. 解析 use 语句以查找依赖项（User、Request、Socialite）
    2. 在应用程序数据库中检查框架类 → 查找缓存的类
    3. 对于核心 Laravel 类 → 从 api.laravel.com 获取
    4. 对于供应商包（Socialite、Spatie 等） → 从 vendor/ 目录读取
    5. 创建缺失的应用类 → 创建 User 模型文件
    6. 使用所有依赖项 UUID 连接文件的 includes 数组
  • 支持的源：
    • Laravel API - 核心 Illuminate\* 类从 api.laravel.com 获取
    • 供应商包 - Laravel\Socialite\*、Laravel\Cashier\*、Spatie\*、Livewire\* 等直接从 vendor/ 目录使用 PHP-Parser 读取
    • 响应中包含一个 dependencies 报告，显示创建/解析的内容以及来源。
• get_file：通过 UUID 获取文件及其所有元数据、方法和语句。
  • 参数：
    • uuid（必填）：文件的 UUID
• save_file：使用完整配置保存/更新文件。在 create_file 之后完成文件配置。
  • 参数：
    • uuid（必填）：文件的 UUID
    • name（必填）：文件名（不带扩展名）
    • type（必填）：文件类型（"js"、"class"、"controller"、"model"、"middleware"）
    • extension（可选）：文件扩展名（对于 Vue SFC，使用 "vue"）
    • template（可选）：Vue <template> 部分的根元素 UUID 数组
    • data（可选）：仅包含方法 UUID 的数组（函数）
    • statements（可选）：语句 UUID 数组（导入、变量、引用）
    • includes（可选）：要导入的文件 UUID 数组
  • 重要提示：data 仅包含方法 UUID，statements 包含语句 UUID（方法外的代码）
• search_files：按名称或类型在项目中搜索文件。
  • 参数：
    • name（可选）：要搜索的文件名模式
    • type（可选）：文件类型过滤器

方法工具

• create_method：在文件中创建方法签名（无实现）。
  • 参数：
    • file（必填）：要添加方法的文件的 UUID
    • name（必填）：方法名称（例如，"increment"、"store"、"handleClick"）
    • visibility（可选）："public"、"protected" 或 "private"（仅适用于 PHP，默认："public"）
    • is_static（可选）：方法是否为静态（仅适用于 PHP，默认：false）
    • returnType（可选）：返回类型（例如，"int"、"string"、"void"）
    • parameters（可选）：{name, type} 对象数组
• add_method_body：解析并向方法体添加代码。Stellify 将代码解析为结构化 JSON 语句。
  • 参数：
    • file_uuid（必填）：包含方法的文件的 UUID
    • method_uuid（必填）：要添加代码的方法的 UUID
    • code（必填）：方法体的代码（仅语句，无函数声明）
  • 示例：

    code: "return $a + $b;"
    

• search_methods：按名称或在特定文件中搜索项目中的方法。
  • 参数：
    • name（可选）：要搜索的方法名称（支持通配符）
    • file_uuid（可选）：将结果过滤到特定文件

语句工具

• create_statement：在文件中创建一个空语句。这是步骤 1，接下来必须调用 add_statement_code。
  • 参数：
    • file（可选）：要添加语句的文件的 UUID
    • method（可选）：要添加语句的方法的 UUID（用于方法体语句）
  • 用例：
    • PHP：类属性、use 语句、常量
    • JS/Vue：变量声明、导入、响应式引用
• add_statement_code：向现有语句添加代码。这是步骤 2，在 create_statement 之后调用。
  • 参数：
    • file_uuid（必填）：包含语句的文件的 UUID
    • statement_uuid（必填）：要添加代码的语句的 UUID
    • code（必填）：要添加的代码
  • 示例：

    code: "use Illuminate\\Http\\Request;"
    code: "const count = ref(0);"
    code: "import { ref } from 'vue';"
    

• get_statement：通过 UUID 获取语句及其子句（代码标记）。
  • 参数：
    • uuid（必填）：语句的 UUID

路由工具

• create_route：在 Stellify 项目中创建一个新路由/页面。
  • 参数：
    • project_id（必填）：Stellify 项目的 UUID
    • name（必填）：路由/页面名称（例如，"Home"、"Counter"、"About"）
    • path（必填）：URL 路径（例如，"/"、"/counter"、"/about"）
    • method（必填）：HTTP 方法（"GET"、"POST"、"PUT"、"DELETE"、"PATCH"）
    • type（可选）：路由类型 - "web" 用于页面，"api" 用于 API 端点（默认："web"）
    • data（可选）：附加路由数据
• get_route：通过 UUID 获取路由/页面。
  • 参数：
    • uuid（必填）：路由的 UUID
• search_routes：按名称在项目中搜索路由/页面。
  • 参数：
    • search（可选）：用于匹配路由名称的搜索词
    • type（可选）：按路由类型过滤（"web" 或 "api"）
    • per_page（可选）：每页结果数（默认：10）

元素工具（UI 组件）

• create_element：创建一个新的 UI 元素。为根元素提供 page（路由 UUID），为子元素提供 parent（元素 UUID）。
  • 参数：
    • type（必填）：元素类型 - 以下之一：
      • HTML5：s-wrapper、s-input、s-form、s-svg、s-shape、s-media、s-iframe
      • 组件：s-loop、s-transition、s-freestyle、s-motion
      • Blade：s-directive
      • Shadcn/ui：s-chart、s-table、s-combobox、s-accordion、s-calendar、s-contiguous
    • page（可选）：页面/路由的 UUID（用于根元素）
    • parent（可选）：父元素的 UUID（用于子元素）
• update_element：更新现有的 UI 元素。
  • 参数：
    • uuid（必填）：要更新的元素的 UUID
    • data（必填）：包含 HTML 属性和 Stellify 字段的对象
  • 标准 HTML 属性：placeholder、href、src、type 等。
  • Stellify 字段：
    • name：编辑器中的元素名称
    • type：元素类型
    • locked：防止编辑（布尔值）
    • tag：HTML 标签（div、input、button 等）
    • classes：CSS 类数组 ["class1", "class2"]
    • text：元素文本内容
  • 事件处理程序（将值设置为方法 UUID）：
    • click：@click
    • submit：@submit
    • change：@change
    • input：@input
    • focus：@focus
    • blur：@blur
    • keydown：@keydown
    • keyup：@keyup
    • mouseenter：@mouseenter
    • mouseleave：@mouseleave
• get_element：通过 UUID 获取单个元素。
  • 参数：
    • uuid（必填）：元素的 UUID
• get_element_tree：获取一个元素及其所有后代的层次树结构。
  • 参数：
    • uuid（必填）：根元素的 UUID
• delete_element：删除一个元素及其所有子元素（级联删除）。
  • 参数：
    • uuid（必填）：要删除的元素的 UUID
• search_elements：在项目中搜索元素。
  • 参数：
    • search（可选）：用于匹配元素名称、类型或内容的搜索查询
    • type（可选）：按元素类型过滤
    • include_metadata（可选）：包含附加元数据（默认：false）
    • per_page（可选）：每页结果数，1 - 100（默认：20）
• html_to_elements：在一次操作中将 HTML 转换为 Stellify 元素。这是构建界面的最快方法！
  • 参数：
    • elements（必填）：要转换的 HTML 字符串
    • page（可选）：要附加元素的路由 UUID。对于 Vue 组件，省略此参数。
    • selection（可选）：要附加到的父元素 UUID（替代 page）
    • test（可选）：如果为 true，则返回结构而不创建元素
  • 特性：
    • 解析 HTML 结构
    • 创建所有具有正确嵌套的元素
    • 保留属性、类、文本内容
    • 自动检测 Vue 绑定 ({{ variable }}) 并创建链接语句
    • 返回元素 UUID，用于 save_file 模板数组
  • 元素类型映射：
    • button、input、textarea、select → s-input
    • div、span、p、section 等 → s-wrapper
    • form → s-form
    • img、video、audio → s-media

全局库工具

• list_globals：列出应用程序数据库中的所有全局文件。全局文件是可重用的、经过整理的代码，可以安装到租户项目中。
  • 参数：无
• get_global：获取全局文件及其所有方法、语句和子句。
  • 参数：
    • uuid（必填）：全局文件的 UUID
• install_global：将应用程序数据库中的全局文件安装到租户项目中。
  • 参数：
    • file_uuid（必填）：要安装的全局文件的 UUID
    • directory_uuid（必填）：要安装到的目录的 UUID
• search_global_methods：在应用程序数据库中搜索方法（全局/框架方法）。
  • 参数：
    • query（必填）：按名称搜索方法的查询

模块工具

模块是相关全局文件的命名集合，可以一起安装。

• list_modules：列出所有可用的模块。
  • 参数：无
• get_module：获取模块及其所有文件。
  • 参数：
    • uuid（必填）：模块的 UUID
• create_module：创建一个新模块来分组相关的全局文件。
  • 参数：
    • name（必填）：模块的唯一名称（例如，"laravel-sanctum-auth"）
    • description（可选）：模块提供的功能描述
    • version（可选）：版本字符串（默认："1.0.0"）
    • tags（可选）：用于分类的标签（例如，["auth", "api", "sanctum"]）
• add_file_to_module：将全局文件添加到模块中。
  • 参数：
    • module_uuid（必填）：模块的 UUID
    • file_uuid（必填）：要添加的全局文件的 UUID
    • order（可选）：安装顺序（如果未指定，则自动递增）
• install_module：将模块中的所有文件安装到租户项目中。
  • 参数：
    • module_uuid（必填）：要安装的模块的 UUID
    • directory_uuid（必填）：要安装文件的目录的 UUID

Stellify 工作原理

Stellify 将应用程序代码以 结构化 JSON 形式存储在数据库中，而不是文本文件。这种架构实现了以下功能：

• 精确修改：AI 可以修改特定方法而不影响其他代码。
• 代码查询：像查询数据一样查询代码库，查找使用特定类的所有方法。
• 即时重构：在整个应用程序中即时重命名方法。
• 语句级版本控制：跟踪单个代码语句的更改。
• AI 原生开发：让 AI 进行精细访问，而不用担心破坏现有代码。
• 自动依赖解析：框架类会自动从 Laravel API 文档中获取。

当你通过此 MCP 服务器使用 Stellify 构建应用程序时，代码会被解析为结构化数据，并在部署时重新组装成可执行代码。

依赖解析

当使用 auto_create_dependencies 时，Stellify 按以下顺序解析依赖项：

1. 租户数据库 - 检查类是否存在于你的项目中。
2. 应用程序数据库 - 检查预定义类的全局库。
3. Laravel API 文档 - 对于核心 Illuminate\* 类，从 api.laravel.com 获取。
4. 供应商目录 - 对于已安装的包，直接从 vendor/ 目录读取。

支持的包源

对于供应商包，Stellify 使用 PHP-Parser 从你安装的包版本中提取实际的方法签名，确保与你特定的依赖项保持一致。

代码结构

Directory
  └── File
        └── Method
              ├── Parameters (Clauses)
              └── Statements
                    └── Clauses / Language Tokens

每个代码片段被分解为：

• 目录：文件的组织容器
• 文件：包含方法和文件元数据
• 方法：具有参数和主体语句的函数
• 语句：单行/代码语句
• 子句：叶节点（变量、字符串、数字等）
• 语言标记：系统定义的关键字和符号（可重用）

工作流

PHP 控制器工作流

1. get_project → 查找目录 UUID
2. create_file → type='controller', name='UserController'
3. create_method → name='store', parameters=[{name:'request', type:'Request'}]
4. add_method_body → code='return response()->json($request->all());'

Vue 组件工作流

1. get_project → 查找 'js' 目录 UUID
2. create_file → type='js', extension='vue' 在 js 目录中
3. 创建导入和数据的语句：
   • create_statement + add_statement_code："import { ref } from 'vue';"
   • create_statement + add_statement_code："const count = ref(0);"
4. create_method + add_method_body → 创建函数
5. html_to_elements → 将模板 HTML 转换为元素
6. update_element → 连接事件处理程序（click → 方法 UUID）
7. save_file → 完成配置：
   • extension：'vue'
   • template：[rootElementUuid]
   • data：[methodUuid]（仅方法 UUID）
   • statements：[importStmtUuid, refStmtUuid]（语句 UUID）

🔧 技术细节

开发

监听模式（更改时自动重建）：

npm run watch

手动构建：

npm run build

故障排除

"STELLIFY_API_TOKEN environment variable is required"

确保你的 .env 文件存在并包含你的 API 令牌。

"Connection refused" 或 API 错误

• 验证你的 API 令牌是否有效
• 检查 STELLIFY_API_URL 是否正确
• 直接测试 API：curl -H "Authorization: Bearer YOUR_TOKEN" https://stellisoft.com/api/v1/file/search

Claude Desktop 看不到工具

1. 验证配置文件路径是否正确
2. 检查 Stellify API 令牌是否有效
3. 完全重启 Claude Desktop（退出，而不仅仅是关闭窗口）
4. 检查 Claude Desktop 日志中的错误消息

构建期间的 TypeScript 错误

rm -rf node_modules package-lock.json
npm install
npm run build

安装问题

# 清除 npm 缓存并重新安装
npm cache clean --force
npm uninstall -g @stellisoft/stellify-mcp
npm install -g @stellisoft/stellify-mcp

架构

Claude Desktop (AI)
       ↓ (stdio)
Stellify MCP Server (Node.js)
       ↓ (HTTPS)
Stellify API (Laravel)
       ↓
Database (Structured Code)

MCP 服务器是一个轻量级客户端，它：

1. 向 Claude 公开工具
2. 将工具调用转换为 API 请求
3. 返回格式化的响应

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

由 Stellify 团队用心打造