@hailer/mcp 0.0.1

package/.claude/skills/mcp-tools/SKILL.md

@@ -0,0 +1,419 @@
+---
+name: MCP Tools
+description: Complete technical reference for building Hailer MCP tools - API endpoints, data structures, implementation patterns, and working code examples.
+---
+
+# MCP Tools Skill
+
+This skill provides comprehensive technical documentation for building MCP tools that integrate with the Hailer API. Use this when implementing new tools or debugging existing integrations.
+
+## When to Use This Skill
+
+Invoke this skill when:
+- Building a new MCP tool for Hailer integration
+- Debugging API calls or data structures
+- Understanding endpoint signatures and request formats
+- Implementing filters, pagination, or complex queries
+- Working with workflow schemas or activity structures
+
+## Quick Reference
+
+### API Configuration
+
+- **Base URL**: `https://api.hailer.local.gd`
+- **Authentication**: `hlrkey` header with auth token
+- **Request Format**: Most endpoints expect JSON array as body: `[...args]`
+- **API Versions**: v2 (init), v3 (activities, discussions), mixed usage
+- **Protocol**: Socket.io via `@hailer/cli` package + REST endpoints
+
+### Key Implementation Principles
+
+1. **Use UserContext**: All tools receive UserContext with client connections
+2. **Stateless Tools**: Tools are static methods, no instance state
+3. **Connection Pooling**: Reuse connections from global pool
+4. **returnFlat Mode**: Use `returnFlat: true` for cleaner field access via keys
+5. **Error Handling**: Always wrap in try/catch, return user-friendly messages
+
+## Documentation Structure
+
+### [API Endpoints](references/api-endpoints.md)
+Complete reference for all working Hailer API endpoints with exact request/response formats:
+- Activity operations (list, create, update)
+- Discussion messages (fetch, send, pagination)
+- Workflow operations
+- Socket.io methods
+- Filter operators and query syntax
+
+### [Data Structures](references/data-structures.md)
+Detailed schemas for Hailer data types:
+- Workflow structure (processes, fields, phases)
+- Activity structure (with/without returnFlat)
+- Field types (text, activitylink, date, etc.)
+- ActivityLink relationships
+- Phase transitions
+
+### [Implementation Patterns](references/implementation-patterns.md)
+Step-by-step guides for common tasks:
+- Adding new API endpoints
+- Creating MCP tools
+- Implementing filters and pagination
+- Handling socket.io connections
+- Error handling best practices
+- Testing and debugging tools
+
+## Common Code Patterns
+
+### Complete Tool Structure (2024 Pattern)
+
+```typescript
+// In ReadTools.ts, WriteTools.ts, or PlaygroundTools.ts
+import { z } from 'zod';
+import { UserContext, McpResponse } from '../types';
+
+export class ReadTools {
+  /**
+   * Register all tools - called by GlobalToolRegistry
+   */
+  static getTools() {
+    return [
+      {
+        name: 'list_activities',
+        description: ReadTools.getListActivitiesDescription(),
+        validationSchema: ReadTools.getListActivitiesSchema(),
+        handler: ReadTools.listActivities
+      }
+    ];
+  }
+
+  /**
+   * Tool description
+   */
+  private static getListActivitiesDescription(): string {
+    return `📋 List activities in a workflow phase with filtering.
+
+**Example:**
+\`\`\`javascript
+list_activities({
+  workflowId: "6756e099410306cab03a7dfb",
+  phaseId: "6756e0bd410306cab03a7fa7",
+  fields: ["name", "status"],
+  limit: 50
+})
+\`\`\``;
+  }
+
+  /**
+   * Zod schema with type coercion for MCP clients
+   */
+  private static getListActivitiesSchema() {
+    return z.object({
+      workflowId: z.string().describe("Workflow ID to list activities from"),
+      phaseId: z.string().describe("Phase ID to filter activities"),
+
+      // CRITICAL: Use z.coerce for numbers (MCP clients send as strings)
+      limit: z.coerce.number().optional().default(50)
+        .describe("Maximum number of activities to return"),
+      page: z.coerce.number().optional().default(0)
+        .describe("Page number for pagination (0-based)"),
+
+      // CRITICAL: Use z.coerce for booleans (MCP clients send "false" as string)
+      includeStats: z.coerce.boolean().optional().default(true)
+        .describe("Include total count and pagination metadata"),
+
+      // CRITICAL: Use z.preprocess for arrays (MCP clients send JSON strings)
+      fields: z.preprocess(
+        (val) => {
+          if (typeof val === 'string') {
+            try {
+              return JSON.parse(val);
+            } catch {
+              return val;
+            }
+          }
+          return val;
+        },
+        z.array(z.string()).optional()
+      ).describe("Array of field IDs to return")
+    });
+  }
+
+  /**
+   * Static handler method
+   */
+  static async listActivities(args: Record<string, unknown>, context: UserContext): Promise<McpResponse> {
+    // Args already validated by GlobalToolRegistry
+    const validatedArgs = args as {
+      workflowId: string;
+      phaseId: string;
+      limit?: number;
+      page?: number;
+      includeStats?: boolean;
+      fields?: string[];
+    };
+
+    try {
+      // Use context.client.baseUrl instead of hardcoded URL
+      const apiClient = new HailerApiClient(context.client, context.client.baseUrl);
+
+      const activities = await apiClient.listActivities(
+        validatedArgs.workflowId,
+        {
+          phaseId: validatedArgs.phaseId,
+          limit: validatedArgs.limit,
+          returnFlat: true
+        }
+      );
+
+      return {
+        content: [{
+          type: "text",
+          text: formatActivitiesResponse(activities)
+        }]
+      };
+    } catch (error) {
+      return {
+        content: [{
+          type: "text",
+          text: `❌ **Error listing activities**\n\n${error.message}`
+        }]
+      };
+    }
+  }
+}
+```
+
+### Calling Hailer API
+
+```typescript
+// In hailer-api.ts
+export async function listActivities(
+  client: HailerClient,
+  workflowId: string,
+  options: ActivityListOptions = {}
+): Promise<any> {
+  const { phaseId, limit = 50, returnFlat = true } = options;
+
+  const response = await fetch(
+    `${client.baseUrl}/v3/activity/list`,
+    {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'hlrkey': client.authToken
+      },
+      body: JSON.stringify([
+        { processId: workflowId, phaseId },
+        { limit, page: 1, returnFlat }
+      ])
+    }
+  );
+
+  if (!response.ok) {
+    throw new Error(`API error: ${response.statusText}`);
+  }
+
+  return response.json();
+}
+```
+
+## Tool Registration (GlobalToolRegistry)
+
+```typescript
+// In GlobalToolRegistry.ts
+import { z } from 'zod';
+
+export class GlobalToolRegistry {
+  private tools = new Map<string, {
+    name: string;
+    description: string;
+    validationSchema: any;  // Zod schema
+    handler: ToolHandler;
+    group: ToolGroup;
+  }>();
+
+  private constructor() {
+    // Register tools from each class
+    this.registerToolsFromClass(ReadTools.getTools(), 'read');
+    this.registerToolsFromClass(WriteTools.getTools(), 'write');
+    this.registerToolsFromClass(PlaygroundTools.getTools(), 'playground');
+  }
+
+  /**
+   * Register tools from a tool class
+   */
+  private registerToolsFromClass(toolRegs: Array<{
+    name: string;
+    description: string;
+    validationSchema: any;
+    handler: ToolHandler;
+  }>, group: ToolGroup): void {
+    for (const toolReg of toolRegs) {
+      this.tools.set(toolReg.name, {
+        name: toolReg.name,
+        description: toolReg.description,
+        validationSchema: toolReg.validationSchema,
+        handler: toolReg.handler,
+        group: group
+      });
+    }
+  }
+
+  /**
+   * Execute tool with centralized Zod validation
+   */
+  async executeTool(toolName: string, args: any, context: UserContext): Promise<McpResponse> {
+    const tool = this.tools.get(toolName);
+    if (!tool) {
+      throw new Error(`Tool not found: ${toolName}`);
+    }
+
+    // CENTRALIZED VALIDATION with Zod
+    try {
+      const validatedArgs = tool.validationSchema.parse(args);
+      return await tool.handler(validatedArgs, context);
+    } catch (error) {
+      if (error instanceof z.ZodError) {
+        const errorDetails = error.errors.map(e => `${e.path.join('.')}: ${e.message}`).join(', ');
+        return {
+          content: [{
+            type: "text",
+            text: `❌ **Validation Error for \`${toolName}\`**\n\n**Errors:** ${errorDetails}`
+          }]
+        };
+      }
+      throw error;
+    }
+  }
+}
+```
+
+## Type Coercion Patterns (CRITICAL for MCP Compatibility)
+
+### Boolean Parameters
+**Problem:** MCP clients send `"false"` as a string, not boolean `false`
+**Solution:** Use `z.coerce.boolean()`
+
+```typescript
+enabled: z.coerce.boolean().optional().default(true)
+  .describe("Enable feature")
+```
+
+### Numeric Parameters
+**Problem:** MCP clients send `"123"` as a string, not number `123`
+**Solution:** Use `z.coerce.number()`
+
+```typescript
+limit: z.coerce.number().optional().default(50)
+  .describe("Maximum results")
+```
+
+### Array Parameters
+**Problem:** MCP clients send `'["field1","field2"]'` as JSON string
+**Solution:** Use `z.preprocess()` to parse JSON strings
+
+```typescript
+fields: z.preprocess(
+  (val) => {
+    if (typeof val === 'string') {
+      try {
+        return JSON.parse(val);
+      } catch {
+        return val;
+      }
+    }
+    return val;
+  },
+  z.array(z.string()).optional()
+).describe("Array of field IDs")
+```
+
+### Object Parameters
+**Problem:** MCP clients send configuration objects as JSON strings
+**Solution:** Use `z.preprocess()` to parse JSON strings
+
+```typescript
+configuration: z.preprocess(
+  (val) => {
+    if (typeof val === 'string') {
+      try {
+        return JSON.parse(val);
+      } catch {
+        return val;
+      }
+    }
+    return val;
+  },
+  z.record(z.any()).optional()
+).describe("Configuration object")
+```
+
+## API URL Pattern (CRITICAL for Environment Support)
+
+**Always use `context.client.baseUrl` instead of hardcoded URLs:**
+
+```typescript
+// ❌ WRONG - hardcoded production URL
+const apiClient = new HailerApiClient(context.client, 'https://api.hailer.com');
+
+// ✅ CORRECT - uses client's configured URL (local/staging/production)
+const apiClient = new HailerApiClient(context.client, context.client.baseUrl);
+```
+
+## Working Endpoint Summary
+
+### V3 Activity Endpoints
+- `POST /v3/activity/list` - List activities with advanced filtering
+- `POST /v3/activity/createMany` - Create activities (batch)
+- `POST /v3/activity/updateMany` - Update activities (batch)
+
+### V3 Discussion Endpoints
+- `POST /v3/discussion/message/latest` - Fetch latest messages
+- `POST /v3/discussion/message/previous` - Fetch older messages (pagination)
+- `POST /api/messenger/send` - Send message to discussion
+
+### V2 Endpoints
+- `POST /v2/core/init` - Workspace initialization
+- `POST /v2/search/global` - Global search
+
+### Socket.io Methods
+- `activities.follow` - Follow/unfollow activity (joins/leaves discussion)
+- `messenger.leave_discussion` - Leave any discussion
+
+## Filter Operators (v3 API)
+
+- `textSearch` - Partial text search in field
+- `equalTo` / `notEqualTo` - Exact matching
+- `contains` - Partial text matching
+- `greaterThan` / `lessThan` / `greaterThanOrEqual` / `lessThanOrEqual` - Numeric comparisons
+- `between` - Range filter for dates/numbers [start, end]
+
+## Example: Activity List with Filters
+
+```typescript
+// Filter activities by company and date range
+const activities = await listActivities(client, workflowId, {
+  filters: {
+    and: [
+      { "field-id-company": { equalTo: "company-id" } },
+      { "field-id-created": { between: ["1717200000000", "1719791999000"] } }
+    ]
+  },
+  returnFlat: true,
+  limit: 100
+});
+```
+
+## Next Steps
+
+For detailed information on any topic:
+1. Check [API Endpoints](references/api-endpoints.md) for exact endpoint signatures
+2. Review [Data Structures](references/data-structures.md) for schema details
+3. Follow [Implementation Patterns](references/implementation-patterns.md) for step-by-step guides
+
+## TODO - Research Needed
+
+- Activity comments (add_comment endpoint)
+- Cross-workspace search API endpoint
+- Proper permission requirements for write operations
+- File upload/download endpoints
+- Workflow automation triggers