@maka/maka-cli 5.2.10 → 5.3.0

package/docs/MCP_SERVER.md

@@ -1,396 +0,0 @@
-# Maka CLI MCP Server
-
-The Maka CLI includes an enhanced Model Context Protocol (MCP) server that exposes **all maka-cli capabilities** to AI agents like Claude. This allows AI assistants to discover, understand, and help you use any maka-cli command.
-
-## Quick Start
-
-Start the MCP server:
-
-```bash
-maka ai:mcp
-```
-
-The server starts on `http://localhost:3000` by default and automatically discovers all available maka-cli commands.
-
-## Options
-
-- `--port` - Port to listen on (default: 3000)
-- `--host` - Host to bind to (default: localhost)
-
-### Examples
-
-```bash
-# Start on default port
-maka ai:mcp
-
-# Custom port
-maka ai:mcp --port=8080
-
-# Bind to all network interfaces
-maka ai:mcp --host=0.0.0.0 --port=3001
-```
-
-## Server Features
-
-### Tools
-
-The MCP server provides these tools for AI agents:
-
-#### 1. `list-maka-commands`
-List all available Maka CLI commands with descriptions and usage.
-
-**Parameters:**
-- `filter` (optional): Filter commands by name or category (e.g., "aws", "generate", "deploy")
-
-**Example Usage:**
-```json
-{
-  "name": "list-maka-commands",
-  "arguments": {
-    "filter": "generate"
-  }
-}
-```
-
-#### 2. `get-command-info`
-Get detailed information about a specific command including usage, options, examples, and description.
-
-**Parameters:**
-- `command` (required): Command name (e.g., "create", "generate:component", "aws:create-instance")
-
-**Example Usage:**
-```json
-{
-  "name": "get-command-info",
-  "arguments": {
-    "command": "generate:component"
-  }
-}
-```
-
-#### 3. `execute-maka-command`
-Execute Maka CLI commands with safety restrictions to prevent destructive operations.
-
-**Parameters:**
-- `command` (required): Full command to execute (e.g., "maka --help")
-- `workingDirectory` (optional): Working directory for the command
-
-**Safety Features:**
-- Blocks destructive commands (murder, uninstall, rm, delete)
-- 30-second timeout
-- 10MB output buffer limit
-
-**Example Usage:**
-```json
-{
-  "name": "execute-maka-command",
-  "arguments": {
-    "command": "maka --help"
-  }
-}
-```
-
-#### 4. `get-project-info`
-Get information about the current Maka project including configuration.
-
-**Example Usage:**
-```json
-{
-  "name": "get-project-info",
-  "arguments": {}
-}
-```
-
-### Resources
-
-#### 1. `maka://commands/all`
-Complete reference of all Maka CLI commands in JSON format.
-
-**Format:**
-```json
-[
-  {
-    "name": "create",
-    "aliases": "None",
-    "shortDesc": "Create a new Meteor application",
-    "description": "...",
-    "usage": "maka create <app-name>",
-    "examples": ["maka create MyApp"],
-    "validOpts": ["..."],
-    "requiredOpts": [],
-    "experimental": false
-  }
-]
-```
-
-#### 2. `maka://project/config`
-Current project configuration and metadata.
-
-#### 3. `maka://info`
-Maka CLI version, platform, and system information.
-
-### Prompts
-
-Interactive conversation starters for common workflows:
-
-#### 1. `create-component`
-Component creation wizard with examples and best practices.
-
-**Parameters:**
-- `componentName` (required): Name of the component
-- `componentType` (optional): Type (component, page, layout, template)
-
-#### 2. `deploy-help`
-Deployment guide for different platforms and environments.
-
-**Parameters:**
-- `environment` (optional): Target environment (dev, staging, production)
-- `platform` (optional): Deployment platform (aws, docker, custom)
-
-#### 3. `project-setup`
-Interactive guide for setting up a new Maka project.
-
-**Parameters:**
-- `projectType` (optional): Project type (basic, full-stack, api)
-
-## Protocol
-
-The server implements the [Model Context Protocol](https://modelcontextprotocol.io) specification:
-
-- **Transport**: Streamable HTTP (stateless mode)
-- **Format**: Server-Sent Events (SSE)
-- **Message Protocol**: JSON-RPC 2.0
-- **Protocol Version**: 2024-11-05
-
-## Endpoints
-
-- `POST /mcp` - MCP protocol endpoint (Server-Sent Events)
-- `GET /health` - Health check endpoint
-
-## Testing
-
-### Health Check
-```bash
-curl http://localhost:3000/health
-```
-
-### List Available Tools
-```bash
-curl -X POST http://localhost:3000/mcp \
-  -H "Content-Type: application/json" \
-  -H "Accept: application/json, text/event-stream" \
-  -d '{
-    "jsonrpc": "2.0",
-    "id": 1,
-    "method": "tools/list",
-    "params": {}
-  }'
-```
-
-### Call a Tool
-```bash
-curl -X POST http://localhost:3000/mcp \
-  -H "Content-Type: application/json" \
-  -H "Accept: application/json, text/event-stream" \
-  -d '{
-    "jsonrpc": "2.0",
-    "id": 2,
-    "method": "tools/call",
-    "params": {
-      "name": "list-maka-commands",
-      "arguments": {
-        "filter": "aws"
-      }
-    }
-  }'
-```
-
-## Integrating with Claude Desktop
-
-Add this configuration to your Claude Desktop MCP settings:
-
-```json
-{
-  "mcpServers": {
-    "maka-cli": {
-      "command": "maka",
-      "args": ["ai:mcp", "--port=3000"],
-      "transport": "http",
-      "url": "http://localhost:3000/mcp"
-    }
-  }
-}
-```
-
-Alternatively, run the server manually and configure Claude Desktop to connect to the HTTP endpoint:
-
-```json
-{
-  "mcpServers": {
-    "maka-cli": {
-      "transport": "http",
-      "url": "http://localhost:3000/mcp"
-    }
-  }
-}
-```
-
-## How It Works
-
-### Command Discovery
-
-The MCP server automatically discovers all commands by traversing the Maka CLI command tree:
-
-1. Starts at the root `Maka` command
-2. Recursively explores all subcommands
-3. Extracts metadata (name, description, usage, options, examples)
-4. Filters out internal/hidden commands
-5. Builds a complete command registry
-
-This means **any new command added to maka-cli is automatically exposed** through the MCP server.
-
-### Project Detection
-
-The server detects if you're in a Maka project by looking for `.maka/config.json`. Project-specific information is exposed through the `get-project-info` tool and `maka://project/config` resource.
-
-## Use Cases for AI Agents
-
-With this MCP server, AI agents like Claude can:
-
-1. **Discover Commands**: "What commands are available in maka-cli?"
-2. **Get Help**: "How do I create a new component?"
-3. **Learn Usage**: "Show me examples of the deploy command"
-4. **Execute Commands**: "Run maka --version for me"
-5. **Guide Workflows**: "Walk me through deploying to AWS"
-6. **Project Context**: "What's configured in my current project?"
-
-## Customization
-
-### Adding Custom Tools
-
-Edit `src/commands/ai/mcp.sub.cmd.ts` and add new tools:
-
-```typescript
-server.tool(
-  'my-custom-tool',
-  'Description of what my tool does',
-  {
-    param1: z.string().describe('Description of parameter')
-  },
-  async ({ param1 }) => {
-    // Your tool logic here
-    return {
-      content: [
-        {
-          type: 'text',
-          text: `Result: ${param1}`
-        }
-      ]
-    };
-  }
-);
-```
-
-### Adding Custom Resources
-
-```typescript
-server.resource(
-  'my-resource',
-  'maka://custom/resource',
-  {
-    mimeType: 'application/json',
-    description: 'My custom resource'
-  },
-  async () => {
-    return {
-      contents: [
-        {
-          uri: 'maka://custom/resource',
-          mimeType: 'application/json',
-          text: JSON.stringify({ data: 'value' }, null, 2)
-        }
-      ]
-    };
-  }
-);
-```
-
-### Adding Custom Prompts
-
-```typescript
-server.prompt(
-  'my-workflow',
-  'Guided workflow for a specific task',
-  {
-    taskType: z.enum(['option1', 'option2']).describe('Type of task')
-  },
-  async ({ taskType }) => {
-    return {
-      messages: [
-        {
-          role: 'user',
-          content: {
-            type: 'text',
-            text: `Help me with ${taskType}`
-          }
-        },
-        {
-          role: 'assistant',
-          content: {
-            type: 'text',
-            text: `Here's how to handle ${taskType}...`
-          }
-        }
-      ]
-    };
-  }
-);
-```
-
-## CORS Configuration
-
-The server is configured with CORS enabled for all origins by default. For production:
-
-```typescript
-app.use(cors({
-  origin: 'https://yourdomain.com', // Restrict to specific origin
-  exposedHeaders: ['Mcp-Session-Id']
-}));
-```
-
-## Dependencies
-
-- `@modelcontextprotocol/sdk` - MCP SDK
-- `express` - HTTP server
-- `cors` - CORS middleware
-- `zod` - Schema validation
-
-## Architecture
-
-```
-┌─────────────────┐
-│   AI Agent      │
-│  (e.g. Claude)  │
-└────────┬────────┘
-         │ MCP over HTTP
-         │
-┌────────▼────────┐
-│   MCP Server    │
-│  (ai:mcp cmd)   │
-├─────────────────┤
-│ • Tools         │
-│ • Resources     │
-│ • Prompts       │
-└────────┬────────┘
-         │
-         ├─► Command Discovery (Maka._commands)
-         ├─► Project Detection (.maka/config.json)
-         └─► Command Execution (execSync with safety)
-```
-
-## Resources
-
-- [Model Context Protocol Documentation](https://modelcontextprotocol.io)
-- [MCP SDK on GitHub](https://github.com/modelcontextprotocol/typescript-sdk)
-- [Claude Desktop MCP Integration](https://docs.anthropic.com/claude/docs/model-context-protocol)
-- [Maka CLI Documentation](https://www.maka-cli.com)