@prmichaelsen/task-mcp 0.2.0

package/agent/design/sdk-export-requirements.md

@@ -0,0 +1,549 @@
+# task-mcp SDK Requirements for agentbase.me Integration
+
+**Concept**: Requirements for task-mcp to export TypeScript types and REST API SDK for consumption by agentbase.me
+**Created**: 2026-02-16
+**Status**: Design Specification
+**Audience**: task-mcp development team
+
+---
+
+## Overview
+
+For agentbase.me to integrate with task-mcp without duplicating code, task-mcp must export:
+1. **TypeScript types** - Shared type definitions for tasks, milestones, and task items
+2. **REST API SDK** - Client library for calling task-mcp REST endpoints
+3. **MCP tools** - Already implemented for agent use
+
+This document specifies what agentbase.me expects from the task-mcp npm package.
+
+---
+
+## Package Structure
+
+```
+task-mcp/
+├── package.json
+├── src/
+│   ├── index.ts                    # Main exports
+│   ├── types/                      # TypeScript types (exported)
+│   │   ├── index.ts
+│   │   ├── task.ts
+│   │   ├── milestone.ts
+│   │   └── task-item.ts
+│   │
+│   ├── sdk/                        # REST API SDK (exported)
+│   │   ├── index.ts
+│   │   ├── client.ts
+│   │   ├── tasks.ts
+│   │   ├── milestones.ts
+│   │   └── progress.ts
+│   │
+│   ├── tools/                      # MCP tools (not exported)
+│   │   └── ...
+│   │
+│   └── server/                     # MCP server (not exported)
+│       └── ...
+│
+└── dist/                           # Built package
+    ├── index.js
+    ├── index.d.ts
+    ├── types/
+    └── sdk/
+```
+
+---
+
+## 1. TypeScript Types Export
+
+### What to Export
+
+Export all TypeScript types from Zod schemas:
+
+```typescript
+// task-mcp/src/types/index.ts
+export * from './task'
+export * from './milestone'
+export * from './task-item'
+
+// task-mcp/src/types/task.ts
+import { z } from 'zod'
+
+// Zod schemas
+export const TaskStatusSchema = z.enum([
+  'not_started',
+  'in_progress',
+  'paused',
+  'completed',
+  'failed'
+])
+
+export const TaskSchema = z.object({
+  id: z.string(),
+  user_id: z.string(),
+  title: z.string().min(1).max(200),
+  description: z.string().min(1).max(5000),
+  status: TaskStatusSchema,
+  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
+})
+
+// TypeScript types
+export type TaskStatus = z.infer<typeof TaskStatusSchema>
+export type Task = z.infer<typeof TaskSchema>
+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>
+
+// Helper functions
+export function createTaskTemplate(
+  userId: string,
+  title: string,
+  description: string,
+  config?: Partial<TaskConfig>
+): Omit<Task, 'id'>
+
+export function validateTask(data: unknown): 
+  | { success: true; data: Task }
+  | { success: false; error: z.ZodError }
+```
+
+### Usage in agentbase.me
+
+```typescript
+// In agentbase.me
+import { Task, Milestone, TaskItem, createTaskTemplate } from 'task-mcp'
+
+// Use types
+const task: Task = {
+  id: 'task_123',
+  user_id: 'user_456',
+  // ...
+}
+
+// Use helpers
+const template = createTaskTemplate('user_456', 'My Task', 'Description')
+```
+
+---
+
+## 2. REST API SDK Export
+
+### SDK Client Interface
+
+```typescript
+// task-mcp/src/sdk/client.ts
+export interface TaskMCPClientConfig {
+  endpoint: string          // https://task-mcp.agentbase.me
+  serviceToken: string      // Authentication token
+  timeout?: number          // Request timeout (default: 30000ms)
+}
+
+export class TaskMCPClient {
+  constructor(config: TaskMCPClientConfig)
+  
+  // Task operations
+  tasks: TasksAPI
+  
+  // Milestone operations
+  milestones: MilestonesAPI
+  
+  // Progress operations
+  progress: ProgressAPI
+}
+```
+
+### Tasks API
+
+```typescript
+// task-mcp/src/sdk/tasks.ts
+export interface TasksAPI {
+  // List user's tasks
+  list(userId: string, options?: {
+    status?: TaskStatus
+    limit?: number
+    offset?: number
+  }): Promise<Task[]>
+  
+  // Get single task
+  get(userId: string, taskId: string): Promise<Task | null>
+  
+  // Create task
+  create(userId: string, data: Omit<Task, 'id' | 'created_at' | 'updated_at'>): Promise<Task>
+  
+  // Update task
+  update(userId: string, taskId: string, data: Partial<Task>): Promise<Task>
+  
+  // Delete task
+  delete(userId: string, taskId: string): Promise<void>
+  
+  // Get task messages
+  getMessages(userId: string, taskId: string, options?: {
+    limit?: number
+    startAfter?: string
+  }): Promise<TaskMessage[]>
+}
+```
+
+### Milestones API
+
+```typescript
+// task-mcp/src/sdk/milestones.ts
+export interface MilestonesAPI {
+  // List milestones for a task
+  list(userId: string, taskId: string): Promise<Milestone[]>
+  
+  // Get single milestone
+  get(userId: string, taskId: string, milestoneId: string): Promise<Milestone | null>
+  
+  // Create milestone
+  create(userId: string, taskId: string, data: Omit<Milestone, 'id'>): Promise<Milestone>
+  
+  // Update milestone
+  update(userId: string, taskId: string, milestoneId: string, data: Partial<Milestone>): Promise<Milestone>
+  
+  // Complete milestone
+  complete(userId: string, taskId: string, milestoneId: string): Promise<Milestone>
+}
+```
+
+### Progress API
+
+```typescript
+// task-mcp/src/sdk/progress.ts
+export interface ProgressAPI {
+  // Get task progress
+  get(userId: string, taskId: string): Promise<TaskProgress>
+  
+  // Update progress
+  update(userId: string, taskId: string, progress: Partial<TaskProgress>): Promise<TaskProgress>
+  
+  // Complete task item
+  completeTaskItem(userId: string, taskId: string, milestoneId: string, taskItemId: string): Promise<void>
+}
+```
+
+### Usage in agentbase.me
+
+```typescript
+// In agentbase.me
+import { TaskMCPClient } from 'task-mcp/sdk'
+import { MCPServerDatabaseService } from '@/services/mcp-server-database.service'
+
+// Get credentials from MCP integrations service (not env vars)
+const server = await MCPServerDatabaseService.getServerById('task-mcp')
+if (!server) {
+  throw new Error('task-mcp server not registered')
+}
+
+const client = new TaskMCPClient({
+  endpoint: server.endpoint,
+  serviceToken: server.service_token
+})
+
+// List tasks
+const tasks = await client.tasks.list('user_123', {
+  status: 'in_progress',
+  limit: 10
+})
+
+// Create task
+const newTask = await client.tasks.create('user_123', {
+  title: 'My Task',
+  description: 'Task description',
+  status: 'not_started',
+  // ...
+})
+
+// Get progress
+const progress = await client.progress.get('user_123', 'task_456')
+```
+
+**Note**: Credentials retrieved from MCP integrations service (Firestore `mcp_servers` collection), following the same pattern as other MCP servers.
+
+---
+
+## 3. Package Configuration
+
+### package.json
+
+```json
+{
+  "name": "task-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for autonomous task execution with SDK",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./types": {
+      "import": "./dist/types/index.js",
+      "types": "./dist/types/index.d.ts"
+    },
+    "./sdk": {
+      "import": "./dist/sdk/index.js",
+      "types": "./dist/sdk/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "zod": "^4.3.6"
+  },
+  "peerDependencies": {
+    "zod": "^4.0.0"
+  }
+}
+```
+
+### Main Export
+
+```typescript
+// task-mcp/src/index.ts
+// Export types
+export * from './types'
+
+// Export SDK
+export * from './sdk'
+
+// Do NOT export server or tools (internal only)
+```
+
+---
+
+## 4. REST API Endpoints (task-mcp Server)
+
+The SDK calls these REST endpoints on the task-mcp server:
+
+### Task Endpoints
+
+```
+GET    /api/tasks?user_id={userId}&status={status}&limit={limit}&offset={offset}
+POST   /api/tasks
+GET    /api/tasks/{taskId}?user_id={userId}
+PATCH  /api/tasks/{taskId}?user_id={userId}
+DELETE /api/tasks/{taskId}?user_id={userId}
+GET    /api/tasks/{taskId}/messages?user_id={userId}&limit={limit}&startAfter={cursor}
+```
+
+### Milestone Endpoints
+
+```
+GET    /api/tasks/{taskId}/milestones?user_id={userId}
+POST   /api/tasks/{taskId}/milestones?user_id={userId}
+GET    /api/tasks/{taskId}/milestones/{milestoneId}?user_id={userId}
+PATCH  /api/tasks/{taskId}/milestones/{milestoneId}?user_id={userId}
+POST   /api/tasks/{taskId}/milestones/{milestoneId}/complete?user_id={userId}
+```
+
+### Progress Endpoints
+
+```
+GET    /api/tasks/{taskId}/progress?user_id={userId}
+PATCH  /api/tasks/{taskId}/progress?user_id={userId}
+POST   /api/tasks/{taskId}/progress/complete-item?user_id={userId}
+```
+
+### Authentication
+
+All endpoints require authentication via service token:
+
+```
+Authorization: Bearer {serviceToken}
+X-User-ID: {userId}
+```
+
+---
+
+## 5. Error Handling
+
+### SDK Error Types
+
+```typescript
+// task-mcp/src/sdk/errors.ts
+export class TaskMCPError extends Error {
+  constructor(
+    message: string,
+    public statusCode: number,
+    public code: string
+  ) {
+    super(message)
+    this.name = 'TaskMCPError'
+  }
+}
+
+export class TaskNotFoundError extends TaskMCPError {
+  constructor(taskId: string) {
+    super(`Task not found: ${taskId}`, 404, 'TASK_NOT_FOUND')
+  }
+}
+
+export class UnauthorizedError extends TaskMCPError {
+  constructor() {
+    super('Unauthorized', 401, 'UNAUTHORIZED')
+  }
+}
+
+export class ValidationError extends TaskMCPError {
+  constructor(message: string) {
+    super(message, 400, 'VALIDATION_ERROR')
+  }
+}
+```
+
+### Usage in agentbase.me
+
+```typescript
+import { TaskMCPClient, TaskNotFoundError } from 'task-mcp/sdk'
+
+try {
+  const task = await client.tasks.get('user_123', 'task_456')
+} catch (error) {
+  if (error instanceof TaskNotFoundError) {
+    // Handle not found
+  } else {
+    // Handle other errors
+  }
+}
+```
+
+---
+
+## 6. Installation in agentbase.me
+
+### Install Package
+
+```bash
+npm install task-mcp
+```
+
+### Configure Client
+
+```typescript
+// agentbase.me/src/lib/task-mcp-client.ts
+import { TaskMCPClient } from 'task-mcp/sdk'
+
+export const taskMCPClient = new TaskMCPClient({
+  endpoint: process.env.TASK_MCP_ENDPOINT!,
+  serviceToken: process.env.TASK_MCP_SERVICE_TOKEN!,
+  timeout: 30000
+})
+```
+
+### Use in Components
+
+```typescript
+// agentbase.me/src/components/TaskList.tsx
+import { Task } from 'task-mcp'
+import { taskMCPClient } from '@/lib/task-mcp-client'
+
+export function TaskList({ userId }: { userId: string }) {
+  const [tasks, setTasks] = useState<Task[]>([])
+  
+  useEffect(() => {
+    taskMCPClient.tasks.list(userId, { status: 'in_progress' })
+      .then(setTasks)
+  }, [userId])
+  
+  return (
+    <div>
+      {tasks.map(task => (
+        <TaskCard key={task.id} task={task} />
+      ))}
+    </div>
+  )
+}
+```
+
+---
+
+## 7. Deliverables Checklist
+
+For task-mcp to be consumable by agentbase.me:
+
+- [ ] Export TypeScript types from Zod schemas
+- [ ] Export helper functions (createTaskTemplate, validateTask, etc.)
+- [ ] Implement TaskMCPClient class
+- [ ] Implement TasksAPI with all methods
+- [ ] Implement MilestonesAPI with all methods
+- [ ] Implement ProgressAPI with all methods
+- [ ] Implement error classes
+- [ ] Create REST API endpoints on task-mcp server
+- [ ] Add authentication middleware (service token + user_id)
+- [ ] Build and publish npm package
+- [ ] Generate TypeScript declaration files (.d.ts)
+- [ ] Document SDK usage in README
+
+---
+
+## 8. Testing
+
+### Unit Tests (task-mcp)
+
+```typescript
+// task-mcp/src/sdk/client.spec.ts
+describe('TaskMCPClient', () => {
+  it('should list tasks', async () => {
+    const client = new TaskMCPClient({ endpoint, serviceToken })
+    const tasks = await client.tasks.list('user_123')
+    expect(tasks).toBeInstanceOf(Array)
+  })
+})
+```
+
+### Integration Tests (agentbase.me)
+
+```typescript
+// agentbase.me/src/lib/task-mcp-client.spec.ts
+import { taskMCPClient } from './task-mcp-client'
+
+describe('task-mcp integration', () => {
+  it('should create and retrieve task', async () => {
+    const created = await taskMCPClient.tasks.create('user_123', {
+      title: 'Test Task',
+      description: 'Test',
+      // ...
+    })
+    
+    const retrieved = await taskMCPClient.tasks.get('user_123', created.id)
+    expect(retrieved).toEqual(created)
+  })
+})
+```
+
+---
+
+## Summary
+
+For agentbase.me to successfully integrate with task-mcp:
+
+1. **task-mcp exports types** - No duplication of schemas
+2. **task-mcp exports SDK** - Clean REST API client
+3. **task-mcp provides REST endpoints** - SDK calls these
+4. **agentbase.me imports and uses** - No direct Firestore access
+
+This creates a clean separation:
+- **task-mcp**: Data layer + MCP tools + REST API + SDK
+- **agentbase.me**: UI layer + Agent orchestration + SDK consumer
+
+---
+
+**Status**: Design Specification
+**Next Action**: Implement SDK in task-mcp
+**Owner**: task-mcp development team
+**Consumer**: agentbase.me