@prmichaelsen/task-mcp 0.2.0

package/src/schemas/task.ts

@@ -0,0 +1,154 @@
+/**
+ * Task Data Model and Schemas
+ * 
+ * Zod schemas and TypeScript interfaces for the task execution system.
+ * These schemas define the structure of Task documents in Firestore.
+ */
+
+import { z } from 'zod'
+
+/**
+ * Milestone Schema
+ * Represents a major phase in task execution with multiple sub-tasks
+ */
+export const MilestoneSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  description: z.string(),
+  status: z.enum(['not_started', 'in_progress', 'completed']),
+  progress: z.number().min(0).max(100),
+  tasks_completed: z.number().min(0),
+  tasks_total: z.number().min(0),
+  started_at: z.string().optional(),
+  completed_at: z.string().optional()
+})
+
+/**
+ * Task Item Schema
+ * Represents a granular work item within a milestone
+ */
+export const TaskItemSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  description: z.string(),
+  status: z.enum(['not_started', 'in_progress', 'completed']),
+  estimated_hours: z.number().optional(),
+  completed_at: z.string().optional(),
+  notes: z.string().optional()
+})
+
+/**
+ * Task Progress Schema
+ * Tracks overall progress and milestone/task completion
+ */
+export const TaskProgressSchema = z.object({
+  current_milestone: z.string(),
+  current_task: z.string(),
+  overall_percentage: z.number().min(0).max(100),
+  milestones: z.array(MilestoneSchema),
+  tasks: z.record(z.string(), z.array(TaskItemSchema))
+})
+
+/**
+ * Task Execution Schema
+ * Stores execution state including messages and tool results
+ */
+export const TaskExecutionSchema = z.object({
+  api_messages: z.array(z.any()),
+  task_messages: z.array(z.any()),
+  tool_results: z.array(z.any()),
+  error: z.string().optional(),
+  abort_reason: z.string().optional()
+})
+
+/**
+ * Task Configuration Schema
+ * Configuration for task execution behavior
+ * Note: Model is configured globally by the tenant platform, not per-task
+ */
+export const TaskConfigSchema = z.object({
+  system_prompt: z.string(),
+  auto_approve: z.boolean(),
+  max_iterations: z.number().optional()
+})
+
+/**
+ * Task Metadata Schema
+ * Optional metadata for task organization and tracking
+ */
+export const TaskMetadataSchema = z.object({
+  conversation_id: z.string().optional(),
+  parent_task_id: z.string().optional(),
+  tags: z.array(z.string()).optional()
+}).optional()
+
+/**
+ * Task Schema
+ * Complete task document structure
+ */
+export const TaskSchema = z.object({
+  id: z.string(),
+  user_id: z.string(),
+  title: z.string(),
+  description: z.string(),
+  status: z.enum(['not_started', 'in_progress', 'paused', 'completed', 'failed']),
+  created_at: z.string(),
+  updated_at: z.string(),
+  started_at: z.string().optional(),
+  completed_at: z.string().optional(),
+  
+  progress: TaskProgressSchema,
+  execution: TaskExecutionSchema,
+  config: TaskConfigSchema,
+  metadata: TaskMetadataSchema
+})
+
+/**
+ * Task Message Schema
+ * Messages in the task conversation thread
+ */
+export const TaskMessageSchema = z.object({
+  id: z.string(),
+  task_id: z.string(),
+  role: z.enum(['user', 'assistant', 'system']),
+  content: z.string(),
+  timestamp: z.string(),
+  metadata: z.any().optional()
+})
+
+// Export TypeScript types inferred from Zod schemas
+export type Milestone = z.infer<typeof MilestoneSchema>
+export type TaskItem = z.infer<typeof TaskItemSchema>
+export type TaskProgress = z.infer<typeof TaskProgressSchema>
+export type TaskExecution = z.infer<typeof TaskExecutionSchema>
+export type TaskConfig = z.infer<typeof TaskConfigSchema>
+export type TaskMetadata = z.infer<typeof TaskMetadataSchema>
+export type Task = z.infer<typeof TaskSchema>
+export type TaskMessage = z.infer<typeof TaskMessageSchema>
+
+// Export status enums for convenience
+export const TaskStatus = {
+  NOT_STARTED: 'not_started',
+  IN_PROGRESS: 'in_progress',
+  PAUSED: 'paused',
+  COMPLETED: 'completed',
+  FAILED: 'failed'
+} as const
+
+export const MilestoneStatus = {
+  NOT_STARTED: 'not_started',
+  IN_PROGRESS: 'in_progress',
+  COMPLETED: 'completed'
+} as const
+
+export const TaskItemStatus = {
+  NOT_STARTED: 'not_started',
+  IN_PROGRESS: 'in_progress',
+  COMPLETED: 'completed'
+} as const
+
+export const MessageRole = {
+  USER: 'user',
+  ASSISTANT: 'assistant',
+  SYSTEM: 'system'
+} as const

package/src/server-factory.spec.ts

@@ -0,0 +1,70 @@
+/**
+ * Server Factory Tests
+ */
+
+import { createServer } from './server-factory.js'
+import { FirebaseClient } from './client.js'
+
+// Mock FirebaseClient
+jest.mock('./client.js', () => ({
+  FirebaseClient: jest.fn().mockImplementation(() => ({
+    connect: jest.fn().mockResolvedValue(undefined),
+    disconnect: jest.fn().mockResolvedValue(undefined)
+  }))
+}))
+
+describe('Server Factory', () => {
+  describe('Parameter Validation', () => {
+    it('should create server instance with valid userId', async () => {
+      const server = await createServer('test-token', 'test-user-123')
+      expect(server).toBeDefined()
+      expect(server).toHaveProperty('connect')
+      expect(server).toHaveProperty('setRequestHandler')
+    })
+    
+    it('should throw error if userId is empty', async () => {
+      await expect(createServer('test-token', '')).rejects.toThrow('userId is required')
+    })
+    
+    it('should accept custom options', async () => {
+      const server = await createServer('test-token', 'test-user-123', {
+        name: 'custom-task-mcp',
+        version: '1.0.0'
+      })
+      expect(server).toBeDefined()
+    })
+  })
+  
+  describe('Server Isolation', () => {
+    it('should create separate instances for different users', async () => {
+      const server1 = await createServer('test-token', 'user-1')
+      const server2 = await createServer('test-token', 'user-2')
+      
+      expect(server1).not.toBe(server2)
+    })
+    
+    it('should scope operations to userId', async () => {
+      const server = await createServer('test-token', 'test-user-123')
+      
+      // Server should be isolated to this user
+      expect(server).toBeDefined()
+    })
+  })
+  
+  describe('Options', () => {
+    it('should use default name if not provided', async () => {
+      const server = await createServer('test-token', 'test-user-123')
+      expect(server).toBeDefined()
+    })
+    
+    it('should use custom name if provided', async () => {
+      const server = await createServer('test-token', 'test-user-123', { name: 'custom-name' })
+      expect(server).toBeDefined()
+    })
+    
+    it('should use custom version if provided', async () => {
+      const server = await createServer('test-token', 'test-user-123', { version: '2.0.0' })
+      expect(server).toBeDefined()
+    })
+  })
+})

package/src/server-factory.ts

@@ -0,0 +1,111 @@
+/**
+ * MCP Server Factory
+ * 
+ * Creates isolated MCP server instances for multi-tenant usage.
+ * Each server instance is scoped to a specific userId.
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js'
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  ErrorCode,
+  McpError
+} from '@modelcontextprotocol/sdk/types.js'
+import { FirebaseClient } from './client.js'
+import { allTools, getToolHandler } from './tools/index.js'
+
+/**
+ * Server configuration options
+ */
+export interface ServerOptions {
+  name?: string
+  version?: string
+}
+
+/**
+ * Create an MCP server instance for a specific user
+ *
+ * This function is compatible with mcp-auth wrapper which calls it with:
+ * createServer(accessToken, userId)
+ *
+ * @param accessToken - Access token (not used by task-mcp, but required by mcp-auth)
+ * @param userId - User ID to scope operations to
+ * @param options - Optional server configuration
+ * @returns Configured MCP Server instance
+ */
+export async function createServer(
+  accessToken: string,
+  userId: string,
+  options: ServerOptions = {}
+): Promise<Server> {
+  if (!userId) {
+    throw new Error('userId is required')
+  }
+  
+  // Initialize Firebase client for this user
+  const client = new FirebaseClient({ userId })
+  await client.connect()
+  
+  // Create MCP server
+  const server = new Server(
+    {
+      name: options.name || 'task-mcp',
+      version: options.version || '0.1.0'
+    },
+    {
+      capabilities: {
+        tools: {}
+      }
+    }
+  )
+  
+  // Register list_tools handler
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+      tools: allTools
+    }
+  })
+  
+  // Register call_tool handler
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params
+    
+    try {
+      // Get handler for this tool
+      const handler = getToolHandler(name)
+      
+      if (!handler) {
+        throw new McpError(
+          ErrorCode.MethodNotFound,
+          `Unknown tool: ${name}`
+        )
+      }
+      
+      // Execute tool handler
+      const result = await handler(client, args as any || {})
+      
+      return {
+        content: [
+          {
+            type: 'text',
+            text: result
+          }
+        ]
+      }
+    } catch (error) {
+      // Re-throw MCP errors as-is
+      if (error instanceof McpError) {
+        throw error
+      }
+      
+      // Wrap other errors in MCP error
+      throw new McpError(
+        ErrorCode.InternalError,
+        `Tool execution failed: ${error instanceof Error ? error.message : String(error)}`
+      )
+    }
+  })
+  
+  return server
+}

package/src/server.ts

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+
+/**
+ * MCP Server - Standalone Entry Point
+ * 
+ * Starts an MCP server with stdio transport for a single user.
+ * This is the main entry point for running task-mcp as a standalone server.
+ */
+
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { createServer } from './server-factory.js'
+
+/**
+ * Initialize and start the MCP server
+ */
+async function main(): Promise<void> {
+  // Get userId from environment variable (set by mcp-auth wrapper)
+  const userId = process.env.TASK_MCP_USER_ID
+  
+  if (!userId) {
+    console.error('Error: TASK_MCP_USER_ID environment variable is required')
+    console.error('This server should be run through mcp-auth wrapper')
+    process.exit(1)
+  }
+  
+  try {
+    // Create server instance
+    // Note: accessToken is not used by task-mcp but required by mcp-auth signature
+    const server = await createServer('', userId, {
+      name: 'task-mcp',
+      version: '0.1.0'
+    })
+    
+    // Create stdio transport
+    const transport = new StdioServerTransport()
+    
+    // Connect server to transport
+    await server.connect(transport)
+    
+    // Log startup (to stderr to not interfere with stdio protocol)
+    console.error(`task-mcp server started for user: ${userId}`)
+  } catch (error) {
+    console.error('Failed to start server:', error)
+    process.exit(1)
+  }
+}
+
+/**
+ * Setup graceful shutdown handlers
+ */
+function setupShutdownHandlers(): void {
+  const shutdown = async (signal: string) => {
+    console.error(`\nReceived ${signal}, shutting down gracefully...`)
+    process.exit(0)
+  }
+  
+  process.on('SIGINT', () => shutdown('SIGINT'))
+  process.on('SIGTERM', () => shutdown('SIGTERM'))
+}
+
+// Setup shutdown handlers
+setupShutdownHandlers()
+
+// Start server
+main().catch((error) => {
+  console.error('Fatal error:', error)
+  process.exit(1)
+})

package/src/services/task-database.service.e2e.ts

@@ -0,0 +1,116 @@
+/**
+ * E2E Tests for TaskDatabaseService
+ * 
+ * Tests with real Firestore emulator for integration testing.
+ * 
+ * To run these tests:
+ * 1. Start Firestore emulator: firebase emulators:start --only firestore
+ * 2. Run tests: npm run test:e2e
+ */
+
+import { describe, it, expect, beforeAll, afterAll } from '@jest/globals'
+import { initializeApp, cert, deleteApp } from 'firebase-admin/app'
+import { getFirestore } from 'firebase-admin/firestore'
+import { TaskDatabaseService } from '../../src/services/task-database.service.js'
+import type { Task } from '../../src/schemas/task.js'
+
+describe('TaskDatabaseService E2E', () => {
+  let app: any
+
+  beforeAll(async () => {
+    // Initialize Firebase Admin with emulator
+    process.env.FIRESTORE_EMULATOR_HOST = 'localhost:8080'
+    
+    app = initializeApp({
+      projectId: 'test-project'
+    }, 'task-mcp-e2e-test')
+    
+    const db = getFirestore(app)
+    TaskDatabaseService.initialize(db)
+  })
+
+  afterAll(async () => {
+    if (app) {
+      await deleteApp(app)
+    }
+  })
+
+  describe('Full Task Lifecycle', () => {
+    it('should create, read, update, and delete a task', async () => {
+      const userId = 'test-user-' + Date.now()
+      
+      // Create
+      const task = await TaskDatabaseService.createTask(
+        userId,
+        'E2E Test Task',
+        'Testing full lifecycle'
+      )
+      
+      expect(task.id).toBeDefined()
+      expect(task.title).toBe('E2E Test Task')
+      
+      // Read
+      const retrieved = await TaskDatabaseService.getTask(userId, task.id)
+      expect(retrieved).not.toBeNull()
+      expect(retrieved?.title).toBe('E2E Test Task')
+      
+      // Update status
+      await TaskDatabaseService.updateTaskStatus(userId, task.id, 'in_progress')
+      const updated = await TaskDatabaseService.getTask(userId, task.id)
+      expect(updated?.status).toBe('in_progress')
+      expect(updated?.started_at).toBeDefined()
+      
+      // Delete
+      await TaskDatabaseService.deleteTask(userId, task.id)
+      const deleted = await TaskDatabaseService.getTask(userId, task.id)
+      expect(deleted).toBeNull()
+    })
+
+    it('should handle task messages', async () => {
+      const userId = 'test-user-' + Date.now()
+      
+      const task = await TaskDatabaseService.createTask(
+        userId,
+        'Message Test',
+        'Testing messages'
+      )
+      
+      // Add messages
+      const msg1 = await TaskDatabaseService.addMessage(userId, task.id, 'user', 'Hello')
+      const msg2 = await TaskDatabaseService.addMessage(userId, task.id, 'assistant', 'Hi there')
+      
+      expect(msg1).toBeDefined()
+      expect(msg2).toBeDefined()
+      
+      // Get messages
+      const messages = await TaskDatabaseService.getMessages(userId, task.id)
+      expect(messages).toHaveLength(2)
+      expect(messages[0].role).toBe('user')
+      expect(messages[1].role).toBe('assistant')
+      
+      // Cleanup
+      await TaskDatabaseService.deleteTask(userId, task.id)
+    })
+  })
+
+  describe('Query Operations', () => {
+    it('should filter tasks by status', async () => {
+      const userId = 'test-user-' + Date.now()
+      
+      // Create tasks with different statuses
+      const task1 = await TaskDatabaseService.createTask(userId, 'Task 1', 'Active')
+      await TaskDatabaseService.updateTaskStatus(userId, task1.id, 'in_progress')
+      
+      const task2 = await TaskDatabaseService.createTask(userId, 'Task 2', 'Pending')
+      
+      // Query active tasks
+      const activeTasks = await TaskDatabaseService.getActiveTasks(userId)
+      expect(activeTasks.length).toBeGreaterThanOrEqual(1)
+      expect(activeTasks.some(t => t.id === task1.id)).toBe(true)
+      
+      // Cleanup
+      await TaskDatabaseService.deleteTask(userId, task1.id)
+      await TaskDatabaseService.deleteTask(userId, task2.id)
+    })
+  })
+})