@aithr-ai/mcp-server 1.0.0

package/index.js

@@ -0,0 +1,2178 @@
+#!/usr/bin/env node
+/**
+ * Aether MCP Server
+ *
+ * Connects Claude Code to Aether's canvas via Model Context Protocol.
+ *
+ * QUICK INSTALL (One Command):
+ *
+ * Mac/Linux:
+ *   claude mcp add --transport stdio aether \
+ *     --env AETHER_API_KEY=YOUR_KEY \
+ *     --env AETHER_WORKSPACE_ID=your-workspace \
+ *     --env AETHER_PROJECT_ID=your-project-id \
+ *     -s user -- npx -y @aithr-ai/mcp-server
+ *
+ * Windows:
+ *   claude mcp add --transport stdio aether ^
+ *     --env AETHER_API_KEY=YOUR_KEY ^
+ *     --env AETHER_WORKSPACE_ID=your-workspace ^
+ *     --env AETHER_PROJECT_ID=your-project-id ^
+ *     -s user -- cmd /c npx -y @aithr-ai/mcp-server
+ *
+ * Or visit: https://www.aithr.ai/settings/mcp-install for personalized commands
+ *
+ * Tools provided:
+ * - aether_canvas_state: Get current canvas state
+ * - aether_add_agent: Add an agent to the canvas
+ * - aether_remove_node: Remove a node
+ * - aether_connect_nodes: Create a connection
+ * - aether_trigger_generation: Start AI generation
+ * - aether_list_projects: List your projects
+ * - aether_list_agents: List agents on the canvas
+ * - aether_get_artifacts: Get generated artifacts
+ * - aether_shell: Execute shell command locally
+ *
+ * GitHub Automation (Zero-Intervention Pipeline):
+ * - aether_automation_status: Check what's ready to push
+ * - aether_extract_files: Extract code files from artifact
+ * - aether_push_artifacts: Push to GitHub (branch + commit + PR)
+ *
+ * Canvas Folder Management:
+ * - aether_list_folders: List folders in project
+ * - aether_create_folder: Create a new folder
+ * - aether_delete_folder: Delete a folder
+ * - aether_add_file_to_folder: Add file/artifact to folder
+ *
+ * Artifact Creation:
+ * - aether_create_artifact: Create artifact and place on canvas
+ *
+ * Orchestra (Autonomous Development):
+ * - aether_start_orchestra: Initialize autonomous orchestration session
+ * - aether_set_orchestra_plan: Set development plan with phases/tasks
+ * - aether_orchestra_approve: User approves plan to begin execution
+ * - aether_orchestra_status: Get current progress, running tasks, blockers
+ * - aether_orchestra_next: Get next ready tasks based on dependencies
+ * - aether_orchestra_trigger_task: Execute a specific task
+ * - aether_report_to_orchestrator: Agents report completion/blockers
+ * - aether_orchestra_pause: Pause execution
+ * - aether_orchestra_resume: Resume execution
+ * - aether_complete_orchestra: Mark complete, generate summary
+ */
+
+const readline = require('readline');
+
+// Configuration
+const config = {
+  aetherUrl: process.env.AETHER_URL || 'https://www.aithr.ai',
+  apiKey: process.env.AETHER_API_KEY || '',
+  workspaceSlug: process.env.AETHER_WORKSPACE_ID || '', // Workspace slug (e.g., "my-workspace")
+  projectId: process.env.AETHER_PROJECT_ID || '',
+};
+
+// Startup validation
+if (!config.apiKey) {
+  process.stderr.write('WARNING: AETHER_API_KEY not set. Generate one at Settings > API Keys\n');
+}
+if (!config.workspaceSlug) {
+  process.stderr.write('WARNING: AETHER_WORKSPACE_ID not set\n');
+}
+if (!config.projectId) {
+  process.stderr.write('WARNING: AETHER_PROJECT_ID not set\n');
+}
+
+// MCP Protocol Implementation
+class MCPServer {
+  constructor() {
+    this.tools = this.defineTools();
+  }
+
+  defineTools() {
+    return [
+      {
+        name: 'aether_canvas_state',
+        description: 'Get the current state of the Aether canvas including all nodes and connections',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            projectId: {
+              type: 'string',
+              description: 'Project ID (optional, uses default if not provided)',
+            },
+          },
+        },
+      },
+      {
+        name: 'aether_add_agent',
+        description: 'Add an AI agent to the Aether canvas. Agent types: pm, consultant, architect, engineer, ux_designer, ui_engineer, code_auditor, general_chat. NOTE: Custom nodes require Pro tier.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            agentType: {
+              type: 'string',
+              enum: ['pm', 'consultant', 'architect', 'engineer', 'ux_designer', 'ui_engineer', 'code_auditor', 'general_chat'],
+              description: 'Type of agent to add',
+            },
+            task: {
+              type: 'string',
+              description: 'Task description for the agent',
+            },
+            position: {
+              type: 'object',
+              properties: {
+                x: { type: 'number' },
+                y: { type: 'number' },
+              },
+              description: 'Position on canvas (optional)',
+            },
+            nodeType: {
+              type: 'string',
+              enum: ['standard', 'parent', 'sub'],
+              description: 'Node type: standard (default), parent (orchestrator), or sub (child agent)',
+            },
+            parentNodeId: {
+              type: 'string',
+              description: 'UUID of parent node (required if nodeType is "sub")',
+            },
+            outputArtifactType: {
+              type: 'string',
+              enum: ['code', 'phase_output', 'design_files', 'prd', 'implementation_plan', 'ux_spec', 'audit_report'],
+              description: 'Output artifact type. Use "code" for agents that produce code (enables structured JSON output for GitHub automation). Defaults to "code" for parent/sub agents.',
+            },
+            systemPrompt: {
+              type: 'string',
+              description: 'Custom system prompt for the agent (optional, uses default if not provided)',
+            },
+          },
+          required: ['agentType'],
+        },
+      },
+      {
+        name: 'aether_remove_node',
+        description: 'Remove a node from the Aether canvas',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            nodeId: {
+              type: 'string',
+              description: 'ID of the node to remove',
+            },
+          },
+          required: ['nodeId'],
+        },
+      },
+      {
+        name: 'aether_connect_nodes',
+        description: 'Create a connection between two nodes on the canvas',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            sourceId: {
+              type: 'string',
+              description: 'Source node ID',
+            },
+            targetId: {
+              type: 'string',
+              description: 'Target node ID',
+            },
+            connectionType: {
+              type: 'string',
+              enum: ['dependency', 'data_flow', 'handover', 'context'],
+              description: 'Type of connection',
+            },
+          },
+          required: ['sourceId', 'targetId'],
+        },
+      },
+      {
+        name: 'aether_trigger_generation',
+        description: 'Trigger AI generation for an agent on the canvas',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            nodeId: {
+              type: 'string',
+              description: 'ID of the agent node to trigger',
+            },
+            context: {
+              type: 'string',
+              description: 'Additional context for generation',
+            },
+          },
+          required: ['nodeId'],
+        },
+      },
+      {
+        name: 'aether_list_projects',
+        description: 'List all projects in the current workspace',
+        inputSchema: {
+          type: 'object',
+          properties: {},
+        },
+      },
+      {
+        name: 'aether_list_agents',
+        description: 'List all agents on the current canvas',
+        inputSchema: {
+          type: 'object',
+          properties: {},
+        },
+      },
+      {
+        name: 'aether_get_artifacts',
+        description: 'Get artifacts (PRDs, code, etc.) from a project',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            artifactType: {
+              type: 'string',
+              enum: ['prd', 'code', 'implementation_plan', 'ux_spec', 'audit_report'],
+              description: 'Type of artifact to retrieve',
+            },
+          },
+        },
+      },
+      {
+        name: 'aether_shell',
+        description: 'Execute a shell command through Aether (runs on your local machine if bridge is connected)',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            command: {
+              type: 'string',
+              description: 'Shell command to execute',
+            },
+            cwd: {
+              type: 'string',
+              description: 'Working directory (optional)',
+            },
+          },
+          required: ['command'],
+        },
+      },
+      // Repository tools - with recommendation for local clone
+      {
+        name: 'aether_list_repositories',
+        description: 'List GitHub repositories synced to this workspace. NOTE: For file access, a local git clone is RECOMMENDED for better performance. Use these tools only if you need to access files through Aether\'s synced data.',
+        inputSchema: {
+          type: 'object',
+          properties: {},
+        },
+      },
+      {
+        name: 'aether_list_repo_files',
+        description: 'List files in a synced repository. RECOMMENDATION: For faster file access, clone the repo locally with `git clone` and use standard file tools instead.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            repositoryId: {
+              type: 'string',
+              description: 'Repository ID (from aether_list_repositories)',
+            },
+            path: {
+              type: 'string',
+              description: 'Directory path to list (optional, defaults to root)',
+            },
+          },
+          required: ['repositoryId'],
+        },
+      },
+      {
+        name: 'aether_read_repo_file',
+        description: 'Read a file from a synced repository. RECOMMENDATION: For faster reads, clone the repo locally and use the Read tool directly.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            repositoryId: {
+              type: 'string',
+              description: 'Repository ID',
+            },
+            filePath: {
+              type: 'string',
+              description: 'Path to the file',
+            },
+          },
+          required: ['repositoryId', 'filePath'],
+        },
+      },
+      {
+        name: 'aether_search_repo',
+        description: 'Search for content across a synced repository. RECOMMENDATION: For faster searches, clone the repo locally and use Grep/Glob tools.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            repositoryId: {
+              type: 'string',
+              description: 'Repository ID',
+            },
+            query: {
+              type: 'string',
+              description: 'Search query',
+            },
+            fileTypes: {
+              type: 'array',
+              items: { type: 'string' },
+              description: 'File extensions to search (e.g., [".ts", ".tsx"])',
+            },
+          },
+          required: ['repositoryId', 'query'],
+        },
+      },
+      // =========================================================================
+      // GitHub Automation Tools (Zero-Intervention Pipeline)
+      // =========================================================================
+      {
+        name: 'aether_automation_status',
+        description: 'Check automation readiness - what artifacts are parseable and ready to push to GitHub',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            projectId: {
+              type: 'string',
+              description: 'Project ID (optional, uses default if not provided)',
+            },
+          },
+        },
+      },
+      {
+        name: 'aether_get_artifact_content',
+        description: 'Get full content of a specific artifact for inspection',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            artifactId: {
+              type: 'string',
+              description: 'Artifact ID to fetch',
+            },
+          },
+          required: ['artifactId'],
+        },
+      },
+      {
+        name: 'aether_extract_files',
+        description: 'Extract code files from an artifact. Returns parsed files ready for GitHub push.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            artifactId: {
+              type: 'string',
+              description: 'ID of the artifact to extract files from',
+            },
+            saveToGeneratedFiles: {
+              type: 'boolean',
+              description: 'Save extracted files to database for later push (default: false)',
+            },
+          },
+          required: ['artifactId'],
+        },
+      },
+      {
+        name: 'aether_push_artifacts',
+        description: 'Push artifacts to GitHub - creates branch, commits files, and opens PR. This is the final step in the automation pipeline.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            artifactIds: {
+              type: 'array',
+              items: { type: 'string' },
+              description: 'Specific artifact IDs to push (optional, uses all parseable if not provided)',
+            },
+            branchName: {
+              type: 'string',
+              description: 'Branch name (auto-generated if not provided)',
+            },
+            commitMessage: {
+              type: 'string',
+              description: 'Commit message (default: "feat: Add generated code from Aether AI")',
+            },
+            prTitle: {
+              type: 'string',
+              description: 'Pull request title',
+            },
+            prBody: {
+              type: 'string',
+              description: 'Pull request body/description',
+            },
+            createPR: {
+              type: 'boolean',
+              description: 'Create a pull request (default: true)',
+            },
+            draft: {
+              type: 'boolean',
+              description: 'Create as draft PR (default: false)',
+            },
+            dryRun: {
+              type: 'boolean',
+              description: 'Preview what would be pushed without actually pushing (default: false)',
+            },
+          },
+        },
+      },
+      // =========================================================================
+      // Canvas Folder Tools
+      // =========================================================================
+      {
+        name: 'aether_list_folders',
+        description: 'List all canvas folders in the current project with file counts',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            projectId: {
+              type: 'string',
+              description: 'Project ID (optional, uses default if not provided)',
+            },
+          },
+        },
+      },
+      {
+        name: 'aether_create_folder',
+        description: 'Create a new canvas folder for organizing files and artifacts',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            name: {
+              type: 'string',
+              description: 'Folder name (required)',
+            },
+            color: {
+              type: 'string',
+              enum: ['blue', 'green', 'yellow', 'purple', 'pink', 'orange', 'gray'],
+              description: 'Folder color (optional, defaults to blue)',
+            },
+            position: {
+              type: 'object',
+              properties: {
+                x: { type: 'number' },
+                y: { type: 'number' },
+              },
+              description: 'Position on canvas (optional)',
+            },
+          },
+          required: ['name'],
+        },
+      },
+      {
+        name: 'aether_delete_folder',
+        description: 'Delete a canvas folder (files inside will be unassigned, not deleted)',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            folderId: {
+              type: 'string',
+              description: 'ID of the folder to delete',
+            },
+          },
+          required: ['folderId'],
+        },
+      },
+      {
+        name: 'aether_add_file_to_folder',
+        description: 'Add an existing file or artifact to a canvas folder',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            folderId: {
+              type: 'string',
+              description: 'ID of the target folder',
+            },
+            fileId: {
+              type: 'string',
+              description: 'ID of the file to add (from workspace files)',
+            },
+            artifactId: {
+              type: 'string',
+              description: 'ID of the artifact to add (alternative to fileId)',
+            },
+          },
+          required: ['folderId'],
+        },
+      },
+      // =========================================================================
+      // Artifact Creation Tools
+      // =========================================================================
+      {
+        name: 'aether_create_artifact',
+        description: 'Create a new artifact and optionally link it to a canvas node. Use this to store generated content (code, specs, docs) on the canvas.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            type: {
+              type: 'string',
+              enum: ['prd', 'audit_report', 'implementation_plan', 'phase_output', 'code', 'ux_spec', 'design_files', 'code_audit_report'],
+              description: 'Artifact type: prd, audit_report, implementation_plan, phase_output, code, ux_spec, design_files, code_audit_report',
+            },
+            title: {
+              type: 'string',
+              description: 'Title of the artifact',
+            },
+            content: {
+              type: 'string',
+              description: 'The artifact content (markdown, code, JSON structured output, etc.)',
+            },
+            nodeId: {
+              type: 'string',
+              description: 'Optional canvas node ID to link this artifact to (marks node as complete)',
+            },
+            agentId: {
+              type: 'string',
+              description: 'Optional agent ID that created this (e.g., "ux_designer", "engineer")',
+            },
+          },
+          required: ['type', 'title', 'content'],
+        },
+      },
+      // =========================================================================
+      // Orchestra Tools (Autonomous Development Orchestration)
+      // =========================================================================
+      {
+        name: 'aether_start_orchestra',
+        description: 'Start a new autonomous development orchestration session. Creates a session in "planning" status. After starting, use aether_set_orchestra_plan to define the development plan.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            maxIterations: {
+              type: 'number',
+              description: 'Maximum task iterations before stopping (default: 100)',
+            },
+            maxAgents: {
+              type: 'number',
+              description: 'Maximum concurrent agents (default: 20)',
+            },
+            timeoutMinutes: {
+              type: 'number',
+              description: 'Timeout in minutes (default: 480 = 8 hours)',
+            },
+            completionCriteria: {
+              type: 'array',
+              items: { type: 'string' },
+              description: 'List of criteria that must be met to auto-complete',
+            },
+          },
+        },
+      },
+      {
+        name: 'aether_set_orchestra_plan',
+        description: 'Set the development plan for an orchestra session. The plan should be comprehensive - this is the DEVELOPMENT_PLAN.md that guides the entire orchestra. After setting, status becomes "awaiting_approval".',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            sessionId: {
+              type: 'string',
+              description: 'Orchestra session ID from aether_start_orchestra',
+            },
+            planContent: {
+              type: 'string',
+              description: 'Full DEVELOPMENT_PLAN.md content - the comprehensive plan for the entire development cycle',
+            },
+            phases: {
+              type: 'array',
+              items: {
+                type: 'object',
+                properties: {
+                  phaseNumber: { type: 'number', description: 'Phase order (1-indexed)' },
+                  title: { type: 'string', description: 'Phase title' },
+                  description: { type: 'string', description: 'Phase description' },
+                  tasks: {
+                    type: 'array',
+                    items: {
+                      type: 'object',
+                      properties: {
+                        title: { type: 'string', description: 'Task title' },
+                        description: { type: 'string', description: 'Task details' },
+                        agentId: { type: 'string', description: 'Agent to execute (pm, architect, engineer, etc.)' },
+                        contextPrompt: { type: 'string', description: 'Context/prompt for the agent' },
+                        expectedOutput: { type: 'string', description: 'What output is expected' },
+                        dependsOnTasks: {
+                          type: 'array',
+                          items: { type: 'number' },
+                          description: 'Task numbers this depends on',
+                        },
+                      },
+                      required: ['title', 'agentId'],
+                    },
+                    description: 'Tasks for this phase',
+                  },
+                },
+                required: ['phaseNumber', 'title', 'tasks'],
+              },
+              description: 'Array of phases with their tasks',
+            },
+            completionCriteria: {
+              type: 'array',
+              items: { type: 'string' },
+              description: 'Updated completion criteria (optional)',
+            },
+          },
+          required: ['sessionId', 'planContent', 'phases'],
+        },
+      },
+      {
+        name: 'aether_orchestra_approve',
+        description: 'Approve the development plan and start autonomous execution. This is the point of no return - after approval, the orchestra will execute continuously until stopped or completion criteria are met.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            sessionId: {
+              type: 'string',
+              description: 'Orchestra session ID',
+            },
+          },
+          required: ['sessionId'],
+        },
+      },
+      {
+        name: 'aether_orchestra_status',
+        description: 'Get the current status of an orchestra session including progress, running tasks, pending reports, and safeguard checks. Call this frequently to monitor progress.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            sessionId: {
+              type: 'string',
+              description: 'Orchestra session ID (optional - uses latest if not provided)',
+            },
+            includeReports: {
+              type: 'boolean',
+              description: 'Include unprocessed agent reports (default: true)',
+            },
+            includeLogs: {
+              type: 'boolean',
+              description: 'Include recent event logs (default: false)',
+            },
+          },
+        },
+      },
+      {
+        name: 'aether_orchestra_next',
+        description: 'Get the next tasks that are ready to execute (dependencies satisfied). Use this to determine what to trigger next.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            sessionId: {
+              type: 'string',
+              description: 'Orchestra session ID',
+            },
+            maxTasks: {
+              type: 'number',
+              description: 'Maximum number of ready tasks to return (default: 5)',
+            },
+          },
+          required: ['sessionId'],
+        },
+      },
+      {
+        name: 'aether_orchestra_trigger_task',
+        description: 'Trigger execution of a specific task. This marks the task as "running" and provides the context needed to trigger the agent. After calling this, use aether_trigger_generation with the appropriate nodeId.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            sessionId: {
+              type: 'string',
+              description: 'Orchestra session ID',
+            },
+            taskId: {
+              type: 'string',
+              description: 'Task ID to trigger',
+            },
+            additionalContext: {
+              type: 'string',
+              description: 'Additional context to inject into the task prompt',
+            },
+          },
+          required: ['sessionId', 'taskId'],
+        },
+      },
+      {
+        name: 'aether_report_to_orchestrator',
+        description: 'Report task completion, blockers, or progress from an agent back to the orchestrator. Agents MUST call this when they complete or encounter issues.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            sessionId: {
+              type: 'string',
+              description: 'Orchestra session ID',
+            },
+            taskId: {
+              type: 'string',
+              description: 'Task ID being reported on',
+            },
+            reportType: {
+              type: 'string',
+              enum: ['completion', 'blocker', 'progress', 'error', 'needs_clarification'],
+              description: 'Type of report',
+            },
+            summary: {
+              type: 'string',
+              description: 'Brief summary of the report',
+            },
+            details: {
+              type: 'string',
+              description: 'Detailed report content',
+            },
+            artifactId: {
+              type: 'string',
+              description: 'ID of artifact produced (for completion reports)',
+            },
+            blockerDescription: {
+              type: 'string',
+              description: 'Description of blocker (for blocker reports)',
+            },
+            suggestedAction: {
+              type: 'string',
+              description: 'Suggested next action',
+            },
+          },
+          required: ['sessionId', 'taskId', 'reportType', 'summary'],
+        },
+      },
+      {
+        name: 'aether_orchestra_pause',
+        description: 'Pause orchestra execution. Running tasks will complete but no new tasks will start. Use aether_orchestra_resume to continue.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            sessionId: {
+              type: 'string',
+              description: 'Orchestra session ID',
+            },
+          },
+          required: ['sessionId'],
+        },
+      },
+      {
+        name: 'aether_orchestra_resume',
+        description: 'Resume a paused orchestra session.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            sessionId: {
+              type: 'string',
+              description: 'Orchestra session ID',
+            },
+          },
+          required: ['sessionId'],
+        },
+      },
+      {
+        name: 'aether_complete_orchestra',
+        description: 'Manually complete an orchestra session. Use this when all work is done or when stopping the session.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            sessionId: {
+              type: 'string',
+              description: 'Orchestra session ID',
+            },
+            completionReason: {
+              type: 'string',
+              enum: ['all_criteria_met', 'all_phases_complete', 'manual_stop', 'timeout', 'max_iterations'],
+              description: 'Reason for completion',
+            },
+            summary: {
+              type: 'string',
+              description: 'Summary of what was accomplished',
+            },
+          },
+          required: ['sessionId', 'completionReason'],
+        },
+      },
+    ];
+  }
+
+  async handleRequest(request) {
+    const { method, params, id } = request;
+
+    switch (method) {
+      case 'initialize':
+        return this.handleInitialize(id, params);
+      case 'tools/list':
+        return this.handleToolsList(id);
+      case 'tools/call':
+        return this.handleToolCall(id, params);
+      default:
+        return this.errorResponse(id, -32601, `Method not found: ${method}`);
+    }
+  }
+
+  handleInitialize(id, params) {
+    return {
+      jsonrpc: '2.0',
+      id,
+      result: {
+        protocolVersion: '2024-11-05',
+        capabilities: {
+          tools: {},
+        },
+        serverInfo: {
+          name: 'aether-mcp-server',
+          version: '1.0.0',
+        },
+      },
+    };
+  }
+
+  handleToolsList(id) {
+    return {
+      jsonrpc: '2.0',
+      id,
+      result: {
+        tools: this.tools,
+      },
+    };
+  }
+
+  async handleToolCall(id, params) {
+    const { name, arguments: args } = params;
+
+    try {
+      let result;
+
+      switch (name) {
+        case 'aether_canvas_state':
+          result = await this.getCanvasState(args);
+          break;
+        case 'aether_add_agent':
+          result = await this.addAgent(args);
+          break;
+        case 'aether_remove_node':
+          result = await this.removeNode(args);
+          break;
+        case 'aether_connect_nodes':
+          result = await this.connectNodes(args);
+          break;
+        case 'aether_trigger_generation':
+          result = await this.triggerGeneration(args);
+          break;
+        case 'aether_list_projects':
+          result = await this.listProjects();
+          break;
+        case 'aether_list_agents':
+          result = await this.listAgents();
+          break;
+        case 'aether_get_artifacts':
+          result = await this.getArtifacts(args);
+          break;
+        case 'aether_shell':
+          result = await this.executeShell(args);
+          break;
+        case 'aether_list_repositories':
+          result = await this.listRepositories();
+          break;
+        case 'aether_list_repo_files':
+          result = await this.listRepoFiles(args);
+          break;
+        case 'aether_read_repo_file':
+          result = await this.readRepoFile(args);
+          break;
+        case 'aether_search_repo':
+          result = await this.searchRepo(args);
+          break;
+        // GitHub Automation Tools
+        case 'aether_automation_status':
+          result = await this.getAutomationStatus(args);
+          break;
+        case 'aether_get_artifact_content':
+          result = await this.getArtifactContent(args);
+          break;
+        case 'aether_extract_files':
+          result = await this.extractFiles(args);
+          break;
+        case 'aether_push_artifacts':
+          result = await this.pushArtifacts(args);
+          break;
+        // Canvas Folder Tools
+        case 'aether_list_folders':
+          result = await this.listFolders(args);
+          break;
+        case 'aether_create_folder':
+          result = await this.createFolder(args);
+          break;
+        case 'aether_delete_folder':
+          result = await this.deleteFolder(args);
+          break;
+        case 'aether_add_file_to_folder':
+          result = await this.addFileToFolder(args);
+          break;
+        case 'aether_create_artifact':
+          result = await this.createArtifact(args);
+          break;
+        // Orchestra Tools
+        case 'aether_start_orchestra':
+          result = await this.startOrchestra(args);
+          break;
+        case 'aether_set_orchestra_plan':
+          result = await this.setOrchestraPlan(args);
+          break;
+        case 'aether_orchestra_approve':
+          result = await this.orchestraApprove(args);
+          break;
+        case 'aether_orchestra_status':
+          result = await this.orchestraStatus(args);
+          break;
+        case 'aether_orchestra_next':
+          result = await this.orchestraNext(args);
+          break;
+        case 'aether_orchestra_trigger_task':
+          result = await this.orchestraTriggerTask(args);
+          break;
+        case 'aether_report_to_orchestrator':
+          result = await this.reportToOrchestrator(args);
+          break;
+        case 'aether_orchestra_pause':
+          result = await this.orchestraPause(args);
+          break;
+        case 'aether_orchestra_resume':
+          result = await this.orchestraResume(args);
+          break;
+        case 'aether_complete_orchestra':
+          result = await this.completeOrchestra(args);
+          break;
+        default:
+          return this.errorResponse(id, -32602, `Unknown tool: ${name}`);
+      }
+
+      return {
+        jsonrpc: '2.0',
+        id,
+        result: {
+          content: [
+            {
+              type: 'text',
+              text: typeof result === 'string' ? result : JSON.stringify(result, null, 2),
+            },
+          ],
+        },
+      };
+    } catch (error) {
+      return {
+        jsonrpc: '2.0',
+        id,
+        result: {
+          content: [
+            {
+              type: 'text',
+              text: `Error: ${error.message}`,
+            },
+          ],
+          isError: true,
+        },
+      };
+    }
+  }
+
+  errorResponse(id, code, message) {
+    return {
+      jsonrpc: '2.0',
+      id,
+      error: { code, message },
+    };
+  }
+
+  // Tool implementations
+  async apiCall(endpoint, method = 'GET', body = null) {
+    const url = `${config.aetherUrl}/api${endpoint}`;
+    const headers = {
+      'Content-Type': 'application/json',
+    };
+
+    if (config.apiKey) {
+      headers['Authorization'] = `Bearer ${config.apiKey}`;
+    }
+
+    const options = { method, headers };
+    if (body) {
+      options.body = JSON.stringify(body);
+    }
+
+    const response = await fetch(url, options);
+    if (!response.ok) {
+      throw new Error(`API error: ${response.status} ${response.statusText}`);
+    }
+    return response.json();
+  }
+
+  async getCanvasState(args) {
+    const projectId = args.projectId || config.projectId;
+    if (!projectId) {
+      return { error: 'No project ID configured. Set AETHER_PROJECT_ID environment variable.' };
+    }
+
+    try {
+      const data = await this.apiCall(`/workspaces/${config.workspaceSlug}/projects/${projectId}/canvas`);
+      return {
+        nodes: data.nodes?.length || 0,
+        edges: data.edges?.length || 0,
+        details: data,
+      };
+    } catch (e) {
+      return {
+        message: 'Could not fetch canvas state. Make sure you are logged into Aether.',
+        hint: 'Open https://www.aithr.ai and log in, then try again.',
+      };
+    }
+  }
+
+  async addAgent(args) {
+    const { agentType, task, position, parentNodeId, nodeType, outputArtifactType, systemPrompt } = args;
+    const projectId = config.projectId;
+
+    if (!projectId) {
+      return { error: 'No project ID configured. Set AETHER_PROJECT_ID.' };
+    }
+
+    // Determine effective output artifact type
+    // Only set if explicitly provided - let the agent use its natural output type otherwise
+    // Use outputArtifactType: "code" for structured JSON (GitHub automation)
+    // Use outputArtifactType: "ux_spec", "prd", etc. for documents
+    const effectiveNodeType = nodeType || 'standard';
+    const effectiveOutputType = outputArtifactType || undefined;
+
+    // Build the correct payload format for the API
+    const nodeData = {
+      agentId: agentType, // API expects 'agentId' not 'agentType'
+      position: position || { x: 100 + Math.random() * 200, y: 100 + Math.random() * 200 },
+      customConfig: {
+        task: task || '',
+        label: task ? task.split(' - ')[0] : agentType, // Use first part of task as label
+        outputArtifactType: effectiveOutputType, // For structured output injection
+        systemPrompt: systemPrompt || undefined, // Custom system prompt
+      },
+      agentType: effectiveNodeType, // 'standard', 'parent', or 'sub'
+      parentNodeId: parentNodeId || undefined,
+    };
+
+    try {
+      const result = await this.apiCall(
+        `/workspaces/${config.workspaceSlug}/projects/${projectId}/canvas/nodes`,
+        'POST',
+        nodeData
+      );
+      return { success: true, nodeId: result.id, message: `Added ${agentType} agent`, node: result };
+    } catch (e) {
+      // Check if it's a tier restriction
+      if (e.message.includes('403') || e.message.includes('Pro tier')) {
+        return {
+          success: false,
+          error: 'Custom nodes require Pro tier. Upgrade at Settings > Billing.',
+          hint: 'You can still add default agents through the Aether canvas UI.'
+        };
+      }
+      return { success: false, error: e.message };
+    }
+  }
+
+  async removeNode(args) {
+    const { nodeId } = args;
+    const projectId = config.projectId;
+
+    try {
+      await this.apiCall(
+        `/workspaces/${config.workspaceSlug}/projects/${projectId}/canvas/nodes/${nodeId}`,
+        'DELETE'
+      );
+      return { success: true, message: `Removed node ${nodeId}` };
+    } catch (e) {
+      return { success: false, error: e.message };
+    }
+  }
+
+  async connectNodes(args) {
+    const { sourceId, targetId, connectionType } = args;
+    const projectId = config.projectId;
+
+    try {
+      // Use MCP endpoint with API key auth
+      const result = await this.mcpApiCall(
+        `/mcp/projects/${projectId}/connections`,
+        'POST',
+        {
+          sourceNodeId: sourceId,
+          targetNodeId: targetId,
+          connectionType: connectionType || 'dependency'
+        }
+      );
+      return {
+        success: true,
+        connectionId: result.connection?.id,
+        message: result.message
+      };
+    } catch (e) {
+      return { success: false, error: e.message };
+    }
+  }
+
+  async triggerGeneration(args) {
+    const { nodeId, context } = args;
+    const projectId = config.projectId;
+
+    if (!projectId) {
+      return { error: 'No project ID configured. Set AETHER_PROJECT_ID environment variable.' };
+    }
+
+    try {
+      // The generate endpoint returns SSE (Server-Sent Events), so we need to handle it specially
+      const url = `${config.aetherUrl}/api/workspaces/${config.workspaceSlug}/projects/${projectId}/agents/${nodeId}/generate`;
+      const headers = {
+        'Content-Type': 'application/json',
+      };
+
+      if (config.apiKey) {
+        headers['Authorization'] = `Bearer ${config.apiKey}`;
+      }
+
+      const response = await fetch(url, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify({ context }),
+      });
+
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(`API error: ${response.status} - ${errorText}`);
+      }
+
+      // Read SSE stream and collect events
+      const reader = response.body.getReader();
+      const decoder = new TextDecoder();
+      let buffer = '';
+      let lastEvent = null;
+      let artifactId = null;
+      let sessionId = null;
+      let error = null;
+
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+
+        buffer += decoder.decode(value, { stream: true });
+
+        // Parse SSE events from buffer
+        const lines = buffer.split('\n');
+        buffer = lines.pop() || ''; // Keep incomplete line in buffer
+
+        for (const line of lines) {
+          if (line.startsWith('event: ')) {
+            lastEvent = line.slice(7).trim();
+          } else if (line.startsWith('data: ')) {
+            try {
+              const data = JSON.parse(line.slice(6));
+
+              if (lastEvent === 'generation_complete') {
+                artifactId = data.artifactId;
+                sessionId = data.sessionId;
+              } else if (lastEvent === 'error') {
+                error = data.error || 'Generation failed';
+              }
+            } catch {
+              // Ignore JSON parse errors for partial data
+            }
+          }
+        }
+      }
+
+      if (error) {
+        return { success: false, error };
+      }
+
+      return {
+        success: true,
+        message: 'Generation completed',
+        artifactId,
+        sessionId,
+        hint: artifactId
+          ? 'Use aether_extract_files to extract code from the artifact, then aether_push_artifacts to push to GitHub.'
+          : undefined,
+      };
+    } catch (e) {
+      return { success: false, error: e.message };
+    }
+  }
+
+  async listProjects() {
+    try {
+      const data = await this.apiCall(`/workspaces/${config.workspaceSlug}/projects`);
+      return data.map(p => ({ id: p.id, name: p.name, mode: p.mode }));
+    } catch (e) {
+      return { error: e.message };
+    }
+  }
+
+  async listAgents() {
+    const projectId = config.projectId;
+    if (!projectId) {
+      return { error: 'No project ID configured. Set AETHER_PROJECT_ID environment variable.' };
+    }
+
+    try {
+      const data = await this.apiCall(`/workspaces/${config.workspaceSlug}/projects/${projectId}/canvas`);
+      // Canvas API returns nodes directly - they have agentId, agentType, status, customConfig
+      const nodes = data.nodes || [];
+
+      return {
+        agents: nodes.map(n => ({
+          id: n.id,
+          agentId: n.agentId,
+          agentType: n.agentType || 'standard',
+          status: n.status,
+          name: n.customConfig?.name || n.customConfig?.label || n.agentId,
+          task: n.customConfig?.task,
+          position: n.position,
+          parentNodeId: n.parentNodeId,
+          isCustom: n.isCustom,
+        })),
+        summary: {
+          total: nodes.length,
+          byType: nodes.reduce((acc, n) => {
+            const type = n.agentType || 'standard';
+            acc[type] = (acc[type] || 0) + 1;
+            return acc;
+          }, {}),
+          byStatus: nodes.reduce((acc, n) => {
+            const status = n.status || 'unknown';
+            acc[status] = (acc[status] || 0) + 1;
+            return acc;
+          }, {}),
+        },
+      };
+    } catch (e) {
+      return { error: e.message };
+    }
+  }
+
+  async getArtifactContent(args) {
+    const { artifactId } = args;
+    const projectId = config.projectId;
+
+    if (!projectId) {
+      return { error: 'No project ID configured. Set AETHER_PROJECT_ID environment variable.' };
+    }
+
+    if (!artifactId) {
+      return { error: 'Artifact ID is required' };
+    }
+
+    try {
+      const data = await this.apiCall(
+        `/mcp/projects/${projectId}/artifacts/${artifactId}`
+      );
+      return {
+        artifact: data.artifact,
+        content: data.content,
+        hint: data.content?.contentType === 'json' || data.content?.full?.startsWith('{')
+          ? 'This looks like structured JSON output. Use aether_extract_files to parse it.'
+          : 'This artifact does not appear to have structured JSON output.',
+      };
+    } catch (e) {
+      return { error: e.message };
+    }
+  }
+
+  async getArtifacts(args) {
+    const projectId = config.projectId;
+    try {
+      let url = `/workspaces/${config.workspaceSlug}/projects/${projectId}/artifacts`;
+      if (args.artifactType) {
+        url += `?type=${args.artifactType}`;
+      }
+      const data = await this.apiCall(url);
+      return data.map(a => {
+        // Handle content that might be object, string, or null
+        let preview = '';
+        if (typeof a.content === 'string') {
+          preview = a.content.slice(0, 200);
+        } else if (a.content && typeof a.content === 'object') {
+          preview = JSON.stringify(a.content).slice(0, 200);
+        }
+        return {
+          id: a.id,
+          type: a.type,
+          agentType: a.agentType,
+          createdAt: a.createdAt,
+          preview,
+        };
+      });
+    } catch (e) {
+      return { error: e.message };
+    }
+  }
+
+  async executeShell(args) {
+    const { command, cwd } = args;
+
+    // Execute locally using child_process
+    const { exec } = require('child_process');
+    const { promisify } = require('util');
+    const execAsync = promisify(exec);
+
+    try {
+      const { stdout, stderr } = await execAsync(command, {
+        cwd: cwd || process.cwd(),
+        timeout: 30000,
+        shell: process.platform === 'win32' ? 'powershell.exe' : '/bin/bash',
+      });
+
+      return {
+        success: true,
+        stdout: stdout || '',
+        stderr: stderr || '',
+      };
+    } catch (e) {
+      return {
+        success: false,
+        exitCode: e.code,
+        stdout: e.stdout || '',
+        stderr: e.stderr || e.message,
+      };
+    }
+  }
+
+  // Repository tools with recommendation messaging
+  async listRepositories() {
+    try {
+      const data = await this.apiCall(`/workspaces/${config.workspaceSlug}/repositories`);
+      return {
+        recommendation: '💡 TIP: For faster file access, clone the repo locally: `git clone <url>` and use standard file tools (Read, Grep, Glob).',
+        repositories: data.map(r => ({
+          id: r.id,
+          name: r.name,
+          fullName: r.fullName,
+          defaultBranch: r.defaultBranch,
+          cloneUrl: r.cloneUrl,
+          lastSyncedAt: r.lastSyncedAt,
+        })),
+      };
+    } catch (e) {
+      return { error: e.message };
+    }
+  }
+
+  async listRepoFiles(args) {
+    const { repositoryId, path = '' } = args;
+
+    try {
+      const url = `/workspaces/${config.workspaceSlug}/repositories/${repositoryId}/files${path ? `?path=${encodeURIComponent(path)}` : ''}`;
+      const data = await this.apiCall(url);
+      return {
+        recommendation: '💡 TIP: For faster access, clone this repo locally and use standard file tools.',
+        path: path || '/',
+        files: data,
+      };
+    } catch (e) {
+      return { error: e.message };
+    }
+  }
+
+  async readRepoFile(args) {
+    const { repositoryId, filePath } = args;
+
+    try {
+      // First get file info to get the file ID
+      const filesUrl = `/workspaces/${config.workspaceSlug}/repositories/${repositoryId}/files?path=${encodeURIComponent(filePath)}`;
+      const fileInfo = await this.apiCall(filesUrl);
+
+      if (!fileInfo || fileInfo.length === 0) {
+        return { error: `File not found: ${filePath}` };
+      }
+
+      const file = fileInfo.find(f => f.path === filePath || f.name === filePath.split('/').pop());
+      if (!file) {
+        return { error: `File not found: ${filePath}` };
+      }
+
+      // Get file content
+      const contentUrl = `/workspaces/${config.workspaceSlug}/repositories/${repositoryId}/files/${file.id}`;
+      const content = await this.apiCall(contentUrl);
+
+      return {
+        recommendation: '💡 TIP: For faster reads, clone the repo locally and use: Read tool with the file path.',
+        filePath,
+        content: content.content || content,
+      };
+    } catch (e) {
+      return { error: e.message };
+    }
+  }
+
+  async searchRepo(args) {
+    const { repositoryId, query, fileTypes } = args;
+
+    try {
+      let url = `/workspaces/${config.workspaceSlug}/repositories/${repositoryId}/search?q=${encodeURIComponent(query)}`;
+      if (fileTypes && fileTypes.length > 0) {
+        url += `&fileTypes=${encodeURIComponent(fileTypes.join(','))}`;
+      }
+
+      const data = await this.apiCall(url);
+      return {
+        recommendation: '💡 TIP: For faster searches, clone the repo locally and use: Grep tool for content search, Glob tool for file patterns.',
+        query,
+        results: data,
+      };
+    } catch (e) {
+      return { error: e.message };
+    }
+  }
+
+  // =========================================================================
+  // GitHub Automation Tool Implementations
+  // =========================================================================
+
+  async getAutomationStatus(args) {
+    const projectId = args.projectId || config.projectId;
+    if (!projectId) {
+      return { error: 'No project ID configured. Set AETHER_PROJECT_ID environment variable.' };
+    }
+
+    try {
+      // Use MCP endpoint which doesn't require workspace slug in path
+      const data = await this.mcpApiCall(`/mcp/projects/${projectId}/push-artifacts`, 'GET');
+      return {
+        project: data.project,
+        automation: data.automation,
+        artifacts: {
+          total: data.artifacts?.total || 0,
+          parseable: data.artifacts?.parseable || 0,
+          items: data.artifacts?.items?.map(a => ({
+            id: a.id,
+            title: a.title,
+            parseable: a.parseable,
+            filesCount: a.filesCount,
+          })) || [],
+        },
+        generatedFiles: data.generatedFiles,
+        hints: data.hints,
+      };
+    } catch (e) {
+      return { error: e.message };
+    }
+  }
+
+  async extractFiles(args) {
+    const { artifactId, saveToGeneratedFiles } = args;
+    const projectId = config.projectId;
+
+    if (!projectId) {
+      return { error: 'No project ID configured. Set AETHER_PROJECT_ID environment variable.' };
+    }
+
+    try {
+      // Use POST to get full file contents
+      const data = await this.mcpApiCall(
+        `/mcp/projects/${projectId}/artifacts/${artifactId}/files`,
+        'POST',
+        { saveToGeneratedFiles: saveToGeneratedFiles || false }
+      );
+
+      return {
+        artifact: data.artifact,
+        extraction: {
+          success: data.extraction?.success,
+          method: data.extraction?.method,
+          filesCount: data.extraction?.files?.length || 0,
+          files: data.extraction?.files?.map(f => ({
+            path: f.path,
+            language: f.language,
+            contentLength: f.content?.length || 0,
+          })) || [],
+          warnings: data.extraction?.warnings,
+        },
+        readyForPush: data.readyForPush,
+        savedFiles: data.savedFiles,
+      };
+    } catch (e) {
+      return { error: e.message };
+    }
+  }
+
+  async pushArtifacts(args) {
+    const projectId = config.projectId;
+
+    if (!projectId) {
+      return { error: 'No project ID configured. Set AETHER_PROJECT_ID environment variable.' };
+    }
+
+    const {
+      artifactIds,
+      branchName,
+      commitMessage,
+      prTitle,
+      prBody,
+      createPR = true,
+      draft = false,
+      dryRun = false,
+    } = args;
+
+    try {
+      const data = await this.mcpApiCall(
+        `/mcp/projects/${projectId}/push-artifacts`,
+        'POST',
+        {
+          artifactIds,
+          branchName,
+          commitMessage,
+          prTitle,
+          prBody,
+          createPR,
+          draft,
+          dryRun,
+        }
+      );
+
+      if (dryRun) {
+        return {
+          dryRun: true,
+          wouldPush: data.wouldPush,
+          message: `Would push ${data.wouldPush?.filesCount || 0} files to branch ${data.wouldPush?.branch}`,
+        };
+      }
+
+      return {
+        success: data.success,
+        branch: data.branch,
+        commit: data.commit,
+        pullRequest: data.pullRequest,
+        filesCount: data.files?.length || 0,
+        message: data.message,
+      };
+    } catch (e) {
+      return { error: e.message };
+    }
+  }
+
+  // =========================================================================
+  // Canvas Folder Tool Implementations
+  // =========================================================================
+
+  async listFolders(args) {
+    const projectId = args.projectId || config.projectId;
+    if (!projectId) {
+      return { error: 'No project ID configured. Set AETHER_PROJECT_ID environment variable.' };
+    }
+
+    try {
+      // Use MCP endpoint with API key auth
+      const data = await this.mcpApiCall(`/mcp/projects/${projectId}/folders`);
+
+      return {
+        folders: (data.folders || []).map(f => ({
+          id: f.id,
+          name: f.name,
+          color: f.color,
+          fileCount: f.fileCount || 0,
+          position: f.canvasX && f.canvasY ? { x: f.canvasX, y: f.canvasY } : null,
+          createdAt: f.createdAt,
+        })),
+        count: data.count || 0,
+      };
+    } catch (e) {
+      return { error: e.message };
+    }
+  }
+
+  async createFolder(args) {
+    const { name, color, position } = args;
+    const projectId = config.projectId;
+
+    if (!projectId) {
+      return { error: 'No project ID configured. Set AETHER_PROJECT_ID environment variable.' };
+    }
+
+    if (!name) {
+      return { error: 'Folder name is required' };
+    }
+
+    try {
+      // Use MCP endpoint with API key auth
+      const result = await this.mcpApiCall(
+        `/mcp/projects/${projectId}/folders`,
+        'POST',
+        {
+          name,
+          color: color || 'blue',
+          canvasX: position?.x,
+          canvasY: position?.y,
+        }
+      );
+
+      return {
+        success: true,
+        folder: {
+          id: result.folder?.id,
+          name: result.folder?.name,
+          color: result.folder?.color,
+        },
+        message: result.message || `Created folder "${name}"`,
+      };
+    } catch (e) {
+      return { success: false, error: e.message };
+    }
+  }
+
+  async deleteFolder(args) {
+    const { folderId } = args;
+    const projectId = config.projectId;
+
+    if (!projectId) {
+      return { error: 'No project ID configured. Set AETHER_PROJECT_ID environment variable.' };
+    }
+
+    if (!folderId) {
+      return { error: 'Folder ID is required' };
+    }
+
+    try {
+      // Use MCP endpoint with API key auth
+      const result = await this.mcpApiCall(
+        `/mcp/projects/${projectId}/folders/${folderId}`,
+        'DELETE'
+      );
+
+      return {
+        success: true,
+        message: `Deleted folder ${folderId}`,
+      };
+    } catch (e) {
+      return { success: false, error: e.message };
+    }
+  }
+
+  async addFileToFolder(args) {
+    const { folderId, fileId, artifactId } = args;
+    const projectId = config.projectId;
+
+    if (!projectId) {
+      return { error: 'No project ID configured. Set AETHER_PROJECT_ID environment variable.' };
+    }
+
+    if (!folderId) {
+      return { error: 'Folder ID is required' };
+    }
+
+    if (!fileId && !artifactId) {
+      return { error: 'Either fileId or artifactId is required' };
+    }
+
+    try {
+      // If artifactId provided, use the artifact push-to-folder endpoint
+      if (artifactId) {
+        const result = await this.apiCall(
+          `/workspaces/${config.workspaceSlug}/projects/${projectId}/artifacts/${artifactId}/push-to-folder`,
+          'POST',
+          { folderId }
+        );
+
+        return {
+          success: true,
+          message: `Added artifact to folder`,
+          result,
+        };
+      }
+
+      // If fileId provided, update the file's folder assignment
+      const result = await this.apiCall(
+        `/workspaces/${config.workspaceSlug}/projects/${projectId}/workspace-files/${fileId}`,
+        'PATCH',
+        { folderId }
+      );
+
+      return {
+        success: true,
+        message: `Added file to folder`,
+        result,
+      };
+    } catch (e) {
+      return { success: false, error: e.message };
+    }
+  }
+
+  async createArtifact(args) {
+    const { type, title, content, nodeId, agentId } = args;
+    const projectId = config.projectId;
+
+    if (!projectId) {
+      return { error: 'No project ID configured. Set AETHER_PROJECT_ID environment variable.' };
+    }
+
+    if (!type) {
+      return { error: 'Artifact type is required (e.g., "code", "ux_spec", "prd")' };
+    }
+
+    if (!title) {
+      return { error: 'Title is required' };
+    }
+
+    if (!content) {
+      return { error: 'Content is required' };
+    }
+
+    try {
+      const result = await this.mcpApiCall(
+        `/mcp/projects/${projectId}/artifacts`,
+        'POST',
+        {
+          type,
+          title,
+          content,
+          nodeId: nodeId || undefined,
+          agentId: agentId || undefined,
+        }
+      );
+
+      return {
+        success: true,
+        message: `Created artifact: ${title}`,
+        artifactId: result.artifact?.id,
+        nodeUpdated: result.nodeUpdated,
+        artifact: result.artifact,
+      };
+    } catch (e) {
+      return { success: false, error: e.message };
+    }
+  }
+
+  // MCP API call helper (uses /api/mcp/* endpoints with API key auth)
+  async mcpApiCall(endpoint, method = 'GET', body = null) {
+    const url = `${config.aetherUrl}/api${endpoint}`;
+    const headers = {
+      'Content-Type': 'application/json',
+    };
+
+    if (config.apiKey) {
+      headers['Authorization'] = `Bearer ${config.apiKey}`;
+    }
+
+    const options = { method, headers };
+    if (body) {
+      options.body = JSON.stringify(body);
+    }
+
+    const response = await fetch(url, options);
+    const responseData = await response.json();
+
+    if (!response.ok) {
+      // Include hints and code in error message for better debugging
+      let errorMsg = responseData.error || `API error: ${response.status}`;
+      if (responseData.code) {
+        errorMsg += ` [${responseData.code}]`;
+      }
+      if (responseData.hints && responseData.hints.length > 0) {
+        errorMsg += `. Hints: ${responseData.hints.join(' | ')}`;
+      }
+      throw new Error(errorMsg);
+    }
+
+    return responseData;
+  }
+
+  // =========================================================================
+  // Orchestra Tool Implementations
+  // =========================================================================
+
+  async startOrchestra(args) {
+    const projectId = config.projectId;
+
+    if (!projectId) {
+      return { error: 'No project ID configured. Set AETHER_PROJECT_ID environment variable.' };
+    }
+
+    try {
+      const data = await this.mcpApiCall(
+        `/mcp/projects/${projectId}/orchestra`,
+        'POST',
+        {
+          action: 'start',
+          maxIterations: args.maxIterations,
+          maxAgents: args.maxAgents,
+          timeoutMinutes: args.timeoutMinutes,
+          completionCriteria: args.completionCriteria,
+        }
+      );
+
+      return {
+        success: true,
+        sessionId: data.sessionId,
+        status: data.status,
+        message: data.message,
+        nextStep: 'Use aether_set_orchestra_plan to define the development plan',
+      };
+    } catch (e) {
+      return { success: false, error: e.message };
+    }
+  }
+
+  async setOrchestraPlan(args) {
+    const projectId = config.projectId;
+
+    if (!projectId) {
+      return { error: 'No project ID configured. Set AETHER_PROJECT_ID environment variable.' };
+    }
+
+    const { sessionId, planContent, phases, completionCriteria } = args;
+
+    if (!sessionId || !planContent || !phases) {
+      return { error: 'sessionId, planContent, and phases are required' };
+    }
+
+    try {
+      const data = await this.mcpApiCall(
+        `/mcp/projects/${projectId}/orchestra`,
+        'POST',
+        {
+          action: 'set-plan',
+          sessionId,
+          planContent,
+          phases,
+          completionCriteria,
+        }
+      );
+
+      return {
+        success: true,
+        sessionId,
+        status: data.status,
+        totalPhases: data.totalPhases,
+        totalTasks: data.totalTasks,
+        message: data.message,
+        nextStep: 'Use aether_orchestra_approve to begin autonomous execution',
+      };
+    } catch (e) {
+      return { success: false, error: e.message };
+    }
+  }
+
+  async orchestraApprove(args) {
+    const projectId = config.projectId;
+
+    if (!projectId) {
+      return { error: 'No project ID configured. Set AETHER_PROJECT_ID environment variable.' };
+    }
+
+    const { sessionId } = args;
+
+    if (!sessionId) {
+      return { error: 'sessionId is required' };
+    }
+
+    try {
+      const data = await this.mcpApiCall(
+        `/mcp/projects/${projectId}/orchestra`,
+        'POST',
+        {
+          action: 'approve',
+          sessionId,
+        }
+      );
+
+      return {
+        success: true,
+        sessionId,
+        status: data.status,
+        message: data.message,
+        warning: '⚠️ ORCHESTRA STARTED: Claude Code is now in autonomous control. The system will execute tasks until stopped or completion criteria are met.',
+        nextStep: 'Use aether_orchestra_next to get the first batch of ready tasks',
+      };
+    } catch (e) {
+      return { success: false, error: e.message };
+    }
+  }
+
+  async orchestraStatus(args) {
+    const projectId = config.projectId;
+
+    if (!projectId) {
+      return { error: 'No project ID configured. Set AETHER_PROJECT_ID environment variable.' };
+    }
+
+    try {
+      let url = `/mcp/projects/${projectId}/orchestra`;
+      const params = [];
+      if (args.sessionId) params.push(`sessionId=${args.sessionId}`);
+      if (args.includeReports !== undefined) params.push(`includeReports=${args.includeReports}`);
+      if (args.includeLogs !== undefined) params.push(`includeLogs=${args.includeLogs}`);
+      if (params.length > 0) url += `?${params.join('&')}`;
+
+      const data = await this.mcpApiCall(url);
+
+      if (!data.session) {
+        return {
+          hasSession: false,
+          message: 'No orchestra session found. Use aether_start_orchestra to begin.',
+        };
+      }
+
+      return {
+        session: data.session,
+        progress: data.progress,
+        currentPhase: data.currentPhase,
+        phases: data.phases,
+        tasks: data.tasks,
+        reports: data.reports,
+        safeguards: data.safeguards,
+        completionCriteria: data.completionCriteria,
+      };
+    } catch (e) {
+      return { error: e.message };
+    }
+  }
+
+  async orchestraNext(args) {
+    const projectId = config.projectId;
+
+    if (!projectId) {
+      return { error: 'No project ID configured. Set AETHER_PROJECT_ID environment variable.' };
+    }
+
+    const { sessionId, maxTasks = 5 } = args;
+
+    if (!sessionId) {
+      return { error: 'sessionId is required' };
+    }
+
+    try {
+      const data = await this.mcpApiCall(
+        `/mcp/projects/${projectId}/orchestra/next`,
+        'POST',
+        { sessionId, maxTasks }
+      );
+
+      return {
+        readyTasks: data.tasks || [],
+        count: data.count || 0,
+        hint: data.count > 0
+          ? 'Use aether_orchestra_trigger_task with each taskId to start execution'
+          : 'No tasks ready. Check aether_orchestra_status for blockers or completion.',
+      };
+    } catch (e) {
+      return { error: e.message };
+    }
+  }
+
+  async orchestraTriggerTask(args) {
+    const projectId = config.projectId;
+
+    if (!projectId) {
+      return { error: 'No project ID configured. Set AETHER_PROJECT_ID environment variable.' };
+    }
+
+    const { sessionId, taskId, additionalContext } = args;
+
+    if (!sessionId || !taskId) {
+      return { error: 'sessionId and taskId are required' };
+    }
+
+    try {
+      const data = await this.mcpApiCall(
+        `/mcp/projects/${projectId}/orchestra`,
+        'POST',
+        {
+          action: 'trigger-task',
+          sessionId,
+          taskId,
+          additionalContext,
+        }
+      );
+
+      return {
+        success: true,
+        taskId: data.taskId,
+        agentId: data.agentId,
+        status: data.status,
+        contextPrompt: data.contextPrompt,
+        expectedOutput: data.expectedOutput,
+        message: data.message,
+        nextStep: `Now trigger the agent with aether_trigger_generation(nodeId: "...", context: "${data.contextPrompt || ''}")`,
+      };
+    } catch (e) {
+      return { success: false, error: e.message };
+    }
+  }
+
+  async reportToOrchestrator(args) {
+    const projectId = config.projectId;
+
+    if (!projectId) {
+      return { error: 'No project ID configured. Set AETHER_PROJECT_ID environment variable.' };
+    }
+
+    const { sessionId, taskId, reportType, summary, details, artifactId, blockerDescription, suggestedAction } = args;
+
+    if (!sessionId || !taskId || !reportType || !summary) {
+      return { error: 'sessionId, taskId, reportType, and summary are required' };
+    }
+
+    try {
+      const data = await this.mcpApiCall(
+        `/mcp/projects/${projectId}/orchestra/report`,
+        'POST',
+        {
+          sessionId,
+          taskId,
+          reportType,
+          summary,
+          details,
+          artifactId,
+          blockerDescription,
+          suggestedAction,
+        }
+      );
+
+      return {
+        success: true,
+        reportId: data.reportId,
+        taskStatus: data.taskStatus,
+        message: data.message,
+      };
+    } catch (e) {
+      return { success: false, error: e.message };
+    }
+  }
+
+  async orchestraPause(args) {
+    const projectId = config.projectId;
+
+    if (!projectId) {
+      return { error: 'No project ID configured. Set AETHER_PROJECT_ID environment variable.' };
+    }
+
+    const { sessionId } = args;
+
+    if (!sessionId) {
+      return { error: 'sessionId is required' };
+    }
+
+    try {
+      const data = await this.mcpApiCall(
+        `/mcp/projects/${projectId}/orchestra`,
+        'POST',
+        {
+          action: 'pause',
+          sessionId,
+        }
+      );
+
+      return {
+        success: true,
+        sessionId,
+        status: data.status,
+        message: data.message,
+      };
+    } catch (e) {
+      return { success: false, error: e.message };
+    }
+  }
+
+  async orchestraResume(args) {
+    const projectId = config.projectId;
+
+    if (!projectId) {
+      return { error: 'No project ID configured. Set AETHER_PROJECT_ID environment variable.' };
+    }
+
+    const { sessionId } = args;
+
+    if (!sessionId) {
+      return { error: 'sessionId is required' };
+    }
+
+    try {
+      const data = await this.mcpApiCall(
+        `/mcp/projects/${projectId}/orchestra`,
+        'POST',
+        {
+          action: 'resume',
+          sessionId,
+        }
+      );
+
+      return {
+        success: true,
+        sessionId,
+        status: data.status,
+        message: data.message,
+      };
+    } catch (e) {
+      return { success: false, error: e.message };
+    }
+  }
+
+  async completeOrchestra(args) {
+    const projectId = config.projectId;
+
+    if (!projectId) {
+      return { error: 'No project ID configured. Set AETHER_PROJECT_ID environment variable.' };
+    }
+
+    const { sessionId, completionReason, summary } = args;
+
+    if (!sessionId || !completionReason) {
+      return { error: 'sessionId and completionReason are required' };
+    }
+
+    try {
+      const data = await this.mcpApiCall(
+        `/mcp/projects/${projectId}/orchestra`,
+        'POST',
+        {
+          action: 'complete',
+          sessionId,
+          completionReason,
+          summary,
+        }
+      );
+
+      return {
+        success: true,
+        sessionId,
+        status: data.status,
+        completionReason: data.completionReason,
+        summary: data.summary,
+        message: data.message,
+      };
+    } catch (e) {
+      return { success: false, error: e.message };
+    }
+  }
+
+  async run() {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+      terminal: false,
+    });
+
+    // Send initialized notification
+    process.stderr.write('Aether MCP Server started\n');
+
+    let buffer = '';
+
+    rl.on('line', async (line) => {
+      buffer += line;
+
+      try {
+        const request = JSON.parse(buffer);
+        buffer = '';
+
+        const response = await this.handleRequest(request);
+        console.log(JSON.stringify(response));
+      } catch (e) {
+        // Incomplete JSON, wait for more
+        if (e instanceof SyntaxError) {
+          return;
+        }
+        console.log(JSON.stringify({
+          jsonrpc: '2.0',
+          id: null,
+          error: { code: -32700, message: 'Parse error' },
+        }));
+        buffer = '';
+      }
+    });
+
+    rl.on('close', () => {
+      process.exit(0);
+    });
+  }
+}
+
+// Run the server
+const server = new MCPServer();
+server.run();