hmn-masterclass-mcp 1.0.0

package/bin/hmn-masterclass.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+const { main } = require('../src/server');
+
+main().catch((err) => {
+  process.stderr.write(`Fatal: ${err.message}\n`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "hmn-masterclass-mcp",
+  "version": "1.0.0",
+  "description": "HMN Masterclass MCP Server — adaptive learning for AI upskilling",
+  "bin": { "hmn-masterclass": "./bin/hmn-masterclass.js" },
+  "main": "src/server.js",
+  "scripts": { "start": "node bin/hmn-masterclass.js" },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.20.2",
+    "zod": "^3.25.76",
+    "axios": "^1.12.0"
+  }
+}

package/src/activity/logger.js

@@ -0,0 +1,67 @@
+/**
+ * Activity logger — appends sanitized JSON-line events to ~/.hmn/activity.jsonl.
+ * Thread-safe via appendFileSync (simplest approach in single-process MCP context).
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { ensureConfigDir } = require('../util/config');
+const { sanitizeEvent } = require('../util/privacy');
+
+const ACTIVITY_FILE = 'activity.jsonl';
+
+class ActivityLogger {
+  constructor(config) {
+    this.config = config;
+    this.trackingEnabled = config.tracking_enabled !== false;
+    ensureConfigDir();
+    this.filePath = path.join(require('../util/config').getConfigPath(), ACTIVITY_FILE);
+  }
+
+  /**
+   * Log a single event to activity.jsonl.
+   * Applies privacy sanitization before writing.
+   * Silently skips if tracking is disabled (except for explicit user actions).
+   *
+   * @param {Object} event - ActivityEvent object
+   * @param {Object} [options] - { force: boolean } — force logging even if tracking disabled
+   */
+  logEvent(event, options = {}) {
+    // Allow force-logging for explicit user actions (log_build, submit_homework)
+    if (!this.trackingEnabled && !options.force) {
+      return;
+    }
+
+    try {
+      const enriched = {
+        timestamp: new Date().toISOString(),
+        participant_email: this.config.email,
+        ...event
+      };
+
+      const sanitized = sanitizeEvent(enriched);
+      const line = JSON.stringify(sanitized) + '\n';
+
+      fs.appendFileSync(this.filePath, line, 'utf-8');
+    } catch (err) {
+      // Never throw from logger — just write to stderr
+      process.stderr.write(`[hmn-mcp] Logger error: ${err.message}\n`);
+    }
+  }
+
+  /**
+   * Set tracking enabled/disabled state.
+   */
+  setTracking(enabled) {
+    this.trackingEnabled = enabled;
+  }
+
+  /**
+   * Get the path to the activity log file.
+   */
+  getFilePath() {
+    return this.filePath;
+  }
+}
+
+module.exports = { ActivityLogger };

package/src/activity/sync.js

@@ -0,0 +1,216 @@
+/**
+ * Background sync engine — reads events from activity.jsonl after sync_cursor,
+ * batches them, and POSTs to the platform API.
+ *
+ * Non-blocking: sync failures never affect MCP tool responses.
+ * Exponential backoff: 60s -> 120s -> 240s -> 600s max on failure.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { getConfigPath } = require('../util/config');
+
+const SYNC_CURSOR_FILE = 'sync_cursor.txt';
+const ACTIVITY_FILE = 'activity.jsonl';
+const MAX_BATCH_SIZE = 100;
+const MAX_BACKOFF_MS = 600000; // 10 minutes
+
+class SyncEngine {
+  constructor(config, httpClient, logger) {
+    this.config = config;
+    this.http = httpClient;
+    this.logger = logger;
+    this.intervalId = null;
+    this.currentIntervalMs = config.sync_interval_ms || 60000;
+    this.baseIntervalMs = this.currentIntervalMs;
+    this.backoffMultiplier = 1;
+    this.authError = false;
+
+    const configDir = getConfigPath();
+    this.cursorPath = path.join(configDir, SYNC_CURSOR_FILE);
+    this.activityPath = path.join(configDir, ACTIVITY_FILE);
+  }
+
+  /**
+   * Start the background sync interval.
+   */
+  start() {
+    // Run an initial sync after a short delay to catch any pending events
+    setTimeout(() => this.sync(), 5000);
+
+    this.intervalId = setInterval(() => {
+      this.sync();
+    }, this.currentIntervalMs);
+
+    return this;
+  }
+
+  /**
+   * Stop the background sync.
+   */
+  stop() {
+    if (this.intervalId) {
+      clearInterval(this.intervalId);
+      this.intervalId = null;
+    }
+  }
+
+  /**
+   * Trigger an immediate sync (used after log_build, submit_homework).
+   */
+  async syncNow() {
+    return this.sync();
+  }
+
+  /**
+   * Read the current sync cursor (line number of last synced line).
+   */
+  readCursor() {
+    try {
+      if (fs.existsSync(this.cursorPath)) {
+        const raw = fs.readFileSync(this.cursorPath, 'utf-8').trim();
+        const num = parseInt(raw, 10);
+        return isNaN(num) ? 0 : num;
+      }
+    } catch {
+      // Ignore
+    }
+    return 0;
+  }
+
+  /**
+   * Write the sync cursor.
+   */
+  writeCursor(lineNumber) {
+    try {
+      fs.writeFileSync(this.cursorPath, String(lineNumber), 'utf-8');
+    } catch (err) {
+      process.stderr.write(`[hmn-mcp] Failed to write sync cursor: ${err.message}\n`);
+    }
+  }
+
+  /**
+   * Read unsynced lines from activity.jsonl.
+   */
+  readUnsyncedEvents() {
+    try {
+      if (!fs.existsSync(this.activityPath)) {
+        return { events: [], totalLines: 0 };
+      }
+
+      const content = fs.readFileSync(this.activityPath, 'utf-8');
+      const lines = content.split('\n').filter((line) => line.trim().length > 0);
+      const cursor = this.readCursor();
+
+      // Get lines after the cursor
+      const unsyncedLines = lines.slice(cursor);
+      const events = [];
+
+      for (const line of unsyncedLines.slice(0, MAX_BATCH_SIZE)) {
+        try {
+          events.push(JSON.parse(line));
+        } catch {
+          // Skip malformed lines
+        }
+      }
+
+      return { events, totalLines: lines.length, cursor };
+    } catch (err) {
+      process.stderr.write(`[hmn-mcp] Failed to read activity log: ${err.message}\n`);
+      return { events: [], totalLines: 0, cursor: 0 };
+    }
+  }
+
+  /**
+   * Core sync method — reads unsynced events and POSTs them to the API.
+   */
+  async sync() {
+    // Don't retry if we got a 401
+    if (this.authError) return;
+
+    try {
+      const { events, totalLines, cursor } = this.readUnsyncedEvents();
+
+      if (events.length === 0) return;
+
+      await this.http.post('/api/masterclass/activity', {
+        participant_email: this.config.email,
+        events
+      });
+
+      // Success — advance cursor
+      const newCursor = cursor + events.length;
+      this.writeCursor(newCursor);
+
+      // Reset backoff on success
+      this.resetBackoff();
+
+      process.stderr.write(
+        `[hmn-mcp] Synced ${events.length} events (cursor: ${newCursor}/${totalLines})\n`
+      );
+    } catch (err) {
+      // Check for auth errors — don't retry
+      if (err.message && err.message.includes('401')) {
+        this.authError = true;
+        process.stderr.write(
+          `[hmn-mcp] Auth error during sync — will not retry until next manual trigger.\n`
+        );
+        return;
+      }
+
+      // Apply exponential backoff
+      this.applyBackoff();
+      process.stderr.write(
+        `[hmn-mcp] Sync failed (next retry in ${this.currentIntervalMs / 1000}s): ${err.message}\n`
+      );
+    }
+  }
+
+  /**
+   * Apply exponential backoff — doubles the interval up to MAX_BACKOFF_MS.
+   */
+  applyBackoff() {
+    this.backoffMultiplier = Math.min(this.backoffMultiplier * 2, MAX_BACKOFF_MS / this.baseIntervalMs);
+    this.currentIntervalMs = Math.min(this.baseIntervalMs * this.backoffMultiplier, MAX_BACKOFF_MS);
+
+    // Restart interval with new timing
+    if (this.intervalId) {
+      clearInterval(this.intervalId);
+      this.intervalId = setInterval(() => this.sync(), this.currentIntervalMs);
+    }
+  }
+
+  /**
+   * Reset backoff to base interval after a successful sync.
+   */
+  resetBackoff() {
+    if (this.backoffMultiplier !== 1) {
+      this.backoffMultiplier = 1;
+      this.currentIntervalMs = this.baseIntervalMs;
+
+      // Restart interval with base timing
+      if (this.intervalId) {
+        clearInterval(this.intervalId);
+        this.intervalId = setInterval(() => this.sync(), this.currentIntervalMs);
+      }
+    }
+  }
+
+  /**
+   * Reset auth error flag (called when user manually triggers sync).
+   */
+  resetAuthError() {
+    this.authError = false;
+  }
+}
+
+/**
+ * Factory: create and start the sync engine.
+ */
+function startSync(config, httpClient, logger) {
+  const engine = new SyncEngine(config, httpClient, logger);
+  engine.start();
+  return engine;
+}
+
+module.exports = { SyncEngine, startSync };

package/src/server.js

@@ -0,0 +1,122 @@
+/**
+ * @hmn/masterclass-mcp — MCP Server
+ *
+ * Adaptive learning server for HMN Masterclass participants.
+ * Exposes tools for progress tracking, personalized prompts, build logging,
+ * and homework submission. Passively logs activity and syncs to the platform.
+ */
+
+const { McpServer } = require('@modelcontextprotocol/sdk/server/mcp.js');
+const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
+const { loadConfig } = require('./util/config');
+const { createHttpClient } = require('./util/http-client');
+const { ActivityLogger } = require('./activity/logger');
+const { startSync } = require('./activity/sync');
+const { registerProgressTools } = require('./tools/progress');
+const { registerContentTools } = require('./tools/content');
+const { registerLoggingTools } = require('./tools/logging');
+const { registerTrackingTools } = require('./tools/tracking');
+
+function createServer(config) {
+  const server = new McpServer({
+    name: 'hmn-masterclass',
+    version: '1.0.0'
+  });
+
+  // Initialize HTTP client
+  const http = createHttpClient(config);
+
+  // Initialize activity logger
+  const logger = new ActivityLogger(config);
+
+  // Initialize sync engine (background interval)
+  const syncEngine = startSync(config, http, logger);
+
+  // Register all tool groups
+  registerProgressTools(server, http, logger);
+  registerContentTools(server, http, logger);
+  registerLoggingTools(server, http, logger, syncEngine);
+  registerTrackingTools(server, http, logger);
+
+  // Log session_start event
+  logger.logEvent({
+    event_type: 'session_start',
+    data: {
+      timestamp: new Date().toISOString()
+    }
+  });
+
+  // Handle process exit — log session_end and stop sync
+  const cleanup = () => {
+    logger.logEvent({
+      event_type: 'session_end',
+      data: {
+        timestamp: new Date().toISOString()
+      }
+    }, { force: true });
+    syncEngine.stop();
+  };
+
+  process.on('SIGINT', () => {
+    cleanup();
+    process.exit(0);
+  });
+
+  process.on('SIGTERM', () => {
+    cleanup();
+    process.exit(0);
+  });
+
+  process.on('exit', () => {
+    // Best-effort — synchronous only at this point
+    try {
+      logger.logEvent({
+        event_type: 'session_end',
+        data: {
+          timestamp: new Date().toISOString()
+        }
+      }, { force: true });
+    } catch {
+      // Can't do anything here
+    }
+  });
+
+  return server;
+}
+
+async function main() {
+  const config = loadConfig();
+
+  // Validate required config
+  if (!config.email) {
+    process.stderr.write(
+      'Error: HMN_EMAIL environment variable is required.\n' +
+      'Set it in your MCP server config:\n' +
+      '  "env": { "HMN_EMAIL": "your.email@company.com" }\n'
+    );
+    process.exit(1);
+  }
+
+  if (!config.api_key) {
+    process.stderr.write(
+      'Error: HMN_API_KEY environment variable is required.\n' +
+      'Generate one at https://behmn.com/dashboard → Settings → API Key\n' +
+      'Then set it in your MCP server config:\n' +
+      '  "env": { "HMN_API_KEY": "hmn_ak_..." }\n'
+    );
+    process.exit(1);
+  }
+
+  process.stderr.write(
+    `[hmn-mcp] Starting HMN Masterclass MCP server for ${config.email}\n` +
+    `[hmn-mcp] API host: ${config.api_host}\n` +
+    `[hmn-mcp] Tracking: ${config.tracking_enabled ? 'enabled' : 'disabled'}\n` +
+    `[hmn-mcp] Sync interval: ${config.sync_interval_ms / 1000}s\n`
+  );
+
+  const server = createServer(config);
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+module.exports = { createServer, main };

package/src/tools/content.js

@@ -0,0 +1,221 @@
+/**
+ * Content tools — hmn_get_prompt and hmn_my_profile.
+ */
+
+const { z } = require('zod');
+
+function registerContentTools(server, http, logger) {
+
+  // ─── hmn_get_prompt ───────────────────────────────────────────────────
+  server.tool(
+    'hmn_get_prompt',
+    'Get personalized prompts for a specific module and section',
+    {
+      module_number: z.number().describe('Module number (e.g. 1, 2, 3)'),
+      section_id: z.string().describe('Section identifier (e.g. "competitive-intel", "client-brief")')
+    },
+    async ({ module_number, section_id }) => {
+      try {
+        const profile = await http.get('/api/masterclass/me');
+        const modules = profile.modules || [];
+
+        // Find the matching module
+        const mod = modules.find(
+          (m) => (m.module_number || m.number) === module_number
+        );
+
+        if (!mod) {
+          return {
+            content: [{
+              type: 'text',
+              text: `Module ${module_number} not found. Available modules: ${modules.map((m) => m.module_number || m.number).join(', ')}`
+            }]
+          };
+        }
+
+        // Find the matching section
+        const section = (mod.sections || []).find(
+          (s) => s.id === section_id || s.title?.toLowerCase().includes(section_id.toLowerCase())
+        );
+
+        if (!section) {
+          const sectionIds = (mod.sections || []).map((s) => s.id || s.title);
+          return {
+            content: [{
+              type: 'text',
+              text: `Section "${section_id}" not found in Module ${module_number}. Available sections: ${sectionIds.join(', ')}`
+            }]
+          };
+        }
+
+        // Get personalized content for this section
+        const personalizedContent = profile.personalizedContent || profile.personalized_content || {};
+        const moduleKey = `module_${module_number}`;
+        const sectionContent = personalizedContent[moduleKey]?.[section_id] ||
+                               personalizedContent[section_id] ||
+                               null;
+
+        let text = `## Module ${module_number}: ${mod.title}\n`;
+        text += `### ${section.title || section_id}\n\n`;
+
+        if (section.description) {
+          text += `${section.description}\n\n`;
+        }
+
+        // Format personalized examples
+        if (sectionContent) {
+          if (sectionContent.examples && sectionContent.examples.length > 0) {
+            text += `### Personalized Examples\n\n`;
+            for (const example of sectionContent.examples) {
+              text += `**${example.title || 'Example'}**\n`;
+              if (example.context) text += `_Context:_ ${example.context}\n`;
+              if (example.prompt) {
+                text += `\n\`\`\`\n${example.prompt}\n\`\`\`\n\n`;
+              }
+              if (example.expected_outcome) {
+                text += `_Expected outcome:_ ${example.expected_outcome}\n\n`;
+              }
+            }
+          }
+
+          if (sectionContent.homework) {
+            text += `### Homework\n\n`;
+            text += `${sectionContent.homework.description || sectionContent.homework}\n\n`;
+
+            if (sectionContent.homework.checklist) {
+              text += `**Checklist:**\n`;
+              for (const item of sectionContent.homework.checklist) {
+                text += `- [ ] ${item}\n`;
+              }
+              text += `\n`;
+            }
+          }
+
+          if (sectionContent.callouts && sectionContent.callouts.length > 0) {
+            text += `### Key Notes\n\n`;
+            for (const callout of sectionContent.callouts) {
+              text += `> ${callout}\n\n`;
+            }
+          }
+        } else {
+          text += `_No personalized content available for this section yet. `;
+          text += `Complete the section activities and your content will be generated based on your profile._\n`;
+        }
+
+        return { content: [{ type: 'text', text }] };
+      } catch (err) {
+        return { content: [{ type: 'text', text: `Error fetching prompt: ${err.message}` }] };
+      }
+    }
+  );
+
+  // ─── hmn_my_profile ───────────────────────────────────────────────────
+  server.tool(
+    'hmn_my_profile',
+    'View your full AI profile — maturity level, pain points, use cases, learning goals',
+    {},
+    async () => {
+      try {
+        const profile = await http.get('/api/masterclass/me');
+
+        const profileData = profile.profile_data || profile.profileData || profile;
+        const maturityLevel = profile.maturity_level || profile.maturityLevel || 0;
+
+        let text = `## Your AI Profile\n\n`;
+
+        // Basic info
+        text += `**Name:** ${profile.name || profile.full_name || 'N/A'}\n`;
+        text += `**Email:** ${profile.email || 'N/A'}\n`;
+        text += `**Organization:** ${profile.organization || profile.company || 'N/A'}\n`;
+        text += `**Role:** ${profile.role || profile.job_title || 'N/A'}\n\n`;
+
+        // Maturity level
+        text += `### AI Maturity Level\n`;
+        text += `**Level ${maturityLevel}** — ${getLevelLabel(maturityLevel)}\n\n`;
+
+        // Background
+        if (profileData.background || profileData.experience) {
+          text += `### Background\n`;
+          text += `${profileData.background || profileData.experience}\n\n`;
+        }
+
+        // Pain points
+        if (profileData.pain_points || profileData.painPoints) {
+          const pains = profileData.pain_points || profileData.painPoints;
+          text += `### Pain Points\n`;
+          if (Array.isArray(pains)) {
+            for (const pain of pains) {
+              text += `- ${pain}\n`;
+            }
+          } else {
+            text += `${pains}\n`;
+          }
+          text += `\n`;
+        }
+
+        // Use cases
+        if (profileData.use_cases || profileData.useCases) {
+          const cases = profileData.use_cases || profileData.useCases;
+          text += `### Use Cases\n`;
+          if (Array.isArray(cases)) {
+            for (const uc of cases) {
+              text += `- ${uc}\n`;
+            }
+          } else {
+            text += `${cases}\n`;
+          }
+          text += `\n`;
+        }
+
+        // Wants to learn
+        if (profileData.wants_to_learn || profileData.wantsToLearn || profileData.learning_goals) {
+          const goals = profileData.wants_to_learn || profileData.wantsToLearn || profileData.learning_goals;
+          text += `### Wants to Learn\n`;
+          if (Array.isArray(goals)) {
+            for (const goal of goals) {
+              text += `- ${goal}\n`;
+            }
+          } else {
+            text += `${goals}\n`;
+          }
+          text += `\n`;
+        }
+
+        // Tools already using
+        if (profileData.tools_using || profileData.toolsUsing || profileData.current_tools) {
+          const tools = profileData.tools_using || profileData.toolsUsing || profileData.current_tools;
+          text += `### Tools Currently Using\n`;
+          if (Array.isArray(tools)) {
+            for (const tool of tools) {
+              text += `- ${tool}\n`;
+            }
+          } else {
+            text += `${tools}\n`;
+          }
+          text += `\n`;
+        }
+
+        return { content: [{ type: 'text', text }] };
+      } catch (err) {
+        return { content: [{ type: 'text', text: `Error fetching profile: ${err.message}` }] };
+      }
+    }
+  );
+}
+
+/**
+ * Map maturity level number to label.
+ */
+function getLevelLabel(level) {
+  const labels = {
+    0: 'Not Assessed',
+    1: 'AI Curious',
+    2: 'AI Experimenting',
+    3: 'AI Connecting',
+    4: 'AI Collaborating',
+    5: 'AI Leading'
+  };
+  return labels[level] || `Level ${level}`;
+}
+
+module.exports = { registerContentTools };

package/src/tools/logging.js

@@ -0,0 +1,122 @@
+/**
+ * Logging tools — hmn_log_build and hmn_submit_homework.
+ */
+
+const { z } = require('zod');
+
+function registerLoggingTools(server, http, logger, syncEngine) {
+
+  // ─── hmn_log_build ────────────────────────────────────────────────────
+  server.tool(
+    'hmn_log_build',
+    'Log something you built — tell the system what you created',
+    {
+      description: z.string().describe('What you built — describe it in plain language'),
+      tools_used: z.array(z.string()).optional().describe('Tools you used (e.g. ["Firecrawl", "Claude", "Chrome DevTools"])')
+    },
+    async ({ description, tools_used }) => {
+      try {
+        // Write build_logged event to activity log
+        logger.logEvent({
+          event_type: 'build_logged',
+          data: {
+            description,
+            tools_used: tools_used || []
+          }
+        }, { force: true });
+
+        // Trigger immediate sync so the platform sees it right away
+        if (syncEngine) {
+          syncEngine.resetAuthError();
+          syncEngine.syncNow().catch(() => {
+            // Non-blocking — ignore sync errors
+          });
+        }
+
+        let text = `## Build Logged\n\n`;
+        text += `**What you built:** ${description}\n`;
+        if (tools_used && tools_used.length > 0) {
+          text += `**Tools used:** ${tools_used.join(', ')}\n`;
+        }
+        text += `\nYour build has been recorded and will be synced to the platform. `;
+        text += `Builds like this help demonstrate your AI maturity growth.\n`;
+
+        return { content: [{ type: 'text', text }] };
+      } catch (err) {
+        return { content: [{ type: 'text', text: `Error logging build: ${err.message}` }] };
+      }
+    }
+  );
+
+  // ─── hmn_submit_homework ──────────────────────────────────────────────
+  server.tool(
+    'hmn_submit_homework',
+    'Submit your homework assignment',
+    {
+      module_number: z.number().describe('Module number (e.g. 1, 2, 3)'),
+      description: z.string().describe('Describe what you did for the homework'),
+      files_created: z.array(z.string()).optional().describe('File paths or names you created for this assignment')
+    },
+    async ({ module_number, description, files_created }) => {
+      try {
+        // POST to platform to mark progress
+        let progressResult = null;
+        try {
+          progressResult = await http.post('/api/masterclass/progress', {
+            module_number,
+            description,
+            files_created: files_created || []
+          });
+        } catch (apiErr) {
+          // Log the event even if the API call fails
+          process.stderr.write(
+            `[hmn-mcp] Progress API error (event still logged locally): ${apiErr.message}\n`
+          );
+        }
+
+        // Write homework_submitted event to activity log
+        logger.logEvent({
+          event_type: 'homework_submitted',
+          data: {
+            module_number,
+            description,
+            file_names: files_created || [],
+            success: progressResult !== null
+          }
+        }, { force: true });
+
+        // Trigger immediate sync
+        if (syncEngine) {
+          syncEngine.resetAuthError();
+          syncEngine.syncNow().catch(() => {
+            // Non-blocking
+          });
+        }
+
+        let text = `## Homework Submitted\n\n`;
+        text += `**Module ${module_number}**\n`;
+        text += `**Description:** ${description}\n`;
+        if (files_created && files_created.length > 0) {
+          text += `**Files:** ${files_created.join(', ')}\n`;
+        }
+        text += `\n`;
+
+        if (progressResult) {
+          text += `Your submission has been recorded on the platform.\n`;
+          if (progressResult.next_assignment) {
+            text += `\n### Next Assignment\n`;
+            text += `${progressResult.next_assignment}\n`;
+          }
+        } else {
+          text += `Your submission has been logged locally and will sync when the platform is available.\n`;
+        }
+
+        return { content: [{ type: 'text', text }] };
+      } catch (err) {
+        return { content: [{ type: 'text', text: `Error submitting homework: ${err.message}` }] };
+      }
+    }
+  );
+}
+
+module.exports = { registerLoggingTools };

package/src/tools/progress.js

@@ -0,0 +1,170 @@
+/**
+ * Progress tools — hmn_check_progress and hmn_whats_next.
+ */
+
+const { z } = require('zod');
+
+function registerProgressTools(server, http, logger) {
+
+  // ─── hmn_check_progress ───────────────────────────────────────────────
+  server.tool(
+    'hmn_check_progress',
+    'Check your masterclass progress — current level, completed sections, what\'s next',
+    {},
+    async () => {
+      try {
+        const profile = await http.get('/api/masterclass/me');
+
+        const maturityLevel = profile.maturity_level || profile.maturityLevel || 0;
+        const maturityLabel = getLevelLabel(maturityLevel);
+        const modules = profile.modules || [];
+        const totalSections = modules.reduce(
+          (acc, m) => acc + (m.sections?.length || 0), 0
+        );
+        const completedSections = modules.reduce(
+          (acc, m) => acc + (m.sections?.filter((s) => s.completed).length || 0), 0
+        );
+        const completionPct = totalSections > 0
+          ? Math.round((completedSections / totalSections) * 100)
+          : 0;
+
+        // Find next uncompleted sections
+        const nextSections = [];
+        for (const mod of modules) {
+          for (const section of (mod.sections || [])) {
+            if (!section.completed && nextSections.length < 3) {
+              nextSections.push({
+                module: mod.module_number || mod.number,
+                title: mod.title,
+                section: section.id || section.title,
+                sectionTitle: section.title
+              });
+            }
+          }
+        }
+
+        let text = `## Your Masterclass Progress\n\n`;
+        text += `**Maturity Level:** ${maturityLevel} — ${maturityLabel}\n`;
+        text += `**Completion:** ${completedSections}/${totalSections} sections (${completionPct}%)\n\n`;
+
+        if (nextSections.length > 0) {
+          text += `### Up Next\n`;
+          for (const ns of nextSections) {
+            text += `- **Module ${ns.module}** (${ns.title}): ${ns.sectionTitle}\n`;
+          }
+        } else if (completionPct === 100) {
+          text += `You've completed all sections! Check with your instructor about next steps.\n`;
+        }
+
+        return { content: [{ type: 'text', text }] };
+      } catch (err) {
+        return { content: [{ type: 'text', text: `Error checking progress: ${err.message}` }] };
+      }
+    }
+  );
+
+  // ─── hmn_whats_next ───────────────────────────────────────────────────
+  server.tool(
+    'hmn_whats_next',
+    'Get a personalized recommendation for what to work on next',
+    {},
+    async () => {
+      try {
+        const [profile, activitySummary] = await Promise.all([
+          http.get('/api/masterclass/me'),
+          http.get('/api/masterclass/activity/summary').catch(() => null)
+        ]);
+
+        const modules = profile.modules || [];
+        const maturityLevel = profile.maturity_level || profile.maturityLevel || 0;
+
+        // Find incomplete sections
+        const incompleteSections = [];
+        for (const mod of modules) {
+          for (const section of (mod.sections || [])) {
+            if (!section.completed) {
+              incompleteSections.push({
+                module: mod.module_number || mod.number,
+                moduleTitle: mod.title,
+                sectionId: section.id || section.title,
+                sectionTitle: section.title
+              });
+            }
+          }
+        }
+
+        // Analyze activity patterns
+        const toolsUsed = activitySummary?.tools_used || [];
+        const toolsNeverUsed = activitySummary?.tools_never_used || [];
+        const totalBuilds = activitySummary?.total_builds || 0;
+        const homeworkStatus = activitySummary?.homework_submitted || [];
+        const pendingHomework = homeworkStatus.filter((h) => !h.submitted);
+
+        let text = `## What to Work on Next\n\n`;
+
+        // Priority 1: Pending homework
+        if (pendingHomework.length > 0) {
+          const hw = pendingHomework[0];
+          text += `### Priority: Submit Homework\n`;
+          text += `You have outstanding homework for **Module ${hw.module}**. `;
+          text += `Use \`hmn_submit_homework\` when you're ready to submit.\n\n`;
+        }
+
+        // Priority 2: Next incomplete section
+        if (incompleteSections.length > 0) {
+          const next = incompleteSections[0];
+          text += `### Next Section\n`;
+          text += `**Module ${next.module}** (${next.moduleTitle}): ${next.sectionTitle}\n`;
+          text += `Use \`hmn_get_prompt\` to get personalized prompts for this section.\n\n`;
+        }
+
+        // Priority 3: Try unused tools
+        if (toolsNeverUsed.length > 0) {
+          text += `### Try Something New\n`;
+          text += `You haven't used these tools yet: **${toolsNeverUsed.slice(0, 3).join(', ')}**. `;
+          text += `Experimenting with new tools is key to advancing your maturity level.\n\n`;
+        }
+
+        // Priority 4: Build more
+        if (totalBuilds < 3) {
+          text += `### Build Challenge\n`;
+          text += `You've logged ${totalBuilds} build${totalBuilds !== 1 ? 's' : ''} so far. `;
+          text += `Try building something with AI and log it with \`hmn_log_build\`.\n\n`;
+        }
+
+        // Maturity hint
+        if (activitySummary?.maturity_evidence?.suggested_level &&
+            activitySummary.maturity_evidence.suggested_level > maturityLevel) {
+          text += `### Level Up Potential\n`;
+          text += `Your activity suggests you might be ready for **Level ${activitySummary.maturity_evidence.suggested_level}**. `;
+          text += `Keep building — your instructor will review your progress.\n`;
+        }
+
+        if (incompleteSections.length === 0 && pendingHomework.length === 0) {
+          text += `You've completed all assigned work! Talk to your instructor about advanced challenges.\n`;
+        }
+
+        return { content: [{ type: 'text', text }] };
+      } catch (err) {
+        return { content: [{ type: 'text', text: `Error generating recommendation: ${err.message}` }] };
+      }
+    }
+  );
+}
+
+/**
+ * Map maturity level number to label.
+ */
+function getLevelLabel(level) {
+  const labels = {
+    0: 'Not Assessed',
+    1: 'AI Curious',
+    2: 'AI Experimenting',
+    3: 'AI Connecting',
+    4: 'AI Collaborating',
+    5: 'AI Leading'
+  };
+  return labels[level] || `Level ${level}`;
+}
+
+module.exports = { registerProgressTools };

package/src/tools/tracking.js

@@ -0,0 +1,64 @@
+/**
+ * Tracking control tools — hmn_pause_tracking and hmn_resume_tracking.
+ */
+
+const { z } = require('zod');
+const { loadConfig, saveConfig } = require('../util/config');
+
+function registerTrackingTools(server, http, logger) {
+
+  // ─── hmn_pause_tracking ───────────────────────────────────────────────
+  server.tool(
+    'hmn_pause_tracking',
+    'Pause passive activity tracking — your explicit actions (log_build, submit_homework) still work',
+    {},
+    async () => {
+      try {
+        saveConfig({ tracking_enabled: false });
+        logger.setTracking(false);
+
+        let text = `## Tracking Paused\n\n`;
+        text += `Passive activity tracking is now **disabled**.\n\n`;
+        text += `**What still works:**\n`;
+        text += `- \`hmn_log_build\` — explicitly log something you built\n`;
+        text += `- \`hmn_submit_homework\` — submit homework assignments\n`;
+        text += `- \`hmn_check_progress\` — check your progress\n`;
+        text += `- All other MCP tools\n\n`;
+        text += `**What's paused:**\n`;
+        text += `- Automatic logging of tasks, sessions, and tool usage\n\n`;
+        text += `Use \`hmn_resume_tracking\` to re-enable passive tracking.\n`;
+
+        return { content: [{ type: 'text', text }] };
+      } catch (err) {
+        return { content: [{ type: 'text', text: `Error pausing tracking: ${err.message}` }] };
+      }
+    }
+  );
+
+  // ─── hmn_resume_tracking ──────────────────────────────────────────────
+  server.tool(
+    'hmn_resume_tracking',
+    'Resume passive activity tracking',
+    {},
+    async () => {
+      try {
+        saveConfig({ tracking_enabled: true });
+        logger.setTracking(true);
+
+        let text = `## Tracking Resumed\n\n`;
+        text += `Passive activity tracking is now **enabled**.\n\n`;
+        text += `Your activity (tasks, tool usage, sessions) will be logged locally `;
+        text += `and synced to the platform to help personalize your learning experience.\n\n`;
+        text += `**Privacy:** Only metadata is tracked (tool names, task counts, session durations). `;
+        text += `File contents and full prompts are never logged. `;
+        text += `Prompts are truncated to 200 characters and secrets are redacted.\n`;
+
+        return { content: [{ type: 'text', text }] };
+      } catch (err) {
+        return { content: [{ type: 'text', text: `Error resuming tracking: ${err.message}` }] };
+      }
+    }
+  );
+}
+
+module.exports = { registerTrackingTools };

package/src/util/config.js

@@ -0,0 +1,93 @@
+/**
+ * Configuration management — reads from env vars + ~/.hmn/config.json.
+ * Env vars always take precedence over the config file.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const CONFIG_DIR = path.join(os.homedir(), '.hmn');
+const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
+
+/**
+ * Ensure ~/.hmn/ directory exists.
+ */
+function ensureConfigDir() {
+  if (!fs.existsSync(CONFIG_DIR)) {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true });
+  }
+}
+
+/**
+ * Get the path to the ~/.hmn/ directory.
+ */
+function getConfigPath() {
+  ensureConfigDir();
+  return CONFIG_DIR;
+}
+
+/**
+ * Load config from env vars + ~/.hmn/config.json.
+ * Env vars take precedence over file values.
+ */
+function loadConfig() {
+  ensureConfigDir();
+
+  // Read file config if it exists
+  let fileConfig = {};
+  if (fs.existsSync(CONFIG_FILE)) {
+    try {
+      const raw = fs.readFileSync(CONFIG_FILE, 'utf-8');
+      fileConfig = JSON.parse(raw);
+    } catch {
+      // Corrupted config file — ignore it
+    }
+  }
+
+  // Merge: env vars override file config
+  const config = {
+    email: process.env.HMN_EMAIL || fileConfig.email || '',
+    api_key: process.env.HMN_API_KEY || fileConfig.api_key || '',
+    api_host: process.env.HMN_API_HOST || fileConfig.api_host || 'https://behmn.com',
+    tracking_enabled:
+      fileConfig.tracking_enabled !== undefined
+        ? fileConfig.tracking_enabled
+        : true,
+    sync_interval_ms:
+      fileConfig.sync_interval_ms !== undefined
+        ? fileConfig.sync_interval_ms
+        : 60000
+  };
+
+  return config;
+}
+
+/**
+ * Write updates to ~/.hmn/config.json.
+ * Merges with existing config — does not overwrite unrelated keys.
+ */
+function saveConfig(updates) {
+  ensureConfigDir();
+
+  let existing = {};
+  if (fs.existsSync(CONFIG_FILE)) {
+    try {
+      const raw = fs.readFileSync(CONFIG_FILE, 'utf-8');
+      existing = JSON.parse(raw);
+    } catch {
+      // Start fresh
+    }
+  }
+
+  const merged = { ...existing, ...updates };
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(merged, null, 2) + '\n', 'utf-8');
+  return merged;
+}
+
+module.exports = {
+  loadConfig,
+  saveConfig,
+  getConfigPath,
+  ensureConfigDir
+};

package/src/util/http-client.js

@@ -0,0 +1,61 @@
+/**
+ * HTTP client — Axios instance with auth headers and error handling.
+ */
+
+const axios = require('axios');
+
+/**
+ * Create an authenticated HTTP client for the HMN platform API.
+ *
+ * @param {Object} config - { api_key, api_host }
+ * @returns {import('axios').AxiosInstance} — response interceptor returns .data directly
+ */
+function createHttpClient(config) {
+  const client = axios.create({
+    baseURL: config.api_host,
+    headers: {
+      'Authorization': `Bearer ${config.api_key}`,
+      'X-HMN-API-Key': config.api_key,
+      'Content-Type': 'application/json'
+    },
+    timeout: 10000
+  });
+
+  // Unwrap response → return .data directly
+  client.interceptors.response.use(
+    (response) => response.data,
+    (error) => {
+      const status = error.response?.status;
+      const message =
+        error.response?.data?.message ||
+        error.response?.data?.error ||
+        error.message;
+
+      if (status === 401) {
+        return Promise.reject(
+          new Error(
+            `HMN API auth error (401): Invalid or expired API key. ` +
+            `Regenerate at ${config.api_host}/dashboard → Settings → API Key.`
+          )
+        );
+      }
+
+      if (status === 404) {
+        return Promise.reject(
+          new Error(
+            `HMN API not found (404): ${message}. ` +
+            `Check that your HMN_API_HOST is correct (current: ${config.api_host}).`
+          )
+        );
+      }
+
+      return Promise.reject(
+        new Error(`HMN API error (${status || 'network'}): ${message}`)
+      );
+    }
+  );
+
+  return client;
+}
+
+module.exports = { createHttpClient };

package/src/util/privacy.js

@@ -0,0 +1,119 @@
+/**
+ * Privacy utilities — truncation, path stripping, secret redaction.
+ * All sanitization happens before any event is written to disk or sent to the API.
+ */
+
+const path = require('path');
+
+const SECRET_PATTERNS = [
+  // Generic API keys / tokens
+  /(?:api[_-]?key|apikey|token|secret|password|passwd|authorization|bearer)\s*[:=]\s*['"]?[A-Za-z0-9_\-./+=]{8,}['"]?/gi,
+  // AWS
+  /AKIA[0-9A-Z]{16}/g,
+  // GitHub
+  /gh[pso]_[A-Za-z0-9_]{36,}/g,
+  // Slack
+  /xox[bporas]-[A-Za-z0-9-]+/g,
+  // Generic long hex/base64 strings that look like secrets (32+ chars)
+  /(?:sk|pk|key|token|secret)[_-][A-Za-z0-9]{32,}/gi,
+  // HMN API keys
+  /hmn_ak_[A-Za-z0-9_\-]{16,}/g,
+  // Bearer tokens in text
+  /Bearer\s+[A-Za-z0-9_\-./+=]{20,}/gi,
+  // Connection strings
+  /(?:postgres|mysql|mongodb|redis):\/\/[^\s]+/gi
+];
+
+/**
+ * Truncate prompt text to 200 characters.
+ */
+function sanitizePrompt(text) {
+  if (!text || typeof text !== 'string') return '';
+  return text.length > 200 ? text.slice(0, 200) + '...' : text;
+}
+
+/**
+ * Extract only the last folder name from a full path.
+ * /Users/matty/Documents/my-project/src/index.js → my-project
+ */
+function sanitizePath(fullPath) {
+  if (!fullPath || typeof fullPath !== 'string') return '';
+  // Normalize and split
+  const normalized = path.normalize(fullPath);
+  const parts = normalized.split(path.sep).filter(Boolean);
+  // If it looks like a file path, return the parent folder name
+  if (parts.length === 0) return '';
+  // Check if last segment has an extension (it's a file)
+  const last = parts[parts.length - 1];
+  if (last.includes('.') && parts.length > 1) {
+    return parts[parts.length - 2] + '/';
+  }
+  return last + '/';
+}
+
+/**
+ * Strip patterns matching API keys, tokens, passwords from text.
+ */
+function redactSecrets(text) {
+  if (!text || typeof text !== 'string') return '';
+  let cleaned = text;
+  for (const pattern of SECRET_PATTERNS) {
+    // Reset lastIndex for global patterns
+    pattern.lastIndex = 0;
+    cleaned = cleaned.replace(pattern, '[REDACTED]');
+  }
+  return cleaned;
+}
+
+/**
+ * Apply all sanitization to an ActivityEvent before logging.
+ */
+function sanitizeEvent(event) {
+  if (!event) return event;
+
+  const sanitized = { ...event };
+
+  if (sanitized.data) {
+    sanitized.data = { ...sanitized.data };
+
+    // Truncate prompt summaries
+    if (sanitized.data.prompt_summary) {
+      sanitized.data.prompt_summary = redactSecrets(
+        sanitizePrompt(sanitized.data.prompt_summary)
+      );
+    }
+
+    // Strip file paths to folder names
+    if (sanitized.data.project_dir) {
+      sanitized.data.project_dir = sanitizePath(sanitized.data.project_dir);
+    }
+
+    // Sanitize file names — keep names but redact any secret-looking names
+    if (Array.isArray(sanitized.data.file_names)) {
+      sanitized.data.file_names = sanitized.data.file_names.map((f) =>
+        redactSecrets(path.basename(f))
+      );
+    }
+
+    // Redact secrets from description
+    if (sanitized.data.description) {
+      sanitized.data.description = redactSecrets(sanitized.data.description);
+    }
+
+    // Redact secrets from tool names (unlikely but safe)
+    if (Array.isArray(sanitized.data.tools_used)) {
+      sanitized.data.tools_used = sanitized.data.tools_used.map((t) =>
+        redactSecrets(t)
+      );
+    }
+  }
+
+  return sanitized;
+}
+
+module.exports = {
+  sanitizePrompt,
+  sanitizePath,
+  redactSecrets,
+  sanitizeEvent
+};