@hailer/mcp 1.1.11 → 1.1.13

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

@@ -1,250 +0,0 @@
----
-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,126 +0,0 @@
----
-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

@@ -1,92 +0,0 @@
----
-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>