@prmichaelsen/task-mcp 0.2.0

package/agent/design/rest-api-integration.md

@@ -0,0 +1,489 @@
+# REST API Integration Design
+
+**Concept**: Deploy separate REST API service alongside MCP server, both accessing same Firestore
+**Created**: 2026-02-16
+**Updated**: 2026-02-16
+**Status**: Design Specification
+
+---
+
+## Overview
+
+This document specifies the architecture for deploying TWO separate Cloud Run services that share the same codebase and Firestore database:
+
+1. **task-mcp-mcp**: MCP protocol server (for AI agents)
+2. **task-mcp-api**: REST API server (for agentbase.me UI)
+
+Both services use the same FirebaseClient, TaskDatabaseService, and schemas, but have different entry points and protocols.
+
+**Core Principle**: Separate services, shared business logic. No code duplication.
+
+**Why Separate Services**:
+- mcp-auth only supports stdio transport currently
+- Different protocols (MCP vs REST)
+- Independent scaling and deployment
+- Clear separation of concerns
+
+---
+
+## Architecture Pattern
+
+### Two-Service Architecture
+
+```
+┌──────────────────────────────────────────────────────┐
+│                  agentbase.me                        │
+│                                                      │
+│  ┌──────────────┐         ┌──────────────┐         │
+│  │   Web UI     │         │  AI Agent    │         │
+│  └──────┬───────┘         └──────┬───────┘         │
+│         │                        │                  │
+│         │ HTTP REST              │ MCP Protocol     │
+└─────────┼────────────────────────┼──────────────────┘
+          │                        │
+          ▼                        ▼
+   ┌──────────────┐         ┌──────────────┐
+   │ task-mcp-api │         │ task-mcp-mcp │
+   │ (Cloud Run)  │         │ (Cloud Run)  │
+   │              │         │              │
+   │ Fastify      │         │ MCP SDK +    │
+   │ REST API     │         │ mcp-auth     │
+   └──────┬───────┘         └──────┬───────┘
+          │                        │
+          └────────┬───────────────┘
+                   │
+                   ▼
+    ┌──────────────────────────────────┐
+    │    Shared Business Logic         │
+    │  (same codebase, different entry)│
+    │                                  │
+    │  ┌────────────────────────────┐ │
+    │  │    FirebaseClient          │ │
+    │  │    TaskDatabaseService     │ │
+    │  │    Schemas                 │ │
+    │  │    Tool Handlers           │ │
+    │  └────────────────────────────┘ │
+    └──────────────────────────────────┘
+                   │
+                   ▼
+            ┌──────────────┐
+            │   Firestore  │
+            │ (Single DB)  │
+            └──────────────┘
+```
+
+### Key Design Decisions
+
+1. **Separate Services**: Two Cloud Run deployments (task-mcp-mcp + task-mcp-api)
+2. **Shared Codebase**: Same repo, different entry points (server.ts vs api.ts)
+3. **Shared Database**: Both services access same Firestore database
+4. **Shared Business Logic**: Both use FirebaseClient and TaskDatabaseService
+5. **Different Protocols**: MCP protocol for agents, REST for UI
+6. **User-Scoped**: All operations scoped to `userId` for multi-tenancy
+7. **No 1:1 Mapping**: REST endpoints NOT 1:1 mappings of MCP tools
+
+---
+
+## REST API Endpoints
+
+### Task Management
+
+**Base Path**: `/api/tasks`
+
+#### 1. List Tasks
+```
+GET /api/tasks
+Query Parameters:
+  - status?: 'not_started' | 'in_progress' | 'paused' | 'completed' | 'failed'
+  - limit?: number (default: 50)
+  - search?: string
+
+Response: Task[]
+```
+
+#### 2. Get Task
+```
+GET /api/tasks/:taskId
+
+Response: Task
+```
+
+#### 3. Create Task
+```
+POST /api/tasks
+Body: {
+  title: string
+  description: string
+  config?: Partial<TaskConfig>
+  metadata?: TaskMetadata
+}
+
+Response: Task
+```
+
+#### 4. Update Task Status
+```
+PATCH /api/tasks/:taskId/status
+Body: {
+  status: 'not_started' | 'in_progress' | 'paused' | 'completed' | 'failed'
+}
+
+Response: { success: boolean }
+```
+
+#### 5. Delete Task
+```
+DELETE /api/tasks/:taskId
+
+Response: { success: boolean }
+```
+
+### Progress Management
+
+#### 6. Update Progress
+```
+PATCH /api/tasks/:taskId/progress
+Body: {
+  percentage: number
+}
+
+Response: { success: boolean, progress: number }
+```
+
+#### 7. Get Task Messages
+```
+GET /api/tasks/:taskId/messages
+Query Parameters:
+  - limit?: number (default: 100)
+
+Response: TaskMessage[]
+```
+
+#### 8. Add Message
+```
+POST /api/tasks/:taskId/messages
+Body: {
+  role: 'user' | 'assistant' | 'system'
+  content: string
+  metadata?: any
+}
+
+Response: { message_id: string }
+```
+
+### Milestone Management
+
+#### 9. Create Milestone
+```
+POST /api/tasks/:taskId/milestones
+Body: {
+  milestone_id: string
+  name: string
+  description: string
+}
+
+Response: { success: boolean, milestone: Milestone }
+```
+
+#### 10. Update Milestone
+```
+PATCH /api/tasks/:taskId/milestones/:milestoneId
+Body: Partial<Milestone>
+
+Response: { success: boolean }
+```
+
+### Task Item Management
+
+#### 11. Create Task Item
+```
+POST /api/tasks/:taskId/milestones/:milestoneId/items
+Body: {
+  task_item_id: string
+  name: string
+  description: string
+  estimated_hours?: number
+}
+
+Response: { success: boolean, task_item: TaskItem }
+```
+
+#### 12. Complete Task Item
+```
+POST /api/tasks/:taskId/milestones/:milestoneId/items/:taskItemId/complete
+
+Response: {
+  success: boolean
+  milestone_progress: number
+  next_task: TaskItem | null
+}
+```
+
+---
+
+## Implementation Example
+
+### REST API Handler (agentbase.me)
+
+**Option 1: Using TaskDatabaseService (Recommended for REST API)**
+```typescript
+// In agentbase.me/src/routes/api/tasks/$taskId/index.tsx
+import { TaskDatabaseService } from 'task-mcp/services'
+import { getAuth } from '@/lib/auth/server-fn'
+
+export const Route = createAPIFileRoute('/api/tasks/$taskId')({
+  GET: async ({ request, params }) => {
+    try {
+      // Get authenticated user
+      const auth = await getAuth(request)
+      if (!auth) {
+        return new Response(JSON.stringify({ error: 'Unauthorized' }), {
+          status: 401,
+          headers: { 'Content-Type': 'application/json' }
+        })
+      }
+      
+      // Use TaskDatabaseService directly (simpler for REST)
+      const task = await TaskDatabaseService.getTask(auth.uid, params.taskId)
+      
+      if (!task) {
+        return new Response(JSON.stringify({ error: 'Task not found' }), {
+          status: 404,
+          headers: { 'Content-Type': 'application/json' }
+        })
+      }
+      
+      return new Response(JSON.stringify({ task }), {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' }
+      })
+    } catch (error) {
+      return new Response(JSON.stringify({
+        error: 'Internal server error',
+        message: error instanceof Error ? error.message : 'Unknown error'
+      }), {
+        status: 500,
+        headers: { 'Content-Type': 'application/json' }
+      })
+    }
+  }
+})
+```
+
+**Option 2: Using FirebaseClient (For Connection Management)**
+```typescript
+// In agentbase.me - Alternative approach with client wrapper
+import { FirebaseClient } from 'task-mcp/client'
+import { getAuth } from '@/lib/auth/server-fn'
+
+export const Route = createAPIFileRoute('/api/tasks/$taskId')({
+  GET: async ({ request, params }) => {
+    const auth = await getAuth(request)
+    if (!auth) {
+      return new Response(JSON.stringify({ error: 'Unauthorized' }), { status: 401 })
+    }
+    
+    // Create client instance (manages connection)
+    const client = new FirebaseClient({
+      userId: auth.uid,
+      serviceAccountPath: process.env.FIREBASE_SERVICE_ACCOUNT_PATH
+    })
+    
+    const task = await client.getTask(params.taskId)
+    
+    return new Response(JSON.stringify({ task }), { status: 200 })
+  }
+})
+```
+
+**Recommendation**: Use **TaskDatabaseService** directly in REST API handlers (Option 1) as it's simpler and matches agentbase.me's existing task documentation (Task 89).
+
+### MCP Tool Handler (task-mcp)
+
+```typescript
+// In task-mcp/src/tools/task-get-status.ts
+import { FirebaseClient } from '../client.js'
+
+export async function handleTaskGetStatus(
+  client: FirebaseClient,
+  args: { task_id: string }
+): Promise<string> {
+  // Uses same FirebaseClient as REST API
+  const task = await client.getTask(args.task_id)
+  
+  if (!task) {
+    throw new Error(`Task not found: ${args.task_id}`)
+  }
+  
+  // Returns instructions for agent (different from REST)
+  return JSON.stringify({
+    task_title: task.title,
+    status: task.status,
+    current_milestone: /* ... */,
+    instructions: /* ... */
+  }, null, 2)
+}
+```
+
+---
+
+## Key Differences: MCP Tools vs REST Endpoints
+
+### MCP Tools (Agent-Centric)
+- **Purpose**: Provide instructions and guidance for AI agents
+- **Response**: JSON with instructions, context, and next steps
+- **Example**: `task_get_next_step` returns "Continue work on: Task 1\n\nDescription: ..."
+- **Workflow**: Designed around agent decision-making
+
+### REST Endpoints (UI-Centric)
+- **Purpose**: Provide data for web UI rendering
+- **Response**: JSON with raw data
+- **Example**: `GET /api/tasks/:id` returns complete Task object
+- **Workflow**: Designed around CRUD operations
+
+---
+
+## Authentication & Authorization
+
+### REST API
+```typescript
+// In agentbase.me
+import { auth } from '@/lib/firebase-auth'
+
+export async function GET(request: NextRequest) {
+  // Verify Firebase Auth token
+  const token = request.headers.get('Authorization')?.replace('Bearer ', '')
+  const decodedToken = await auth.verifyIdToken(token)
+  const userId = decodedToken.uid
+  
+  // Use userId for scoped operations
+  const client = new FirebaseClient({ userId })
+  // ...
+}
+```
+
+### MCP Server
+```typescript
+// In task-mcp
+export function createServer(userId: string, options: ServerOptions) {
+  // userId passed from MCP client (agentbase.me)
+  const client = new FirebaseClient({ userId })
+  // All operations scoped to this user
+}
+```
+
+---
+
+## Security Considerations
+
+### Shared Security Model
+1. **User Isolation**: Both MCP and REST enforce user-scoped operations
+2. **Firestore Rules**: Security rules apply to both access paths
+3. **Service Account**: Same service account used by both
+4. **Rate Limiting**: Apply to both MCP and REST endpoints
+
+### REST-Specific Security
+```typescript
+// Rate limiting
+import { rateLimit } from '@/lib/rate-limit'
+
+export async function POST(request: NextRequest) {
+  const userId = await getUserIdFromRequest(request)
+  
+  // Rate limit per user
+  const { success } = await rateLimit.check(userId, 'tasks:create')
+  if (!success) {
+    return NextResponse.json(
+      { error: 'Rate limit exceeded' },
+      { status: 429 }
+    )
+  }
+  
+  // ... proceed with request
+}
+```
+
+---
+
+## Benefits of Dual Interface
+
+1. **Code Reuse**: Single business logic layer for both interfaces
+2. **Consistency**: Same data model and validation for MCP and REST
+3. **Flexibility**: UI can use REST, agents can use MCP
+4. **Maintainability**: Changes to business logic affect both interfaces
+5. **Testing**: Test business logic once, works for both interfaces
+
+---
+
+## Anti-Patterns to Avoid
+
+### ❌ 1:1 REST-to-MCP Mapping
+```typescript
+// WRONG - Just wrapping REST endpoints as MCP tools
+export const taskGetTool = {
+  name: 'task_get',
+  // ...
+}
+// This is just GET /api/tasks/:id as an MCP tool
+```
+
+### ❌ Calling MCP Tools from REST
+```typescript
+// WRONG - Bypassing MCP protocol
+import { handleTaskGetStatus } from 'task-mcp/tools'
+
+app.get('/api/tasks/:id/status', async (req, res) => {
+  const result = await handleTaskGetStatus(client, { task_id: req.params.id })
+  res.json(JSON.parse(result))
+})
+```
+
+### ✅ Correct Approach
+```typescript
+// CORRECT - Sharing business logic
+import { FirebaseClient } from 'task-mcp'
+
+app.get('/api/tasks/:id', async (req, res) => {
+  const client = new FirebaseClient({ userId: req.user.id })
+  const task = await client.getTask(req.params.id) // Shared logic
+  res.json(task)
+})
+```
+
+---
+
+## Implementation Phases
+
+### Phase 1: MCP Server (Current)
+- ✅ FirebaseClient and TaskDatabaseService
+- ✅ 8 MCP tools for agent workflows
+- 📋 MCP server with stdio transport
+
+### Phase 2: REST API (agentbase.me)
+- 📋 REST endpoints using FirebaseClient
+- 📋 Authentication middleware
+- 📋 Rate limiting
+- 📋 OpenAPI documentation
+
+### Phase 3: Integration
+- 📋 Deploy both MCP server and REST API
+- 📋 Test dual interface
+- 📋 Monitor performance
+
+---
+
+## Success Criteria
+
+- [ ] REST endpoints use FirebaseClient (shared logic)
+- [ ] No code duplication between MCP and REST
+- [ ] User isolation enforced in both interfaces
+- [ ] REST endpoints documented with OpenAPI
+- [ ] Integration tests for both interfaces
+- [ ] Performance metrics for both paths
+
+---
+
+**Status**: Design Specification
+**Next Action**: Implement REST endpoints in agentbase.me after MCP server is complete
+**Owner**: Development Team
+**Created**: 2026-02-16