@hailer/mcp 1.1.12 → 1.1.13

package/dist/mcp/tools/investigate.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Investigation Tool - Spawn Claude Code agents to investigate local repos
+ *
+ * Uses `claude -p` (headless mode, subscription-based) to autonomously
+ * explore codebases, search for bugs, and analyze code.
+ */
+import { Tool } from '../tool-registry';
+export declare const investigateRepoTool: Tool;
+//# sourceMappingURL=investigate.d.ts.map

package/dist/mcp/tools/investigate.js

@@ -0,0 +1,254 @@
+"use strict";
+/**
+ * Investigation Tool - Spawn Claude Code agents to investigate local repos
+ *
+ * Uses `claude -p` (headless mode, subscription-based) to autonomously
+ * explore codebases, search for bugs, and analyze code.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.investigateRepoTool = void 0;
+const zod_1 = require("zod");
+const child_process_1 = require("child_process");
+const tool_registry_1 = require("../tool-registry");
+const logger_1 = require("../../lib/logger");
+const config_1 = require("../../config");
+const logger = (0, logger_1.createLogger)({ component: 'investigate-tool' });
+/**
+ * Resolve claude CLI path at module load
+ */
+const CLAUDE_BIN = (() => {
+    try {
+        return (0, child_process_1.execSync)('which claude', { encoding: 'utf-8' }).trim();
+    }
+    catch {
+        return 'claude'; // fallback to PATH lookup
+    }
+})();
+/**
+ * Parse DEV_AI_REPOS env var into a name->path map.
+ * Format: "name1:/path/one,name2:/path/two"
+ */
+function parseRepoPaths() {
+    const raw = config_1.environment.DEV_AI_REPOS;
+    const map = new Map();
+    if (!raw)
+        return map;
+    for (const entry of raw.split(',')) {
+        const colonIdx = entry.indexOf(':');
+        if (colonIdx === -1)
+            continue;
+        const name = entry.slice(0, colonIdx).trim();
+        const repoPath = entry.slice(colonIdx + 1).trim();
+        if (name && repoPath) {
+            map.set(name, repoPath);
+        }
+    }
+    return map;
+}
+/**
+ * Resolve a repo name to its local filesystem path.
+ */
+function resolveRepoPath(repoName) {
+    const repos = parseRepoPaths();
+    return repos.get(repoName) || null;
+}
+/**
+ * Spawn `claude -p` in a repo directory and return its output.
+ */
+async function spawnInvestigation(prompt, cwd, maxTurns, repoName) {
+    const timeout = config_1.environment.DEV_AI_INVESTIGATION_TIMEOUT;
+    return new Promise((resolve, reject) => {
+        const proc = (0, child_process_1.spawn)(CLAUDE_BIN, [
+            '-p', prompt,
+            '--output-format', 'stream-json',
+            '--verbose',
+            '--allowedTools', 'Read,Glob,Grep,Bash,Task',
+            '--max-turns', String(maxTurns),
+        ], {
+            cwd,
+            timeout,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            env: {
+                ...process.env,
+                // Strip MCP vars so investigation agent doesn't connect to our MCP server
+                MCP_SERVER_URL: undefined,
+                MCP_CLIENT_API_KEY: undefined,
+                MCP_CLIENT_ENABLED: undefined,
+                CLIENT_CONFIGS: undefined,
+                BOT_EMAIL: undefined,
+                BOT_PASSWORD: undefined,
+                BOT_API_BASE_URL: undefined,
+                ANTHROPIC_API_KEY: undefined,
+            },
+        });
+        let lineBuffer = '';
+        let resultText = '';
+        let stderr = '';
+        proc.stdout.on('data', (data) => {
+            lineBuffer += data.toString();
+            const lines = lineBuffer.split('\n');
+            lineBuffer = lines.pop() || ''; // Keep incomplete last line in buffer
+            for (const line of lines) {
+                const trimmed = line.trim();
+                if (!trimmed)
+                    continue;
+                try {
+                    const event = JSON.parse(trimmed);
+                    if (event.type === 'system' && event.subtype === 'init') {
+                        logger.debug(`[investigation:${repoName}] Agent initialized | tools: ${(event.tools || []).length} | model: ${event.model || 'unknown'}`);
+                    }
+                    else if (event.type === 'assistant' && event.message?.content) {
+                        for (const block of event.message.content) {
+                            if (block.type === 'tool_use') {
+                                const inputStr = JSON.stringify(block.input || {});
+                                logger.debug(`[investigation:${repoName}] Tool: ${block.name} ${inputStr.length > 200 ? inputStr.slice(0, 200) + '...' : inputStr}`);
+                            }
+                            else if (block.type === 'text') {
+                                const text = (block.text || '').trim();
+                                if (text) {
+                                    logger.debug(`[investigation:${repoName}] ${text.length > 300 ? text.slice(0, 300) + '...' : text}`);
+                                }
+                            }
+                        }
+                    }
+                    else if (event.type === 'tool') {
+                        const content = typeof event.content === 'string' ? event.content : JSON.stringify(event.content || '');
+                        logger.debug(`[investigation:${repoName}] Tool result (${event.tool_name}): ${content.length > 300 ? content.slice(0, 300) + '...' : content}`);
+                    }
+                    else if (event.type === 'result') {
+                        resultText = event.result || '';
+                        const cost = event.total_cost_usd ? `$${event.total_cost_usd.toFixed(4)}` : 'unknown';
+                        const duration = event.duration_ms ? `${(event.duration_ms / 1000).toFixed(1)}s` : 'unknown';
+                        logger.info(`[investigation:${repoName}] Complete | ${resultText.length} chars | ${duration} | cost: ${cost}`);
+                    }
+                }
+                catch {
+                    // Non-JSON line
+                    if (trimmed.length > 0) {
+                        logger.debug(`[investigation:${repoName}] ${trimmed.length > 300 ? trimmed.slice(0, 300) + '...' : trimmed}`);
+                    }
+                }
+            }
+        });
+        proc.stderr.on('data', (data) => {
+            const chunk = data.toString();
+            stderr += chunk;
+            const trimmed = chunk.trim();
+            if (trimmed) {
+                logger.warn(`[investigation:${repoName}] ${trimmed.length > 500 ? trimmed.slice(0, 500) + '...' : trimmed}`);
+            }
+        });
+        proc.on('error', (err) => {
+            reject(new Error(`Failed to spawn claude: ${err.message}`));
+        });
+        proc.on('close', (code) => {
+            // Process any remaining data in lineBuffer
+            if (lineBuffer.trim()) {
+                try {
+                    const event = JSON.parse(lineBuffer.trim());
+                    if (event.type === 'result') {
+                        resultText = event.result || '';
+                    }
+                }
+                catch {
+                    // ignore
+                }
+            }
+            if (code === 0) {
+                resolve(resultText || 'Investigation completed but returned no structured result.');
+            }
+            else {
+                const errDetail = stderr.trim() || `exit code ${code}`;
+                reject(new Error(`Investigation failed: ${errDetail}`));
+            }
+        });
+    });
+}
+const investigateRepoSchema = zod_1.z.object({
+    repoName: zod_1.z.string().describe('Target repo name (must match a configured repo). Available repos depend on DEV_AI_REPOS config.'),
+    prompt: zod_1.z.string().describe('What to investigate - bug description, search query, code question, etc.'),
+    maxTurns: zod_1.z.number().optional().default(30).describe('Max investigation depth (number of agentic turns). Default: 30.'),
+});
+exports.investigateRepoTool = {
+    name: 'investigate_repo',
+    group: tool_registry_1.ToolGroup.PLAYGROUND,
+    description: 'Spawn a Claude Code agent to investigate code in a local repo. ' +
+        'Uses claude -p (headless mode, subscription-based). ' +
+        'The agent can explore files, search code, analyze the codebase autonomously, ' +
+        'and spawn investigation teams for parallel exploration of complex issues. ' +
+        'Returns the investigation findings as text.',
+    schema: investigateRepoSchema,
+    async execute(args, _context) {
+        const repos = parseRepoPaths();
+        // If no repos configured, return helpful error
+        if (repos.size === 0) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: 'No repos configured. Set DEV_AI_REPOS in .env.local (format: "name:/path,name2:/path2").',
+                    }],
+            };
+        }
+        const repoPath = resolveRepoPath(args.repoName);
+        if (!repoPath) {
+            const available = Array.from(repos.keys()).join(', ');
+            return {
+                content: [{
+                        type: 'text',
+                        text: `Unknown repo: "${args.repoName}". Available repos: ${available}`,
+                    }],
+            };
+        }
+        const enhancedPrompt = `You are a lead investigator. Use parallel agents to explore the codebase efficiently.
+
+HOW TO USE PARALLEL AGENTS:
+- Call multiple Task tools in a SINGLE response to run them in parallel
+- Each Task call blocks until that agent finishes and returns its findings directly to you
+- Use subagent_type: "Explore" with model: "haiku" — these are fast, read-only codebase search agents
+- Do NOT use TeamCreate, SendMessage, or TaskCreate — just call Task directly
+
+APPROACH:
+1. In your FIRST response, call 2-3 Task tools simultaneously, each with a focused search prompt
+2. You will receive all their findings in the next turn
+3. If needed, do additional targeted searches yourself with Grep/Read
+4. Write your FINAL REPORT
+
+REPORT FORMAT:
+- Root cause of the issue
+- Affected files with paths and line numbers
+- Suggested fix with specific code changes
+
+INVESTIGATION TASK:
+${args.prompt}`;
+        logger.info('Starting investigation', {
+            repo: args.repoName,
+            repoPath,
+            maxTurns: args.maxTurns,
+            promptLength: enhancedPrompt.length,
+        });
+        try {
+            const result = await spawnInvestigation(enhancedPrompt, repoPath, args.maxTurns, args.repoName);
+            logger.info('Investigation completed', {
+                repo: args.repoName,
+                resultLength: result.length,
+            });
+            return {
+                content: [{
+                        type: 'text',
+                        text: result || 'Investigation completed but returned no output.',
+                    }],
+            };
+        }
+        catch (error) {
+            const errMsg = error instanceof Error ? error.message : String(error);
+            logger.error('Investigation failed', { repo: args.repoName, error: errMsg });
+            return {
+                content: [{
+                        type: 'text',
+                        text: `Investigation failed: ${errMsg}`,
+                    }],
+            };
+        }
+    },
+};
+//# sourceMappingURL=investigate.js.map

package/dist/mcp/tools/workflow-permissions.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Workflow Permission Tools
+ *
+ * Tools for managing workflow member permissions in Hailer workspaces:
+ * - List members and their permission levels
+ * - Grant user or team access with a specific permission level
+ * - Revoke user or team access
+ * - Check what permissions a specific user has
+ */
+import { Tool } from '../tool-registry';
+export declare const listWorkflowPermissionsTool: Tool;
+export declare const grantWorkflowPermissionTool: Tool;
+export declare const revokeWorkflowPermissionTool: Tool;
+export declare const checkUserPermissionsTool: Tool;
+//# sourceMappingURL=workflow-permissions.d.ts.map

package/dist/mcp/tools/workflow-permissions.js

@@ -0,0 +1,204 @@
+"use strict";
+/**
+ * Workflow Permission Tools
+ *
+ * Tools for managing workflow member permissions in Hailer workspaces:
+ * - List members and their permission levels
+ * - Grant user or team access with a specific permission level
+ * - Revoke user or team access
+ * - Check what permissions a specific user has
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkUserPermissionsTool = exports.revokeWorkflowPermissionTool = exports.grantWorkflowPermissionTool = exports.listWorkflowPermissionsTool = void 0;
+const zod_1 = require("zod");
+const tool_registry_1 = require("../tool-registry");
+const index_1 = require("../utils/index");
+const tool_helpers_1 = require("../utils/tool-helpers");
+const request_logger_1 = require("../../lib/request-logger");
+const logger = (0, index_1.createLogger)({ component: 'workflow-permissions-tools' });
+/** Ensure memberId has the required prefix (user_, team_, network_, group_) */
+function ensureMemberPrefix(memberId) {
+    if (memberId.startsWith('user_') || memberId.startsWith('team_') ||
+        memberId.startsWith('network_') || memberId.startsWith('group_')) {
+        return memberId;
+    }
+    return `user_${memberId}`;
+}
+// ============================================================================
+// TOOL 1: LIST WORKFLOW PERMISSIONS
+// ============================================================================
+exports.listWorkflowPermissionsTool = {
+    name: 'list_workflow_permissions',
+    group: tool_registry_1.ToolGroup.READ,
+    description: 'List members and their permission levels for a workflow',
+    schema: zod_1.z.object({
+        workflowId: zod_1.z
+            .string()
+            .describe('The workflow ID to list permissions for'),
+    }),
+    async execute(args, context) {
+        logger.debug('Listing workflow permissions', {
+            workflowId: args.workflowId,
+            apiKey: context.apiKey.substring(0, 8) + '...',
+        });
+        try {
+            const result = await context.hailer.request('v2.process.member.list', [args.workflowId]);
+            return (0, index_1.textResponse)(JSON.stringify(result, null, 2));
+        }
+        catch (error) {
+            if (!request_logger_1.RequestLogger.getCurrent())
+                logger.error('Error listing workflow permissions', error);
+            const msg = error?.msg || error?.message || (0, index_1.getErrorMessage)(error);
+            return (0, index_1.errorResponse)(`Error listing workflow permissions: ${msg}`);
+        }
+    },
+};
+// ============================================================================
+// TOOL 2: GRANT WORKFLOW PERMISSION
+// ============================================================================
+const permissionLevels = ['admin', 'any', 'ownteam', 'own'];
+exports.grantWorkflowPermissionTool = {
+    name: 'grant_workflow_permission',
+    group: tool_registry_1.ToolGroup.WRITE,
+    description: 'Grant a user or team access to a workflow with a specific permission level',
+    schema: zod_1.z.object({
+        workflowId: zod_1.z
+            .string()
+            .describe('The workflow ID to grant permission on'),
+        memberId: zod_1.z
+            .string()
+            .describe('The user ID or team ID to grant access to'),
+        level: zod_1.z
+            .enum(permissionLevels)
+            .describe('Permission level: admin (full access), any (all activities), ownteam (own team activities), own (own activities only)'),
+    }),
+    async execute(args, context) {
+        logger.debug('Granting workflow permission', {
+            workflowId: args.workflowId,
+            memberId: args.memberId,
+            level: args.level,
+            apiKey: context.apiKey.substring(0, 8) + '...',
+        });
+        try {
+            const prefixedMemberId = ensureMemberPrefix(args.memberId);
+            // Step 1: Add as member first (may fail if already a member — that's OK)
+            try {
+                await context.hailer.request('v2.process.member.add', [args.workflowId, prefixedMemberId]);
+            }
+            catch (addError) {
+                logger.debug('member.add failed (possibly already a member), continuing to grant', {
+                    error: (0, index_1.getErrorMessage)(addError),
+                });
+            }
+            // Step 2: Set the permission level
+            const result = await context.hailer.request('v2.process.permissions.grant', [
+                args.workflowId,
+                prefixedMemberId,
+                args.level,
+            ]);
+            return (0, index_1.textResponse)(JSON.stringify({
+                success: true,
+                workflowId: args.workflowId,
+                memberId: prefixedMemberId,
+                level: args.level,
+                result,
+            }, null, 2));
+        }
+        catch (error) {
+            if (!request_logger_1.RequestLogger.getCurrent())
+                logger.error('Error granting workflow permission', error);
+            const msg = error?.msg || error?.message || (0, index_1.getErrorMessage)(error);
+            return (0, index_1.errorResponse)(`Error granting workflow permission: ${msg}`);
+        }
+    },
+};
+// ============================================================================
+// TOOL 3: REVOKE WORKFLOW PERMISSION
+// ============================================================================
+exports.revokeWorkflowPermissionTool = {
+    name: 'revoke_workflow_permission',
+    group: tool_registry_1.ToolGroup.WRITE,
+    description: "Remove a user or team's access to a workflow",
+    schema: zod_1.z.object({
+        workflowId: zod_1.z
+            .string()
+            .describe('The workflow ID to revoke permission on'),
+        memberId: zod_1.z
+            .string()
+            .describe('The user ID or team ID to remove access from'),
+    }),
+    async execute(args, context) {
+        logger.debug('Revoking workflow permission', {
+            workflowId: args.workflowId,
+            memberId: args.memberId,
+            apiKey: context.apiKey.substring(0, 8) + '...',
+        });
+        try {
+            const prefixedMemberId = ensureMemberPrefix(args.memberId);
+            // Step 1: Deny permissions (may fail if no explicit grant — that's OK)
+            try {
+                await context.hailer.request('v2.process.permissions.deny', [args.workflowId, prefixedMemberId]);
+            }
+            catch (denyError) {
+                logger.debug('permissions.deny failed (possibly no explicit grant), continuing to remove', {
+                    error: (0, index_1.getErrorMessage)(denyError),
+                });
+            }
+            // Step 2: Remove from members
+            const result = await context.hailer.request('v2.process.member.remove', [
+                args.workflowId,
+                prefixedMemberId,
+            ]);
+            return (0, index_1.textResponse)(JSON.stringify({
+                success: true,
+                workflowId: args.workflowId,
+                memberId: prefixedMemberId,
+                result,
+            }, null, 2));
+        }
+        catch (error) {
+            if (!request_logger_1.RequestLogger.getCurrent())
+                logger.error('Error revoking workflow permission', error);
+            const msg = error?.msg || error?.message || (0, index_1.getErrorMessage)(error);
+            return (0, index_1.errorResponse)(`Error revoking workflow permission: ${msg}`);
+        }
+    },
+};
+// ============================================================================
+// TOOL 4: CHECK USER PERMISSIONS
+// ============================================================================
+exports.checkUserPermissionsTool = {
+    name: 'check_user_permissions',
+    group: tool_registry_1.ToolGroup.READ,
+    description: 'Check what permissions a specific user has in the workspace',
+    schema: zod_1.z.object({
+        userId: zod_1.z
+            .string()
+            .describe('The user ID to check permissions for'),
+        workspaceId: zod_1.z
+            .string()
+            .optional()
+            .describe('The workspace ID to check permissions in. Defaults to the current workspace.'),
+    }),
+    async execute(args, context) {
+        logger.debug('Checking user permissions', {
+            userId: args.userId,
+            apiKey: context.apiKey.substring(0, 8) + '...',
+        });
+        try {
+            const workspaceId = (0, tool_helpers_1.getResolvedWorkspaceId)(args, context);
+            const result = await context.hailer.request('v3.user.permissions', [
+                args.userId,
+                workspaceId,
+            ]);
+            return (0, index_1.textResponse)(JSON.stringify(result, null, 2));
+        }
+        catch (error) {
+            if (!request_logger_1.RequestLogger.getCurrent())
+                logger.error('Error checking user permissions', error);
+            const msg = error?.msg || error?.message || (0, index_1.getErrorMessage)(error);
+            return (0, index_1.errorResponse)(`Error checking user permissions: ${msg}`);
+        }
+    },
+};
+//# sourceMappingURL=workflow-permissions.js.map

package/dist/mcp/tools/workflow.js

@@ -54,7 +54,13 @@ function parseErrorType(errorMessage) {
 // ============================================================================
 // READ TOOLS - Workflow Schema and Information
 // ============================================================================
-const getWorkflowSchemaDescription = `📋 Get workflow field schema and structure - REQUIRED before using list_activities to understand available fields. Shows all field IDs, labels, types, and options. Requires both workflowId and phaseId (use list_workflow_phases first).`;
+const getWorkflowSchemaDescription = `Get workflow field structure - CALL THIS BEFORE create_activity or update_activity.
+
+**Hailer Concept:** Shows all fields (columns) in a workflow with their IDs, types, and options. You MUST know field IDs to create or update activities.
+
+**Returns:** Field IDs, labels, types (text, numeric, date, dropdown, user, activitylink), required status, dropdown options.
+
+**Critical:** Never guess field IDs - always get them from this tool first.`;
 exports.getWorkflowSchemaTool = {
     name: 'get_workflow_schema',
     group: tool_registry_1.ToolGroup.READ,
@@ -179,7 +185,13 @@ exports.getWorkflowSchemaTool = {
         }
     },
 };
-const listWorkflowPhasesDescription = `📊 List available phases in a workflow - Required before using list_activities to get phase IDs. Use this first to see all phases, then call list_activities for each phase to get complete workflow overview. TIP: Also call get_workflow_schema to understand field structure.`;
+const listWorkflowPhasesDescription = `List phases (stages/statuses) in a workflow - REQUIRED to get phase IDs.
+
+**Hailer Concept:** Phases are stages like "New" → "In Progress" → "Done". Activities move through phases as work progresses.
+
+**When to use:** Before list_activities (need phaseId), before create_activity (need initial phase), before update_activity (to move to new phase).
+
+**Returns:** Phase names, IDs, which phase is initial (for new items), which is endpoint (completed).`;
 exports.listWorkflowPhasesTool = {
     name: 'list_workflow_phases',
     group: tool_registry_1.ToolGroup.READ,
@@ -258,7 +270,15 @@ exports.listWorkflowPhasesTool = {
         }
     },
 };
-const listWorkflowsDescription = `List workflows - Get workflow info with optional detailed data`;
+const listWorkflowsDescription = `List workflows (processes/pipelines) in the Hailer workspace.
+
+**Hailer Concept:** A Workflow is like a database table or Kanban board - it defines a process with fields (columns) and phases (stages). Examples: "Sales Pipeline", "Customer Database", "Project Tasks".
+
+**When to use:** To see all available workflows, find workflow IDs, or understand the workspace structure.
+
+**Returns:** Workflow names, IDs, activity counts, and relationships between workflows.
+
+**Next steps:** Use \`list_workflow_phases\` to see stages, then \`get_workflow_schema\` for field structure.`;
 exports.listWorkflowsTool = {
     name: 'list_workflows',
     group: tool_registry_1.ToolGroup.READ,
@@ -1069,23 +1089,15 @@ ${errorMessage}
 // ============================================================================
 // TOOL 5: LIST WORKFLOWS MINIMAL
 // ============================================================================
-const listWorkflowsMinimalDescription = `🧪 [PLAYGROUND] List workflows with minimal output - Returns only id and name to avoid token limits
+const listWorkflowsMinimalDescription = `Quick list of all workflows - START HERE to find workflow IDs.
 
-**⚡ PERFORMANCE ADVANTAGE:**
-- Uses cached data from init (v2.core.init) - **ZERO extra API calls**
-- Returns activity counts for ALL workflows in one call
-- **Preferred method for getting bulk workflow counts**
-- Much faster and more efficient than calling \`count_activities\` for each workflow
+**Hailer Concept:** Returns all workflows (processes/boards) with their IDs and names. This is usually your FIRST CALL to discover what's available.
 
-**When to use this vs count_activities:**
-- ✅ Use \`list_workflows_minimal\` for: Bulk counts, workflow discovery, listing all workflows with counts
-- ❌ Use \`count_activities\` for: Phase-level breakdown, real-time count for single workflow
+**When to use:** User asks "show my tasks", "what workflows do I have", "find customers" - use this to locate the right workflow ID.
 
-**Response includes**:
-- Workflow ID and name
-- Activity count (from cached init data)
-- Starred status
-- Workspace ID`;
+**Returns:** Workflow name, ID, activity count. Use the ID in subsequent calls.
+
+**Typical flow:** list_workflows_minimal → list_workflow_phases → get_workflow_schema → list_activities`;
 const listWorkflowsMinimalSchema = zod_1.z.object({
     workspace: zod_1.z.string().optional().describe("Optional workspace ID or name"),
     limit: zod_1.z.coerce.number().optional().describe("Maximum number of workflows to return"),
@@ -1313,7 +1325,34 @@ const updateWorkflowPhaseSchema = zod_1.z.object({
 // ============================================================================
 // CORE INIT TOOL - Workspace overview for terminal Claude Code sessions
 // ============================================================================
-const coreInitDescription = `Load workspace context - call once at session start to get workflows, phases, teams with IDs`;
+const coreInitDescription = `🚀 START HERE - Load workspace context and learn how to use Hailer tools.
+
+## What is Hailer?
+Hailer is a workspace platform. Key concepts:
+- **Workflow** = process/board (like "Tasks", "Customers", "Sales Pipeline")
+- **Activity** = item/record/card in a workflow
+- **Phase** = stage/status (like "New" → "In Progress" → "Done")
+- **Field** = property/column on an activity (name, date, priority, etc.)
+
+## How to use these tools:
+
+**Step 1 - Find workflow:** \`list_workflows_minimal\` → get workflow ID
+**Step 2 - Get phases:** \`list_workflow_phases(workflowId)\` → get phase IDs
+**Step 3 - Get fields:** \`get_workflow_schema(workflowId, phaseId)\` → get field IDs
+**Step 4 - Read/Write:**
+- \`list_activities\` - see items (requires workflowId, phaseId, fields[])
+- \`create_activity\` - create item (requires workflowId, use field IDs from schema)
+- \`update_activity\` - update item (requires activityId, use field IDs)
+
+## Field value formats:
+- Text: \`"value"\`
+- Number: \`42\`
+- Date: Unix timestamp in ms \`1730937600000\`
+- Dropdown: exact option string \`"High"\`
+- User: user ID string \`"5f8a1b2c..."\`
+
+## This tool returns:
+All workflows, phases, fields, and teams with IDs. Reference this data for all other calls.`;
 exports.coreInitTool = {
     name: 'core_init',
     group: tool_registry_1.ToolGroup.READ,

package/dist/mcp/utils/index.d.ts

@@ -12,5 +12,7 @@ export { transformActivity, transformActivities, transformFields, transformField
 export { textResponse, errorResponse, successResponse, jsonResponse, paginatedResponse, listResponse, getErrorMessage, withErrorHandling, isErrorResponse } from './response-builder';
 export { normalizePagination, calculatePaginationMeta, formatPaginationText } from './pagination';
 export type { PaginationMeta, PaginationOptions } from './pagination';
+export { deriveUserRole, getAllowedGroups, findCurrentUserMember, extractWorkspaceRoles, getAllowedGroupsForWorkspace, getMaxRole, checkWorkspaceAccess } from './role-utils';
 export type * from './types';
+export { normalizeInitProcesses } from './types';
 //# sourceMappingURL=index.d.ts.map

package/dist/mcp/utils/index.js

@@ -4,7 +4,7 @@
  * Provides centralized access to all utility functions and types
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.formatPaginationText = exports.calculatePaginationMeta = exports.normalizePagination = exports.isErrorResponse = exports.withErrorHandling = exports.getErrorMessage = exports.listResponse = exports.paginatedResponse = exports.jsonResponse = exports.successResponse = exports.errorResponse = exports.textResponse = exports.formatActivityListResponse = exports.formatUserName = exports.formatTimestamp = exports.transformWorkflowFields = exports.transformPhases = exports.transformWorkflow = exports.findFieldByKey = exports.transformFieldValue = exports.transformFields = exports.transformActivities = exports.transformActivity = exports.HailerApiClient = exports.createSuccessResponse = exports.createErrorResponse = exports.handleApiResponse = exports.makeApiCall = exports.HailerApiError = exports.LogTag = exports.LogLevel = exports.logger = exports.createLogger = void 0;
+exports.normalizeInitProcesses = exports.checkWorkspaceAccess = exports.getMaxRole = exports.getAllowedGroupsForWorkspace = exports.extractWorkspaceRoles = exports.findCurrentUserMember = exports.getAllowedGroups = exports.deriveUserRole = exports.formatPaginationText = exports.calculatePaginationMeta = exports.normalizePagination = exports.isErrorResponse = exports.withErrorHandling = exports.getErrorMessage = exports.listResponse = exports.paginatedResponse = exports.jsonResponse = exports.successResponse = exports.errorResponse = exports.textResponse = exports.formatActivityListResponse = exports.formatUserName = exports.formatTimestamp = exports.transformWorkflowFields = exports.transformPhases = exports.transformWorkflow = exports.findFieldByKey = exports.transformFieldValue = exports.transformFields = exports.transformActivities = exports.transformActivity = exports.HailerApiClient = exports.createSuccessResponse = exports.createErrorResponse = exports.handleApiResponse = exports.makeApiCall = exports.HailerApiError = exports.LogTag = exports.LogLevel = exports.logger = exports.createLogger = void 0;
 // Logging utilities
 var logger_1 = require("../../lib/logger");
 Object.defineProperty(exports, "createLogger", { enumerable: true, get: function () { return logger_1.createLogger; } });
@@ -50,4 +50,15 @@ var pagination_1 = require("./pagination");
 Object.defineProperty(exports, "normalizePagination", { enumerable: true, get: function () { return pagination_1.normalizePagination; } });
 Object.defineProperty(exports, "calculatePaginationMeta", { enumerable: true, get: function () { return pagination_1.calculatePaginationMeta; } });
 Object.defineProperty(exports, "formatPaginationText", { enumerable: true, get: function () { return pagination_1.formatPaginationText; } });
+// Role-based access control
+var role_utils_1 = require("./role-utils");
+Object.defineProperty(exports, "deriveUserRole", { enumerable: true, get: function () { return role_utils_1.deriveUserRole; } });
+Object.defineProperty(exports, "getAllowedGroups", { enumerable: true, get: function () { return role_utils_1.getAllowedGroups; } });
+Object.defineProperty(exports, "findCurrentUserMember", { enumerable: true, get: function () { return role_utils_1.findCurrentUserMember; } });
+Object.defineProperty(exports, "extractWorkspaceRoles", { enumerable: true, get: function () { return role_utils_1.extractWorkspaceRoles; } });
+Object.defineProperty(exports, "getAllowedGroupsForWorkspace", { enumerable: true, get: function () { return role_utils_1.getAllowedGroupsForWorkspace; } });
+Object.defineProperty(exports, "getMaxRole", { enumerable: true, get: function () { return role_utils_1.getMaxRole; } });
+Object.defineProperty(exports, "checkWorkspaceAccess", { enumerable: true, get: function () { return role_utils_1.checkWorkspaceAccess; } });
+var types_1 = require("./types");
+Object.defineProperty(exports, "normalizeInitProcesses", { enumerable: true, get: function () { return types_1.normalizeInitProcesses; } });
 //# sourceMappingURL=index.js.map