@hailer/mcp 0.0.1

package/.env.example

@@ -0,0 +1,81 @@
+# Hailer MCP Server Configuration
+# Copy this file to .env.local and update with your own credentials
+
+# ==============================================
+# MCP SERVER CONFIGURATION (for external clients)
+# ==============================================
+
+# Hailer instance configuration
+# Multiple agents can be configured with different API keys
+# DO NOT USE YOUR LOGIN ALWAYS CREATE A +ai example WHEN INVITING THE MCP TO A WORKSPACE!
+
+# ⚠️ CLIENT_CONFIGS is COMMENTED OUT by default
+#
+# MANUAL SETUP (if you want to configure now):
+# 1. Create a Hailer user account with +ai suffix (e.g., yourname+ai@example.com)
+# 2. Generate a unique API key for the mcpServerApiKey field (any random string)
+# 3. Uncomment the CLIENT_CONFIGS below and fill in your credentials
+# 4. Copy this file to .env.local (which is gitignored)
+# 5. Never commit .env.local to version control
+#
+# EXAMPLE CONFIGURATION (uncomment and modify):
+# CLIENT_CONFIGS='[
+#  {
+#    "email": "your-email+ai@example.com",
+#    "password": "your-password",
+#    "mcpServerApiKey": "unique-api-key-for-this-agent",
+#    "apiBaseUrl": "https://api.hailer.com"
+#  }
+#]'
+
+
+
+# Workspace configuration path (optional)
+# Point to a directory containing workspace configs (workflows.json, insights.json, etc.)
+# Used by /ws-pull command to download workspace configuration
+# If not set, looks in current directory
+# WORKSPACE_CONFIG_PATH=/path/to/workspace-config
+
+# Development apps path (optional)
+# Point to a directory where Hailer apps will be scaffolded
+# Keeps the repo clean from development app projects
+# If not set, apps are created in current directory
+# DEV_APPS_PATH=/path/to/hailer-apps
+
+# Enable destructive operations (remove_workflow, remove_app, remove_insight, delete_template)
+# ⚠️ SECURITY: NUCLEAR tools are HIDDEN and BLOCKED by default for safety
+# When disabled (default): Nuclear tools don't appear in tool listings
+# When enabled: Nuclear tools become available and visible
+# Set to 'true' to explicitly enable destructive operations
+# Default: false (nuclear tools completely hidden)
+# ENABLE_NUCLEAR_TOOLS=true
+
+
+# ==============================================
+# OPTIONAL: MCP CLIENT CONFIGURATION (automated agent)
+# ==============================================
+
+# Enable the MCP Client (enabled by default)
+MCP_CLIENT_ENABLED=false
+
+# LLM Provider API Keys (add at least one)
+# ANTHROPIC_API_KEY=sk-ant-your-key-here
+# OPENAI_API_KEY=sk-your-openai-key-here
+
+# MCP Server URL (for client to call our own tools)
+MCP_SERVER_URL=http://localhost:3030/api/mcp
+#MCP_CLIENT_API_KEY=your-api-key
+
+# MCP Agent User IDs (required for agent tagging - get these from Hailer)
+MCP_CLIENT_AGENT_IDS='[]'
+
+# Bot Features (optional, defaults to true)
+TOKEN_USAGE_BOT_ENABLED=false
+AGENT_ACTIVITY_BOT_ENABLED=false
+
+# Adaptive Documentation Bot (automatically improves tool descriptions based on errors)
+ADAPTIVE_DOCUMENTATION_BOT_ENABLED=false
+ADAPTIVE_AUTO_UPDATE=false
+ADAPTIVE_UPDATE_INTERVAL=60000
+ADAPTIVE_MIN_ERROR_COUNT=3
+ADAPTIVE_SKILL_GENERATION=false

package/.mcp.json

@@ -0,0 +1,13 @@
+{
+  "mcpServers": {
+    "hailer": {
+      "type": "stdio",
+      "command": "npx",
+      "args": [
+        "mcp-remote",
+        "http://localhost:3030/api/mcp?apiKey=unique-api-key-for-this-agent"
+      ],
+      "env": {}
+    }
+  }
+}

package/README.md

@@ -0,0 +1,297 @@
+# Hailer MCP
+
+**MCP** stands for **Model Context Protocol** - a standardized way for AI assistants to securely access and interact with external tools and data sources. This project implements both an MCP Server (providing Hailer tools to external MCP clients) and an MCP Client (automated agents that respond to mentions in Hailer chats).
+
+## ToDo List
+- [ ] For questions during André's vacation, ask Tatu (Tatu Vähä-Tuisku) & Levi
+
+MCP Client
+- [ ] Allow agent to see/switch between workspaces
+- [ ] let agent fill descriptions for workflows, and phases (empty, and add to existing)
+- [ ] Let Bot read through old messages (didnt check 2024 week 26 messages, but 2025)
+- [ ] Review HR AI Workspace, what fields are needed for prompt/behavior, and what notes to take
+- [ ] Add Hailer data structure to system prompt
+- [ ] Add system prompt and memory, fetch from HR for AI agents
+- [ ] Hailer Bug: Sometimes agents response doesnt show (Hailer Bug suspected, because after page reload they are visible). maybe temporarily solve by addind 300ms delay for message, or send another signal to refresh/update
+- [ ] Check which workflows and datasets Agent #1 and #2 have access to, Check CACHING
+- [ ] reduce temperature to 0 for predictability
+
+- [X] Provide additional context (which workspace, 10 most recent messages) when bot gets triggered
+- [X] If 2 agents get asked in one message, make sure both respond
+- [X] Read User ID from Hailer, to simplify the config
+- [X] Test if Agent can be messaged directly without manually tagging
+- [X] Update Anthropic model to newer one
+- [X] Fix OpenAI Provider
+- [X] Check how many activities results bot fetches, tell him there are more and show him how to fetch more
+- [X] Tell bot what MCP means (not Mission Control Protocol...)
+
+
+Ideas for agent improvements:
+- [ ] Debug: why are certain fields not filled by agent, if it said it did?
+- [ ] Try to prompt it to fetch the workflow before attempting to set fields.
+- [ ] When using create activity always lookup the available fields of the workflow before adding data
+- [ ] Reason what data should go into what field before adding data to the fields
+- [ ] Use a short and describing name for the activity created if not given a clear instruction by the person who makes the request
+- [X] For all requests preload the 10 last messages from the chat from which the message comes to the context window
+- [X] The agent seems to load only a limited amount of activities when asked how many activities are in a certain phase -> show to agent how many total records OR pagination OR etc
+
+
+
+
+
+
+
+
+
+This project provides both an **MCP Server** and an **MCP Client** for Hailer integration:
+
+- **MCP Server** - Provides Hailer tools to external MCP clients (like Claude Desktop)
+- **MCP Client** - Automated agent that responds to `@mcp-agent` mentions in Hailer chats
+To understand this codebase, see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) (mermaid support recommended).
+
+## Testing with K3D cluster
+
+## Architecture
+
+The project uses a **Vite frontend + Express backend** architecture for optimal development experience and proper background service management:
+
+- **Backend** (`server/`) - Express server with MCP server and client
+- **Frontend** (`frontend/`) - Vite-powered React interface for tool management
+- **Agent Tracking** - Comprehensive analytics and performance monitoring for AI agents
+- **Benefits**: MCP client starts immediately on server boot (no page loads required!)
+
+## Quick Start
+
+### 1. Install Dependencies
+
+```bash
+# Backend
+cd server && npm install
+
+# Frontend  
+cd frontend && npm install
+```
+
+### 2. Environment Configuration
+
+The system works out-of-the-box with default local development settings. For custom configuration, create `.env.local` in the `/server` directory (not the project root):
+
+```bash
+# MCP Client Configuration (enabled by default)
+MCP_CLIENT_ENABLED=true
+
+# LLM Provider API Keys
+ANTHROPIC_API_KEY=sk-ant-your-anthropic-key-here
+OPENAI_API_KEY=sk-your-openai-key-here
+
+# MCP Agent User IDs (required for agent tagging)
+MCP_CLIENT_AGENT_IDS='["your-mcp-agent-user-id-1", "your-mcp-agent-user-id-2"]'
+
+# Custom Hailer Configuration (required for multi-bot setup)
+CLIENT_CONFIGS='[
+  {
+    "userId": "bot-user-id-1",
+    "email": "bot1@example.com",
+    "password": "bot1-password",
+    "mcpServerApiKey": "unique-api-key-1",
+    "apiBaseUrl": "https://api.hailer.com"
+  },
+  {
+    "userId": "bot-user-id-2", 
+    "email": "bot2@example.com",
+    "password": "bot2-password",
+    "mcpServerApiKey": "unique-api-key-2",
+    "apiBaseUrl": "https://api.hailer.com"
+  }
+]'
+```
+
+### 3. Development
+
+**Option A: Development Mode**
+```bash
+# Terminal 1: Start backend (includes MCP client auto-start)
+cd server && npm run dev
+
+# Terminal 2: Start frontend dev server  
+cd frontend && npm run dev
+```
+
+**Option B: Production Mode**
+```bash
+# Build frontend
+cd frontend && npm run build
+
+# Start backend (serves both API and frontend)
+cd server && npm start
+```
+
+## Usage
+
+### MCP Server (Tools for External Clients)
+
+Add to Claude Desktop or other MCP clients:
+
+```json
+{
+  "mcpServers": {
+    "hailer-mcp": {
+      "command": "npx",
+      "args": ["mcp-remote", "http://localhost:3030/api/mcp?apiKey=test-key"]
+    }
+  }
+}
+```
+
+### MCP Client (Automated Agent)
+
+**✅ The MCP client now starts automatically when the server boots!**
+
+**Setup Steps:**
+1. **Create MCP Agent Profiles** in your Hailer instance (create user profiles for your agents)
+2. **Get the User IDs** of these agent profiles and add them to `MCP_CLIENT_AGENT_IDS`
+3. **Configure bot credentials** in `CLIENT_CONFIGS` with unique `userId` and **unique `mcpServerApiKey`** for each bot
+4. **Configure LLM API keys** (OpenAI or Anthropic)
+5. **Create `.env.local` file** in the `/server` directory (not project root!)
+6. **Start the server** (`npm run dev` in server/)
+7. **Use in Hailer**: Tag/mention your MCP agent profiles in any discussion to trigger the automated agent!
+
+**⚠️ IMPORTANT**: Each bot MUST have a unique `mcpServerApiKey` in `CLIENT_CONFIGS`. This is how the MCP server identifies which bot's credentials to use for tool execution.
+
+**Multi-Bot Architecture:**
+- Each bot uses its own Hailer credentials and socket connection
+- Each bot has a unique MCP server API key for tool authentication
+- When a bot is mentioned, all MCP tool calls use that bot's credentials
+- Multiple bots can operate simultaneously in different discussions
+
+Example: Tag your MCP agent and ask: `list my activities in the Tasks workflow`
+
+The agent will:
+- Process your request immediately (no delays!)
+- Call appropriate MCP tools (`list_activities`, etc.)
+- Respond back in the chat with results
+
+## Troubleshooting
+
+**Problem: Bot uses wrong credentials for tool execution**
+- **Solution**: Ensure each bot has a unique `mcpServerApiKey` in `CLIENT_CONFIGS`
+- **Check**: Look for "✅ MCP Config: Using credentials for..." in server logs
+
+**Problem: Messages processed multiple times**
+- **Solution**: The system now includes message deduplication
+- **Check**: Look for "🔄 MCP Client: Message ... already processed, skipping"
+
+**Problem: Bot doesn't respond to mentions**
+- **Check**: Verify bot user IDs are in `MCP_CLIENT_AGENT_IDS`
+- **Check**: Ensure `.env.local` is in `/server` directory, not project root
+- **Check**: Look for "✅ MCP Client: Found mention of bot: ..." in logs
+
+## Available Providers
+
+- **Anthropic Claude** (`anthropic-claude`) - Uses Claude 3.5 Sonnet with MCP tool integration
+- **OpenAI GPT** (`openai-gpt4o`) - Uses GPT-4o with OpenAI's native MCP support
+
+The system automatically uses the first available provider based on configured API keys.
+
+## Development Tools
+
+### Web Interface
+
+Visit `http://localhost:3030` (production) or `http://localhost:3031` (development) to access:
+
+- **Tools page**: Browse and test all available MCP tools
+- **Activity page**: Monitor agent performance, success rates, and conversation flows
+- **Feedback page**: Development feedback interface
+
+### Agent Analytics
+
+The system includes comprehensive agent activity tracking that captures:
+- **Conversation flows**: Complete trigger → completion correlation with request IDs
+- **Performance metrics**: Success rates, response times, and tool usage statistics  
+- **Tool analytics**: Detailed request/response data for every tool call
+- **Environment-aware**: JSON files in development, OTLP logging in production
+
+View analytics via `/activity` endpoint or programmatically via `src/client/agent-tracker.ts`.
+
+### Claude Code Integration
+
+```bash
+# Add MCP server to Claude Code
+claude mcp add -s project hailer npx mcp-remote "http://localhost:3030/api/mcp?apiKey=test-key"
+
+# Remove MCP server
+claude mcp remove -s project hailer
+
+# Debug mode
+claude --debug
+```
+
+### MCP Inspector
+
+Use the official [MCP Inspector](https://github.com/modelcontextprotocol/inspector) for direct tool testing:
+
+```bash
+npx @modelcontextprotocol/inspector http://localhost:3030/api/mcp?apiKey=test-key
+```
+
+## Configuration Examples
+
+### Basic Setup (Anthropic)
+```bash
+# .env.local
+ANTHROPIC_API_KEY=sk-ant-your-key-here
+MCP_CLIENT_ENABLED=true
+```
+
+### Multi-Provider Setup
+```bash
+# .env.local  
+ANTHROPIC_API_KEY=sk-ant-your-key-here
+OPENAI_API_KEY=sk-your-openai-key
+MCP_CLIENT_ENABLED=true
+```
+
+### Custom Hailer Instance
+```bash
+# .env.local
+ANTHROPIC_API_KEY=sk-ant-your-key-here
+CLIENT_CONFIGS='[{"email":"you@company.com","password":"yourpassword","mcpServerApiKey":"custom-key","apiBaseUrl":"https://your-hailer.com"}]'
+MCP_CLIENT_ENABLED=true
+MCP_CLIENT_API_KEY=custom-key
+```
+
+## Troubleshooting
+
+### MCP Client Not Responding
+- Check that API keys are configured correctly
+- Verify the backend server is running (`npm run dev` in `server/`)
+- Check logs for provider initialization messages
+
+### MCP Server Connection Issues
+- Ensure the server is accessible at the configured URL
+- For external MCP clients, the server must be publicly accessible (not localhost)
+- Use ngrok or similar for testing with external services
+
+### Signal Processing Issues  
+- The MCP client processes `messenger.new` signals from Hailer
+- Verify socket.io connection is established in server logs
+- Check that the Hailer instance supports real-time signals
+
+## What's New
+
+### ✅ Immediate Background Services
+- **Fixed**: MCP client now starts immediately on server boot
+- **No more**: Waiting for page loads to initialize background services
+- **Benefit**: `@mcp-agent` mentions work instantly
+
+### ✅ Modern Development Stack
+- **Frontend**: Vite + React (faster than Next.js)
+- **Backend**: Express (lighter than Next.js) 
+- **Architecture**: Clean separation of concerns
+
+### ✅ Enhanced Provider Support
+- **Anthropic Claude**: Full MCP tool integration
+- **OpenAI GPT**: Native MCP support via Responses API
+- **Auto-detection**: Uses first available provider
+
+All existing functionality is preserved while providing a much better development experience!

package/dist/app.d.ts

@@ -0,0 +1,4 @@
+import { Core } from './core';
+declare const core: Core;
+export default core;
+//# sourceMappingURL=app.d.ts.map

package/dist/app.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("./core");
+const config_1 = require("./config");
+const file_1 = require("./mcp/tools/file");
+const activity_1 = require("./mcp/tools/activity");
+const discussion_1 = require("./mcp/tools/discussion");
+const user_1 = require("./mcp/tools/user");
+const workflow_1 = require("./mcp/tools/workflow");
+const insight_1 = require("./mcp/tools/insight");
+const app_1 = require("./mcp/tools/app");
+const skill_1 = require("./mcp/tools/skill");
+const core = new core_1.Core();
+console.log('Registering tools...');
+console.log(`Nuclear tools ${config_1.environment.ENABLE_NUCLEAR_TOOLS ? 'ENABLED' : 'DISABLED'} (set ENABLE_NUCLEAR_TOOLS=true in .env.local to enable)`);
+core.addTool(file_1.uploadFilesTool);
+core.addTool(activity_1.listActivitiesTool);
+core.addTool(activity_1.showActivityByIdTool);
+core.addTool(activity_1.createActivityTool);
+core.addTool(activity_1.updateActivityTool);
+// core.addTool(searchActivitiesTool);
+// core.addTool(filterActivitiesTool);
+// core.addTool(activityToolsGuideTool);
+core.addTool(discussion_1.listMyDiscussionsTool);
+core.addTool(discussion_1.fetchDiscussionMessagesTool);
+core.addTool(discussion_1.fetchPreviousDiscussionMessagesTool);
+core.addTool(discussion_1.joinDiscussionTool);
+core.addTool(discussion_1.leaveDiscussionTool);
+core.addTool(discussion_1.addDiscussionMessageTool);
+core.addTool(discussion_1.inviteDiscussionMembersTool);
+core.addTool(discussion_1.getActivityFromDiscussionTool);
+core.addTool(user_1.searchWorkspaceUsersTool);
+// core.addTool(hailerGetInitTool);
+// core.addTool(validateUserIdTool);
+core.addTool(workflow_1.getWorkflowSchemaTool);
+core.addTool(workflow_1.listWorkflowPhasesTool);
+core.addTool(workflow_1.listWorkflowsTool);
+core.addTool(workflow_1.installWorkflowTool);
+if (config_1.environment.ENABLE_NUCLEAR_TOOLS) {
+    core.addTool(workflow_1.removeWorkflowTool);
+}
+core.addTool(workflow_1.updateWorkflowFieldTool);
+core.addTool(workflow_1.updateWorkflowPhaseTool);
+core.addTool(workflow_1.testFunctionFieldTool);
+core.addTool(workflow_1.listWorkflowsMinimalTool);
+core.addTool(workflow_1.countActivitiesTool);
+core.addTool(insight_1.createInsightTool);
+core.addTool(insight_1.previewInsightTool);
+core.addTool(insight_1.getInsightDataTool);
+if (config_1.environment.ENABLE_NUCLEAR_TOOLS) {
+    core.addTool(insight_1.removeInsightTool);
+}
+core.addTool(insight_1.listInsightsTool);
+core.addTool(app_1.createAppTool);
+core.addTool(app_1.listAppsTool);
+core.addTool(app_1.updateAppTool);
+if (config_1.environment.ENABLE_NUCLEAR_TOOLS) {
+    core.addTool(app_1.removeAppTool);
+}
+core.addTool(app_1.addAppMemberTool);
+core.addTool(app_1.removeAppMemberTool);
+core.addTool(app_1.scaffoldHailerAppTool);
+core.addTool(app_1.publishHailerAppTool);
+core.addTool(skill_1.listSkillsTool);
+core.addTool(skill_1.getSkillTool);
+console.log('All tools registered successfully!');
+// Start the application
+core.start().catch((error) => {
+    console.error('Failed to start Hailer MCP application:', error);
+    process.exit(1);
+});
+// Export core for testing and external access
+exports.default = core;
+//# sourceMappingURL=app.js.map

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import './app';
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+require("./app");
+//# sourceMappingURL=cli.js.map

package/dist/client/adaptive-documentation-bot.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Adaptive Documentation Bot
+ *
+ * Monitors MCP logs for tool call errors and automatically improves
+ * tool descriptions and skills based on actual LLM usage patterns.
+ *
+ * Key Features:
+ * - Detects when LLMs make mistakes calling tools
+ * - Uses LLM to analyze what went wrong
+ * - Automatically updates tool descriptions
+ * - Creates/updates skill documents with common mistakes
+ * - Learns and improves over time
+ */
+import { ToolCallError, ErrorPattern, AdaptiveBotConfig } from './adaptive-documentation-types';
+export declare class AdaptiveDocumentationBot {
+    private logParser;
+    private descriptionUpdater;
+    private skillGenerator;
+    private llmCaller;
+    private config;
+    private errorPatterns;
+    private monitoringInterval?;
+    private isMonitoring;
+    constructor(apiKey: string, provider?: 'anthropic' | 'openai', config?: Partial<AdaptiveBotConfig>);
+    /**
+     * Start monitoring logs for errors
+     */
+    startMonitoring(): void;
+    /**
+     * Analyze logs immediately after a conversation ends
+     * Called by MCP Client after each bot conversation
+     */
+    analyzeAfterConversation(): Promise<void>;
+    /**
+     * Report error directly (not from logs)
+     * Use this to capture errors from active conversations
+     */
+    reportError(error: ToolCallError): void;
+    /**
+     * Stop monitoring logs
+     */
+    stopMonitoring(): void;
+    /**
+     * Main monitoring loop: parse errors and apply improvements
+     */
+    private monitorAndImprove;
+    /**
+     * Update error patterns with new errors
+     */
+    private updateErrorPatterns;
+    /**
+     * Analyze error pattern and apply improvements
+     */
+    private analyzeAndImprove;
+    /**
+     * Analyze error pattern using LLM
+     */
+    private analyzeWithLLM;
+    /**
+     * Apply improvements based on analysis
+     */
+    private applyImprovements;
+    /**
+     * Generate improved description using LLM
+     */
+    private generateImprovedDescription;
+    /**
+     * Generate improved parameter description using LLM
+     */
+    private generateImprovedParameterDescription;
+    /**
+     * Generate pattern key for grouping similar errors
+     */
+    private getPatternKey;
+    /**
+     * Generate human-readable description for error pattern
+     */
+    private generatePatternDescription;
+    /**
+     * Get statistics about adaptive bot performance
+     */
+    getStats(): {
+        monitoring: boolean;
+        errorPatterns: number;
+        improvements: any;
+        skills: any;
+    };
+    /**
+     * Get error patterns for a specific tool
+     */
+    getToolErrorPatterns(toolName: string): ErrorPattern[];
+    /**
+     * Test mode - parse errors and show what would be improved (without applying changes)
+     */
+    testRun(): Promise<{
+        errors: ToolCallError[];
+        patterns: ErrorPattern[];
+        suggestions: Array<{
+            toolName: string;
+            errorCount: number;
+            errorMessage: string;
+            existingSkill?: string;
+            wouldCreateSkill: boolean;
+            wouldUpdateSkill: boolean;
+        }>;
+    }>;
+}
+//# sourceMappingURL=adaptive-documentation-bot.d.ts.map