@hailer/mcp 0.0.1

package/.claude/skills/mcp-tools/references/implementation-patterns.md

@@ -0,0 +1,717 @@
+# Implementation Patterns
+
+Step-by-step guides for common MCP tool development tasks.
+
+---
+
+## Pattern 1: Adding a New API Endpoint
+
+Follow this pattern when you need to call a new Hailer API endpoint.
+
+### Step 1: Add Function to `hailer-api.ts`
+
+```typescript
+// server/src/lib/hailer-api.ts
+
+export async function myNewEndpoint(
+  client: HailerClient,
+  arg1: string,
+  options: MyOptions = {}
+): Promise<MyResponse> {
+  const { option1, option2 = 'default' } = options;
+
+  const response = await fetch(
+    `${client.baseUrl}/v3/my/endpoint`,
+    {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'hlrkey': client.authToken
+      },
+      body: JSON.stringify([arg1, { option1, option2 }])
+    }
+  );
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    throw new Error(`API error (${response.status}): ${errorText}`);
+  }
+
+  return response.json();
+}
+```
+
+**Key Points**:
+- Always use JSON array format: `[arg1, arg2, ...]`
+- Include `hlrkey` header with auth token
+- Check `response.ok` before parsing JSON
+- Provide helpful error messages with status code
+
+### Step 2: Test the Endpoint
+
+Before building MCP tool, test the API function directly:
+
+```typescript
+// In a test file or debug route
+const result = await myNewEndpoint(
+  context.client,
+  "test-arg",
+  { option1: "value" }
+);
+console.log('Result:', result);
+```
+
+### Step 3: Document the Endpoint
+
+Add to `api-endpoints.md` with full request/response examples.
+
+---
+
+## Pattern 2: Creating a New MCP Tool
+
+Once your API endpoint works, wrap it in an MCP tool.
+
+### Step 1: Add Static Method to Tool Class
+
+Choose the appropriate class:
+- **ReadTools.ts** - Read-only operations (list, get, search)
+- **WriteTools.ts** - Write operations (create, update, delete)
+- **WorkflowTools.ts** - Workflow metadata operations
+- **WorkspaceTools.ts** - Workspace operations
+
+```typescript
+// server/src/mcp/tools/ReadTools.ts
+
+export class ReadTools {
+  static async my_new_tool(
+    context: UserContext,
+    args: { arg1: string; option1?: string }
+  ): Promise<string> {
+    try {
+      const { arg1, option1 } = args;
+
+      // Validate required arguments
+      if (!arg1) {
+        return "Error: arg1 is required";
+      }
+
+      // Call API function
+      const result = await myNewEndpoint(
+        context.client,
+        arg1,
+        { option1 }
+      );
+
+      // Format response for LLM
+      return formatMyResponse(result);
+
+    } catch (error) {
+      console.error('Error in my_new_tool:', error);
+      return `Error: ${error.message}`;
+    }
+  }
+}
+```
+
+**Key Points**:
+- Always wrap in try/catch
+- Validate required arguments upfront
+- Return user-friendly error messages
+- Log errors for debugging
+- Format response for LLM readability
+
+### Step 2: Format Response
+
+Create a helper function to format API response:
+
+```typescript
+function formatMyResponse(data: MyResponse): string {
+  if (!data || data.items.length === 0) {
+    return "No items found.";
+  }
+
+  const lines = [`Found ${data.items.length} items:\n`];
+
+  for (const item of data.items) {
+    lines.push(`- ${item.name} (ID: ${item._id})`);
+    if (item.description) {
+      lines.push(`  ${item.description}`);
+    }
+  }
+
+  return lines.join('\n');
+}
+```
+
+**Formatting Tips**:
+- Start with summary count
+- Use bullet points for lists
+- Include relevant IDs for follow-up actions
+- Keep it concise but informative
+- Use markdown formatting
+
+### Step 3: Register Tool in GlobalToolRegistry
+
+```typescript
+// server/src/mcp/GlobalToolRegistry.ts
+
+{
+  name: "my_new_tool",
+  description: "Clear description of what this tool does and when to use it",
+  inputSchema: {
+    type: "object",
+    properties: {
+      arg1: {
+        type: "string",
+        description: "Description of arg1"
+      },
+      option1: {
+        type: "string",
+        description: "Optional parameter description"
+      }
+    },
+    required: ["arg1"]
+  },
+  execute: async (args: any, context: UserContext) => {
+    return ReadTools.my_new_tool(context, args);
+  }
+}
+```
+
+**Description Guidelines**:
+- Be specific about what it does
+- Mention key parameters
+- Indicate when LLM should use it
+- Include examples if complex
+
+### Step 4: Test the Tool
+
+Test via debug endpoint:
+
+```bash
+curl -X POST http://localhost:3030/api/debug/execute-tool \
+  -H "Content-Type: application/json" \
+  -d '{
+    "apiKey": "test-key",
+    "toolName": "my_new_tool",
+    "args": {
+      "arg1": "test-value",
+      "option1": "optional-value"
+    }
+  }'
+```
+
+Or test with Claude Code:
+```
+Use my_new_tool with arg1="test"
+```
+
+---
+
+## Pattern 3: Implementing Filters
+
+Advanced filtering for activity queries.
+
+### Basic Filter
+
+```typescript
+const activities = await listActivities(client, workflowId, {
+  filters: {
+    and: [
+      { "priority": { equalTo: "high" } }
+    ]
+  },
+  returnFlat: true
+});
+```
+
+### Multiple Conditions (AND)
+
+```typescript
+filters: {
+  and: [
+    { "status": { equalTo: "active" } },
+    { "priority": { equalTo: "high" } },
+    { "created": { greaterThan: "2025-10-01" } }
+  ]
+}
+```
+
+### Multiple Conditions (OR)
+
+```typescript
+filters: {
+  or: [
+    { "status": { equalTo: "active" } },
+    { "status": { equalTo: "pending" } }
+  ]
+}
+```
+
+### Range Filters
+
+```typescript
+// Date range
+filters: {
+  and: [
+    { "created": { between: ["2025-10-01", "2025-10-31"] } }
+  ]
+}
+
+// Numeric range
+filters: {
+  and: [
+    { "budget": { greaterThanOrEqual: 10000 } },
+    { "budget": { lessThanOrEqual: 50000 } }
+  ]
+}
+```
+
+### Text Search
+
+```typescript
+filters: {
+  and: [
+    { "description": { textSearch: "urgent" } }
+  ]
+}
+```
+
+### Filter by Relationship
+
+```typescript
+// Find all tasks for a specific topic
+filters: {
+  and: [
+    { "relatedTo": { equalTo: topicActivityId } }
+  ]
+}
+```
+
+### Complex Filter Example
+
+```typescript
+// Find high-priority active tasks created this month
+const filters = {
+  and: [
+    { "priority": { equalTo: "high" } },
+    { "status": { equalTo: "active" } },
+    { "created": {
+        between: [
+          new Date('2025-10-01').getTime().toString(),
+          new Date('2025-10-31').getTime().toString()
+        ]
+      }
+    }
+  ]
+};
+```
+
+---
+
+## Pattern 4: Implementing Pagination
+
+Handle large result sets efficiently.
+
+### Simple Pagination
+
+```typescript
+async function getAllActivities(
+  client: HailerClient,
+  workflowId: string
+): Promise<Activity[]> {
+  const allActivities: Activity[] = [];
+  let page = 1;
+  let hasMore = true;
+
+  while (hasMore) {
+    const response = await listActivities(client, workflowId, {
+      page,
+      limit: 100,
+      returnFlat: true
+    });
+
+    allActivities.push(...response.data);
+
+    hasMore = page < response.totalPages;
+    page++;
+  }
+
+  return allActivities;
+}
+```
+
+### Pagination with Progress
+
+```typescript
+async function getAllActivitiesWithProgress(
+  client: HailerClient,
+  workflowId: string,
+  onProgress?: (current: number, total: number) => void
+): Promise<Activity[]> {
+  const allActivities: Activity[] = [];
+  let page = 1;
+
+  // Get first page to know total
+  const firstResponse = await listActivities(client, workflowId, {
+    page: 1,
+    limit: 100,
+    returnFlat: true
+  });
+
+  allActivities.push(...firstResponse.data);
+  const totalPages = firstResponse.totalPages;
+
+  onProgress?.(1, totalPages);
+
+  // Fetch remaining pages
+  for (page = 2; page <= totalPages; page++) {
+    const response = await listActivities(client, workflowId, {
+      page,
+      limit: 100,
+      returnFlat: true
+    });
+
+    allActivities.push(...response.data);
+    onProgress?.(page, totalPages);
+  }
+
+  return allActivities;
+}
+```
+
+### Discussion Message Pagination
+
+```typescript
+async function getAllMessages(
+  client: HailerClient,
+  discussionId: string
+): Promise<Message[]> {
+  const allMessages: Message[] = [];
+
+  // Fetch latest 50
+  const latest = await fetchLatestMessages(client, discussionId, 50);
+  allMessages.push(...latest.messages);
+
+  // Fetch older messages
+  let oldestId = latest.messages[latest.messages.length - 1]?._id;
+
+  while (oldestId) {
+    const previous = await fetchPreviousMessages(client, oldestId, 50);
+
+    if (previous.messages.length === 0) {
+      break;
+    }
+
+    allMessages.push(...previous.messages);
+    oldestId = previous.messages[previous.messages.length - 1]?._id;
+  }
+
+  return allMessages;
+}
+```
+
+---
+
+## Pattern 5: Socket.io Operations
+
+Working with socket.io methods via `@hailer/cli`.
+
+### Basic Socket Call
+
+```typescript
+async function followActivity(
+  client: HailerClient,
+  activityId: string,
+  follow: boolean
+): Promise<void> {
+  await client.socket.call('activities.follow', {
+    activityId,
+    follow
+  });
+}
+```
+
+### Socket Call with Response
+
+```typescript
+async function getActivityDetails(
+  client: HailerClient,
+  activityId: string
+): Promise<any> {
+  const response = await client.socket.call('activities.get', {
+    activityId
+  });
+
+  return response;
+}
+```
+
+### Socket Call with Error Handling
+
+```typescript
+async function leaveDiscussion(
+  client: HailerClient,
+  discussionId: string
+): Promise<string> {
+  try {
+    await client.socket.call('messenger.leave_discussion', {
+      discussionId
+    });
+
+    return `Successfully left discussion ${discussionId}`;
+  } catch (error) {
+    console.error('Socket error:', error);
+    return `Error leaving discussion: ${error.message}`;
+  }
+}
+```
+
+---
+
+## Pattern 6: Error Handling Best Practices
+
+Comprehensive error handling for robust tools.
+
+### Multi-Level Error Handling
+
+```typescript
+export class ReadTools {
+  static async list_activities(
+    context: UserContext,
+    args: any
+  ): Promise<string> {
+    try {
+      // Level 1: Validate arguments
+      if (!args.workflowId) {
+        return "Error: workflowId is required";
+      }
+
+      // Level 2: Validate workflow exists
+      const workflow = await getWorkflow(context.client, args.workflowId);
+      if (!workflow) {
+        return `Error: Workflow ${args.workflowId} not found`;
+      }
+
+      // Level 3: Call API
+      const activities = await listActivities(
+        context.client,
+        args.workflowId,
+        { returnFlat: true }
+      );
+
+      // Level 4: Validate response
+      if (!activities || !activities.data) {
+        return "Error: Invalid response from API";
+      }
+
+      return formatActivities(activities.data);
+
+    } catch (error) {
+      // Level 5: Catch unexpected errors
+      console.error('Error in list_activities:', error);
+
+      // Provide helpful error message based on error type
+      if (error.message.includes('401')) {
+        return "Error: Authentication failed. Check API credentials.";
+      }
+      if (error.message.includes('404')) {
+        return "Error: Endpoint not found. Check API version.";
+      }
+      if (error.message.includes('timeout')) {
+        return "Error: Request timed out. Try again.";
+      }
+
+      return `Error: ${error.message}`;
+    }
+  }
+}
+```
+
+### Specific Error Types
+
+```typescript
+class HailerAPIError extends Error {
+  constructor(
+    public statusCode: number,
+    public details: any,
+    message: string
+  ) {
+    super(message);
+    this.name = 'HailerAPIError';
+  }
+}
+
+// Usage in API function
+if (!response.ok) {
+  const details = await response.json().catch(() => ({}));
+  throw new HailerAPIError(
+    response.status,
+    details,
+    `API request failed: ${response.statusText}`
+  );
+}
+
+// Catch specific error type
+try {
+  await apiCall();
+} catch (error) {
+  if (error instanceof HailerAPIError) {
+    if (error.statusCode === 422) {
+      return `Validation error: ${JSON.stringify(error.details)}`;
+    }
+  }
+  throw error;
+}
+```
+
+---
+
+## Pattern 7: Testing Tools
+
+Test tools thoroughly before deployment.
+
+### Unit Test Pattern
+
+```typescript
+// server/src/mcp/tools/__tests__/ReadTools.test.ts
+
+import { ReadTools } from '../ReadTools';
+import { UserContext } from '../../UserContextCache';
+
+describe('ReadTools', () => {
+  let mockContext: UserContext;
+
+  beforeEach(() => {
+    mockContext = {
+      client: createMockClient(),
+      initData: mockInitData,
+      workspaceCache: mockCache
+    };
+  });
+
+  it('should list activities', async () => {
+    const result = await ReadTools.list_activities(
+      mockContext,
+      { workflowId: 'test-workflow-id' }
+    );
+
+    expect(result).toContain('Found');
+    expect(result).not.toContain('Error');
+  });
+
+  it('should handle missing workflowId', async () => {
+    const result = await ReadTools.list_activities(
+      mockContext,
+      {}
+    );
+
+    expect(result).toContain('Error');
+    expect(result).toContain('workflowId is required');
+  });
+});
+```
+
+### Integration Test Pattern
+
+```typescript
+// Test against real API (local development)
+describe('ReadTools Integration', () => {
+  it('should fetch real activities', async () => {
+    const context = await createRealContext('test-key');
+
+    const result = await ReadTools.list_activities(
+      context,
+      { workflowId: '68446dc05b30685f67c6fcd4' }
+    );
+
+    console.log('Result:', result);
+    expect(result).not.toContain('Error');
+  });
+});
+```
+
+### Manual Test via Debug Endpoint
+
+```bash
+#!/bin/bash
+# test-tool.sh
+
+curl -X POST http://localhost:3030/api/debug/execute-tool \
+  -H "Content-Type: application/json" \
+  -d "{
+    \"apiKey\": \"test-key\",
+    \"toolName\": \"$1\",
+    \"args\": $2
+  }" | jq
+```
+
+Usage:
+```bash
+./test-tool.sh list_activities '{"workflowId":"68446dc05b30685f67c6fcd4"}'
+```
+
+---
+
+## Pattern 8: Optimizing for Context
+
+Keep MCP tool responses concise to save context.
+
+### Bad: Verbose Response
+
+```typescript
+return `Successfully listed activities. Total count: ${activities.length}
+Activities:
+${activities.map(a => `
+- ID: ${a._id}
+- Name: ${a.name}
+- Process ID: ${a.processId}
+- Phase ID: ${a.phaseId}
+- Created: ${a.created}
+- Updated: ${a.updated}
+- Discussion: ${a.discussion}
+- Fields: ${JSON.stringify(a.fields, null, 2)}
+`).join('\n')}`;
+```
+
+### Good: Concise Response
+
+```typescript
+const summary = activities.length === 0
+  ? "No activities found."
+  : `Found ${activities.length} activities:`;
+
+const items = activities.slice(0, 10).map(a =>
+  `- ${a.name} (${a._id})`
+).join('\n');
+
+const more = activities.length > 10
+  ? `\n... and ${activities.length - 10} more`
+  : '';
+
+return `${summary}\n${items}${more}`;
+```
+
+### Include Only What's Needed
+
+```typescript
+// For listing: names and IDs only
+// For details: full data when requested
+```
+
+---
+
+## Checklist: New MCP Tool
+
+- [ ] API endpoint function in `hailer-api.ts`
+- [ ] Test API function directly
+- [ ] Static method in appropriate tool class
+- [ ] Input validation
+- [ ] Error handling (try/catch)
+- [ ] User-friendly response formatting
+- [ ] Tool registration in GlobalToolRegistry
+- [ ] Clear description in schema
+- [ ] Test via debug endpoint
+- [ ] Test with Claude Code
+- [ ] Document in skill if complex
+- [ ] Update CLAUDE.md if adds new capability