@10kdevs/matha 0.1.0

package/dist/mcp/server.js

@@ -0,0 +1,305 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { mathaGetRules, mathaGetDangerZones, mathaGetDecisions, mathaGetStability, mathaBrief, mathaRecordDecision, mathaRecordDanger, mathaRecordContract, } from './tools.js';
+import { checkSchemaVersion, getSchemaMessage } from '../utils/schema-version.js';
+/**
+ * MATHA MCP Server
+ *
+ * Exposes the MATHA brain via MCP protocol for IDE integration.
+ * Loads config from .matha/config.json or uses project root if not initialized.
+ *
+ * Tools:
+ * - READ: matha_get_rules, matha_get_danger_zones, matha_get_decisions, matha_get_stability, matha_brief
+ * - WRITE: matha_record_decision, matha_record_danger, matha_record_contract
+ */
+const server = new Server({
+    name: 'MATHA',
+    version: '1.0.0',
+});
+let mathaDir;
+// ──────────────────────────────────────────────────────────────────────
+// TOOL DEFINITIONS
+// ──────────────────────────────────────────────────────────────────────
+const tools = [
+    {
+        name: 'matha_get_rules',
+        description: 'Returns all non-negotiable business rules for the project. Used to understand project constraints.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+        },
+    },
+    {
+        name: 'matha_get_danger_zones',
+        description: 'Returns identified danger zones (patterns to avoid). Optionally filter by context.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                context: {
+                    type: 'string',
+                    description: 'Optional context to filter danger zones (e.g., component name)',
+                },
+            },
+            required: [],
+        },
+    },
+    {
+        name: 'matha_get_decisions',
+        description: 'Returns past decisions made on this project. Optionally filter by component.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                component: {
+                    type: 'string',
+                    description: 'Optional component name to filter decisions',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Optional limit on number of results',
+                },
+            },
+            required: [],
+        },
+    },
+    {
+        name: 'matha_get_stability',
+        description: 'Returns stability classification for specified files. Stability indicates how mature/frozen a file is.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                files: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Array of file paths to check stability for',
+                },
+            },
+            required: ['files'],
+        },
+    },
+    {
+        name: 'matha_brief',
+        description: 'Returns the most recent session brief, or intent + rules if no session exists. Used to understand current project state.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                scope: {
+                    type: 'string',
+                    description: 'Optional scope to filter session brief',
+                },
+            },
+            required: [],
+        },
+    },
+    {
+        name: 'matha_record_decision',
+        description: 'Records a decision (learning) about what was assumed vs. what was discovered. Confidence defaults to "probable" (not "confirmed" which requires human verification).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                component: {
+                    type: 'string',
+                    description: 'Component or file this decision relates to',
+                },
+                previous_assumption: {
+                    type: 'string',
+                    description: 'What was previously thought to be true',
+                },
+                correction: {
+                    type: 'string',
+                    description: 'What was discovered to actually be true',
+                },
+                confidence: {
+                    type: 'string',
+                    enum: ['confirmed', 'probable', 'uncertain'],
+                    description: 'Confidence level. Default: probable (agent-level). Use "confirmed" only for human-verified facts.',
+                },
+            },
+            required: ['component', 'previous_assumption', 'correction'],
+        },
+    },
+    {
+        name: 'matha_record_danger',
+        description: 'Records a danger zone (pattern to avoid) discovered during development.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                component: {
+                    type: 'string',
+                    description: 'Component or file where danger zone was found',
+                },
+                description: {
+                    type: 'string',
+                    description: 'Description of the danger pattern',
+                },
+            },
+            required: ['component', 'description'],
+        },
+    },
+    {
+        name: 'matha_record_contract',
+        description: 'Records a behaviour contract (set of invariant assertions) for a component. Overwrites existing contract for the same component.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                component: {
+                    type: 'string',
+                    description: 'Component or file this contract applies to',
+                },
+                assertions: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'List of invariant assertions (must remain true)',
+                },
+            },
+            required: ['component', 'assertions'],
+        },
+    },
+];
+// ──────────────────────────────────────────────────────────────────────
+// REQUEST HANDLERS
+// ──────────────────────────────────────────────────────────────────────
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools,
+}));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const name = request.params?.name;
+    const args = request.params?.arguments;
+    try {
+        let result;
+        switch (name) {
+            case 'matha_get_rules':
+                result = await mathaGetRules(mathaDir);
+                break;
+            case 'matha_get_danger_zones':
+                result = await mathaGetDangerZones(mathaDir, args?.context);
+                break;
+            case 'matha_get_decisions':
+                result = await mathaGetDecisions(mathaDir, args?.component, args?.limit);
+                break;
+            case 'matha_get_stability':
+                result = await mathaGetStability(mathaDir, args?.files || []);
+                break;
+            case 'matha_brief':
+                result = await mathaBrief(mathaDir, args?.scope);
+                break;
+            case 'matha_record_decision':
+                result = await mathaRecordDecision(mathaDir, args?.component, args?.previous_assumption, args?.correction, args?.confidence || 'probable');
+                break;
+            case 'matha_record_danger':
+                result = await mathaRecordDanger(mathaDir, args?.component, args?.description);
+                break;
+            case 'matha_record_contract':
+                result = await mathaRecordContract(mathaDir, args?.component, args?.assertions);
+                break;
+            default:
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({ error: `Unknown tool: ${name}` }),
+                        },
+                    ],
+                };
+        }
+        // All tool results are JSON strings
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: result,
+                },
+            ],
+        };
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({ error: `Tool execution failed: ${err.message}` }),
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+// ──────────────────────────────────────────────────────────────────────
+// INITIALIZATION & STARTUP
+// ──────────────────────────────────────────────────────────────────────
+/**
+ * Initialize the server by locating and validating the MATHA directory.
+ *
+ * Strategy:
+ * 1. Look for .matha/ directory in current working directory or parent directories
+ * 2. If found, use that
+ * 3. If not found, use CWD/.matha (will use defaults gracefully)
+ * 4. Write mcp-config.json with absolute paths for this session
+ */
+async function initialize() {
+    const cwd = process.cwd();
+    // Try to find existing .matha directory
+    let found = false;
+    let searchDir = cwd;
+    for (let i = 0; i < 10; i++) {
+        const candidate = path.join(searchDir, '.matha');
+        try {
+            await fs.access(candidate);
+            mathaDir = candidate;
+            found = true;
+            break;
+        }
+        catch {
+            // Not found, try parent
+        }
+        const parent = path.dirname(searchDir);
+        if (parent === searchDir)
+            break; // Reached root
+        searchDir = parent;
+    }
+    // If not found, use default location
+    if (!found) {
+        mathaDir = path.join(cwd, '.matha');
+    }
+    // Write mcp-config.json with absolute paths
+    try {
+        const configPath = path.join(mathaDir, 'mcp-config.json');
+        const config = {
+            matha_dir: mathaDir,
+            cwd: cwd,
+            initialized: found,
+            timestamp: new Date().toISOString(),
+        };
+        await fs.mkdir(mathaDir, { recursive: true });
+        await fs.writeFile(configPath, JSON.stringify(config, null, 2));
+    }
+    catch {
+        // Ignore write errors - server can still run in degraded mode
+    }
+    // SCHEMA VERSION CHECK
+    const schemaResult = await checkSchemaVersion(mathaDir);
+    const schemaMsg = getSchemaMessage(schemaResult);
+    if (schemaMsg)
+        console.error(schemaMsg);
+    if (schemaResult.status === 'newer') {
+        process.exit(1);
+    }
+}
+/**
+ * Start the MCP server on stdio
+ */
+async function main() {
+    await initialize();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Log startup info to stderr so it doesn't interfere with stdio protocol
+    const msg = `MATHA MCP server running on stdio, mathaDir: ${mathaDir}`;
+    console.error(msg);
+}
+main().catch((err) => {
+    console.error('Server initialization failed:', err);
+    process.exit(1);
+});

package/dist/mcp/tools.js

@@ -0,0 +1,379 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { readJsonOrNull } from '../storage/reader.js';
+import { writeAtomic } from '../storage/writer.js';
+import { getRules, getDangerZones, getDecisions, recordDecision, recordDangerZone, } from '../brain/hippocampus.js';
+import { refreshFromGit, getStability, getSnapshot, } from '../brain/cortex.js';
+import { matchAll } from '../analysis/contract-matcher.js';
+import { analyseDeltas, persistAnalysis, getRecommendation } from '../brain/dopamine.js';
+// Simple UUID-like ID generator
+function generateId() {
+    return Math.random().toString(36).substring(2, 15) +
+        Math.random().toString(36).substring(2, 15);
+}
+// ──────────────────────────────────────────────────────────────────────
+// READ TOOLS
+// ──────────────────────────────────────────────────────────────────────
+/**
+ * matha_get_rules: Returns all business rules.
+ */
+export async function mathaGetRules(mathaDir) {
+    try {
+        const rules = await getRules(mathaDir);
+        return JSON.stringify({ rules });
+    }
+    catch (err) {
+        return JSON.stringify({ error: `Failed to get rules: ${err.message}` });
+    }
+}
+/**
+ * matha_get_danger_zones: Returns danger zones, optionally filtered by context.
+ */
+export async function mathaGetDangerZones(mathaDir, context) {
+    try {
+        const zones = await getDangerZones(mathaDir, context);
+        return JSON.stringify({ zones });
+    }
+    catch (err) {
+        return JSON.stringify({ error: `Failed to get danger zones: ${err.message}` });
+    }
+}
+/**
+ * matha_get_decisions: Returns decisions, optionally filtered by component and limit.
+ */
+export async function mathaGetDecisions(mathaDir, component, limit) {
+    try {
+        const decisions = await getDecisions(mathaDir, component, limit);
+        return JSON.stringify({ decisions });
+    }
+    catch (err) {
+        return JSON.stringify({ error: `Failed to get decisions: ${err.message}` });
+    }
+}
+/**
+ * matha_get_stability: Returns stability classification for requested files.
+ * Uses cortex.getStability — returns StabilityRecord | null per file.
+ * repoPath assumption: process.cwd() is the project root.
+ */
+export async function mathaGetStability(mathaDir, files) {
+    try {
+        const stability = await getStability(mathaDir, files);
+        return JSON.stringify({ stability });
+    }
+    catch (err) {
+        // On any error, return null for all
+        const stability = {};
+        for (const file of files) {
+            stability[file] = null;
+        }
+        return JSON.stringify({ stability });
+    }
+}
+/**
+ * matha_brief: Returns the most recent session brief, or intent + rules.
+ * If directory provided, filters decisions/danger zones/stability to that directory.
+ */
+export async function mathaBrief(mathaDir, scope, directory) {
+    try {
+        // DIRECTORY FILTER MODE
+        if (directory) {
+            const dirLower = directory.toLowerCase();
+            // Filter decisions by component matching directory
+            let decisions = [];
+            try {
+                const allDecisions = await getDecisions(mathaDir);
+                decisions = allDecisions.filter((d) => (d.component || '').toLowerCase().includes(dirLower));
+            }
+            catch {
+                decisions = [];
+            }
+            // Filter danger zones by component matching directory
+            let zones = [];
+            try {
+                zones = await getDangerZones(mathaDir, directory);
+            }
+            catch {
+                zones = [];
+            }
+            // Filter stability records where filepath starts with directory
+            let stabilityRecords = [];
+            try {
+                const snapshot = await getSnapshot(mathaDir);
+                if (snapshot && snapshot.stability) {
+                    stabilityRecords = snapshot.stability.filter((s) => s.filepath.toLowerCase().startsWith(dirLower));
+                }
+            }
+            catch {
+                stabilityRecords = [];
+            }
+            const hasData = decisions.length > 0 || zones.length > 0 || stabilityRecords.length > 0;
+            const matchContext = {
+                scope: directory,
+                intent: '',
+                operationType: 'unknown',
+                filepaths: [directory],
+            };
+            let matchResults = [];
+            try {
+                matchResults = await matchAll(matchContext, mathaDir);
+            }
+            catch {
+                matchResults = [];
+            }
+            const hasCritical = matchResults.some((r) => r.severity === 'critical');
+            return JSON.stringify({
+                directory,
+                filtered: true,
+                hasData,
+                message: hasData ? null : `No MATHA data found for directory: ${directory}`,
+                decisions,
+                dangerZones: zones,
+                stability: stabilityRecords,
+                matchResults,
+                hasCritical,
+            });
+        }
+        // STANDARD MODE — most recent session brief
+        const sessionsDir = path.join(mathaDir, 'sessions');
+        // Try to find the most recent .brief file
+        let briefData = null;
+        try {
+            const files = await fs.readdir(sessionsDir);
+            const briefFiles = files
+                .filter((f) => f.endsWith('.brief'))
+                .sort()
+                .reverse();
+            if (briefFiles.length > 0) {
+                const briefPath = path.join(sessionsDir, briefFiles[0]);
+                briefData = await readJsonOrNull(briefPath);
+            }
+        }
+        catch {
+            // Sessions directory might not exist
+            briefData = null;
+        }
+        // If we have a brief and scope provided, check if it matches
+        if (briefData && scope) {
+            const briefScope = briefData.scope || '';
+            if (!briefScope.toLowerCase().includes(scope.toLowerCase())) {
+                briefData = null;
+            }
+        }
+        // Determine base response
+        let baseResponse;
+        if (briefData) {
+            baseResponse = briefData;
+        }
+        else {
+            // Otherwise return intent + rules
+            const intentPath = path.join(mathaDir, 'hippocampus/intent.json');
+            const intent = await readJsonOrNull(intentPath);
+            const rules = await getRules(mathaDir).catch(() => []);
+            const parsedRules = typeof rules === 'string' ? JSON.parse(rules).rules : [];
+            baseResponse = {
+                why: intent?.why ?? '',
+                rules: parsedRules,
+            };
+        }
+        // Augment with matchAll
+        const matchContext = {
+            scope: baseResponse.scope || '',
+            intent: baseResponse.operation_description || baseResponse.why || '',
+            operationType: baseResponse.operationType || 'unknown',
+            filepaths: (baseResponse.scope || '').split(',').map((s) => s.trim()).filter(Boolean),
+        };
+        let matchResults = [];
+        try {
+            matchResults = await matchAll(matchContext, mathaDir);
+        }
+        catch {
+            matchResults = [];
+        }
+        const hasCritical = matchResults.some((r) => r.severity === 'critical');
+        return JSON.stringify({
+            ...baseResponse,
+            matchResults,
+            hasCritical,
+        });
+    }
+    catch (err) {
+        return JSON.stringify({ error: `Failed to get brief: ${err.message}` });
+    }
+}
+// ──────────────────────────────────────────────────────────────────────
+// WRITE TOOLS
+// ──────────────────────────────────────────────────────────────────────
+/**
+ * matha_record_decision: Records a decision from an AI agent.
+ * Uses 'probable' confidence (not 'confirmed' — that is human-verified).
+ */
+export async function mathaRecordDecision(mathaDir, component, previousAssumption, correction, confidence = 'probable') {
+    try {
+        const id = `${Date.now()}-${generateId()}`;
+        const timestamp = new Date().toISOString();
+        const decision = {
+            id,
+            timestamp,
+            component,
+            previous_assumption: previousAssumption,
+            correction,
+            trigger: 'mcp-call',
+            confidence,
+            status: 'active',
+            supersedes: null,
+            session_id: id,
+        };
+        await recordDecision(mathaDir, decision);
+        return JSON.stringify({ success: true, id });
+    }
+    catch (err) {
+        return JSON.stringify({
+            success: false,
+            error: `Failed to record decision: ${err.message}`,
+        });
+    }
+}
+/**
+ * matha_record_danger: Records a danger zone discovered by an agent.
+ */
+export async function mathaRecordDanger(mathaDir, component, description) {
+    try {
+        const id = `danger-${Date.now()}-${generateId()}`;
+        const zone = {
+            id,
+            component,
+            pattern: description,
+            description: description,
+        };
+        await recordDangerZone(mathaDir, zone);
+        return JSON.stringify({ success: true, id });
+    }
+    catch (err) {
+        return JSON.stringify({
+            success: false,
+            error: `Failed to record danger zone: ${err.message}`,
+        });
+    }
+}
+/**
+ * matha_record_contract: Records a behaviour contract for a component.
+ * Overwrites existing contract for same component (versioned).
+ */
+export async function mathaRecordContract(mathaDir, component, assertions) {
+    try {
+        // Sanitize component name for filename
+        const filename = component
+            .replace(/[^a-zA-Z0-9._-]/g, '-')
+            .toLowerCase();
+        const contractPath = path.join(mathaDir, `cerebellum/contracts/${filename}.json`);
+        const contract = {
+            component,
+            version: 1,
+            last_updated: new Date().toISOString(),
+            assertions: assertions.map((description, idx) => ({
+                id: `${component}-assertion-${idx}`,
+                description,
+                type: 'invariant',
+                status: 'active',
+                violation_count: 0,
+                last_violated: null,
+            })),
+        };
+        await writeAtomic(contractPath, contract, { overwrite: true });
+        return JSON.stringify({ success: true, component });
+    }
+    catch (err) {
+        return JSON.stringify({
+            success: false,
+            error: `Failed to record contract: ${err.message}`,
+        });
+    }
+}
+/**
+ * matha_match: Runs the contract matcher independently to get danger/history warnings.
+ */
+export async function mathaMatch(mathaDir, scope, intent, operationType = 'unknown', filepaths = []) {
+    try {
+        const context = {
+            scope,
+            intent,
+            operationType,
+            filepaths: filepaths.length > 0 ? filepaths : scope.split(',').map((s) => s.trim()).filter(Boolean),
+        };
+        const results = await matchAll(context, mathaDir);
+        const hasCritical = results.some((r) => r.severity === 'critical');
+        const summary = {
+            critical: results.filter((r) => r.severity === 'critical').length,
+            warning: results.filter((r) => r.severity === 'warning').length,
+            info: results.filter((r) => r.severity === 'info').length,
+            total: results.length,
+        };
+        return JSON.stringify({
+            results,
+            hasCritical,
+            summary,
+        });
+    }
+    catch (err) {
+        return JSON.stringify({ error: `Failed to run contract matcher: ${err.message}`, results: [], hasCritical: false });
+    }
+}
+/**
+ * matha_get_routing: Close the Dopamine Loop.
+ * If operationType provided: returns specific recommendation.
+ * If not provided: runs full delta analysis and returns DopamineAnalysis report.
+ */
+export async function mathaGetRouting(mathaDir, operationType) {
+    try {
+        if (operationType) {
+            const rec = await getRecommendation(mathaDir, operationType);
+            return JSON.stringify({
+                operation_type: operationType,
+                recommended_tier: rec.tier,
+                recommended_budget: rec.budget,
+                source: rec.source,
+                confidence: rec.confidence,
+                sample_size: rec.sample_size
+            });
+        }
+        else {
+            // Full analysis trigger
+            const analysis = await analyseDeltas(mathaDir);
+            await persistAnalysis(mathaDir, analysis);
+            return JSON.stringify(analysis);
+        }
+    }
+    catch (err) {
+        return JSON.stringify({ error: err.message });
+    }
+}
+// ──────────────────────────────────────────────────────────────────────
+// CORTEX TOOLS
+// ──────────────────────────────────────────────────────────────────────
+/**
+ * matha_refresh_cortex: Triggers a git analysis refresh of the cortex.
+ * repoPath assumption: process.cwd() is the project root.
+ * Never throws to MCP caller.
+ */
+export async function mathaRefreshCortex(mathaDir) {
+    try {
+        // Use mathaDir to derive repoPath (go up from .matha)
+        const repoPath = path.dirname(mathaDir);
+        const snapshot = await refreshFromGit(repoPath, mathaDir);
+        return JSON.stringify({
+            success: true,
+            commitCount: snapshot.commitCount,
+            fileCount: snapshot.fileCount,
+            summary: snapshot.summary,
+        });
+    }
+    catch (err) {
+        return JSON.stringify({
+            success: false,
+            error: `Failed to refresh cortex: ${err.message}`,
+            commitCount: 0,
+            fileCount: 0,
+            summary: null,
+        });
+    }
+}