@hailer/mcp 0.0.6 → 0.1.1

package/.claude/skills/SDK-create-function-field-skill/SKILL.md

@@ -1,313 +0,0 @@
----
-name: Create Function Field (Local Config)
-description: Add new calculated function fields to workflows using hailer-sdk local config - use when MCP tools cannot create new fields
----
-
-# Create Function Field via Local Config
-
-## When to Use This Skill
-
-Use this when you need to **create a NEW function field** in an existing workflow.
-
-| Method | Creates New Fields | Updates Existing |
-|--------|-------------------|------------------|
-| `update_workflow_field` (MCP) | ❌ No | ✅ Yes |
-| Local config + `ws-fields-push` | ✅ Yes | ✅ Yes |
-
-**MCP limitation**: The `update_workflow_field` tool can only modify existing fields, not create new ones.
-
----
-
-## Prerequisites
-
-1. **Local workspace config** pulled via `hailer-sdk ws-config pull`
-2. **Workspace directory** structure:
-   ```
-   workspace/
-   ├── workflow_name_id/
-   │   ├── main.ts
-   │   ├── fields.ts
-   │   ├── phases.ts
-   │   └── functions/
-   │       ├── index.ts
-   │       └── existing_function.ts
-   └── enums.ts
-   ```
-
----
-
-## Step-by-Step Process
-
-### 1. Create Function File
-
-Create `workspace/[workflow]/functions/[function_name].ts`:
-
-```typescript
-/**
- * Field function for: Goals Per 90
- * Formula: (goals / minutesPlayed) * 90
- */
-
-interface Dependencies {
-  goals: number;
-  minutesPlayed: number;
-}
-
-export function goals_per_90(dep: Dependencies): number {
-  const goals = dep.goals || 0;
-  const minutes = dep.minutesPlayed || 0;
-
-  if (minutes === 0) return 0;
-
-  return Math.round(((goals / minutes) * 90) * 100) / 100;
-}
-```
-
-### 2. Export in index.ts
-
-Update `workspace/[workflow]/functions/index.ts`:
-
-```typescript
-export { existing_function } from "./existing_function";
-export { goals_per_90 } from "./goals_per_90";  // Add this line
-```
-
-### 3. Add Field to fields.ts
-
-Add to `workspace/[workflow]/fields.ts`:
-
-```typescript
-// ⚠️ CRITICAL: Do NOT include _id for new fields!
-{
-  // NO _id - SDK will create it
-  data: [],
-  function: "@function:goals_per_90",
-  functionEnabled: true,
-  functionVariables: {
-    goals: {
-      data: [
-        Workflow_FieldIds.goals_696  // Use enum reference
-      ],
-      type: "="
-    },
-    minutesPlayed: {
-      data: [
-        Workflow_FieldIds.minutes_played_698
-      ],
-      type: "="
-    }
-  },
-  key: "goalsPer90",
-  label: "Goals Per 90",
-  type: "numeric"
-}
-```
-
-### 4. Push Fields
-
-```bash
-npm run ws-fields-push
-```
-
-### 5. Pull to Sync
-
-```bash
-npm run ws-pull
-```
-
-This will:
-- Generate the real field ID
-- Rename function file to include ID suffix (e.g., `goals_per_90_a2e.ts`)
-- Update enums.ts with new field ID
-- Update all references
-
-### 6. Push Workflow (if needed)
-
-After pull, the field will be added to `phases.ts` and `main.ts` automatically. If not, add manually and push:
-
-```bash
-npm run ws-workflows-push
-npm run ws-phases-push
-```
-
----
-
-## Common Errors & Solutions
-
-### Error: "ObjectId must only contain hexadecimal characters"
-
-**Cause**: You included an `_id` with invalid format
-
-```typescript
-// ❌ WRONG
-{ _id: "goals_per_90", label: "Goals Per 90", ... }
-
-// ❌ WRONG
-{ _id: "000000000000000000000001", label: "Goals Per 90", ... }
-
-// ✅ CORRECT - omit _id entirely
-{ label: "Goals Per 90", key: "goalsPer90", ... }
-```
-
-### Error: "No matching remote field found, skipping update"
-
-**Cause**: SDK is trying to update but field doesn't exist
-
-**Solution**: Ensure you omitted `_id` - the SDK creates new fields only when `_id` is missing
-
-### Error: "New field order doesn't match process fields"
-
-**Cause**: `fieldsOrder` in `main.ts` references a field that doesn't exist yet
-
-**Solution**:
-1. Push fields first: `npm run ws-fields-push`
-2. Pull to get IDs: `npm run ws-pull`
-3. Then push workflow: `npm run ws-workflows-push`
-
-### Error: "Invalid Login Data"
-
-**Cause**: Credentials expired or incorrect
-
-**Solution**: Update password in `.env` file:
-```
-HAILER_PASSWORD="your-new-password"
-```
-
-### Duplicate Fields Created
-
-**Cause**: Multiple push attempts before pull
-
-**Solution**:
-1. Pull to see current state: `npm run ws-pull`
-2. Remove duplicate from `fields.ts`
-3. Push with deletion: `echo "Y" | npm run ws-push`
-4. Pull again to sync
-
----
-
-## Function Field Structure
-
-### functionVariables Format
-
-```typescript
-functionVariables: {
-  variableName: {
-    data: ["field-id"],  // Array with source field ID
-    type: "="            // "=" means same activity
-  }
-}
-```
-
-### Accessing Dependencies
-
-In function code, use `dep.variableName`:
-
-```typescript
-export function my_function(dep: Dependencies): number {
-  return (dep.goals || 0) + (dep.assists || 0);
-}
-```
-
-### Return Types
-
-| Field Type | Return |
-|------------|--------|
-| `numeric` | `number` |
-| `text` | `string` |
-| `date` | `number` (timestamp) |
-
----
-
-## Complete Example: Goals Per 90
-
-### 1. Function File
-`functions/goals_per_90.ts`:
-```typescript
-interface Dependencies {
-  goals: number;
-  minutesPlayed: number;
-}
-
-export function goals_per_90(dep: Dependencies): number {
-  const goals = dep.goals || 0;
-  const minutes = dep.minutesPlayed || 0;
-  if (minutes === 0) return 0;
-  return Math.round(((goals / minutes) * 90) * 100) / 100;
-}
-```
-
-### 2. Index Export
-`functions/index.ts`:
-```typescript
-export { goals_per_90 } from "./goals_per_90";
-```
-
-### 3. Field Definition
-`fields.ts`:
-```typescript
-{
-  data: [],
-  function: "@function:goals_per_90",
-  functionEnabled: true,
-  functionVariables: {
-    goals: {
-      data: [Player_Statistics_FieldIds.goals_696],
-      type: "="
-    },
-    minutesPlayed: {
-      data: [Player_Statistics_FieldIds.minutes_played_698],
-      type: "="
-    }
-  },
-  key: "goalsPer90",
-  label: "Goals Per 90",
-  type: "numeric"
-}
-```
-
-### 4. Commands
-```bash
-npm run ws-fields-push    # Create field
-npm run ws-pull           # Sync IDs
-npm run ws-push           # Update workflow/phases
-```
-
----
-
-## Post-Creation
-
-After successful creation:
-
-1. **Function file renamed**: `goals_per_90.ts` → `goals_per_90_a2e.ts`
-2. **Enum generated**: `Player_Statistics_FieldIds.goals_per_90_a2e`
-3. **Real ID assigned**: `692809f415a6def7ba29da2e`
-
-Use the enum in your code for type safety:
-```typescript
-Player_Statistics_FieldIds.goals_per_90_a2e
-```
-
----
-
-## Workflow Summary
-
-```
-1. Create function file     → functions/my_function.ts
-2. Export in index.ts       → export { my_function }
-3. Add to fields.ts         → NO _id, include functionVariables
-4. ws-fields-push           → Creates field in Hailer
-5. ws-pull                  → Syncs real IDs back
-6. ws-push                  → Updates workflow order
-```
-
----
-
-## Key Rules
-
-| Rule | Why |
-|------|-----|
-| **Omit `_id` for new fields** | SDK creates ID on push |
-| **Push fields before workflow** | fieldsOrder must reference existing fields |
-| **Always pull after push** | Syncs real IDs to local config |
-| **Use enums after pull** | Type-safe field references |
-| **Function name = export name** | `@function:name` matches `export function name` |

package/.claude/skills/SDK-generate-skill/SKILL.md

@@ -1,223 +0,0 @@
----
-name: TypeScript Types Generation
-description: Generate TypeScript enums and types from Hailer workspace - workflows, phases, fields, and optional insight types
----
-
-# `hailer-sdk generate`
-
-Generate TypeScript enums and types from your Hailer workspace.
-
-## Usage
-
-```bash
-hailer-sdk generate [options]
-```
-
-**Alias:** `gen`
-
-## Description
-
-The `generate` command creates TypeScript enums and types from your Hailer workspace. It generates a single `hailer-types.ts` file containing:
-
-- **Workflow enums** - All workflows in the workspace
-- **Phase enums** - Phases for each workflow
-- **Field enums** - Fields for each workflow (excludes subheaders and fields without labels)
-- **Insight types** (optional) - TypeScript types inferred from insight data
-
-## Options
-
-| Option | Alias | Required | Description |
-|--------|-------|----------|-------------|
-| `--output <path>` | `-o` | ✅ | Output directory for generated files |
-| `--email <email>` | `-e` | * | Hailer account email |
-| `--password <password>` | `-p` | * | Hailer account password |
-| `--workspace <id>` | `-w` | * | Workspace ID |
-| `--insights <file>` | `-i` | | Path to JSON file with insights array (optional) |
-| `--ids` | | | Use IDs instead of names/keys as enum values |
-| `--verbose` | | | Show detailed logging |
-
-\* Credentials can be provided via CLI options or `config.json` file
-
-## Understanding the `--ids` Flag
-
-The `--ids` flag controls what values are used in the generated enums:
-
-### Without `--ids` (default)
-
-Uses human-readable names and keys:
-
-```typescript
-export enum MyWorkspace_Workflows {
-  SalesPipeline = "Sales Pipeline",
-  CustomerSupport = "Customer Support",
-}
-
-export enum MyWorkspace_SalesPipeline_Fields {
-  customer_name = "customer_name",  // Uses field.key
-  deal_value = "deal_value",
-}
-
-export enum MyWorkspace_SalesPipeline_Phases {
-  Lead = "Lead",            // Uses phase.name
-  Negotiation = "Negotiation",
-}
-```
-
-### With `--ids`
-
-Uses Hailer internal IDs:
-
-```typescript
-export enum MyWorkspace_Workflows {
-  SalesPipeline = "507f1f77bcf86cd799439011",
-  CustomerSupport = "507f191e810c19729de860ea",
-}
-
-export enum MyWorkspace_SalesPipeline_Fields {
-  customer_name = "507f1f77bcf86cd799439012",  // Uses field._id
-  deal_value = "507f1f77bcf86cd799439013",
-}
-
-export enum MyWorkspace_SalesPipeline_Phases {
-  Lead = "507f1f77bcf86cd799439014",    // Uses phase._id
-  Negotiation = "507f1f77bcf86cd799439015",
-}
-```
-
-
-## Field Filtering
-
-The generator automatically **excludes** certain fields:
-
-1. **Subheaders** - Fields with `type: "subheader"` (visual separators, not data fields)
-2. **Fields without keys** - When `--ids` is not used, fields must have a `key` property
-3. **Fields without labels** - All fields must have a `label` property
-
-## How Insights Work
-
-- If you provide `--insights <file>`, the generator will include insight types in the output
-- If you don't provide `--insights`, only workflow/phase/field enums are generated
-- The types of the each individual insight's property is decided based on the value returned when fetched the insight. It can be a `string`, `number`, `boolean`, `null`, `any` or an array of each of previously mentioned types.
-
-## Examples
-
-### Basic usage - Generate workflow enums only
-
-```bash
-hailer-sdk generate -e email@example.com -p password -w workspace-id -o ./src/types
-```
-
-**Generates:** Workflow, phase, and field enums
-
-### Generate with IDs instead of names
-
-```bash
-hailer-sdk generate -e email@example.com -p password -w workspace-id -o ./src/types --ids
-```
-
-**Generates:** Same enums but with internal IDs as values
-
-### Generate workflows + insights types
-
-```bash
-hailer-sdk generate -e email@example.com -p password -w workspace-id -o ./output --insights ./insights.json
-```
-
-**Generates:** Workflow enums + insight types (both included)
-
-### Using config.json for credentials
-
-```bash
-# Reads credentials from config.json in current directory
-hailer-sdk generate -o ./types
-```
-
-### Verbose output
-
-```bash
-hailer-sdk generate -o ./types --verbose
-```
-
-**Shows:** Detailed information about each workflow being processed
-
-## Insights File Format
-
-If you want to generate insight types, provide a JSON file with this format:
-
-```json
-[
-  {
-    "id": "insight-id-1",
-    "name": "My Insight"
-  },
-  {
-    "id": "insight-id-2",
-    "name": "Another Insight"
-  }
-]
-```
-
-## Generated Files
-
-The command generates TypeScript file in your specified output directory:
-
-- `hailer-types.ts` - Contains all generated enums and types
-
-## Credentials Resolution
-
-Credentials are resolved in this order (highest priority first):
-
-1. CLI options (`--email`, `--password`, `--workspace`)
-2. `config.json` file in current directory
-
-## Generated Output Structure
-
-The command generates a single `hailer-types.ts` file with this structure:
-
-```typescript
-/**
- * All workflows/datasets in the MyWorkspace workspace
- * @generated This enum is auto-generated. Do not edit manually.
- */
-export enum MyWorkspace_Workflows {
-  SalesPipeline = "Sales Pipeline",
-  // ... more workflows
-}
-
-/**
- * Phases for Sales Pipeline workflow
- * @generated This enum is auto-generated. Do not edit manually.
- */
-export enum MyWorkspace_SalesPipeline_Phases {
-  Lead = "Lead",
-  Qualified = "Qualified",
-  // ... more phases
-}
-
-/**
- * Fields for Sales Pipeline workflow
- * Values are names of the fields
- * @generated This enum is auto-generated. Do not edit manually.
- */
-export enum MyWorkspace_SalesPipeline_Fields {
-  customer_name = "customer_name",
-  deal_value = "deal_value",
-  // ... more fields
-}
-
-// Insight types (if --insights provided)
-export type MyInsight = {
-  "Column1": string;
-  "Column2": number;
-  // ... inferred from data
-};
-```
-
-## Notes
-
-- The generated enums provide type-safe references to workflow, field, and phase IDs
-- Insights are optional - simply omit `--insights` to generate only workflows
-- All generated types include `@generated` JSDoc comments indicating they're auto-generated
-- Enum keys are sanitized (special characters removed, spaces replaced with underscores)
-- Generated file is always named `hailer-types.ts` in the output directory
-- Re-run the command anytime to regenerate types with latest workspace data

package/.claude/skills/SDK-init-skill/SKILL.md

@@ -1,177 +0,0 @@
----
-name: Project Initialization
-description: Complete guide to initializing Hailer projects with hailer-sdk init - project setup, bot accounts, and MCP server configuration
----
-
-# `hailer-sdk init`
-
-Initialize a new Hailer project with proper structure and configuration.
-
-## Usage
-
-```bash
-hailer-sdk init
-```
-
-## Description
-
-The `init` command is an interactive wizard that guides you through setting up a new Hailer project. It handles authentication, workspace selection, optional bot account creation, optional MCP server setup, and creates all necessary project files and configurations.
-
-## Interactive Steps
-
-1. **Project name** - Choose a name for your project
-2. **Email** - Enter your Hailer account email
-3. **Password** - Enter your Hailer account password
-4. **Workspace selection** - Choose from your available workspaces or create a new one
-5. **Bot account creation** - Optionally create a bot user for automated workspace operations
-6. **MCP server setup** - Optionally set up the Model Context Protocol server for Claude Code integration
-
-## What it Creates
-
-The command generates a complete project structure:
-
-```
-my-project/
-├── workspace/           # Workflow configurations will be generated here
-├── .claude/            # Claude Code configuration (if MCP enabled)
-├── .mcp.json           # MCP configuration (if MCP enabled)
-├── .env.local          # MCP server credentials (if MCP enabled)
-├── docs/               # Copy of SDK documentation
-├── .env                # Environment variables (password)
-├── .gitignore          # Excludes .env and other sensitive files
-├── config.json         # Workspace configuration
-├── package.json        # Node.js project configuration with useful scripts
-├── tsconfig.json       # TypeScript configuration
-├── CLAUDE.md           # Claude Code instructions
-└── README.md           # Project documentation
-```
-
-### Generated npm scripts
-
-The `package.json` includes these helpful scripts:
-
-**Workspace Management:**
-- `npm run pull` - Pull workflows from Hailer
-- `npm run push` - Push all configurations to Hailer
-- `npm run workflows-push` - Push only workflow configurations
-- `npm run workflows-sync` - Create/delete workflows
-- `npm run fields-push` - Push only field configurations
-- `npm run phases-push` - Push only phase configurations
-- `npm run groups-push` - Push only group configurations
-- `npm run teams-push` - Push only team configurations
-- `npm run insights-push` - Push only insights configurations
-
-**MCP Server (if enabled):**
-- `npm run mcp-start` - Start the MCP server
-- `npm run mcp-update` - Update @hailer/mcp package and refresh .claude directory
-
-## Bot Account (Optional)
-
-During initialization, you can choose to create a bot account for your workspace. The bot account:
-
-- Is created with email pattern: `{workspace}_{timestamp}@botinen.fi`
-- Gets a randomly generated secure password (32 characters)
-- Is added to a "Bots" team in your workspace (created if it doesn't exist)
-- Has "owner" role for full workspace access
-- Its credentials replace your personal credentials in the project's `.env` file
-
-**This is useful for:**
-- Separating bot actions from personal user actions
-
-**Note:** The bot credentials are displayed once during initialization. But you can see the bot's email in the `config.json` file and the password in `.env` file.
-
-## MCP Server Setup (Optional)
-
-The MCP (Model Context Protocol) server enables Claude Code to interact with your Hailer workspace programmatically.
-
-When enabled, the initialization:
-- Installs `@hailer/mcp` npm package as a dev dependency
-- Creates `.mcp.json` with MCP server connection configuration
-- Creates `.env.local` with client credentials
-- Adds a `postinstall` script that automatically copies `.claude/` directory from `@hailer/mcp` package
-- Adds MCP-specific npm scripts to `package.json`
-
-### Starting the MCP Server
-
-After initialization and installing dependencies:
-
-```bash
-cd my-project
-npm install
-npm run mcp-start
-```
-
-The `npm install` step will automatically:
-- Install all dependencies including `@hailer/mcp`
-- Run the `postinstall` script to copy `.claude/` configuration
-
-Then open a new terminal and start Claude Code to interact with your workspace through the MCP server.
-
-### Updating the MCP Server
-
-To get the latest version of the MCP server:
-
-```bash
-npm run mcp-update
-```
-
-This will:
-- Update `@hailer/mcp` to the latest version
-- Run the `postinstall` script to refresh `.claude/` configuration
-
-**Note:** After updating, restart the MCP server and any running Claude Code agents that depend on it.
-
-## Next Steps
-
-After initialization:
-
-1. Navigate to your project:
-   ```bash
-   cd my-project
-   npm install
-   ```
-
-2. Pull your workspace configuration:
-   ```bash
-   npm run pull
-   ```
-
-3. (Optional) If you set up the MCP server, start it:
-   ```bash
-   npm run mcp-start
-   ```
-
-4. Start developing with type-safe workflow definitions!
-
-## Notes
-
-- The `.env` file contains your credentials - **never commit this to version control**
-- The `.env.local` file (if MCP enabled) contains MCP server credentials - also git-ignored
-- The generated `.gitignore` automatically excludes `.env`, `.env.local`, and `.claude/` for safety
-- Type definitions are copied to your project for IDE support
-- Bot credentials are displayed only once during initialization - save them securely!
-- The MCP server is installed as an npm package (`@hailer/mcp`) in your `node_modules/`
-
-## Troubleshooting
-
-### MCP Server Setup Fails
-
-If the MCP server setup fails during initialization:
-- Check your network connection (npm package must be downloaded)
-- Ensure you have Node.js 18+ installed
-- Verify that `@hailer/mcp` package is available on npm
-- Try running `npm install` manually after initialization to trigger the `postinstall` script
-
-### Bot Account Creation Fails
-
-If bot account creation fails:
-- You can continue with your personal credentials
-- The project will still be initialized successfully
-- You can manually create a bot account later through the Hailer UI
-
-### Workspace Creation Fails
-
-If creating a new workspace fails:
-- Select an existing workspace instead
-- Check your account permissions
-- Verify your network connection