@theihtisham/agent-shadow-brain 7.0.0 → 7.1.3

package/dist/brain/mcp-server.js

@@ -2,17 +2,28 @@
 // Exposes analysis tools via Model Context Protocol
 // v6.0.0 — Hive Mind Edition (Cursor + Claude Code + Codex + Copilot + sub-agent frameworks)
 import * as http from 'http';
+import { randomUUID } from 'node:crypto';
+import * as path from 'node:path';
+import { performance } from 'node:perf_hooks';
+const MEMORY_TOOLS = new Set(['global_recall', 'global_recall_scored', 'global_stats', 'global_storage_health',
+    'global_timeline', 'workflow_analyze', 'workflow_skills', 'context_pack', 'feature_flags', 'activity_report']);
 export class MCPServer {
-    constructor(orchestrator, options) {
+    constructor(orchestrator, options, dependencies = {}) {
+        this.dependencies = dependencies;
         this.server = null;
         this.sseClients = new Map();
         this.lastHealthScore = null;
+        this.telemetrySession = 'mcp-' + randomUUID();
+        this.telemetryAgent = 'mcp-client';
+        this.telemetryInitialized = false;
+        this.telemetryWarning = false;
         this.orchestrator = orchestrator;
         this.options = {
             port: options?.port ?? 7342,
             host: options?.host ?? 'localhost',
             authToken: options?.authToken ?? process.env.SHADOW_BRAIN_MCP_TOKEN ?? '',
             corsOrigin: options?.corsOrigin ?? `http://${options?.host ?? 'localhost'}:${options?.port ?? 7342}`,
+            toolProfile: options?.toolProfile ?? 'full',
         };
         this.toolHandlers = {
             analyze: this.handleAnalyze.bind(this),
@@ -40,6 +51,11 @@ export class MCPServer {
             global_recall_scored: this.handleGlobalRecallScored.bind(this),
             global_stats: this.handleGlobalStats.bind(this),
             global_storage_health: this.handleGlobalStorageHealth.bind(this),
+            workflow_analyze: this.handleWorkflowAnalyze.bind(this),
+            workflow_skills: this.handleWorkflowSkills.bind(this),
+            context_pack: this.handleContextPack.bind(this),
+            feature_flags: this.handleFeatureFlags.bind(this),
+            activity_report: this.handleActivityReport.bind(this),
             attach_status: this.handleAttachStatus.bind(this),
             global_timeline: this.handleGlobalTimeline.bind(this),
             firewall_check: this.handleFirewallCheck.bind(this),
@@ -312,10 +328,10 @@ export class MCPServer {
         const tokens = getTokenEconomy();
         const formal = getFormalBridge();
         const airgap = getAirGapMode();
-        const brain = getGlobalBrain();
+        const brain = this.dependencies.brain ?? getGlobalBrain();
         await Promise.all([sabb.init(), causal.init(), collisions.init(), dream.init(), rep.init(), tokens.init(), formal.init(), airgap.init(), brain.init()]);
         return {
-            version: '7.0.0',
+            version: '7.1.3',
             modules: {
                 sabb: sabb.getStats(),
                 causal: causal.stats(),
@@ -348,7 +364,7 @@ export class MCPServer {
     }
     async handleGlobalRecall(params) {
         const { getGlobalBrain } = await import('./global-brain.js');
-        const brain = getGlobalBrain();
+        const brain = this.dependencies.brain ?? getGlobalBrain();
         await brain.init();
         return brain.recall({
             projectId: params.projectId,
@@ -361,7 +377,7 @@ export class MCPServer {
     }
     async handleGlobalRecallScored(params) {
         const { getGlobalBrain } = await import('./global-brain.js');
-        const brain = getGlobalBrain();
+        const brain = this.dependencies.brain ?? getGlobalBrain();
         await brain.init();
         return brain.recallScored({
             projectId: params.projectId,
@@ -376,7 +392,7 @@ export class MCPServer {
     async handleGlobalStats(_params) {
         const { getGlobalBrain } = await import('./global-brain.js');
         const { getAllCacheStats } = await import('./l0-cache.js');
-        const brain = getGlobalBrain();
+        const brain = this.dependencies.brain ?? getGlobalBrain();
         await brain.init();
         return {
             brain: brain.getStats(),
@@ -385,7 +401,50 @@ export class MCPServer {
     }
     async handleGlobalStorageHealth(_params) {
         const { getGlobalBrain } = await import('./global-brain.js');
-        return getGlobalBrain().getStorageHealth();
+        return (this.dependencies.brain ?? getGlobalBrain()).getStorageHealth();
+    }
+    async handleWorkflowAnalyze(params) {
+        const { analyzeTask } = await import('./task-workflow.js');
+        return analyzeTask(params.request, {
+            mode: params.mode,
+            taskType: params.taskType,
+            complexity: params.complexity,
+        });
+    }
+    async handleWorkflowSkills(params) {
+        const { getBundledSkill, listBundledSkills } = await import('./workflow-skills.js');
+        if (params.name !== undefined && typeof params.name !== 'string')
+            throw new TypeError('name must be a bundled skill name.');
+        return params.name === undefined ? listBundledSkills() : getBundledSkill(params.name);
+    }
+    async handleContextPack(params) {
+        const { assembleContext } = await import('./context-assembly.js');
+        const { getFeatureSettings } = await import('./feature-settings.js');
+        const { getGlobalBrain } = await import('./global-brain.js');
+        if (typeof params.projectId !== 'string' || !params.projectId.trim())
+            throw new TypeError('A project ID is required.');
+        if (params.query !== undefined && typeof params.query !== 'string')
+            throw new TypeError('Query must be text.');
+        if (params.tokenBudget !== undefined && (!Number.isSafeInteger(params.tokenBudget) || Number(params.tokenBudget) < 0 || Number(params.tokenBudget) > 12000))
+            throw new TypeError('Token budget must be an integer from 0 to 12000.');
+        if (params.includeCrossProject !== undefined && typeof params.includeCrossProject !== 'boolean')
+            throw new TypeError('Cross-project choice must be boolean.');
+        const features = (this.dependencies.settings ?? getFeatureSettings()).get().features;
+        const brain = this.dependencies.brain ?? getGlobalBrain();
+        if (features.contextAssembly) {
+            await brain.init();
+            await brain.sync();
+            if (brain.getStorageHealth().lastError)
+                throw new Error('Memory store is not readable. Check global_storage_health.');
+        }
+        const { memoryAnnotationsFor } = await import('./memory-annotations.js');
+        return assembleContext(brain, { projectId: params.projectId, query: params.query,
+            tokenBudget: params.tokenBudget, includeCrossProject: params.includeCrossProject, features,
+            annotations: features.contextAssembly ? memoryAnnotationsFor(brain).get() : undefined });
+    }
+    async handleFeatureFlags(_params) {
+        const { getFeatureSettings, FEATURE_DEFINITIONS } = await import('./feature-settings.js');
+        return { ...(this.dependencies.settings ?? getFeatureSettings()).get(), definitions: FEATURE_DEFINITIONS };
     }
     async handleAttachStatus(params) {
         const { getHookInstaller } = await import('./session-hooks.js');
@@ -396,7 +455,7 @@ export class MCPServer {
     async handleGlobalTimeline(params) {
         const { getGlobalBrain, GlobalBrain } = await import('./global-brain.js');
         const projectDir = params.projectDir;
-        const brain = getGlobalBrain();
+        const brain = this.dependencies.brain ?? getGlobalBrain();
         await brain.init();
         return brain.timeline({
             projectId: projectDir ? GlobalBrain.projectIdFor(projectDir) : params.projectId,
@@ -500,7 +559,7 @@ export class MCPServer {
                 // Lightweight health endpoint for tool connectivity checks
                 this.sendJSON(res, 200, {
                     status: 'ok',
-                    version: '7.0.0',
+                    version: '7.1.3',
                     uptime: process.uptime(),
                     tools: Object.keys(this.toolHandlers).length,
                 });
@@ -554,14 +613,26 @@ export class MCPServer {
         }
     }
     async handleRequest(request) {
-        if (request.jsonrpc !== '2.0') {
-            return this.makeError(request.id, -32600, 'Invalid Request: jsonrpc must be "2.0"');
+        if (!request || typeof request !== 'object' || Array.isArray(request) || request.jsonrpc !== '2.0' ||
+            typeof request.method !== 'string' || (request.id !== undefined && typeof request.id !== 'string' && typeof request.id !== 'number') ||
+            (request.params !== undefined && (!request.params || typeof request.params !== 'object' || Array.isArray(request.params)))) {
+            return this.makeError(undefined, -32600, 'Invalid JSON-RPC request.');
         }
         const { method, params } = request;
         try {
             switch (method) {
-                case 'initialize':
-                    return this.makeResult(request.id, this.handleInitialize());
+                case 'initialize': {
+                    if (this.options.toolProfile === 'memory') {
+                        const name = String(params?.clientInfo?.name ?? '').toLowerCase();
+                        this.telemetryAgent = name.includes('codex') ? 'codex' : name.includes('claude') ? 'claude-code' :
+                            name.includes('opencode') ? 'opencode' : name.includes('deepseek') ? 'deepseek-harness' : 'mcp-client';
+                        this.telemetryInitialized = true;
+                        await this.recordMeasured({ kind: 'session-start' });
+                    }
+                    return this.makeResult(request.id, this.handleInitialize(params));
+                }
+                case 'ping':
+                    return this.makeResult(request.id, {});
                 case 'notifications/initialized':
                     // Cursor sends this after initialize — acknowledge silently
                     return this.makeResult(request.id, {});
@@ -574,15 +645,44 @@ export class MCPServer {
                 case 'tools/call': {
                     const toolName = params?.name;
                     const toolArgs = params?.arguments ?? {};
-                    if (!toolName) {
+                    if (typeof toolName !== 'string' || !toolName || !toolArgs || typeof toolArgs !== 'object' || Array.isArray(toolArgs)) {
                         return this.makeError(request.id, -32602, 'Missing tool name in params.name');
                     }
                     const handler = this.toolHandlers[toolName];
-                    if (!handler) {
+                    if (!Object.hasOwn(this.toolHandlers, toolName) || !handler || (this.options.toolProfile === 'memory' && !MEMORY_TOOLS.has(toolName))) {
                         return this.makeError(request.id, -32601, `Unknown tool: ${toolName}`);
                     }
-                    const result = await handler(toolArgs);
-                    return this.makeResult(request.id, { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] });
+                    try {
+                        if (this.options.toolProfile === 'memory')
+                            this.validateMemoryArguments(toolName, toolArgs);
+                        const measured = this.options.toolProfile === 'memory' && toolName !== 'activity_report';
+                        const correlationId = randomUUID();
+                        const projectId = typeof toolArgs.projectId === 'string' && /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$/.test(toolArgs.projectId)
+                            ? toolArgs.projectId : undefined;
+                        if (measured)
+                            await this.recordMeasured({ kind: 'tool-start', tool: toolName, correlationId, ...(projectId ? { projectId } : {}) });
+                        const started = performance.now();
+                        let result;
+                        try {
+                            result = await handler(toolArgs);
+                            if (measured)
+                                await this.recordMeasured({ kind: 'tool-end', tool: toolName, correlationId, outcome: 'success',
+                                    durationMs: Math.max(0, Math.round((performance.now() - started) * 1000) / 1000), ...(projectId ? { projectId } : {}) });
+                        }
+                        catch (error) {
+                            if (measured)
+                                await this.recordMeasured({ kind: 'tool-end', tool: toolName, correlationId, outcome: 'error',
+                                    durationMs: Math.max(0, Math.round((performance.now() - started) * 1000) / 1000), ...(projectId ? { projectId } : {}) });
+                            throw error;
+                        }
+                        return this.makeResult(request.id, { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] });
+                    }
+                    catch (error) {
+                        const message = error instanceof Error ? error.message : 'Tool execution failed.';
+                        if (error instanceof TypeError || error instanceof RangeError)
+                            return this.makeError(request.id, -32602, message);
+                        return this.makeResult(request.id, { content: [{ type: 'text', text: message }], isError: true });
+                    }
                 }
                 default:
                     return this.makeError(request.id, -32601, `Method not found: ${method}`);
@@ -593,18 +693,77 @@ export class MCPServer {
         }
     }
     // ── Tool Handlers ──────────────────────────────────────────────────────
-    handleInitialize() {
+    async telemetryProject() {
+        if (this.dependencies.projectId)
+            return this.dependencies.projectId;
+        const { GlobalBrain } = await import('./global-brain.js');
+        return GlobalBrain.projectIdFor(path.resolve(this.dependencies.projectDir ?? process.cwd()));
+    }
+    async recordMeasured(event) {
+        if (this.options.toolProfile !== 'memory')
+            return;
+        try {
+            const { getFeatureSettings } = await import('./feature-settings.js');
+            if (!(this.dependencies.settings ?? getFeatureSettings()).get().features.activityRecording)
+                return;
+            const { getGlobalBrain } = await import('./global-brain.js');
+            const { ActivityJournal, ACTIVITY_JOURNAL_FILENAME } = await import('./activity-journal.js');
+            const brain = this.dependencies.brain ?? getGlobalBrain();
+            const journal = new ActivityJournal({ filePath: path.join(path.dirname(brain.dbPath), ACTIVITY_JOURNAL_FILENAME), lockTimeoutMs: 250 });
+            await journal.append({ projectId: await this.telemetryProject(), sessionId: this.telemetrySession,
+                agent: this.telemetryAgent, ...event, source: 'measured', transport: 'mcp' });
+        }
+        catch {
+            if (!this.telemetryWarning) {
+                this.telemetryWarning = true;
+                console.error('Shadow Brain activity recording is unavailable. Tool execution continues.');
+            }
+        }
+    }
+    async finishMemorySession() {
+        if (this.telemetryInitialized) {
+            this.telemetryInitialized = false;
+            await this.recordMeasured({ kind: 'session-end' });
+        }
+    }
+    async handleActivityReport(params) {
+        const { reportAgentActivity } = await import('./activity-reporting.js');
+        const { getFeatureSettings } = await import('./feature-settings.js');
+        const { getGlobalBrain } = await import('./global-brain.js');
+        return reportAgentActivity(this.dependencies.brain ?? getGlobalBrain(), this.dependencies.settings ?? getFeatureSettings(), {
+            projectId: await this.telemetryProject(), sessionId: this.telemetrySession, agent: this.telemetryAgent, ...params,
+        });
+    }
+    validateMemoryArguments(name, args) {
+        if (!['global_recall', 'global_recall_scored', 'global_timeline'].includes(name))
+            return;
+        if (args.limit !== undefined && (!Number.isSafeInteger(args.limit) || Number(args.limit) < 1 || Number(args.limit) > 200)) {
+            throw new TypeError('limit must be an integer from 1 to 200.');
+        }
+        for (const key of ['projectId', 'projectDir', 'agentTool', 'category']) {
+            if (args[key] !== undefined && (typeof args[key] !== 'string' || args[key].length > 1000))
+                throw new TypeError(key + ' must be bounded text.');
+        }
+        for (const key of ['minImportance', 'minConfidence']) {
+            if (args[key] !== undefined && (typeof args[key] !== 'number' || !Number.isFinite(args[key]) || Number(args[key]) < 0 || Number(args[key]) > 1))
+                throw new TypeError(key + ' must be from 0 to 1.');
+        }
+        if (args.keywords !== undefined && (!Array.isArray(args.keywords) || args.keywords.length > 32 || args.keywords.some(word => typeof word !== 'string' || word.length > 256))) {
+            throw new TypeError('keywords must contain at most 32 text terms of at most 256 characters.');
+        }
+    }
+    handleInitialize(params) {
+        const versions = ['2025-06-18', '2024-11-05'];
         return {
-            protocolVersion: '2024-11-05',
+            protocolVersion: versions.includes(String(params?.protocolVersion)) ? params.protocolVersion : versions[0],
             capabilities: {
                 tools: { listChanged: false },
                 resources: { subscribe: false, listChanged: false },
                 prompts: { listChanged: false },
-                logging: {},
             },
             serverInfo: {
                 name: 'agent-shadow-brain',
-                version: '7.0.0',
+                version: '7.1.3',
                 description: 'Cross-agent memory and safety layer for AI coding agents',
             },
         };
@@ -893,7 +1052,7 @@ export class MCPServer {
     async handleStatus(params) {
         const status = this.orchestrator.getStatus?.() || {};
         return {
-            version: '7.0.0',
+            version: '7.1.3',
             ...status,
         };
     }
@@ -919,7 +1078,7 @@ export class MCPServer {
             const instance = this.orchestrator[mod.key];
             modules.push({
                 name: mod.name,
-                version: '7.0.0',
+                version: '7.1.3',
                 status: instance ? 'active' : 'idle',
             });
         }
@@ -946,7 +1105,14 @@ export class MCPServer {
     }
     // ── Tool Definitions ───────────────────────────────────────────────────
     getToolDefinitions() {
-        return [
+        const definitions = [
+            { name: 'activity_report', description: 'Explicitly report an agent phase or tool span to the live portal. Writes only bounded activity labels/timing; reports remain labelled host-reported. Do not send request text, arguments, file paths, or secrets.',
+                inputSchema: { type: 'object', additionalProperties: false, required: ['kind'], properties: {
+                        kind: { type: 'string', enum: ['session-start', 'phase', 'tool-start', 'tool-end', 'session-end'] },
+                        projectId: { type: 'string' }, sessionId: { type: 'string' }, agent: { type: 'string' },
+                        phase: { type: 'string', enum: ['understand', 'plan', 'work', 'verify'] }, tool: { type: 'string' }, correlationId: { type: 'string' },
+                        outcome: { type: 'string', enum: ['success', 'error', 'cancelled'] }, durationMs: { type: 'number', minimum: 0 },
+                    } }, annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false } },
             {
                 name: 'analyze',
                 description: 'Run full analysis on project files and return insights',
@@ -1166,6 +1332,37 @@ export class MCPServer {
                 description: 'Inspect this process memory-store status, pending operations, last successful save, and last storage error. Does not initialize or flush the store. (v7.0.0)',
                 inputSchema: { type: 'object', properties: {}, additionalProperties: false },
             },
+            {
+                name: 'workflow_analyze',
+                description: 'Suggest a focused workflow and relevant bundled skills for a user request. Pure local heuristic: no execution, file changes, provider calls, or permission grants. (v7.1.0)',
+                inputSchema: {
+                    type: 'object', required: ['request'], additionalProperties: false,
+                    properties: {
+                        request: { type: 'string', description: 'The requested task, including scope and planning-only constraints.' },
+                        mode: { type: 'string', enum: ['auto', 'plan-only', 'execute'] },
+                        taskType: { type: 'string', enum: ['auto', 'implement', 'debug', 'review', 'research', 'release'] },
+                        complexity: { type: 'string', enum: ['auto', 'simple', 'complex'] },
+                    },
+                },
+            },
+            {
+                name: 'workflow_skills',
+                description: 'List bundled workflow skills, or read one by name. Does not install skills or change client settings. (v7.1.0)',
+                inputSchema: { type: 'object', properties: { name: { type: 'string' } }, additionalProperties: false },
+            },
+            {
+                name: 'context_pack',
+                description: 'Build a bounded reference context pack for a specified project and task, with provenance, selection reasons, and exclusions. Cross-project content requires both the persisted feature and an explicit request. No provider calls or source-file reads. Token counts are estimates. (v7.1.3)',
+                inputSchema: { type: 'object', required: ['projectId'], additionalProperties: false, properties: {
+                        projectId: { type: 'string' }, query: { type: 'string' },
+                        tokenBudget: { type: 'integer', minimum: 0, maximum: 12000 }, includeCrossProject: { type: 'boolean' },
+                    } },
+            },
+            {
+                name: 'feature_flags',
+                description: 'Read the five persisted context, briefing, and activity controls. Does not modify settings or expose provider configuration. (v7.1.3)',
+                inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+            },
             {
                 name: 'attach_status',
                 description: 'Detect which AI agents are installed on this machine (v5.2.0)',
@@ -1256,6 +1453,9 @@ export class MCPServer {
                 },
             },
         ];
+        return this.options.toolProfile === 'memory'
+            ? definitions.filter(tool => MEMORY_TOOLS.has(tool.name)).map(tool => ({ ...tool, annotations: { readOnlyHint: tool.name !== 'activity_report', destructiveHint: false, openWorldHint: false } }))
+            : definitions;
     }
     // ── HTTP Handling ──────────────────────────────────────────────────────
     async handleHTTPMCPRequest(req, res) {