@aithr-ai/mcp-server 1.0.5 → 1.0.7

package/README.md

@@ -1,137 +1,83 @@
-# Aether MCP Server
+# @aithr-ai/mcp-server
 
-Connect [Claude Code](https://claude.com/claude-code) to [Aether](https://www.aithr.ai) - the AI-powered team workspace for software development.
+MCP (Model Context Protocol) server to connect Claude Code to the Aether canvas.
 
 ## Quick Install
 
-### One-Line Setup (Recommended)
-
-**Mac/Linux:**
+### Mac/Linux
 ```bash
 claude mcp add --transport stdio aether \
-  --env AETHER_API_KEY=YOUR_API_KEY \
-  --env AETHER_WORKSPACE_ID=your-workspace-slug \
-  --env AETHER_PROJECT_ID=your-project-uuid \
-  -s user \
-  -- npx -y @aithr-ai/mcp-server
+  --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:**
-```bash
-claude mcp add --transport stdio aether ^
-  --env AETHER_API_KEY=YOUR_API_KEY ^
-  --env AETHER_WORKSPACE_ID=your-workspace-slug ^
-  --env AETHER_PROJECT_ID=your-project-uuid ^
-  -s user ^
-  -- cmd /c npx -y @aithr-ai/mcp-server
+### Windows
+
+Add this to your `~/.claude.json` file (in the `mcpServers` object):
+
+```json
+{
+  "mcpServers": {
+    "aether": {
+      "type": "stdio",
+      "command": "cmd",
+      "args": ["/c", "npx", "-y", "@aithr-ai/mcp-server"],
+      "env": {
+        "AETHER_API_KEY": "YOUR_KEY",
+        "AETHER_WORKSPACE_ID": "your-workspace",
+        "AETHER_PROJECT_ID": "your-project-id"
+      }
+    }
+  }
+}
 ```
 
-### Get Your Credentials
+> **Note**: The `claude mcp add` command has a bug on Windows that drops the command args. Manual config is required.
+
+## Get Your Credentials
 
-1. **API Key**: Go to Aether Settings > API Keys > Create Key
-2. **Workspace ID**: Your workspace slug from the URL (e.g., `my-team`)
-3. **Project ID**: The UUID from your project URL
+Visit [https://www.aithr.ai/settings/mcp-install](https://www.aithr.ai/settings/mcp-install) for personalized install commands with your API key and project ID.
 
 ## Available Tools
 
-### Canvas & Agent Tools
-| Tool | Description |
-|------|-------------|
-| `aether_canvas_state` | Get current canvas nodes, edges, and status |
-| `aether_add_agent` | Add an AI agent to the canvas |
-| `aether_remove_node` | Remove a node from the canvas |
-| `aether_connect_nodes` | Create connections between nodes |
-| `aether_list_agents` | List available agent types |
-| `aether_get_agent_context` | Get context for an agent |
-
-### Generation Tools
-| Tool | Description |
-|------|-------------|
-| `aether_trigger_generation` | Start AI generation for a node |
-| `aether_get_artifacts` | List generated artifacts |
-| `aether_get_artifact_content` | Get full artifact content |
-| `aether_create_artifact` | Create a new artifact |
-| `aether_extract_files` | Extract code files from artifact |
+### Canvas Management
+- `aether_canvas_state` - Get current canvas state
+- `aether_clear_canvas` - Clear all nodes from canvas
+- `aether_add_agent` - Add an AI agent to the canvas
+- `aether_remove_node` - Remove a node
+- `aether_connect_nodes` - Create connections between nodes
+- `aether_list_agents` - List all agents on canvas
+
+### Generation
+- `aether_trigger_generation` - Trigger AI generation for an agent
+- `aether_get_artifacts` - Get generated artifacts
 
 ### GitHub Automation
-| Tool | Description |
-|------|-------------|
-| `aether_automation_status` | Check what's ready to push |
-| `aether_push_artifacts` | Push artifacts to GitHub (branch + commit + PR) |
-| `aether_list_repositories` | List synced repositories |
-| `aether_read_repo_file` | Read a file from a repository |
+- `aether_automation_status` - Check what's ready to push
+- `aether_extract_files` - Extract code from artifacts
+- `aether_push_artifacts` - Push to GitHub (branch + commit + PR)
 
 ### Orchestra (Autonomous Development)
-| Tool | Description |
-|------|-------------|
-| `aether_start_orchestra` | Start an orchestra session |
-| `aether_set_orchestra_plan` | Set the development plan |
-| `aether_orchestra_approve` | Approve and begin execution |
-| `aether_orchestra_status` | Get current progress |
-| `aether_orchestra_next` | Get next ready tasks |
-| `aether_orchestra_trigger_task` | Execute a specific task |
-| `aether_report_to_orchestrator` | Report task completion/blockers |
-| `aether_orchestra_pause` | Pause execution |
-| `aether_orchestra_resume` | Resume execution |
-| `aether_complete_orchestra` | Complete the session |
-
-### Project & Workspace
-| Tool | Description |
-|------|-------------|
-| `aether_list_projects` | List your projects |
-| `aether_list_workspaces` | List your workspaces |
-| `aether_switch_project` | Switch active project |
-
-### Canvas Folders
-| Tool | Description |
-|------|-------------|
-| `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 |
-
-### Utility
-| Tool | Description |
-|------|-------------|
-| `aether_shell` | Execute shell commands locally |
-
-## Management Commands
-
-```bash
-# Check MCP server status
-/mcp
-
-# List all MCP servers
-claude mcp list
-
-# Remove Aether MCP
-claude mcp remove aether
-
-# Update to latest version
-claude mcp remove aether && claude mcp add ...
-```
-
-## Troubleshooting
-
-### "Unauthorized" errors
-- Check your API key is correct
-- Ensure the workspace ID matches your workspace slug
-- Verify the project ID is a valid UUID
-
-### "Project not found" errors
-- Confirm you have access to the project
-- Check the project ID in the URL
-
-### Windows-specific issues
-- Always use `cmd /c` before `npx` commands
-- Use `^` for line continuation instead of `\`
-
-## Links
-
-- [Aether App](https://www.aithr.ai)
-- [Claude Code](https://claude.com/claude-code)
-- [MCP Documentation](https://modelcontextprotocol.io)
-
-## License
-
-MIT
+- `aether_start_orchestra` - Start orchestration session
+- `aether_set_orchestra_plan` - Define development plan
+- `aether_orchestra_approve` - Approve and start execution
+- `aether_orchestra_status` - Get progress and status
+- `aether_orchestra_next` - Get next ready tasks
+- `aether_orchestra_trigger_task` - Execute a specific task
+- `aether_report_to_orchestrator` - Report completion/blockers
+- `aether_orchestra_pause` / `aether_orchestra_resume` - Control execution
+- `aether_complete_orchestra` - Mark session complete
+- `aether_orchestra_set_autonomous` - Enable/disable autonomous mode
+
+### Folders & Artifacts
+- `aether_list_folders` - List project folders
+- `aether_create_folder` - Create a folder
+- `aether_delete_folder` - Delete a folder
+- `aether_add_file_to_folder` - Add files to folders
+- `aether_create_artifact` - Create and place artifacts
+
+## Documentation
+
+Full documentation at [https://www.aithr.ai/docs/orchestra](https://www.aithr.ai/docs/orchestra)

package/index.js

@@ -208,7 +208,7 @@ class MCPServer {
       },
       {
         name: 'aether_trigger_generation',
-        description: 'Trigger AI generation for an agent on the canvas',
+        description: 'Trigger AI generation for an agent on the canvas. For orchestra mode, pass the orchestraContext from aether_orchestra_next to inject full context including upstream artifacts.',
         inputSchema: {
           type: 'object',
           properties: {
@@ -218,7 +218,11 @@ class MCPServer {
             },
             context: {
               type: 'string',
-              description: 'Additional context for generation',
+              description: 'Additional context for generation (runtime override)',
+            },
+            orchestraContext: {
+              type: 'object',
+              description: 'Orchestra context from aether_orchestra_next - includes sessionId, taskId, phase info, upstream artifacts, and plan excerpt. Pass this directly from the task object returned by orchestra_next.',
             },
           },
           required: ['nodeId'],
@@ -665,7 +669,7 @@ class MCPServer {
       },
       {
         name: 'aether_orchestra_next',
-        description: 'Get the next tasks that are ready to execute (dependencies satisfied). Use this to determine what to trigger next.',
+        description: 'Get the next tasks that are ready to execute (dependencies satisfied). Returns tasks with pre-assembled orchestraContext including upstream artifacts. Pass orchestraContext directly to aether_trigger_generation.',
         inputSchema: {
           type: 'object',
           properties: {
@@ -677,6 +681,10 @@ class MCPServer {
               type: 'number',
               description: 'Maximum number of ready tasks to return (default: 5)',
             },
+            createNodes: {
+              type: 'boolean',
+              description: 'Auto-create canvas nodes for ready tasks (default: true)',
+            },
           },
           required: ['sessionId'],
         },
@@ -797,6 +805,28 @@ class MCPServer {
           required: ['sessionId', 'completionReason'],
         },
       },
+      {
+        name: 'aether_orchestra_set_autonomous',
+        description: 'Enable or disable autonomous mode for an orchestra session. When enabled, a background worker automatically advances the session without manual intervention. CAUTION: The system will execute tasks until stopped or completion criteria are met.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            sessionId: {
+              type: 'string',
+              description: 'Orchestra session ID',
+            },
+            enabled: {
+              type: 'boolean',
+              description: 'Enable (true) or disable (false) autonomous mode',
+            },
+            maxConcurrent: {
+              type: 'number',
+              description: 'Maximum number of agents to run in parallel (default: 3)',
+            },
+          },
+          required: ['sessionId', 'enabled'],
+        },
+      },
     ];
   }
 
@@ -951,6 +981,9 @@ class MCPServer {
         case 'aether_complete_orchestra':
           result = await this.completeOrchestra(args);
           break;
+        case 'aether_orchestra_set_autonomous':
+          result = await this.orchestraSetAutonomous(args);
+          break;
         default:
           return this.errorResponse(id, -32602, `Unknown tool: ${name}`);
       }
@@ -1024,7 +1057,8 @@ class MCPServer {
     }
 
     try {
-      const data = await this.apiCall(`/workspaces/${config.workspaceSlug}/projects/${projectId}/canvas`);
+      // Use MCP endpoint which supports API key auth
+      const data = await this.mcpApiCall(`/mcp/projects/${projectId}/canvas`);
 
       // If summary mode, return only essential info (much smaller response)
       if (summary) {
@@ -1206,7 +1240,7 @@ class MCPServer {
   }
 
   async triggerGeneration(args) {
-    const { nodeId, context } = args;
+    const { nodeId, context, orchestraContext } = args;
     const projectId = config.projectId;
 
     if (!projectId) {
@@ -1225,6 +1259,8 @@ class MCPServer {
         {
           nodeId,
           context: context || undefined,
+          // Pass orchestraContext from orchestra_next (includes upstreamArtifacts)
+          orchestraContext: orchestraContext || undefined,
           previewLength: 500,
         }
       );
@@ -1272,7 +1308,8 @@ class MCPServer {
     }
 
     try {
-      const data = await this.apiCall(`/workspaces/${config.workspaceSlug}/projects/${projectId}/canvas`);
+      // Use MCP endpoint which supports API key auth
+      const data = await this.mcpApiCall(`/mcp/projects/${projectId}/canvas`);
       // Canvas API returns nodes directly - they have agentId, agentType, status, customConfig
       const nodes = data.nodes || [];
 
@@ -1990,7 +2027,7 @@ class MCPServer {
       return { error: 'No project ID configured. Set AETHER_PROJECT_ID environment variable.' };
     }
 
-    const { sessionId, maxTasks = 5 } = args;
+    const { sessionId, maxTasks = 5, createNodes = true } = args;
 
     if (!sessionId) {
       return { error: 'sessionId is required' };
@@ -2000,15 +2037,32 @@ class MCPServer {
       const data = await this.mcpApiCall(
         `/mcp/projects/${projectId}/orchestra/next`,
         'POST',
-        { sessionId, maxTasks }
+        { sessionId, maxTasks, createNodes }
       );
 
+      // Enhanced response with orchestraContext for each task
+      // Tasks now include pre-assembled context and are ready to trigger directly
+      const tasks = (data.tasks || []).map((t) => ({
+        id: t.id,
+        taskNumber: t.taskNumber,
+        title: t.title,
+        agentId: t.agentId,
+        nodeId: t.nodeId,
+        // Pre-assembled orchestraContext - pass this to aether_trigger_generation
+        orchestraContext: t.orchestraContext,
+        readyToTrigger: t.readyToTrigger,
+        resolvedArtifactCount: t.resolvedArtifactCount,
+      }));
+
       return {
-        readyTasks: data.tasks || [],
+        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.',
+        totalReady: data.totalReady || data.count || 0,
+        phase: data.phase,
+        hint: tasks.length > 0
+          ? 'Each task includes nodeId and orchestraContext. Call aether_trigger_generation(nodeId, orchestraContext) to execute.'
+          : data.message || 'No tasks ready. Check aether_orchestra_status for blockers or completion.',
+        sessionStatus: data.sessionStatus,
       };
     } catch (e) {
       return { error: e.message };
@@ -2201,6 +2255,45 @@ class MCPServer {
     }
   }
 
+  async orchestraSetAutonomous(args) {
+    const projectId = config.projectId;
+
+    if (!projectId) {
+      return { error: 'No project ID configured. Set AETHER_PROJECT_ID environment variable.' };
+    }
+
+    const { sessionId, enabled, maxConcurrent } = args;
+
+    if (!sessionId || enabled === undefined) {
+      return { error: 'sessionId and enabled are required' };
+    }
+
+    try {
+      const data = await this.mcpApiCall(
+        `/mcp/projects/${projectId}/orchestra`,
+        'POST',
+        {
+          action: 'set_autonomous',
+          sessionId,
+          enabled,
+          maxConcurrent: maxConcurrent || 3,
+        }
+      );
+
+      return {
+        success: true,
+        sessionId,
+        autoAdvance: data.autoAdvance,
+        maxConcurrentAgents: data.maxConcurrentAgents,
+        message: enabled
+          ? '⚠️ AUTONOMOUS MODE ENABLED: The system will automatically execute tasks every minute. Use aether_orchestra_status to monitor progress or aether_orchestra_set_autonomous(enabled: false) to stop.'
+          : 'Autonomous mode disabled. Use aether_orchestra_next and aether_trigger_generation for manual control.',
+      };
+    } catch (e) {
+      return { success: false, error: e.message };
+    }
+  }
+
   async run() {
     const rl = readline.createInterface({
       input: process.stdin,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aithr-ai/mcp-server",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "MCP server to connect Claude Code to Aether canvas - AI-powered team workspace for software development",
   "main": "index.js",
   "bin": {
@@ -20,20 +20,14 @@
     "orchestration",
     "anthropic"
   ],
+  "author": "Aether AI",
   "license": "MIT",
-  "engines": {
-    "node": ">=18.0.0"
-  },
   "repository": {
     "type": "git",
-    "url": "https://github.com/your-org/aether"
+    "url": "https://github.com/aithr-ai/mcp-server"
   },
   "homepage": "https://www.aithr.ai",
-  "bugs": {
-    "url": "https://github.com/your-org/aether/issues"
-  },
-  "files": [
-    "index.js",
-    "README.md"
-  ]
+  "engines": {
+    "node": ">=18.0.0"
+  }
 }