@hailer/mcp 0.1.3 → 0.1.4

package/.claude/skills/insight-join-patterns/SKILL.md

@@ -1,22 +1,24 @@
-# Insight JOIN Patterns
+---
+name: insight-join-patterns
+description: Correct JOIN syntax for Hailer insights with ActivityLink fields
+triggers: JOIN query errors, missing columns, NULL results in insight queries
+---
 
-## Pattern
+<problem>
 When joining workflows with ActivityLink fields in Hailer insights, you must:
 1. Include `_id` meta field in BOTH source definitions
 2. Join ON the activitylink field value equals target _id
 3. Use the activitylink fieldId (NOT the key) for the JOIN condition
+</problem>
 
-## Critical Rules
-
-**Always Required:**
+<rules>
 - Both workflows need `{ name: 'id', meta: '_id' }` in their fields array
 - JOIN condition: `source1.activityLinkFieldName = source2.id`
 - Use LEFT JOIN for optional relationships (activitylink can be null)
 - Use INNER JOIN only when relationship must exist
+</rules>
 
-## Correct Examples
-
-### Basic ActivityLink JOIN
+<correct>
 ```javascript
 // Players workflow has "club" field (activitylink to Clubs workflow)
 {
@@ -42,7 +44,38 @@ When joining workflows with ActivityLink fields in Hailer insights, you must:
   query: 'SELECT p.player_name, c.club_name FROM p LEFT JOIN c ON p.club = c.id'
 }
 ```
+</correct>
+
+<wrong>
+```javascript
+// ❌ WRONG - Missing _id in clubs source
+{
+  sources: [
+    {
+      name: 'p',
+      workflowId: 'players-id',
+      fields: [
+        { name: 'player_name', meta: 'name' },
+        { name: 'id', meta: '_id' },
+        { name: 'club', fieldId: 'club-field-id' }
+      ]
+    },
+    {
+      name: 'c',
+      workflowId: 'clubs-id',
+      fields: [
+        { name: 'club_name', meta: 'name' }
+        // Missing: { name: 'id', meta: '_id' }
+      ]
+    }
+  ],
+  query: 'SELECT p.player_name, c.club_name FROM p LEFT JOIN c ON p.club = c.id'
+}
+// Error: "no such column: c.id"
+```
+</wrong>
 
+<examples>
 ### Three-Way JOIN (Tasks -> Topics -> Projects)
 ```javascript
 {
@@ -53,7 +86,7 @@ When joining workflows with ActivityLink fields in Hailer insights, you must:
       fields: [
         { name: 'task_name', meta: 'name' },
         { name: 'id', meta: '_id' },
-        { name: 'topic', fieldId: 'topic-field-id' }  // Links to Topics
+        { name: 'topic', fieldId: 'topic-field-id' }
       ]
     },
     {
@@ -62,7 +95,7 @@ When joining workflows with ActivityLink fields in Hailer insights, you must:
       fields: [
         { name: 'topic_name', meta: 'name' },
         { name: 'id', meta: '_id' },
-        { name: 'project', fieldId: 'project-field-id' }  // Links to Projects
+        { name: 'project', fieldId: 'project-field-id' }
       ]
     },
     {
@@ -75,10 +108,7 @@ When joining workflows with ActivityLink fields in Hailer insights, you must:
     }
   ],
   query: `
-    SELECT
-      t.task_name,
-      top.topic_name,
-      p.project_name
+    SELECT t.task_name, top.topic_name, p.project_name
     FROM t
     LEFT JOIN top ON t.topic = top.id
     LEFT JOIN p ON top.project = p.id
@@ -109,76 +139,16 @@ When joining workflows with ActivityLink fields in Hailer insights, you must:
     }
   ],
   query: `
-    SELECT
-      teams.team_name,
-      COUNT(*) as match_count
+    SELECT teams.team_name, COUNT(*) as match_count
     FROM matches
     LEFT JOIN teams ON matches.home_team = teams.id
     GROUP BY teams.team_name
   `
 }
 ```
+</examples>
 
-## Wrong Examples
-
-### Missing _id Field
-```javascript
-// ❌ WRONG - Missing _id in clubs source
-{
-  sources: [
-    {
-      name: 'p',
-      workflowId: 'players-id',
-      fields: [
-        { name: 'player_name', meta: 'name' },
-        { name: 'id', meta: '_id' },
-        { name: 'club', fieldId: 'club-field-id' }
-      ]
-    },
-    {
-      name: 'c',
-      workflowId: 'clubs-id',
-      fields: [
-        { name: 'club_name', meta: 'name' }
-        // Missing: { name: 'id', meta: '_id' }
-      ]
-    }
-  ],
-  query: 'SELECT p.player_name, c.club_name FROM p LEFT JOIN c ON p.club = c.id'
-}
-// Error: "no such column: c.id"
-```
-
-### Using Key Instead of FieldId
-```javascript
-// ❌ WRONG - Using field key instead of fieldId
-{
-  sources: [
-    {
-      name: 'p',
-      workflowId: 'players-id',
-      fields: [
-        { name: 'player_name', meta: 'name' },
-        { name: 'id', meta: '_id' },
-        { name: 'club', key: 'club' }  // Wrong! Use fieldId
-      ]
-    }
-  ]
-}
-```
-
-### Wrong JOIN Syntax
-```javascript
-// ❌ WRONG - Trying to join on name instead of id
-query: 'SELECT p.player_name, c.club_name FROM p LEFT JOIN c ON p.club = c.club_name'
-
-// ❌ WRONG - Using field key in JOIN instead of column name
-query: 'SELECT p.player_name, c.club_name FROM p LEFT JOIN c ON p.clubId = c.id'
-// (Should use column name from sources definition: p.club = c.id)
-```
-
-## Troubleshooting
-
+<troubleshooting>
 **Error: "no such column: c.id"**
 - Missing `{ name: 'id', meta: '_id' }` in target workflow source
 
@@ -189,21 +159,13 @@ query: 'SELECT p.player_name, c.club_name FROM p LEFT JOIN c ON p.clubId = c.id'
 **NULL results for joined data**
 - ActivityLink field is empty/null for some activities (expected with LEFT JOIN)
 - Use INNER JOIN if you only want activities with relationships
+</troubleshooting>
 
-## Workflow
-
-1. Get schema: `get_workflow_schema({ workflowId, phaseId })`
-2. Find ActivityLink field ID and target workflow ID
-3. Build sources with BOTH _id fields
-4. Preview query: `preview_insight({ sources, query })`
-5. Fix errors, re-preview
-6. Create insight when preview succeeds
-
-## Quick Checklist
-
+<checklist>
 Before creating an insight with JOINs:
 - [ ] Both workflow sources include `{ name: 'id', meta: '_id' }`
 - [ ] ActivityLink field uses `fieldId` (NOT `key`)
 - [ ] JOIN condition uses column names from sources (e.g., `p.club = c.id`)
 - [ ] Using LEFT JOIN (unless relationship required)
 - [ ] Tested with `preview_insight` first
+</checklist>

package/.claude/skills/json-only-output/SKILL.md

@@ -1,8 +1,12 @@
-# JSON-Only Output
+---
+name: json-only-output
+description: Fix agents adding prose after JSON responses
+triggers: Agent outputs explanation text after valid JSON
+---
 
-<pattern>
+<problem>
 Agents violate JSON-only protocol by adding prose explanations AFTER their JSON response.
-</pattern>
+</problem>
 
 <correct>
 ```json

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

@@ -1,8 +1,12 @@
-# Optional Parameters vs Empty Values
+---
+name: optional-parameters
+description: Omit optional parameters instead of passing empty values
+triggers: Tool error about empty array/string when parameter should be omitted
+---
 
-<pattern>
+<problem>
 Tool parameter is required in schema but should be OMITTED (not passed at all) when not needed, rather than passed as empty array/string.
-</pattern>
+</problem>
 
 <correct>
 ```typescript

package/.claude/skills/tool-response-verification/SKILL.md

@@ -1,8 +1,12 @@
-# Tool Response Verification
+---
+name: tool-response-verification
+description: Ensure agents verify tool execution before claiming success
+triggers: Agent returns success without checking tool result
+---
 
-<pattern>
+<problem>
 Agent fabricates success response without verifying actual tool execution result.
-</pattern>
+</problem>
 
 <correct>
 ```typescript

package/dist/client/mcp-assistant.d.ts

@@ -0,0 +1,21 @@
+/**
+ * MCP Assistant (Lightweight)
+ *
+ * Pure pass-through chatbot. System prompt is loaded on AI PC side.
+ * Just forwards user messages, no local processing.
+ */
+export declare class McpAssistant {
+    private client;
+    constructor(config: {
+        apiKey: string;
+        baseURL?: string;
+    });
+    /**
+     * Chat - pure pass-through to local LLM
+     */
+    chat(userMessage: string, conversationHistory?: Array<{
+        role: 'user' | 'assistant';
+        content: string;
+    }>): Promise<string>;
+}
+//# sourceMappingURL=mcp-assistant.d.ts.map

package/dist/client/mcp-assistant.js

@@ -0,0 +1,58 @@
+"use strict";
+/**
+ * MCP Assistant (Lightweight)
+ *
+ * Pure pass-through chatbot. System prompt is loaded on AI PC side.
+ * Just forwards user messages, no local processing.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.McpAssistant = void 0;
+const openai_1 = __importDefault(require("openai"));
+const logger_1 = require("../lib/logger");
+const logger = (0, logger_1.createLogger)({ component: 'McpAssistant' });
+class McpAssistant {
+    client;
+    constructor(config) {
+        this.client = new openai_1.default({
+            apiKey: config.apiKey,
+            baseURL: config.baseURL,
+        });
+    }
+    /**
+     * Chat - pure pass-through to local LLM
+     */
+    async chat(userMessage, conversationHistory = []) {
+        const model = process.env.OPENAI_MODEL || 'gpt-4o';
+        try {
+            const messages = [
+                ...conversationHistory.slice(-4).map(msg => ({
+                    role: msg.role,
+                    content: msg.content,
+                })),
+                { role: 'user', content: userMessage },
+            ];
+            logger.debug('Chat', { model, msgCount: messages.length });
+            const response = await this.client.chat.completions.create({
+                model,
+                messages,
+                max_tokens: 500,
+                temperature: 0.7,
+            });
+            const reply = response.choices[0]?.message?.content || 'Could not respond.';
+            logger.info('Response', {
+                in: response.usage?.prompt_tokens,
+                out: response.usage?.completion_tokens,
+            });
+            return reply;
+        }
+        catch (error) {
+            logger.error('Chat failed', error);
+            throw error;
+        }
+    }
+}
+exports.McpAssistant = McpAssistant;
+//# sourceMappingURL=mcp-assistant.js.map

package/dist/client/mcp-client.js

@@ -8,6 +8,7 @@ exports.McpClient = void 0;
 const message_processor_1 = require("./message-processor");
 const openai_provider_1 = require("./providers/openai-provider");
 const anthropic_provider_1 = require("./providers/anthropic-provider");
+const assistant_provider_1 = require("./providers/assistant-provider");
 const multi_bot_manager_1 = require("./multi-bot-manager");
 const agent_tracker_1 = require("./agent-tracker");
 const token_tracker_1 = require("./token-tracker");
@@ -102,6 +103,9 @@ class McpClient {
                     case "anthropic":
                         provider = new anthropic_provider_1.AnthropicProvider(providerConfig);
                         break;
+                    case "assistant":
+                        provider = new assistant_provider_1.AssistantProvider(providerConfig);
+                        break;
                     case "gemini":
                         // TODO: Implement GeminiProvider
                         console.warn(`⚠️ Provider type ${providerConfig.type} not yet implemented`);
@@ -306,9 +310,11 @@ class McpClient {
                     }
                     return; // Skip LLM processing
                 }
-                // Generate and post personalized confirmation message
+                // Generate and post personalized confirmation message (skip if empty)
                 const confirmationMessage = await provider.generateConfirmationMessage(message);
-                await this.messageProcessor.postMessage(message.discussionId, confirmationMessage, message.workspaceId, message.mentionedOrDirectMessagedBotId);
+                if (confirmationMessage) {
+                    await this.messageProcessor.postMessage(message.discussionId, confirmationMessage, message.workspaceId, message.mentionedOrDirectMessagedBotId);
+                }
                 const response = await this.processMessage(message, provider);
                 await this.handleResponse(message, response);
                 // LOG COMPLETION EVENT - Bot finished processing

package/dist/client/providers/assistant-provider.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Assistant Provider
+ *
+ * Pure pass-through chatbot. No tools, no local system prompt.
+ * System prompt is loaded on AI PC side via llama-server.
+ */
+import { ChatMessage, McpResponse } from "../types";
+import { LlmProvider } from "./llm-provider";
+import { LlmProviderConfig } from "../types";
+export declare class AssistantProvider extends LlmProvider {
+    private assistant;
+    constructor(config: LlmProviderConfig);
+    generateConfirmationMessage(_userMessage: ChatMessage): Promise<string>;
+    processMessage(userMessage: ChatMessage, _mcpServerUrl: string, _botMcpApiKey: string, _botEmail: string): Promise<McpResponse>;
+    protected callMcpTool(): Promise<any>;
+}
+//# sourceMappingURL=assistant-provider.d.ts.map

package/dist/client/providers/assistant-provider.js

@@ -0,0 +1,51 @@
+"use strict";
+/**
+ * Assistant Provider
+ *
+ * Pure pass-through chatbot. No tools, no local system prompt.
+ * System prompt is loaded on AI PC side via llama-server.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AssistantProvider = void 0;
+const llm_provider_1 = require("./llm-provider");
+const mcp_assistant_1 = require("../mcp-assistant");
+class AssistantProvider extends llm_provider_1.LlmProvider {
+    assistant;
+    constructor(config) {
+        super(config);
+        this.assistant = new mcp_assistant_1.McpAssistant({
+            apiKey: config.apiKey,
+            baseURL: config.baseURL,
+        });
+    }
+    async generateConfirmationMessage(_userMessage) {
+        // No confirmation message - direct response only
+        return '';
+    }
+    async processMessage(userMessage, _mcpServerUrl, _botMcpApiKey, _botEmail) {
+        if (!this.isEnabled()) {
+            return { success: false, error: "Assistant not enabled" };
+        }
+        try {
+            const startTime = Date.now();
+            const cleanedMessage = this.removeMentions(userMessage);
+            this.logger.debug('Chat request', { user: userMessage.userName });
+            const response = await this.assistant.chat(cleanedMessage);
+            this.logger.info('Chat done', { duration: Date.now() - startTime });
+            return {
+                success: true,
+                response,
+                toolCalls: [],
+            };
+        }
+        catch (error) {
+            this.logError(error, "processMessage");
+            return { success: false, error: error.message };
+        }
+    }
+    async callMcpTool() {
+        throw new Error("Assistant does not use tools");
+    }
+}
+exports.AssistantProvider = AssistantProvider;
+//# sourceMappingURL=assistant-provider.js.map

package/dist/client/providers/openai-provider.js

@@ -20,6 +20,7 @@ class OpenAIProvider extends llm_provider_1.LlmProvider {
         super(config);
         this.client = new openai_1.default({
             apiKey: config.apiKey,
+            baseURL: config.baseURL,
         });
         this.contextManager = (0, context_manager_1.getContextManager)({
             openaiApiKey: config.apiKey,
@@ -72,11 +73,19 @@ class OpenAIProvider extends llm_provider_1.LlmProvider {
             const startTime = Date.now();
             // Load tool index with automatic filtering
             // Chat bot only gets READ + WRITE tools (no PLAYGROUND tools)
+            // In 'minimal' mode, only load essential chat tools (~3 tools vs 40+)
             const allowedGroups = [tool_registry_1.ToolGroup.READ, tool_registry_1.ToolGroup.WRITE];
+            const minimalChatTools = [
+                'add_discussion_message',
+                'fetch_discussion_messages',
+                'search_workspace_users'
+            ];
+            const isMinimalMode = process.env.CHAT_BOT_MODE === 'minimal';
             const toolIndex = await this.toolSchemaLoader.loadToolIndex({
                 mcpServerUrl,
                 mcpServerApiKey: botMcpApiKey,
-                allowedGroups
+                allowedGroups,
+                allowedTools: isMinimalMode ? minimalChatTools : undefined
             });
             if (!toolIndex || toolIndex.length === 0) {
                 this.logger.warn("No MCP tools available");

package/dist/client/tool-schema-loader.d.ts

@@ -25,6 +25,7 @@ export interface LoadToolsOptions {
     mcpServerUrl: string;
     mcpServerApiKey: string;
     allowedGroups: ToolGroup[];
+    allowedTools?: string[];
     excludeMessageFetchTools?: boolean;
 }
 export declare class ToolSchemaLoader {

package/dist/client/tool-schema-loader.js

@@ -22,9 +22,17 @@ class ToolSchemaLoader {
      * Returns lightweight tool list with optional exclusions
      */
     async loadToolIndex(options) {
-        const { mcpServerUrl, mcpServerApiKey, allowedGroups, excludeMessageFetchTools } = options;
+        const { mcpServerUrl, mcpServerApiKey, allowedGroups, allowedTools, excludeMessageFetchTools } = options;
         // Fetch tool index from MCP server with group filtering
         let toolIndex = await this.fetchMcpToolIndex(mcpServerUrl, mcpServerApiKey, allowedGroups);
+        // Filter by explicit whitelist if provided (overrides group filtering)
+        if (allowedTools && allowedTools.length > 0) {
+            toolIndex = toolIndex.filter(tool => allowedTools.includes(tool.name));
+            logger.info("Filtered tools by whitelist", {
+                allowedTools,
+                resultCount: toolIndex.length
+            });
+        }
         // Optionally exclude message fetch tools if explicitly requested
         if (excludeMessageFetchTools) {
             const excludedTools = ['fetch_discussion_messages', 'fetch_previous_discussion_messages'];

package/dist/client/types.d.ts

@@ -16,8 +16,9 @@ export interface McpClientConfig {
 }
 export interface LlmProviderConfig {
     name: string;
-    type: "openai" | "anthropic" | "gemini";
+    type: "openai" | "anthropic" | "gemini" | "assistant";
     apiKey: string;
+    baseURL?: string;
     model: string;
     enabled: boolean;
     maxTokens?: number;

package/dist/config.d.ts

@@ -35,6 +35,7 @@ export declare const environment: {
     MCP_CLIENT_AGENT_IDS: string[];
     TOKEN_USAGE_BOT_ENABLED: boolean;
     AGENT_ACTIVITY_BOT_ENABLED: boolean;
+    CHAT_BOT_MODE: "full" | "minimal" | "assistant";
     ADAPTIVE_DOCUMENTATION_BOT_ENABLED: boolean;
     ADAPTIVE_AUTO_UPDATE: boolean;
     ADAPTIVE_UPDATE_INTERVAL: number;
@@ -49,6 +50,8 @@ export declare const environment: {
     WORKSPACE_CONFIG_PATH?: string | undefined;
     DEV_APPS_PATH?: string | undefined;
     OPENAI_API_KEY?: string | undefined;
+    OPENAI_API_BASE?: string | undefined;
+    OPENAI_MODEL?: string | undefined;
     ANTHROPIC_API_KEY?: string | undefined;
 };
 export interface HailerAccount {
@@ -60,8 +63,9 @@ export interface HailerAccount {
 }
 export interface LlmProvider {
     name: string;
-    type: 'openai' | 'anthropic';
+    type: 'openai' | 'anthropic' | 'assistant';
     apiKey: string;
+    baseURL?: string;
     model: string;
     enabled: boolean;
 }

package/dist/config.js

@@ -102,6 +102,8 @@ const environmentSchema = zod_1.z.object({
     DEV_APPS_PATH: zod_1.z.string().optional(),
     // LLM providers
     OPENAI_API_KEY: zod_1.z.string().min(1).optional(),
+    OPENAI_API_BASE: zod_1.z.string().url().optional(),
+    OPENAI_MODEL: zod_1.z.string().optional(),
     ANTHROPIC_API_KEY: zod_1.z.string().min(1).optional(),
     // MCP client settings
     MCP_SERVER_URL: zod_1.z.string().url().default('http://localhost:3030/api/mcp'),
@@ -110,6 +112,8 @@ const environmentSchema = zod_1.z.object({
     // Bot features
     TOKEN_USAGE_BOT_ENABLED: zod_1.z.string().transform(v => v !== 'false').default('true'),
     AGENT_ACTIVITY_BOT_ENABLED: zod_1.z.string().transform(v => v !== 'false').default('true'),
+    // Chat bot mode: 'full' = all tools, 'minimal' = chat tools only, 'assistant' = no tools (knowledge-based help)
+    CHAT_BOT_MODE: zod_1.z.enum(['full', 'minimal', 'assistant']).default('full'),
     ADAPTIVE_DOCUMENTATION_BOT_ENABLED: zod_1.z.string().transform(v => v === 'true').default('false'),
     ADAPTIVE_AUTO_UPDATE: zod_1.z.string().transform(v => v === 'true').default('false'),
     ADAPTIVE_UPDATE_INTERVAL: zod_1.z.string().transform(v => parseInt(v) || 60000).default('60000'),
@@ -164,12 +168,14 @@ class ApplicationConfig {
     }
     get llmProviders() {
         const providers = [];
-        if (exports.environment.OPENAI_API_KEY) {
+        if (exports.environment.OPENAI_API_KEY || exports.environment.OPENAI_API_BASE) {
+            const isAssistantMode = exports.environment.CHAT_BOT_MODE === 'assistant';
             providers.push({
-                name: 'openai-gpt4o',
-                type: 'openai',
-                apiKey: exports.environment.OPENAI_API_KEY,
-                model: 'gpt-4o',
+                name: isAssistantMode ? 'mcp-assistant' : (exports.environment.OPENAI_API_BASE ? 'local-llm' : 'openai-gpt4o'),
+                type: isAssistantMode ? 'assistant' : 'openai',
+                apiKey: exports.environment.OPENAI_API_KEY || 'not-needed',
+                baseURL: exports.environment.OPENAI_API_BASE,
+                model: exports.environment.OPENAI_MODEL || 'gpt-4o',
                 enabled: true,
             });
         }