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 團隊用心打造