@hailer/mcp 1.1.14 → 1.1.16

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

@@ -0,0 +1,126 @@
+---
+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
+---
+
+# 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
+
+The `<incoming>` tag in messages contains critical IDs. ALWAYS extract and use them:
+
+```xml
+<incoming activityId="69384669b7826c5d9ec4e07c" discussionId="69384669b7826c5d9ec4e07d">
+  User message here
+</incoming>
+```
+
+**Extract before calling tools:**
+- `activityId` → use for `show_activity_by_id`, `update_activity`
+- `discussionId` → use for `get_activity_from_discussion`, `add_discussion_message`
+
+## 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
+show_activity_by_id({
+  activityId: "69384669b7826c5d9ec4e07c"
+});
+
+// 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)
+update_activity({
+  activities: [{
+    _id: "69384669b7826c5d9ec4e07c",
+    fields: { "fieldId123": 78 }
+  }]
+});
+```
+
+## Example 3: Correct - Field Value Formats
+
+```typescript
+// CORRECT - numericunit field = plain number
+update_activity({
+  activityId: "69384669b7826c5d9ec4e07c",
+  fields: { "weightFieldId": 78 }
+});
+```
+
+## Example 4: Wrong - Common Errors
+
+```typescript
+// WRONG - Empty parameters (ignoring context)
+show_activity_by_id({});
+// Error: activityId: Required, receivedArgs={}
+
+// WRONG - Using activityId in bulk mode (should be _id)
+update_activity({
+  activities: [{
+    activityId: "69384669b7826c5d9ec4e07c",  // WRONG KEY
+    fields: { "fieldId123": 78 }
+  }]
+});
+// Error: activities.0._id: Required
+
+// WRONG - Passing object for numericunit field
+update_activity({
+  activityId: "69384669b7826c5d9ec4e07c",
+  fields: {
+    "weightFieldId": { "type": "numericunit", "value": 78 }  // WRONG FORMAT
+  }
+});
+// Error: "Weight" must be a number
+
+// WRONG - Empty list_activities call
+list_activities({});
+// Error: workflowId: Required, phaseId: Required
+```
+</examples>

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

@@ -0,0 +1,92 @@
+---
+name: tool-response-verification
+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
+---
+
+# 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
+
+```
+BAD: Call create_activity → immediately return {"status": "success", "created": 1}
+BAD: "I created the customer" (without checking result)
+```
+
+## Example 3: Correct - Error Reporting
+
+When tools fail, report the actual error:
+
+```json
+{
+  "status": "error",
+  "result": { "tool": "tool_name", "error": "actual error message" },
+  "summary": "Tool failed: brief reason"
+}
+```
+</examples>