@hailer/mcp 0.0.6 → 0.1.1

package/.claude/skills/MCP-insight-api/SKILL.md

@@ -1,185 +0,0 @@
----
-name: Insight API Reference
-description: Complete reference for Hailer Insight API (SQL-like reporting over workflow data) - use when building insight-related MCP tools
----
-
-# Insight API Reference Skill
-
-This skill provides comprehensive documentation for Hailer Insight API endpoints. Insights are SQL-like reports that query activity data from workflows, with support for joins across multiple workflows.
-
-## When to Use This Skill
-
-Invoke this skill when:
-- Building insight/reporting MCP tools
-- Creating SQL queries over workflow data
-- Working with cross-workflow data analysis
-- Implementing data visualization features
-- Managing insight permissions and sharing
-
-## What are Insights?
-
-**Insights = SQL queries over Hailer workflow data**
-
-Think of it as:
-- **Workflows** = Database tables
-- **Activities** = Rows in those tables
-- **Fields** = Columns in those tables
-- **Insights** = SQL SELECT queries with JOINs
-
-## Quick Navigation
-
-### Core Insight Operations
-- **v3.insight.create** - Create new insight with SQL query
-- **v3.insight.update** - Update existing insight
-- **v3.insight.list** - List all insights in workspace
-- **v3.insight.data** - Get query results (execute the SQL)
-- **v3.insight.preview** - Preview insight while designing (debugging)
-- **v3.insight.remove** - Delete an insight
-
-### Insight Management
-- **v3.insight.copy** - Duplicate an insight
-- **v3.insight.public** - Get public insight data (shared insights)
-- **v3.insight.member.add** - Add member permissions
-- **v3.insight.member.remove** - Remove member permissions
-
-## Key Concepts
-
-### Insight Structure
-
-```javascript
-{
-  name: 'Insight Name',
-  public: false,  // Whether insight is publicly accessible
-  sources: [
-    {
-      name: 'books',           // Table alias for SQL
-      workflowId: '<id>',      // Which workflow to query
-      fields: [
-        { name: 'title', meta: 'name' },      // Activity name
-        { name: 'publishDate', fieldId: '<fieldId>' }  // Custom field
-      ]
-    }
-  ],
-  query: 'SELECT title, publishDate FROM books'  // Standard SQL
-}
-```
-
-### Field References
-
-**Meta fields** (built-in):
-- `meta: '_id'` - Activity ID (for JOINs)
-- `meta: 'uid'` - User ID (creator)
-- `meta: 'team'` - Owner team ID
-- `meta: 'createdBy'` - Creator user ID
-- `meta: 'name'` - Activity name/title
-- `meta: 'created'` - Creation timestamp
-- `meta: 'updated'` - Last update timestamp
-- `meta: 'phaseId'` - Current phase ID
-- `meta: 'phaseName'` - Current phase name
-- `meta: 'phaseLastMove'` - Last phase change timestamp
-- `meta: 'workflowId'` - Workflow ID
-- `meta: 'workflowName'` - Workflow name
-- `meta: 'priority'` - Activity priority
-
-**Custom fields**:
-- `fieldId: '<fieldId>'` - Reference a workflow field by ID
-
-### SQL Query Support
-
-- Standard SELECT syntax
-- JOINs across multiple workflows
-- WHERE clauses
-- GROUP BY, ORDER BY
-- Aggregation functions (COUNT, SUM, AVG, etc.)
-
-## Common Use Cases
-
-1. **Single Workflow Report**: Query activities from one workflow
-2. **Cross-Workflow Join**: Join data from related workflows (via ActivityLinks)
-3. **Aggregated Reports**: COUNT, SUM, AVG across activities
-4. **Filtered Views**: WHERE clauses to filter activity data
-5. **Public Dashboards**: Share insights publicly with `public: true`
-
-## Documentation
-
-See [Insight API Endpoints](references/insight-endpoints.md) for complete endpoint documentation with request/response schemas and examples.
-
-## MCP Tool Building Rules
-
-When building Insight MCP tools:
-
-1. **Use PlaygroundTools.ts** for testing first
-2. **Follow the three-part pattern**:
-   - Description method (with SQL examples)
-   - Schema method (Zod validation)
-   - Handler method (implementation)
-3. **Use HailerApiClient** with socket calls
-4. **Validate SQL queries** before sending (basic syntax check)
-5. **Format responses** as markdown tables for readability
-6. **Handle permissions** - only workspace admins can modify sources
-
-## Example Patterns
-
-### Simple Report
-```javascript
-create_insight({
-  name: 'All Books',
-  sources: [{
-    name: 'books',
-    workflowId: bookWorkflowId,
-    fields: [
-      { name: 'title', meta: 'name' },
-      { name: 'author', fieldId: authorFieldId }
-    ]
-  }],
-  query: 'SELECT title, author FROM books'
-})
-```
-
-### Cross-Workflow Join
-```javascript
-create_insight({
-  name: 'Books with Authors',
-  sources: [
-    {
-      name: 'books',
-      workflowId: bookWorkflowId,
-      fields: [
-        { name: 'title', meta: 'name' },
-        { name: 'authorId', fieldId: authorLinkFieldId }
-      ]
-    },
-    {
-      name: 'authors',
-      workflowId: authorWorkflowId,
-      fields: [
-        { name: 'id', meta: '_id' },
-        { name: 'authorName', meta: 'name' }
-      ]
-    }
-  ],
-  query: `
-    SELECT books.title, authors.authorName
-    FROM books
-    LEFT JOIN authors ON books.authorId = authors.id
-  `
-})
-```
-
-## Preview vs Execute
-
-**v3.insight.preview**:
-- Used during design/debugging
-- Limited to ~20 activities for performance
-- Can be called frequently
-- Shows errors in SQL syntax
-
-**v3.insight.data**:
-- Executes full query on all activities
-- Returns complete results
-- Use after insight is finalized
-
-## Next Steps
-
-For complete endpoint documentation with request/response schemas and SQL examples, see:
-- [Insight API Endpoints](references/insight-endpoints.md) - All v3.insight.* endpoints

package/.claude/skills/MCP-insight-api/references/insight-endpoints.md

@@ -1,514 +0,0 @@
-# Insight API Endpoints Reference
-
-Complete reference for Hailer Insight API endpoints. Insights provide SQL-like reporting over workflow/activity data.
-
-## Table of Contents
-
-- [v3.insight.create](#v3insightcreate) - Create new insight
-- [v3.insight.update](#v3insightupdate) - Update existing insight
-- [v3.insight.copy](#v3insightcopy) - Copy/duplicate an insight
-- [v3.insight.remove](#v3insightremove) - Delete an insight
-- [v3.insight.list](#v3insightlist) - List all insights
-- [v3.insight.public](#v3insightpublic) - Get public insight data
-- [v3.insight.data](#v3insightdata) - Execute insight query and get results
-- [v3.insight.preview](#v3insightpreview) - Preview insight during design
-- [v3.insight.member.add](#v3insightmemberadd) - Add member permissions
-- [v3.insight.member.remove](#v3insightmemberremove) - Remove member permissions
-
----
-
-## Prerequisites
-
-Before using Insights:
-1. Must have workflows created with activities
-2. Understand workflow schema (field IDs, field types)
-3. Basic SQL knowledge (SELECT, JOIN, WHERE, etc.)
-4. Use `v3.insight.preview` while designing to test queries
-
----
-
-## v3.insight.create
-
-Create new Insight with SQL query over workflow data.
-
-**Endpoint**: `POST /v3/insight/create`
-
-**Request Body**:
-```json
-{
-  "0": "stringstringstringstring",  // workspaceId
-  "1": {
-    "name": "string",
-    "public": false,
-    "sources": [
-      {
-        "name": "tableName",        // SQL table alias
-        "workflowId": "workflowId", // Which workflow to query
-        "fields": [
-          { "name": "columnName", "meta": "name" },       // Activity name
-          { "name": "columnName", "fieldId": "fieldId" }  // Custom field
-        ]
-      }
-    ],
-    "query": "SELECT columnName FROM tableName"  // SQL query
-  }
-}
-```
-
-**Example 1 - Single Workflow**:
-```javascript
-v3.insight.create(
-  workspaceId,
-  {
-    name: 'Book Insights',
-    sources: [{
-      name: 'books',
-      workflowId: bookWorkflowId,
-      fields: [
-        { name: 'title', meta: 'name' },           // Activity name
-        { name: 'publishDate', fieldId: fieldId }   // Custom field
-      ]
-    }],
-    query: 'SELECT title, publishDate FROM books',
-  }
-)
-```
-
-**Example 2 - Join Two Workflows**:
-```javascript
-v3.insight.create(
-  workspaceId,
-  {
-    name: 'Books with Authors',
-    sources: [
-      {
-        name: 'books',
-        workflowId: bookWorkflowId,
-        fields: [
-          { name: 'title', meta: 'name' },
-          { name: 'author', fieldId: authorLinkFieldId }
-        ]
-      },
-      {
-        name: 'authors',
-        workflowId: authorWorkflowId,
-        fields: [
-          { name: 'id', meta: '_id' },          // Activity ID
-          { name: 'authorName', meta: 'name' },  // Activity Name
-          { name: 'born', fieldId: bornFieldId }
-        ]
-      }
-    ],
-    query: `
-      SELECT title, publishDate, authorName
-      FROM authors
-      LEFT JOIN books ON books.author = authors.id
-    `
-  }
-)
-```
-
-**Meta Fields** (built-in activity properties):
-- `meta: 'name'` - Activity name
-- `meta: '_id'` - Activity ID
-- `meta: 'created'` - Creation timestamp
-- `meta: 'updated'` - Last update timestamp
-- `meta: 'phase'` - Current phase ID
-- `meta: 'team'` - Owner team ID
-
-**Response**:
-```json
-{
-  "code": 0,
-  "msg": "string",
-  "details": {
-    "insightId": "stringstringstringstring"
-  },
-  "debug": null
-}
-```
-
----
-
-## v3.insight.update
-
-Update an existing insight (name, query, sources, permissions, etc.).
-
-**Endpoint**: `POST /v3/insight/update`
-
-**Request Body**:
-```json
-{
-  "0": "stringstringstringstring",  // insightId
-  "1": {
-    "name": "string",
-    "public": true,
-    "sources": [],
-    "query": "string",
-    "presets": []
-  }
-}
-```
-
-**Note**: Only workspace admins can modify `sources`. Regular users with edit permission can only update `name`, `query`, and `presets` if sources remain unchanged.
-
-**Response**:
-```json
-{
-  "code": 0,
-  "msg": "string",
-  "details": {},
-  "debug": null
-}
-```
-
----
-
-## v3.insight.copy
-
-Duplicate an existing insight.
-
-**Endpoint**: `POST /v3/insight/copy`
-
-**Request Body**:
-```json
-{
-  "0": "stringstringstringstring",  // insightId to copy
-  "1": {
-    "name": "Copy of Original Insight"
-  }
-}
-```
-
-**Response**:
-```json
-{
-  "code": 0,
-  "msg": "string",
-  "details": {
-    "insightId": "stringstringstringstring"  // New insight ID
-  },
-  "debug": null
-}
-```
-
----
-
-## v3.insight.remove
-
-Delete an insight.
-
-**Endpoint**: `POST /v3/insight/remove`
-
-**Request Body**:
-```json
-{
-  "0": "stringstringstringstring"  // insightId
-}
-```
-
-**Response**:
-```json
-{
-  "code": 0,
-  "msg": "string",
-  "details": {},
-  "debug": null
-}
-```
-
----
-
-## v3.insight.list
-
-List all insights in a workspace that the user has access to.
-
-**Endpoint**: `POST /v3/insight/list`
-
-**Request Body**:
-```json
-{
-  "0": "stringstringstringstring"  // workspaceId
-}
-```
-
-**Response**:
-```json
-{
-  "code": 0,
-  "msg": "string",
-  "details": {
-    "insights": [
-      {
-        "_id": "stringstringstringstring",
-        "name": "Insight Name",
-        "public": false,
-        "sources": [],
-        "query": "SELECT ...",
-        "created": 1234567890,
-        "updated": 1234567890
-      }
-    ]
-  },
-  "debug": null
-}
-```
-
----
-
-## v3.insight.public
-
-Get public data for a publicly shared insight (no authentication required).
-
-**Endpoint**: `POST /v3/insight/public`
-
-**Request Body**:
-```json
-{
-  "0": "string"  // insightKey (max 32 chars)
-}
-```
-
-**Response**:
-```json
-{
-  "code": 0,
-  "msg": "string",
-  "details": {
-    "insight": {},
-    "data": []
-  },
-  "debug": null
-}
-```
-
----
-
-## v3.insight.data
-
-Execute the insight query and get results (actual data).
-
-**Endpoint**: `POST /v3/insight/data`
-
-**Request Body**:
-```json
-{
-  "0": "stringstringstringstring",  // insightId
-  "1": {
-    "update": true  // Whether to refresh/recalculate data
-  }
-}
-```
-
-**Response**:
-```json
-{
-  "code": 0,
-  "msg": "string",
-  "details": {
-    "columns": ["title", "publishDate", "authorName"],
-    "rows": [
-      ["Book 1", "2024-01-01", "Author A"],
-      ["Book 2", "2024-02-01", "Author B"]
-    ]
-  },
-  "debug": null
-}
-```
-
----
-
-## v3.insight.preview
-
-Preview partial insight during design. Used for testing SQL queries before saving.
-
-**Key Features**:
-- Can be called frequently during design
-- Returns errors if SQL is invalid
-- Limited to ~20 activities for performance
-- Workspace admins can modify sources
-- Regular users cannot change sources (security)
-
-**Endpoint**: `POST /v3/insight/preview`
-
-**Request Body**:
-```json
-{
-  "0": "stringstringstringstring",  // workspaceId
-  "1": {
-    "query": "SELECT title FROM books WHERE publishDate > '2024-01-01'",
-    "sources": [
-      {
-        "name": "books",
-        "workflowId": "workflowId",
-        "fields": [
-          { "name": "title", "meta": "name" },
-          { "name": "publishDate", "fieldId": "fieldId" }
-        ]
-      }
-    ]
-  }
-}
-```
-
-**Response** (success):
-```json
-{
-  "code": 0,
-  "msg": "string",
-  "details": {
-    "columns": ["title"],
-    "rows": [
-      ["Book 1"],
-      ["Book 2"]
-    ],
-    "limited": true  // Indicates data was limited for preview
-  },
-  "debug": null
-}
-```
-
-**Response** (error):
-```json
-{
-  "code": 403,
-  "msg": "SQL syntax error near 'SELEC'",
-  "details": {},
-  "debug": null
-}
-```
-
----
-
-## v3.insight.member.add
-
-Add member permissions to an insight (user, team, workspace, or group).
-
-**Endpoint**: `POST /v3/insight.member.add`
-
-**Request Body**:
-```json
-{
-  "0": "stringstringstringstring",  // insightId
-  "1": "network_<networkId>"        // OR: team_<teamId>, user_<userId>, group_<groupId>
-}
-```
-
-**Member Format**:
-- Workspace: `network_<networkId>`
-- Team: `team_<teamId>`
-- User: `user_<userId>`
-- Group: `group_<groupId>`
-
-**Response**:
-```json
-{
-  "code": 0,
-  "msg": "string",
-  "details": {},
-  "debug": null
-}
-```
-
----
-
-## v3.insight.member.remove
-
-Remove member permissions from an insight.
-
-**Endpoint**: `POST /v3/insight.member.remove`
-
-**Request Body**:
-```json
-{
-  "0": "stringstringstringstring",  // insightId
-  "1": "user_<userId>"              // OR: network_<networkId>, team_<teamId>, group_<groupId>
-}
-```
-
-**Response**:
-```json
-{
-  "code": 0,
-  "msg": "string",
-  "details": {},
-  "debug": null
-}
-```
-
----
-
-## SQL Query Guidelines
-
-### Supported SQL Features
-- SELECT with column names or * (all)
-- FROM with table aliases (source names)
-- WHERE clauses with AND/OR
-- JOIN (INNER, LEFT, RIGHT, FULL)
-- GROUP BY with aggregations
-- ORDER BY with ASC/DESC
-- LIMIT and OFFSET
-
-### Common Patterns
-
-**Filter by phase**:
-```sql
-SELECT title FROM books WHERE phase = 'phaseId'
-```
-
-**Count activities**:
-```sql
-SELECT COUNT(*) as total FROM books
-```
-
-**Group and aggregate**:
-```sql
-SELECT author, COUNT(*) as bookCount
-FROM books
-GROUP BY author
-ORDER BY bookCount DESC
-```
-
-**Join workflows**:
-```sql
-SELECT b.title, a.name as authorName
-FROM books b
-LEFT JOIN authors a ON b.authorId = a.id
-WHERE b.publishDate > '2024-01-01'
-```
-
----
-
-## Common Response Format
-
-All endpoints return this format:
-
-```json
-{
-  "code": 0,        // 0 = success, 403 = error
-  "msg": "string",  // Success/error message
-  "details": {},    // Response data
-  "debug": null     // Optional debug info
-}
-```
-
----
-
-## Permissions
-
-**Workspace Admins**:
-- Create, update, delete insights
-- Modify insight sources
-- Share insights (make public)
-- Manage all insight permissions
-
-**Regular Users**:
-- View insights they have access to
-- Edit insights (name, query) if given permission
-- Cannot modify sources (security restriction)
-- Cannot change permissions
-
-**Public Insights**:
-- Accessible without authentication via `insightKey`
-- Read-only access
-- Good for public dashboards/reports