replicas-mcp 0.1.6 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "replicas-mcp",
-  "version": "0.1.6",
+  "version": "0.2.0",
   "license": "UNLICENSED",
   "type": "module",
   "main": "dist/index.js",

package/src/index.ts

@@ -2,7 +2,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
 import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
-import { parseAgentEvents, type AgentType, type ReadReplicaHistoryResponse } from '@replicas/shared';
+import { parseAgentEvents, type AgentProvider, type ReadReplicaHistoryResponse } from '@replicas/shared';
 
 const API_URL = process.env.REPLICAS_API_URL || 'https://api.replicas.dev';
 const API_KEY = process.env.REPLICAS_API_KEY;
@@ -57,11 +57,15 @@ type RegisterToolFn = (
 
 const server = new McpServer({
   name: 'replicas-mcp',
-  version: '0.1.1',
+  version: '0.2.0',
 });
 
 const registerTool = server.registerTool.bind(server) as RegisterToolFn;
 
+// ---------------------------------------------------------------------------
+// Replica CRUD
+// ---------------------------------------------------------------------------
+
 registerTool(
   'create_replica',
   {
@@ -69,8 +73,11 @@ registerTool(
     inputSchema: {
       name: z.string().regex(/^\S+$/, 'Name cannot contain spaces'),
       message: z.string(),
-      repository: z.string(),
-      coding_agent: z.enum(['claude', 'codex']).optional(),
+      repository_ids: z.array(z.string()).min(1).optional().describe('Repository IDs to include. Mutually exclusive with repository_set_id.'),
+      repository_set_id: z.string().optional().describe('Repository set ID to use. Mutually exclusive with repository_ids.'),
+      coding_agent: z.enum(['claude', 'codex']).optional().describe('Coding agent to use (default: claude)'),
+      model: z.string().optional().describe('Model to use for the coding agent'),
+      lifecycle_policy: z.enum(['default', 'delete_when_done', 'delete_after_inactivity']).optional().describe('Lifecycle policy for the workspace'),
     },
   },
   async (args) => {
@@ -78,9 +85,12 @@ registerTool(
       const body: Record<string, unknown> = {
         name: args.name,
         message: args.message,
-        repository: args.repository,
       };
+      if (args.repository_ids) body.repository_ids = args.repository_ids;
+      if (args.repository_set_id) body.repository_set_id = args.repository_set_id;
       if (args.coding_agent) body.coding_agent = args.coding_agent;
+      if (args.model) body.model = args.model;
+      if (args.lifecycle_policy) body.lifecycle_policy = args.lifecycle_policy;
       return result(await api('POST', '/v1/replica', body));
     } catch (e) {
       return result(e instanceof Error ? e.message : String(e), true);
@@ -91,10 +101,13 @@ registerTool(
 registerTool(
   'list_replicas',
   {
-    description: 'List all replicas',
+    description: 'List all replicas with pagination and optional filters',
     inputSchema: {
       page: z.number().optional(),
       limit: z.number().optional(),
+      user_id: z.string().optional().describe('Filter by creator user ID'),
+      source: z.enum(['api', 'dashboard', 'slack', 'linear', 'github', 'automation']).optional().describe('Filter by creation source'),
+      status: z.enum(['active', 'sleeping', 'preparing']).optional().describe('Filter by workspace status'),
     },
   },
   async (args) => {
@@ -102,6 +115,9 @@ registerTool(
       const params = new URLSearchParams();
       if (args.page) params.set('page', String(args.page));
       if (args.limit) params.set('limit', String(args.limit));
+      if (args.user_id) params.set('user_id', args.user_id as string);
+      if (args.source) params.set('source', args.source as string);
+      if (args.status) params.set('status', args.status as string);
       const q = params.toString();
       return result(await api('GET', `/v1/replica${q ? '?' + q : ''}`));
     } catch (e) {
@@ -113,14 +129,18 @@ registerTool(
 registerTool(
   'get_replica',
   {
-    description: 'Get replica by ID',
+    description: 'Get replica details by ID, including current status, chats, and repository statuses',
     inputSchema: {
       id: z.string(),
+      include: z.array(z.enum(['environment', 'diffs'])).optional().describe('Extra data to include in response'),
     },
   },
   async (args) => {
     try {
-      return result(await api('GET', `/v1/replica/${args.id}`));
+      const params = new URLSearchParams();
+      if (args.include) params.set('include', (args.include as string[]).join(','));
+      const q = params.toString();
+      return result(await api('GET', `/v1/replica/${args.id}${q ? '?' + q : ''}`));
     } catch (e) {
       return result(e instanceof Error ? e.message : String(e), true);
     }
@@ -130,18 +150,24 @@ registerTool(
 registerTool(
   'send_replica_message',
   {
-    description: 'Send message to a replica',
+    description: 'Send a message to an existing replica. Automatically handles waking sleeping replicas.',
     inputSchema: {
       id: z.string(),
       message: z.string(),
-      coding_agent: z.enum(['claude', 'codex']).optional(),
+      coding_agent: z.enum(['claude', 'codex']).optional().describe('Coding agent to use'),
+      chat_id: z.string().optional().describe('Chat ID to send the message to (uses default chat if omitted)'),
+      model: z.string().optional().describe('Model to use'),
+      plan_mode: z.boolean().optional().describe('Whether to use plan mode'),
     },
   },
   async (args) => {
     try {
       const body: Record<string, unknown> = { message: args.message };
       if (args.coding_agent) body.coding_agent = args.coding_agent;
-      return result(await api('POST', `/v1/replica/${args.id}/send`, body));
+      if (args.chat_id) body.chat_id = args.chat_id;
+      if (args.model) body.model = args.model;
+      if (args.plan_mode !== undefined) body.plan_mode = args.plan_mode;
+      return result(await api('POST', `/v1/replica/${args.id}/messages`, body));
     } catch (e) {
       return result(e instanceof Error ? e.message : String(e), true);
     }
@@ -151,7 +177,7 @@ registerTool(
 registerTool(
   'delete_replica',
   {
-    description: 'Delete a replica',
+    description: 'Delete a replica. This terminates the workspace and cannot be undone.',
     inputSchema: {
       id: z.string(),
     },
@@ -165,37 +191,117 @@ registerTool(
   }
 );
 
+// ---------------------------------------------------------------------------
+// Repositories & Repository Sets
+// ---------------------------------------------------------------------------
+
 registerTool(
   'list_repositories',
   {
-    description: 'List available repositories',
+    description: 'List available repositories that can be used when creating replicas',
+  },
+  async () => {
+    try {
+      return result(await api('GET', '/v1/replica/repositories'));
+    } catch (e) {
+      return result(e instanceof Error ? e.message : String(e), true);
+    }
+  }
+);
+
+registerTool(
+  'list_repository_sets',
+  {
+    description: 'List available repository sets (named groups of repositories)',
   },
   async () => {
     try {
-      return result(await api('GET', '/v1/repositories'));
+      return result(await api('GET', '/v1/replica/repository-sets'));
+    } catch (e) {
+      return result(e instanceof Error ? e.message : String(e), true);
+    }
+  }
+);
+
+// ---------------------------------------------------------------------------
+// Chat Management
+// ---------------------------------------------------------------------------
+
+registerTool(
+  'list_chats',
+  {
+    description: 'List chats in a replica workspace',
+    inputSchema: {
+      id: z.string().describe('Replica ID'),
+    },
+  },
+  async (args) => {
+    try {
+      return result(await api('GET', `/v1/replica/${args.id}/chats`));
+    } catch (e) {
+      return result(e instanceof Error ? e.message : String(e), true);
+    }
+  }
+);
+
+registerTool(
+  'create_chat',
+  {
+    description: 'Create a new chat in a replica workspace',
+    inputSchema: {
+      id: z.string().describe('Replica ID'),
+      provider: z.enum(['claude', 'codex']).describe('Coding agent provider for the chat'),
+      title: z.string().optional().describe('Optional title for the chat'),
+    },
+  },
+  async (args) => {
+    try {
+      const body: Record<string, unknown> = { provider: args.provider };
+      if (args.title) body.title = args.title;
+      return result(await api('POST', `/v1/replica/${args.id}/chats`, body));
     } catch (e) {
       return result(e instanceof Error ? e.message : String(e), true);
     }
   }
 );
 
+registerTool(
+  'delete_chat',
+  {
+    description: 'Delete a chat from a replica workspace',
+    inputSchema: {
+      id: z.string().describe('Replica ID'),
+      chat_id: z.string().describe('Chat ID to delete'),
+    },
+  },
+  async (args) => {
+    try {
+      return result(await api('DELETE', `/v1/replica/${args.id}/chats/${args.chat_id}`));
+    } catch (e) {
+      return result(e instanceof Error ? e.message : String(e), true);
+    }
+  }
+);
+
+// ---------------------------------------------------------------------------
+// History & Hooks
+// ---------------------------------------------------------------------------
+
 registerTool(
   'read_replica_history',
   {
     description: 'Read conversation history of a replica. Returns parsed DisplayMessage objects (user messages, agent responses, commands, file changes, tool calls, etc). If the workspace is sleeping, it will be woken and you should retry in 30-90 seconds.',
     inputSchema: {
       id: z.string(),
-      limit: z.number().optional().describe('Maximum number of events to return'),
-      offset: z.number().optional().describe('Number of events to skip from the end'),
+      chat_id: z.string().optional().describe('Read history for a specific chat (uses default chat if omitted)'),
     },
   },
   async (args) => {
     try {
       const params = new URLSearchParams();
-      if (args.limit) params.set('limit', String(args.limit));
-      if (args.offset) params.set('offset', String(args.offset));
+      if (args.chat_id) params.set('chat_id', args.chat_id as string);
       const q = params.toString();
-      const response = await api<ReadReplicaHistoryResponse>('GET', `/v1/replica/${args.id}/read${q ? '?' + q : ''}`);
+      const response = await api<ReadReplicaHistoryResponse>('GET', `/v1/replica/${args.id}/history${q ? '?' + q : ''}`);
 
       if (response.waking) {
         return result({
@@ -205,14 +311,14 @@ registerTool(
       }
 
       // Parse raw events into DisplayMessage format
-      const agentType = (response.coding_agent || 'claude') as AgentType;
+      const agentType = (response.coding_agent || 'claude') as AgentProvider;
       const messages = parseAgentEvents(response.events, agentType);
 
       return result({
         thread_id: response.thread_id,
         coding_agent: response.coding_agent,
         total: response.total,
-        hasMore: response.hasMore,
+        has_more: response.has_more,
         messages,
       });
     } catch (e) {
@@ -221,5 +327,22 @@ registerTool(
   }
 );
 
+registerTool(
+  'get_replica_hooks',
+  {
+    description: 'Get warm and start hook logs for a replica workspace',
+    inputSchema: {
+      id: z.string().describe('Replica ID'),
+    },
+  },
+  async (args) => {
+    try {
+      return result(await api('GET', `/v1/replica/${args.id}/hooks`));
+    } catch (e) {
+      return result(e instanceof Error ? e.message : String(e), true);
+    }
+  }
+);
+
 const transport = new StdioServerTransport();
 await server.connect(transport);