@hailer/mcp 1.0.29 → 1.1.2

package/.claude/skills/tool-builder/SKILL.md

@@ -0,0 +1,250 @@
+---
+name: tool-builder
+description: Patterns for building MCP tools in Hailer MCP server
+version: 1.0.0
+triggers: MCP tool creation, Zod schemas, tool registration, API client usage
+---
+
+# MCP Tool Builder Patterns
+
+## Tool Structure
+
+MCP tools live in `src/mcp/tools/` and are registered in `src/app.ts`.
+
+```typescript
+// src/mcp/tools/example.ts
+import { z } from 'zod';
+import { McpTool, ToolContext } from '../types.js';
+
+export const myTool: McpTool = {
+  name: 'my_tool',
+  description: 'What this tool does',
+  inputSchema: z.object({
+    requiredParam: z.string().describe('Description'),
+    optionalParam: z.coerce.number().optional().default(50)
+  }),
+  annotations: { toolGroup: 'READ' },
+  handler: async (args, context: ToolContext) => {
+    // Implementation
+  }
+};
+```
+
+---
+
+## Tool Groups
+
+| Group | Purpose | Examples |
+|-------|---------|----------|
+| `READ` | Safe reads, no side effects | list_workflows, get_activity |
+| `WRITE` | Create/update data | create_activity, update_activity |
+| `PLAYGROUND` | Admin/testing tools | install_workflow, preview_insight |
+| `NUCLEAR` | Destructive operations | remove_workflow, delete_activity |
+
+---
+
+## Zod Schema Coercion
+
+MCP sends all values as strings. Use coercion:
+
+```typescript
+// Numbers
+z.coerce.number().optional().default(50)
+
+// Booleans
+z.coerce.boolean().optional().default(true)
+
+// Arrays (from JSON string)
+z.preprocess(
+  (val) => typeof val === 'string' ? JSON.parse(val) : val,
+  z.array(z.string())
+)
+
+// Objects (from JSON string)
+z.preprocess(
+  (val) => typeof val === 'string' ? JSON.parse(val) : val,
+  z.record(z.any())
+)
+
+// Optional with default
+z.string().optional().default('default_value')
+```
+
+---
+
+## API Client Methods
+
+Access via `context.hailer`:
+
+```typescript
+// Socket API call
+const result = await context.hailer.request('v3.endpoint.method', [arg1, arg2]);
+
+// REST API call
+const result = await context.hailer.callRest({
+  endpoint: '/api/v3/something',
+  method: 'POST',
+  body: { data }
+});
+
+// Convenience methods
+const schema = await context.hailer.getWorkflowSchema(workflowId, phaseId);
+const activity = await context.hailer.fetchActivityById(activityId);
+```
+
+---
+
+## Type Discovery Workflow
+
+When you don't know the exact API response shape:
+
+1. **Implement with `any` + logging**
+   ```typescript
+   handler: async (args, context) => {
+     const result = await context.hailer.request('v3.new.endpoint', [args.id]);
+     context.logger.debug('API response:', JSON.stringify(result, null, 2));
+     return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+   }
+   ```
+
+2. **Test the tool** - Call it and check server logs
+
+3. **Update to proper types** - Based on logged output
+
+4. **Test again** - Verify typed version works
+
+---
+
+## Tool Registration
+
+After creating a tool, register it in `src/app.ts`:
+
+```typescript
+// In src/app.ts
+import { myTool } from './mcp/tools/example.js';
+
+// Add to tools array
+const tools = [
+  // ... existing tools
+  myTool,
+];
+```
+
+---
+
+## Common Patterns
+
+### List endpoint
+```typescript
+export const listThings: McpTool = {
+  name: 'list_things',
+  description: 'List all things in workspace',
+  inputSchema: z.object({
+    limit: z.coerce.number().optional().default(100).describe('Max results')
+  }),
+  annotations: { toolGroup: 'READ' },
+  handler: async (args, context) => {
+    const result = await context.hailer.request('v3.thing.list', [
+      context.workspaceId,
+      { limit: args.limit }
+    ]);
+    return {
+      content: [{
+        type: 'text',
+        text: JSON.stringify(result, null, 2)
+      }]
+    };
+  }
+};
+```
+
+### Get by ID endpoint
+```typescript
+export const getThing: McpTool = {
+  name: 'get_thing',
+  description: 'Get thing by ID',
+  inputSchema: z.object({
+    thingId: z.string().describe('Thing UUID')
+  }),
+  annotations: { toolGroup: 'READ' },
+  handler: async (args, context) => {
+    const result = await context.hailer.request('v3.thing.get', [args.thingId]);
+    return {
+      content: [{
+        type: 'text',
+        text: JSON.stringify(result, null, 2)
+      }]
+    };
+  }
+};
+```
+
+### Create endpoint
+```typescript
+export const createThing: McpTool = {
+  name: 'create_thing',
+  description: 'Create a new thing',
+  inputSchema: z.object({
+    name: z.string().describe('Thing name'),
+    data: z.preprocess(
+      (val) => typeof val === 'string' ? JSON.parse(val) : val,
+      z.record(z.any())
+    ).optional().describe('Additional data as JSON')
+  }),
+  annotations: { toolGroup: 'WRITE' },
+  handler: async (args, context) => {
+    const result = await context.hailer.request('v3.thing.create', [{
+      workspaceId: context.workspaceId,
+      name: args.name,
+      ...args.data
+    }]);
+    return {
+      content: [{
+        type: 'text',
+        text: JSON.stringify({ created: result._id }, null, 2)
+      }]
+    };
+  }
+};
+```
+
+---
+
+## Edit Mode Guard
+
+Before editing MCP server code, enable edit mode:
+
+```bash
+# Enable editing
+node .claude/hooks/src-edit-guard.cjs --on
+
+# ... make edits ...
+
+# Disable editing
+node .claude/hooks/src-edit-guard.cjs --off
+```
+
+---
+
+## Build Verification
+
+Always verify build passes after changes:
+
+```bash
+npm run build
+```
+
+Tool is only complete when build passes without errors.
+
+---
+
+## Common Mistakes
+
+| Wrong | Right |
+|-------|-------|
+| `z.number()` for MCP input | `z.coerce.number()` - values come as strings |
+| `z.boolean()` for MCP input | `z.coerce.boolean()` |
+| `z.array()` directly | `z.preprocess()` wrapper to parse JSON string |
+| Forgetting to register tool | Add to `src/app.ts` tools array |
+| Skipping build check | Always run `npm run build` |
+| Using wrong tool group | READ for queries, WRITE for mutations |

package/.claude/skills/tool-parameter-usage/SKILL.md

@@ -1,14 +1,19 @@
 ---
 name: tool-parameter-usage
 description: Extract IDs from context and use correct parameter formats for Hailer tools
+version: 1.1.0
 triggers: Tool validation failed with "Required" error, empty receivedArgs, or field format errors
 ---
 
-<problem>
-LLM calls tools with empty parameters `{}` even when context contains required IDs, or uses wrong parameter names/formats.
-</problem>
+# Tool Parameter Usage
+
+<purpose>
+Teach correct extraction of IDs from message context and proper parameter formats for Hailer tool calls, preventing empty parameter errors and format mismatches.
+</purpose>
+
+<patterns>
+## Pattern 1: Context Extraction
 
-<context-extraction>
 The `<incoming>` tag in messages contains critical IDs. ALWAYS extract and use them:
 
 ```xml
@@ -20,51 +25,83 @@ The `<incoming>` tag in messages contains critical IDs. ALWAYS extract and use t
 **Extract before calling tools:**
 - `activityId` → use for `show_activity_by_id`, `update_activity`
 - `discussionId` → use for `get_activity_from_discussion`, `add_discussion_message`
-</context-extraction>
 
-<correct>
+## Pattern 2: Single vs Bulk Mode Parameters
+
+| Tool | Single mode | Bulk mode |
+|------|-------------|-----------|
+| `create_activity` | Top-level `name`, `phaseId`, `teamId`, `fields` | Inside each `activities[]` item |
+| `update_activity` | `activityId` | `activities[]._id` |
+| `show_activity_by_id` | `activityId` | N/A |
+| `get_activity_from_discussion` | `discussionId` | N/A |
+
+**CRITICAL for `create_activity` bulk mode:** `teamId`, `phaseId`, and `fields` must be **inside each activity object** in the `activities[]` array. Top-level values (except `workflowId`) are IGNORED in bulk mode. This causes "Missing team(s)" (code 127) if teamId is only at the top level.
+
+## Pattern 3: Field Value Formats
+
+| Field type | Value format |
+|------------|--------------|
+| `numericunit` | Plain number: `78` |
+| `text` | Plain string: `"hello"` |
+| `activitylink` | Activity ID string: `"abc123..."` |
+| `select` | Option key: `"option_key"` |
+
+**Never pass objects with `type` metadata** - Hailer API expects plain values.
+</patterns>
+
+<examples>
+## Example 1: Correct - Extracting IDs from Context
+
 ```typescript
 // Context: <incoming activityId="69384669b7826c5d9ec4e07c" discussionId="69384669b7826c5d9ec4e07d">
 
-// ✅ CORRECT - Extract activityId from context
+// CORRECT - Extract activityId from context
 show_activity_by_id({
   activityId: "69384669b7826c5d9ec4e07c"
 });
 
-// ✅ CORRECT - Single update mode uses activityId
+// CORRECT - Get activity from discussion
+get_activity_from_discussion({
+  discussionId: "69384669b7826c5d9ec4e07d"
+});
+```
+
+## Example 2: Correct - Single vs Bulk Update Mode
+
+```typescript
+// CORRECT - Single update mode uses activityId
 update_activity({
   activityId: "69384669b7826c5d9ec4e07c",
   fields: { "fieldId123": 78 }
 });
 
-// ✅ CORRECT - Bulk update mode uses _id (NOT activityId)
+// CORRECT - Bulk update mode uses _id (NOT activityId)
 update_activity({
   activities: [{
     _id: "69384669b7826c5d9ec4e07c",
     fields: { "fieldId123": 78 }
   }]
 });
+```
+
+## Example 3: Correct - Field Value Formats
 
-// ✅ CORRECT - numericunit field = plain number
+```typescript
+// CORRECT - numericunit field = plain number
 update_activity({
   activityId: "69384669b7826c5d9ec4e07c",
   fields: { "weightFieldId": 78 }
 });
-
-// ✅ CORRECT - Get activity from discussion
-get_activity_from_discussion({
-  discussionId: "69384669b7826c5d9ec4e07d"
-});
 ```
-</correct>
 
-<wrong>
+## Example 4: Wrong - Common Errors
+
 ```typescript
-// ❌ WRONG - Empty parameters (ignoring context)
+// WRONG - Empty parameters (ignoring context)
 show_activity_by_id({});
 // Error: activityId: Required, receivedArgs={}
 
-// ❌ WRONG - Using activityId in bulk mode (should be _id)
+// WRONG - Using activityId in bulk mode (should be _id)
 update_activity({
   activities: [{
     activityId: "69384669b7826c5d9ec4e07c",  // WRONG KEY
@@ -73,7 +110,7 @@ update_activity({
 });
 // Error: activities.0._id: Required
 
-// ❌ WRONG - Passing object for numericunit field
+// WRONG - Passing object for numericunit field
 update_activity({
   activityId: "69384669b7826c5d9ec4e07c",
   fields: {
@@ -82,31 +119,8 @@ update_activity({
 });
 // Error: "Weight" must be a number
 
-// ❌ WRONG - Empty list_activities call
+// WRONG - Empty list_activities call
 list_activities({});
 // Error: workflowId: Required, phaseId: Required
 ```
-</wrong>
-
-<fix>
-**Before calling ANY tool:**
-1. Check `<incoming>` tag for `activityId` and `discussionId`
-2. Extract these values and pass them to tools
-
-**Parameter rules:**
-| Tool | Single mode | Bulk mode |
-|------|-------------|-----------|
-| `update_activity` | `activityId` | `activities[].\_id` |
-| `show_activity_by_id` | `activityId` | N/A |
-| `get_activity_from_discussion` | `discussionId` | N/A |
-
-**Field value formats:**
-| Field type | Value format |
-|------------|--------------|
-| `numericunit` | Plain number: `78` |
-| `text` | Plain string: `"hello"` |
-| `activitylink` | Activity ID string: `"abc123..."` |
-| `select` | Option key: `"option_key"` |
-
-**Never pass objects with `type` metadata** - Hailer API expects plain values.
-</fix>
+</examples>

package/.claude/skills/tool-response-verification/SKILL.md

@@ -1,58 +1,92 @@
 ---
 name: tool-response-verification
-description: Ensure agents verify tool execution before claiming success
-triggers: Agent returns success without checking tool result
+description: Verify MCP tool execution results before reporting success
+version: 1.0.0
+triggers:
+  - MCP tool failure
+  - fabricated response
+  - tool result verification
+  - silent failure
+  - disconnected server
 ---
 
-<problem>
-Agent fabricates success response without verifying actual tool execution result.
-</problem>
-
-<correct>
-```typescript
-// Call tool
-const result = await update_insight({
-  insightId: "abc123",
-  public: false
-});
-
-// Verify tool response before returning to orchestrator
-if (result.error) {
-  return {
-    status: "error",
-    error: result.error,
-    summary: "Update failed"
-  };
+# Tool Response Verification
+
+<purpose>
+Ensure agents verify actual tool execution results before reporting success, preventing fabricated responses when MCP servers are disconnected or tools fail silently.
+</purpose>
+
+<patterns>
+## Pattern 1: Always Check Tool Results
+
+Every MCP tool call returns a result. Read it before proceeding.
+
+## Pattern 2: Never Assume Success
+
+If you didn't see confirmation in the result, it didn't happen.
+
+## Pattern 3: Report Actual Errors
+
+If tool returned error, report error status - don't fabricate success.
+
+## Pattern 4: No Fabrication
+
+Never claim "created 5 activities" if you didn't see 5 activity IDs returned.
+
+## Pattern 5: Verification Checklist
+
+Before returning success:
+- Did the tool return a result (not an error)?
+- Does the result contain expected data (IDs, counts, etc.)?
+- Am I reporting data FROM the result, not data I expected?
+
+## Pattern 6: Detect MCP Connection Errors
+
+When an MCP server is offline, tools return empty results, undefined data, or error messages instead of clear failures. This looks like "success" but is actually a connection problem.
+
+**Red flags:**
+- Empty array when data is expected (e.g., `workflows: []` for a non-empty workspace)
+- Missing schema fields that should always be present
+- Undefined/null responses from tools that normally return structured data
+- Error messages containing: "connection", "ECONNREFUSED", "timeout", "unavailable", "ENOTFOUND"
+
+**What to do:**
+Instead of reporting empty data as success, report: "MCP server appears offline - tool returned empty/error result. Check that the MCP server is running."
+
+Return error status, not success:
+```json
+{
+  "status": "error",
+  "result": { "tool": "tool_name", "error": "MCP server appears offline" },
+  "summary": "Cannot proceed: MCP server not responding"
 }
+```
+</patterns>
+
+<examples>
+## Example 1: Correct - Verify Before Reporting
+
+```
+GOOD: Call create_activity → read result → if result.activityId exists → return success
+GOOD: "Created customer with ID abc123" (ID from actual result)
+```
+
+## Example 2: Wrong - Fabricating Success
 
-return {
-  status: "success",
-  result: { updated: true, insight_id: result.id },
-  summary: "Updated insight"
-};
 ```
-</correct>
-
-<wrong>
-```typescript
-// Call tool (that might fail)
-update_insight({ insightId: "abc123", public: false });
-
-// Immediately return success WITHOUT checking tool result
-return {
-  status: "success",
-  result: { updated: true },
-  summary: "Updated insight"
-};
+BAD: Call create_activity → immediately return {"status": "success", "created": 1}
+BAD: "I created the customer" (without checking result)
 ```
-</wrong>
 
-<fix>
-1. **NEVER assume tool success** - Always capture and check tool response
-2. **Return actual error messages** - If tool fails, return error status with real error message
-3. **Verify before claiming success** - Only return success after confirming tool execution succeeded
-4. **Test error paths** - If unsure about tool behavior, preview/test first
+## Example 3: Correct - Error Reporting
 
-This is a violation of Rule 1: "NEVER FABRICATE - Must call tools."
-Fabricating a success response when tool failed is the same as not calling the tool.
-</fix>
+When tools fail, report the actual error:
+
+```json
+{
+  "status": "error",
+  "result": { "tool": "tool_name", "error": "actual error message" },
+  "summary": "Tool failed: brief reason"
+}
+```
+</examples>