@hailer/mcp 1.1.13 → 1.1.15

package/.claude/skills/lsp-setup/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: lsp-setup
+description: How to set up LSP (Language Server Protocol) for Claude Code - enables code intelligence for Lars and other agents
+version: 1.0.0
+triggers:
+  - LSP not available
+  - typescript-language-server
+  - code intelligence setup
+  - Lars can't find unused code
+---
+
+# LSP Setup for Claude Code
+
+LSP (Language Server Protocol) enables code intelligence features like go-to-definition, find-references, and accurate dead code detection.
+
+## Why LSP?
+
+Without LSP, agents like Lars must guess about code usage via grep/file reads. With LSP:
+- **Accurate dead code detection** - knows if exports are used elsewhere
+- **Type error detection** - without running compiler
+- **Find all references** - across entire codebase
+- **Go to definition** - jump to where symbols are defined
+
+## Requirements
+
+Three things needed for LSP to work:
+
+| Requirement | How to Check | How to Install |
+|-------------|--------------|----------------|
+| `ENABLE_LSP_TOOL=1` | Check `.claude/settings.json` | Add to env section |
+| `typescript-lsp` plugin | `claude plugin list` | `claude plugin install typescript-lsp@claude-plugins-official` |
+| Language server binary | `which typescript-language-server` | `npm install -g typescript-language-server typescript` |
+
+## Setup Steps
+
+### Step 1: Install the language server binary
+
+```bash
+npm install -g typescript-language-server typescript
+```
+
+Verify:
+```bash
+typescript-language-server --version
+# Should show version like: 5.1.3
+```
+
+### Step 2: Install Claude Code plugin
+
+```bash
+claude plugin install typescript-lsp@claude-plugins-official
+```
+
+Verify:
+```bash
+claude plugin list
+# Should show: typescript-lsp@claude-plugins-official ✔ enabled
+```
+
+### Step 3: Ensure settings.json has LSP enabled
+
+Check `.claude/settings.json` (project) or `~/.claude/settings.json` (global):
+
+```json
+{
+  "env": {
+    "ENABLE_LSP_TOOL": "1"
+  }
+}
+```
+
+### Step 4: Restart Claude
+
+LSP plugin activates on Claude restart:
+```bash
+claude -c
+```
+
+### Step 5: Test
+
+Ask Lars to find unused code in a TypeScript file:
+```
+Find unused code in src/App.tsx
+```
+
+Or test LSP directly:
+```
+Use LSP documentSymbol on src/App.tsx
+```
+
+## Supported File Types
+
+The `typescript-lsp` plugin supports:
+- `.ts`, `.tsx` - TypeScript + React
+- `.js`, `.jsx` - JavaScript + React
+- `.mts`, `.cts` - TypeScript ES modules / CommonJS
+- `.mjs`, `.cjs` - JavaScript ES modules / CommonJS
+
+## LSP Operations Available
+
+| Operation | Purpose |
+|-----------|---------|
+| `documentSymbol` | List all symbols in a file |
+| `findReferences` | Find all usages of a symbol |
+| `goToDefinition` | Jump to where symbol is defined |
+| `hover` | Get type info and documentation |
+| `goToImplementation` | Find implementations of interface |
+| `incomingCalls` | What calls this function |
+| `outgoingCalls` | What this function calls |
+| `prepareCallHierarchy` | Get call hierarchy at position |
+
+## Agents That Use LSP
+
+| Agent | How They Use LSP |
+|-------|------------------|
+| **Lars** | Primary user - dead code, unused imports, type errors |
+| **Svetlana** | Type checking during code review (optional) |
+| **Giuseppe** | Verify code compiles before build (optional) |
+
+## Troubleshooting
+
+### "No LSP server available"
+
+1. Check binary is installed: `which typescript-language-server`
+2. Check plugin is installed: `claude plugin list`
+3. Restart Claude: `claude -c`
+
+### LSP times out on first query
+
+Normal - language server is indexing the project. Wait a few seconds and retry.
+
+### LSP works for .ts but not .tsx
+
+Check `typescript` is installed alongside `typescript-language-server`:
+```bash
+npm install -g typescript-language-server typescript
+```
+
+### "Executable not found in $PATH"
+
+The binary isn't in your PATH. Either:
+- Install globally: `npm install -g typescript-language-server`
+- Or add npm global bin to PATH: `export PATH="$PATH:$(npm bin -g)"`
+
+## Without LSP (Fallback)
+
+If LSP isn't available, agents can fall back to:
+
+```bash
+# Type errors
+npx tsc --noEmit 2>&1
+
+# Unused variables (requires eslint config)
+npx eslint --rule '@typescript-eslint/no-unused-vars: error' src/
+
+# Find references (grep-based, less accurate)
+grep -r "functionName" src/
+```
+
+This is less accurate but works without setup.

package/.claude/skills/mcp-direct-tools/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: mcp-direct-tools
+description: Reference for MCP tools not assigned to agents
+version: 1.0.0
+---
+
+# MCP Direct Tools
+
+<purpose>
+Reference for MCP tools not assigned to agents. Load this skill when user requests direct tool usage or needs capabilities not covered by standard agents.
+</purpose>
+
+---
+
+## When to Load This Skill
+
+- User asks "can you use the bug fixer tools?"
+- User needs capabilities not covered by agents
+- Direct MCP tool access requested
+- Debugging/testing MCP tools
+
+---
+
+## Bug Fixer Tools (16 tools)
+
+Automated bug fixing suite for Hailer apps. Use these for automated debugging workflows.
+
+### Discovery & Analysis
+
+| Tool | Description | Parameters |
+|------|-------------|------------|
+| `bug_fixer_find_app` | Locate app by name | `{ appName }` |
+| `bug_fixer_analyze_bug` | Classify bug report | `{ bugReport, appId }` |
+
+### File Operations
+
+| Tool | Description | Parameters |
+|------|-------------|------------|
+| `bug_fixer_list_files` | List project files | `{ appId, path? }` |
+| `bug_fixer_read_file` | Read file content | `{ appId, filePath }` |
+| `bug_fixer_write_file` | Modify file content | `{ appId, filePath, content }` |
+| `bug_fixer_apply_fix` | Apply code patch | `{ appId, filePath, patch }` |
+
+### Build & Test
+
+| Tool | Description | Parameters |
+|------|-------------|------------|
+| `bug_fixer_run_build` | Execute build command | `{ appId }` |
+
+### Git Operations
+
+| Tool | Description | Parameters |
+|------|-------------|------------|
+| `bug_fixer_git_status` | Check git status | `{ appId }` |
+| `bug_fixer_git_pull` | Fetch latest code | `{ appId }` |
+| `bug_fixer_git_commit` | Commit changes | `{ appId, message }` |
+| `bug_fixer_git_push` | Push to remote | `{ appId }` |
+| `bug_fixer_git_revert` | Undo changes | `{ appId }` |
+
+### Workflow Management
+
+| Tool | Description | Parameters |
+|------|-------------|------------|
+| `bug_fixer_start_fix` | Begin fix workflow | `{ bugId, appId }` |
+| `bug_fixer_mark_declined` | Close as not-a-bug | `{ bugId, reason }` |
+| `bug_fixer_publish_fix` | Deploy to production | `{ appId, version }` |
+| `bug_fixer_retry_fix` | Attempt with new context | `{ bugId, newContext }` |
+
+### Bug Fixer Workflow
+
+```
+1. bug_fixer_find_app → Get app ID
+2. bug_fixer_analyze_bug → Classify issue
+3. bug_fixer_start_fix → Begin workflow
+4. bug_fixer_list_files → Find relevant files
+5. bug_fixer_read_file → Understand current code
+6. bug_fixer_write_file / bug_fixer_apply_fix → Make changes
+7. bug_fixer_run_build → Verify fix
+8. bug_fixer_git_commit → Save changes
+9. bug_fixer_publish_fix → Deploy
+```
+
+---
+
+## Insight Tools (Not in Viktor)
+
+Viktor uses `preview_insight` and `get_insight_data`. These additional tools are available:
+
+| Tool | Description | When to Use |
+|------|-------------|-------------|
+| `list_insights` | List all insights in workspace | Discovery, cleanup |
+| `update_insight` | Modify existing insight | Query changes |
+| `remove_insight` | Delete insight (NUCLEAR) | Cleanup |
+
+**Note:** SDK has equivalents via insights.ts push. Use SDK for version-controlled changes, MCP for quick fixes.
+
+---
+
+## Workflow Tools (PLAYGROUND/NUCLEAR)
+
+Direct workflow manipulation. Normally use Helga + SDK, but these exist for quick operations:
+
+| Tool | Description | Group |
+|------|-------------|-------|
+| `install_workflow` | Create workflow via MCP | PLAYGROUND |
+| `remove_workflow` | Delete workflow | NUCLEAR |
+| `update_workflow_field` | Modify field config | PLAYGROUND |
+| `update_workflow_phase` | Modify phase config | PLAYGROUND |
+| `test_function_field` | Test JS function | PLAYGROUND |
+
+**Warning:** NUCLEAR tools require `ENABLE_NUCLEAR_TOOLS=true` in MCP config.
+
+---
+
+## Tool Groups Reference
+
+| Group | Risk Level | Examples |
+|-------|------------|----------|
+| READ | Safe | list_activities, get_workflow_schema |
+| WRITE | Updates data | create_activity, add_discussion_message |
+| PLAYGROUND | Admin ops | install_workflow, update_workflow_field |
+| NUCLEAR | Destructive | remove_workflow, remove_app |
+| BOT_INTERNAL | Bots only | Not exposed to MCP clients |
+
+---
+
+## Usage Pattern
+
+When user requests direct tool usage:
+
+```
+User: "Use the bug fixer to fix this app"
+
+Orchestrator:
+1. Load this skill
+2. Call tools directly via mcp__hailer__<tool_name>
+3. Follow workflow patterns above
+4. Report results
+```
+
+---
+
+## Tools NOT Covered Here
+
+These are assigned to agents - use the agent instead:
+
+| Tool | Agent |
+|------|-------|
+| Activity CRUD | Dmitri |
+| Discussions | Yevgeni |
+| App scaffold/create | Giuseppe |
+| Insights preview/data | Viktor |
+| User search | Permissions Handler |

package/.claude/skills/optional-parameters/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: optional-parameters
+description: Omit optional parameters instead of passing empty values
+version: 1.0.0
+triggers: Tool error about empty array/string when parameter should be omitted
+---
+
+# Optional Parameters
+
+<purpose>
+Teach correct handling of optional tool parameters - OMIT them entirely when not needed, rather than passing empty arrays, strings, or null values.
+</purpose>
+
+<patterns>
+## Pattern 1: Omit vs Empty Value
+
+**Key distinction:**
+- **OMIT parameter**: Don't include it in the function call at all
+- **NOT same as empty value**: `[]`, `""`, `null`, `undefined` are NOT valid replacements for omission
+
+## Pattern 2: When to Omit
+
+- Updating insight public/name but NOT sources → omit sources
+- Updating activity field but NOT name → omit name
+- Any "required" schema parameter that's not relevant to current operation
+
+## Pattern 3: Rule of Thumb
+
+If you're not changing/using a value, OMIT the parameter entirely rather than passing empty/null.
+</patterns>
+
+<examples>
+## Example 1: Correct - Omitting Unused Parameters
+
+```typescript
+// Update insight - only changing public flag
+// sources parameter exists in schema but NOT needed for this update
+update_insight({
+  insightId: "abc123",
+  public: false
+  // sources: NOT included - omit entirely
+});
+
+// Update insight - changing sources
+update_insight({
+  insightId: "abc123",
+  sources: [{
+    name: 'tasks',
+    workflowId: 'wf123',
+    fields: [{ name: 'title', meta: 'name' }]
+  }]
+  // Include sources when actually updating them
+});
+```
+
+## Example 2: Wrong - Passing Empty Values
+
+```typescript
+// WRONG - Passing empty array when parameter should be omitted
+update_insight({
+  insightId: "abc123",
+  public: false,
+  sources: []  // Error: sources must contain at least 1 items
+});
+
+// WRONG - Passing empty string
+update_activity({
+  activityId: "xyz",
+  name: ""  // Error: name cannot be empty
+});
+```
+</examples>

package/.claude/skills/publish-hailer-app/SKILL.md

@@ -0,0 +1,221 @@
+---
+name: publish-hailer-app
+description: Guide for publishing Hailer apps to production
+version: 1.3.0
+triggers:
+  - publish app
+  - deploy app
+  - production app
+---
+
+# Publish Hailer App Skill
+
+Guide for publishing Hailer apps to production using MCP tools.
+
+<warning>
+## ⚠️ Publishing Requires Explicit User Request
+
+**Default is local development** — scaffold creates a dev app at `http://localhost:3000` automatically.
+
+**Only use this skill when the user explicitly asks to publish or deploy to production.**
+
+Before publishing: validate manifest.json (see below), then `publish_hailer_app` (auto-updates URL to production).
+</warning>
+
+<critical>
+## MANDATORY: Validate Before Publishing
+
+The `publish_hailer_app` tool will SILENTLY FAIL if manifest.json is misconfigured.
+
+**YOU MUST validate these before calling publish_hailer_app:**
+
+1. Read `public/manifest.json` in the project
+2. Check `appId` exists and is 24 characters
+3. Check `version` exists and is NOT empty (e.g., "1.0.0")
+4. Check `versionDescription` exists and is NOT empty
+
+If ANY are missing/empty, FIX THEM FIRST before publishing.
+</critical>
+
+<validation-code>
+## Validation Steps (DO THIS FIRST)
+
+```
+1. Read({file_path: "{projectDir}/public/manifest.json"})
+
+2. Verify JSON contains:
+   - "appId": "24-char-id"        ← If missing: use create_app first
+   - "version": "1.0.0"           ← If empty: set to "1.0.0"
+   - "versionDescription": "..."  ← If empty: set to "Initial release"
+
+3. If any field missing/empty → Edit manifest.json to fix
+
+4. ONLY THEN call publish_hailer_app
+```
+</validation-code>
+
+<workflow>
+## Full Publishing Workflow
+
+### Step 1: Validate & Fix manifest.json
+
+Read the manifest:
+```javascript
+Read({file_path: "{projectDir}/public/manifest.json"})
+```
+
+Required structure:
+```json
+{
+  "appId": "695816e2ba1d8bef3af7e018",
+  "version": "1.0.0",
+  "versionDescription": "Initial production release"
+}
+```
+
+**If appId missing:** Add the ID from Step 2
+**If version empty:** Set to "1.0.0"
+**If versionDescription empty:** Set to "Initial release"
+
+### Step 2: Publish
+
+```javascript
+publish_hailer_app({
+  projectDirectory: "/path/to/app"
+})
+```
+
+This does everything in one call:
+- Copies manifest.json into dist/
+- Creates .tgz with `package/` prefix (matches npm pack format)
+- Uploads to S3 via POST /app/publish
+- **Auto-updates app URL** to `https://apps.hailer.com/{workspaceId}/{appId}/`
+
+### Step 3: Verify
+
+```javascript
+list_apps()
+```
+Confirm URL is `https://apps.hailer.com/...` (not localhost).
+</workflow>
+
+<silent-failure>
+## Why Silent Failures Happen
+
+The SDK publish script requires `version` and `versionDescription` in manifest.json.
+If missing/empty, the tool returns "Success" but files are NOT uploaded.
+
+**Symptoms of silent failure:**
+- Tool says "App Published Successfully!"
+- But app URL is still `http://localhost:3000`
+- Or production URL returns 403/404
+
+**Always validate manifest BEFORE publishing.**
+</silent-failure>
+
+<dev-vs-prod>
+## Dev vs Production Apps
+
+| Type | URL | Created By | Purpose |
+|------|-----|------------|---------|
+| Dev | `http://localhost:3000` | `scaffold_hailer_app` (reuses existing) | Local development, always stays at localhost |
+| Prod | `https://apps.hailer.com/{workspaceId}/{appId}/` | `publish_hailer_app` (auto-created) | Published production app |
+
+**Flow:**
+1. `scaffold_hailer_app` checks for existing dev app at localhost:3000 — reuses it instead of creating duplicates
+2. Dev app stays at localhost forever — it's your development slot
+3. When user says "publish": `publish_hailer_app` detects the dev app URL, auto-creates a NEW production app entry, publishes to it, and updates the URL
+
+**No manual `update_app` or `create_app` needed.** The publish tool handles everything automatically.
+</dev-vs-prod>
+
+<updating>
+## Updating Published Apps
+
+1. Bump version in manifest.json:
+```json
+{
+  "version": "1.0.1",
+  "versionDescription": "Fixed data loading bug"
+}
+```
+
+2. Publish:
+```javascript
+publish_hailer_app({
+  projectDirectory: "/path/to/app"
+})
+```
+
+New version replaces old at same URL.
+</updating>
+
+<sharing>
+## Sharing Apps
+
+```javascript
+// Entire workspace
+add_app_member({ appId: "...", member: "network_{workspaceId}" })
+
+// Team
+add_app_member({ appId: "...", member: "team_{teamId}" })
+
+// User
+add_app_member({ appId: "...", member: "user_{userId}" })
+```
+</sharing>
+
+<vite-config>
+## CRITICAL: Vite Base Path
+
+Vite apps MUST have `base: './'` in vite.config.ts for production deployment.
+
+```typescript
+// vite.config.ts
+export default defineConfig({
+  base: './',  // REQUIRED for production
+  // ... other config
+});
+```
+
+**Without this:**
+- Asset paths resolve to root domain instead of app folder
+- Production app returns 403/404 errors
+- Works in localhost but fails in production
+
+**Also verify:** The .tgz package must have files at `package/dist/` path structure.
+</vite-config>
+
+<cache-busting>
+## CRITICAL: Browser Cache for Published Apps
+
+Published Hailer apps serve stale versions from browser cache. Vite's hashed JS/CSS filenames handle asset cache-busting, but `index.html` itself needs no-cache headers.
+
+**Add these meta tags to `index.html` `<head>` before publishing:**
+
+```html
+<meta http-equiv="Cache-Control" content="no-cache, no-store, must-revalidate" />
+<meta http-equiv="Pragma" content="no-cache" />
+<meta http-equiv="Expires" content="0" />
+```
+
+**Without these:**
+- Users see old app version after publish
+- Hard refresh (Ctrl+Shift+R) works but users won't know to do it
+- Particularly bad for bug fix deploys where users expect changes immediately
+
+**Why meta tags not server headers?**
+Hailer apps are served from `apps.hailer.com` static hosting - we can't control server headers. Meta tags are the only client-side cache control available.
+</cache-busting>
+
+<checklist>
+## Pre-Publish Checklist
+
+- [ ] manifest.json `appId` is 24 chars (dev app ID is fine — publish auto-creates prod app)
+- [ ] manifest.json `version` is set (e.g., "1.0.0")
+- [ ] manifest.json `versionDescription` is set (not empty)
+- [ ] vite.config.ts has `base: './'`
+- [ ] index.html has no-cache meta tags (see cache-busting section)
+- [ ] node_modules exists (dependencies installed)
+- [ ] After publish: verify URL auto-updated to production format (check with `list_apps`)
+</checklist>