@stellisoft/stellify-mcp 0.1.0

package/README.md

@@ -0,0 +1,231 @@
+# Stellify MCP Server
+
+Model Context Protocol (MCP) server for Stellify - the AI-native code generation platform.
+
+## What is This?
+
+This MCP server lets AI assistants (like Claude) interact with your Stellify projects to build Laravel applications incrementally. Instead of generating full code files at once, AI can:
+
+1. Create file structures (classes, controllers, models)
+2. Add method signatures
+3. Parse method bodies statement-by-statement
+4. Search existing code
+
+## Installation
+
+### Prerequisites
+
+- Node.js 18 or higher
+- A Stellify account with API access
+- Claude Desktop (or another MCP-compatible client)
+
+### Setup
+
+1. **Install dependencies:**
+```bash
+cd /Users/matthewanderson/stellify-mcp
+npm install
+```
+
+2. **Build the TypeScript:**
+```bash
+npm run build
+```
+
+3. **Create environment file:**
+```bash
+cp .env.example .env
+```
+
+4. **Get your Stellify API token:**
+   - Log into Stellify web interface
+   - Go to Settings → API Tokens
+   - Create a new token
+   - Copy the token
+
+5. **Configure the .env file:**
+```bash
+# Edit .env
+STELLIFY_API_URL=https://stellisoft.com/api/v1
+STELLIFY_API_TOKEN=your-token-here
+```
+
+## Configure Claude Desktop
+
+Add this to your Claude Desktop config file:
+
+**Location:** `~/.config/claude/config.json` (Linux/Mac) or `%APPDATA%\Claude\config.json` (Windows)
+
+```json
+{
+  "mcpServers": {
+    "stellify": {
+      "command": "node",
+      "args": ["/Users/matthewanderson/stellify-mcp/dist/index.js"],
+      "env": {
+        "STELLIFY_API_URL": "https://stellisoft.com/api/v1",
+        "STELLIFY_API_TOKEN": "your-token-here"
+      }
+    }
+  }
+}
+```
+
+**Important:** Replace `/Users/matthewanderson/stellify-mcp` with the actual path and `your-token-here` with your real token.
+
+## Restart Claude Desktop
+
+After adding the configuration, restart Claude Desktop for the changes to take effect.
+
+## Available Tools
+
+### `create_file`
+Create a new file (class, controller, model, middleware) in a Stellify project.
+
+**Parameters:**
+- `project_id` (required): Stellify project UUID
+- `name` (required): File name (e.g., "Calculator", "UserController")
+- `type` (required): File type - "class", "model", "controller", or "middleware"
+- `namespace` (optional): PHP namespace (e.g., "App\\Services\\")
+
+**Example:**
+```
+Create a Calculator class in my Stellify project abc-123
+```
+
+### `create_method`
+Create a method signature in a file (without implementation).
+
+**Parameters:**
+- `file_uuid` (required): UUID of the file
+- `name` (required): Method name (e.g., "add", "store")
+- `visibility` (optional): "public", "protected", or "private" (default: "public")
+- `is_static` (optional): boolean (default: false)
+- `return_type` (optional): Return type (e.g., "int", "JsonResponse")
+- `parameters` (optional): Array of `{name, type}` objects
+
+**Example:**
+```
+Add a public method called "add" that takes two integers and returns an integer
+```
+
+### `add_method_body`
+Parse and add PHP code to a method body.
+
+**Parameters:**
+- `file_uuid` (required): UUID of the file
+- `method_uuid` (required): UUID of the method
+- `code` (required): PHP code (just the body, no function declaration)
+
+**Example:**
+```
+Add this implementation to the add method: return $a + $b;
+```
+
+### `search_methods`
+Search for methods in the project.
+
+**Parameters:**
+- `name` (optional): Method name to search for
+- `file_uuid` (optional): Filter to specific file
+
+### `search_files`
+Search for files in the project.
+
+**Parameters:**
+- `name` (optional): File name pattern
+- `type` (optional): File type filter
+
+## Usage Example
+
+Once configured, you can talk to Claude naturally:
+
+```
+User: "Create a Calculator service in my Stellify project abc-123"
+
+Claude will:
+1. Call create_file to create Calculator.php
+2. Call create_method to add an "add" method
+3. Call add_method_body to implement "return $a + $b;"
+```
+
+## The Incremental Workflow
+
+Stellify works incrementally, not by parsing entire files at once:
+
+1. **Create Structure** → File skeleton with no methods
+2. **Add Signatures** → Method declarations without bodies
+3. **Parse Bodies** → Statement-by-statement implementation
+4. **Assemble** → Stellify converts structured data back to PHP
+
+This gives AI surgical control over your code.
+
+## Development
+
+### Watch mode (auto-rebuild on changes):
+```bash
+npm run watch
+```
+
+### Manual build:
+```bash
+npm run build
+```
+
+## Troubleshooting
+
+### "STELLIFY_API_TOKEN environment variable is required"
+Make sure your `.env` file exists and contains your API token.
+
+### "Connection refused" or API errors
+- Verify your API token is valid
+- Check that `STELLIFY_API_URL` is correct
+- Test the API directly: `curl -H "Authorization: Bearer YOUR_TOKEN" https://stellisoft.com/api/v1/file/search`
+
+### Claude Desktop doesn't see the tools
+- Verify the path in `config.json` is absolute and correct
+- Restart Claude Desktop
+- Check Claude Desktop logs for errors
+
+### TypeScript errors during build
+```bash
+rm -rf node_modules package-lock.json
+npm install
+npm run build
+```
+
+## Architecture
+
+```
+Claude Desktop (AI)
+       ↓ (stdio)
+Stellify MCP Server (Node.js)
+       ↓ (HTTPS)
+Stellify API (Laravel)
+       ↓
+Database (Structured Code)
+```
+
+The MCP server is a thin client that:
+1. Exposes tools to Claude
+2. Translates tool calls to API requests
+3. Returns formatted responses
+
+## Next Steps
+
+After Phase 1 works, we'll add:
+- Global method library (reference battle-tested code)
+- Contribute methods to global library
+- Rich metadata extraction
+- Usage statistics
+
+## Support
+
+For issues or questions:
+- GitHub: https://github.com/stellisoft/stellify-mcp
+- Email: support@stellisoft.com
+- Docs: https://stellisoft.com/docs/mcp
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,280 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { StellifyClient } from './stellify-client.js';
+import dotenv from 'dotenv';
+// Load environment variables
+dotenv.config();
+const API_URL = process.env.STELLIFY_API_URL || 'https://stellisoft.com/api/v1';
+const API_TOKEN = process.env.STELLIFY_API_TOKEN;
+if (!API_TOKEN) {
+    console.error('Error: STELLIFY_API_TOKEN environment variable is required');
+    process.exit(1);
+}
+// Initialize Stellify API client
+const stellify = new StellifyClient({
+    apiUrl: API_URL,
+    apiToken: API_TOKEN,
+});
+// Define MCP tools
+const tools = [
+    {
+        name: 'create_file',
+        description: 'Create a new file (class, model, controller, middleware) in a Stellify project. This creates the file structure but no methods yet.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_id: {
+                    type: 'string',
+                    description: 'The UUID of the Stellify project',
+                },
+                name: {
+                    type: 'string',
+                    description: 'File name (e.g., "Calculator", "UserController")',
+                },
+                type: {
+                    type: 'string',
+                    enum: ['class', 'model', 'controller', 'middleware'],
+                    description: 'Type of file to create',
+                },
+                namespace: {
+                    type: 'string',
+                    description: 'PHP namespace (e.g., "App\\Services\\", "App\\Http\\Controllers\\")',
+                },
+            },
+            required: ['project_id', 'name', 'type'],
+        },
+    },
+    {
+        name: 'create_method',
+        description: 'Create a method signature in a file. This only creates the method declaration, not the body. Use add_method_body to add implementation.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                file_uuid: {
+                    type: 'string',
+                    description: 'UUID of the file to add the method to',
+                },
+                name: {
+                    type: 'string',
+                    description: 'Method name (e.g., "add", "store", "index")',
+                },
+                visibility: {
+                    type: 'string',
+                    enum: ['public', 'protected', 'private'],
+                    description: 'Method visibility',
+                    default: 'public',
+                },
+                is_static: {
+                    type: 'boolean',
+                    description: 'Whether the method is static',
+                    default: false,
+                },
+                return_type: {
+                    type: 'string',
+                    description: 'Return type (e.g., "int", "string", "JsonResponse", "void")',
+                },
+                parameters: {
+                    type: 'array',
+                    description: 'Array of method parameters',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            name: {
+                                type: 'string',
+                                description: 'Parameter name (without $)',
+                            },
+                            type: {
+                                type: 'string',
+                                description: 'Parameter type (e.g., "int", "string", "Request")',
+                            },
+                        },
+                        required: ['name', 'type'],
+                    },
+                },
+            },
+            required: ['file_uuid', 'name'],
+        },
+    },
+    {
+        name: 'add_method_body',
+        description: 'Parse and add PHP code to a method body. Provide the method implementation code (without the function declaration). Stellify will parse it into structured statements.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                file_uuid: {
+                    type: 'string',
+                    description: 'UUID of the file containing the method',
+                },
+                method_uuid: {
+                    type: 'string',
+                    description: 'UUID of the method to add code to',
+                },
+                code: {
+                    type: 'string',
+                    description: 'PHP code for the method body (just the statements, no function declaration). Example: "return $a + $b;"',
+                },
+            },
+            required: ['file_uuid', 'method_uuid', 'code'],
+        },
+    },
+    {
+        name: 'search_methods',
+        description: 'Search for methods in the project by name or within a specific file',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: {
+                    type: 'string',
+                    description: 'Method name to search for (supports wildcards)',
+                },
+                file_uuid: {
+                    type: 'string',
+                    description: 'Optional: filter results to a specific file',
+                },
+            },
+        },
+    },
+    {
+        name: 'search_files',
+        description: 'Search for files in the project by name or type',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: {
+                    type: 'string',
+                    description: 'File name pattern to search for',
+                },
+                type: {
+                    type: 'string',
+                    description: 'File type to filter by (class, model, controller, middleware)',
+                },
+            },
+        },
+    },
+];
+// Create MCP server
+const server = new Server({
+    name: 'stellify-mcp',
+    version: '0.1.0',
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+// Handle tool list requests
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return { tools };
+});
+// Handle tool execution
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    if (!args) {
+        throw new Error('Arguments are required');
+    }
+    try {
+        switch (name) {
+            case 'create_file': {
+                const result = await stellify.createFile(args);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: true,
+                                message: `Created file "${args.name}" (${result.uuid})`,
+                                file: result,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            case 'create_method': {
+                const result = await stellify.createMethod(args);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: true,
+                                message: `Created method "${args.name}" (${result.uuid})`,
+                                method: result,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            case 'add_method_body': {
+                const result = await stellify.addMethodBody(args);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: true,
+                                message: 'Method body parsed and saved successfully',
+                                data: result,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            case 'search_methods': {
+                const result = await stellify.searchMethods(args);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: true,
+                                results: result,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            case 'search_files': {
+                const result = await stellify.searchFiles(args);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: true,
+                                results: result,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            default:
+                throw new Error(`Unknown tool: ${name}`);
+        }
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        success: false,
+                        error: error.message,
+                        details: error.response?.data || error.toString(),
+                    }, null, 2),
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+// Start server
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('Stellify MCP server running on stdio');
+}
+main().catch((error) => {
+    console.error('Server error:', error);
+    process.exit(1);
+});

package/dist/stellify-client.d.ts

@@ -0,0 +1,55 @@
+export interface StellifyConfig {
+    apiUrl: string;
+    apiToken: string;
+}
+export interface CreateFileParams {
+    directory?: string;
+    name: string;
+    type: 'class' | 'model' | 'controller' | 'middleware';
+    namespace?: string;
+}
+export interface CreateMethodParams {
+    file: string;
+    name: string;
+    visibility?: 'public' | 'protected' | 'private';
+    is_static?: boolean;
+    returnType?: string;
+    parameters?: Array<{
+        name: string;
+        type: string;
+    }>;
+}
+export interface AddMethodBodyParams {
+    file_uuid: string;
+    method_uuid: string;
+    code: string;
+}
+export interface SearchMethodsParams {
+    name?: string;
+    file_uuid?: string;
+}
+export interface SearchFilesParams {
+    query: string;
+    type?: string;
+    project?: boolean;
+    includes?: boolean;
+    include_metadata?: boolean;
+    per_page?: number;
+    category?: string;
+    min_rating?: number;
+    tags?: string[];
+    user?: string;
+    sort?: 'created_at' | 'name' | 'type' | 'ai_rating' | 'usage_rating' | 'system_rating' | 'user_name';
+    direction?: 'asc' | 'desc';
+}
+export declare class StellifyClient {
+    private client;
+    constructor(config: StellifyConfig);
+    createFile(params: CreateFileParams): Promise<any>;
+    createMethod(params: CreateMethodParams): Promise<any>;
+    addMethodBody(params: AddMethodBodyParams): Promise<any>;
+    searchMethods(params: SearchMethodsParams): Promise<any>;
+    searchFiles(params: SearchFilesParams): Promise<any>;
+    getFile(uuid: string): Promise<any>;
+    getMethod(uuid: string): Promise<any>;
+}

package/dist/stellify-client.js

@@ -0,0 +1,42 @@
+import axios from 'axios';
+export class StellifyClient {
+    client;
+    constructor(config) {
+        this.client = axios.create({
+            baseURL: config.apiUrl,
+            headers: {
+                'Authorization': `Bearer ${config.apiToken}`,
+                'Content-Type': 'application/json',
+                'Accept': 'application/json',
+            },
+        });
+    }
+    async createFile(params) {
+        const response = await this.client.post('/file', params);
+        return response.data;
+    }
+    async createMethod(params) {
+        const response = await this.client.post('/method', params);
+        return response.data;
+    }
+    async addMethodBody(params) {
+        const response = await this.client.post('/code', params);
+        return response.data;
+    }
+    async searchMethods(params) {
+        const response = await this.client.get('/method/search', { params });
+        return response.data;
+    }
+    async searchFiles(params) {
+        const response = await this.client.get('/file/search', { params });
+        return response.data;
+    }
+    async getFile(uuid) {
+        const response = await this.client.get(`/file/${uuid}`);
+        return response.data;
+    }
+    async getMethod(uuid) {
+        const response = await this.client.get(`/method/${uuid}`);
+        return response.data;
+    }
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@stellisoft/stellify-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for Stellify - AI-native code generation platform",
+  "main": "dist/index.js",
+  "type": "module",
+  "bin": {
+    "stellify-mcp": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc --watch",
+    "prepare": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "stellify",
+    "ai",
+    "code-generation",
+    "laravel"
+  ],
+  "author": "Stellisoft",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "axios": "^1.7.9",
+    "dotenv": "^16.4.7"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.5",
+    "typescript": "^5.7.2"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}