mcp-learning-memory 0.2.0

package/dist/index.js

@@ -0,0 +1,424 @@
+#!/usr/bin/env node
+/**
+ * ACE Flash Memory MCP Server
+ * Model Context Protocol server for managing insights with feedback
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { log } from './logger.js';
+import { addInsight, listIndex, getDetail, markHelpful, markHarmful, searchInsights, deleteInsight, exportMemory, } from './tools.js';
+const server = new Server({
+    name: 'mcp-learning-memory',
+    version: '0.2.0',
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+// List available tools
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+        tools: [
+            {
+                name: 'add_insight',
+                description: 'Add a new insight to memory',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        title: {
+                            type: 'string',
+                            description: 'Title of the insight (max 200 chars)',
+                        },
+                        tags: {
+                            type: 'array',
+                            items: { type: 'string' },
+                            description: 'Tags for categorization (max 10 tags, 50 chars each)',
+                        },
+                        content: {
+                            type: 'string',
+                            description: 'Content of the insight (max 10000 chars)',
+                        },
+                        overwrite: {
+                            type: 'boolean',
+                            description: 'If true, overwrite existing insight with same title (default: false)',
+                        },
+                        sourceUrl: {
+                            type: 'string',
+                            description: 'Optional source URL for the insight (max 2000 chars)',
+                        },
+                    },
+                    required: ['title', 'tags', 'content'],
+                },
+            },
+            {
+                name: 'list_index',
+                description: 'List all insights (index view without full content) with optional filtering and sorting',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        tags: {
+                            type: 'array',
+                            items: { type: 'string' },
+                            description: 'Filter by tags (AND logic - insight must have all specified tags)',
+                        },
+                        minHelpful: {
+                            type: 'number',
+                            description: 'Minimum helpful count (default: 0)',
+                        },
+                        sortBy: {
+                            type: 'string',
+                            enum: ['created', 'lastUsed', 'helpful'],
+                            description: 'Sort field (default: lastUsed)',
+                        },
+                        limit: {
+                            type: 'number',
+                            description: 'Maximum number of results (default: 50)',
+                        },
+                    },
+                },
+            },
+            {
+                name: 'get_detail',
+                description: 'Get full details of a specific insight',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        id: {
+                            type: 'string',
+                            description: 'ID of the insight to retrieve',
+                        },
+                    },
+                    required: ['id'],
+                },
+            },
+            {
+                name: 'mark_helpful',
+                description: 'Mark an insight as helpful',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        id: {
+                            type: 'string',
+                            description: 'ID of the insight to mark as helpful',
+                        },
+                    },
+                    required: ['id'],
+                },
+            },
+            {
+                name: 'mark_harmful',
+                description: 'Mark an insight as harmful',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        id: {
+                            type: 'string',
+                            description: 'ID of the insight to mark as harmful',
+                        },
+                    },
+                    required: ['id'],
+                },
+            },
+            {
+                name: 'search_insights',
+                description: 'Search insights by query string with contextual ranking',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        query: {
+                            type: 'string',
+                            description: 'Search query string (searches in title, content, and tags)',
+                        },
+                        limit: {
+                            type: 'number',
+                            description: 'Maximum number of results (default: 5)',
+                        },
+                    },
+                    required: ['query'],
+                },
+            },
+            {
+                name: 'delete_insight',
+                description: 'Delete an insight by ID',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        id: {
+                            type: 'string',
+                            description: 'ID of the insight to delete',
+                        },
+                    },
+                    required: ['id'],
+                },
+            },
+            {
+                name: 'export_memory',
+                description: 'Export all insights in JSON or Markdown format',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        format: {
+                            type: 'string',
+                            enum: ['json', 'markdown'],
+                            description: 'Export format: json (default) or markdown',
+                        },
+                    },
+                },
+            },
+        ],
+    };
+});
+// Handle tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        switch (name) {
+            case 'add_insight': {
+                const { title, tags, content, overwrite, sourceUrl } = args;
+                const addResult = await addInsight(title, tags, content, overwrite ?? false, sourceUrl);
+                // Return human-readable format
+                if (addResult.success) {
+                    const data = addResult.data;
+                    return {
+                        content: [{
+                                type: 'text',
+                                text: `${addResult.message}\n\nID: ${data.id}\nOverwritten: ${data.overwritten ? 'Yes' : 'No'}`,
+                            }],
+                    };
+                }
+                else {
+                    // Handle error case (including duplicate detection)
+                    let errorText = addResult.message;
+                    if (addResult.data) {
+                        const dupData = addResult.data;
+                        if (dupData.duplicate) {
+                            errorText += `\n\nExisting insight:\nID: ${dupData.existingId}\nTitle: "${dupData.existingTitle}"`;
+                        }
+                    }
+                    return {
+                        content: [{ type: 'text', text: errorText }],
+                        isError: true,
+                    };
+                }
+            }
+            case 'list_index': {
+                const { tags, minHelpful, sortBy, limit } = args;
+                const listResult = await listIndex({ tags, minHelpful, sortBy, limit });
+                // Return human-readable text format instead of JSON
+                if (listResult.success && Array.isArray(listResult.data)) {
+                    const entries = listResult.data;
+                    if (entries.length === 0) {
+                        return {
+                            content: [{ type: 'text', text: 'No insights found.' }],
+                        };
+                    }
+                    const lines = [`${listResult.message}\n`];
+                    for (const entry of entries) {
+                        lines.push(`[${entry.id}] ${entry.title}`);
+                        let statsLine = `Tags: ${entry.tags.join(', ') || 'none'} | Stats: Helpful ${entry.helpful} / Harmful ${entry.harmful} (Trust: ${entry.trustScore})`;
+                        if (entry.warning) {
+                            statsLine += ` ⚠️ ${entry.warning}`;
+                        }
+                        lines.push(statsLine);
+                        if (entry.sourceUrl) {
+                            lines.push(`Source: ${entry.sourceUrl}`);
+                        }
+                        if (entry.contentPreview) {
+                            const preview = entry.contentTruncated
+                                ? entry.contentPreview + '...'
+                                : entry.contentPreview;
+                            lines.push(`> ${preview}`);
+                        }
+                        lines.push('');
+                    }
+                    return {
+                        content: [{ type: 'text', text: lines.join('\n').trim() }],
+                    };
+                }
+                else {
+                    // Handle error case
+                    return {
+                        content: [{ type: 'text', text: listResult.message }],
+                        isError: true,
+                    };
+                }
+            }
+            case 'get_detail': {
+                const { id } = args;
+                const detailResult = await getDetail(id);
+                // Return human-readable format
+                if (detailResult.success) {
+                    const insight = detailResult.data;
+                    // Calculate trust score for display
+                    const trustScore = Number(((insight.helpful - insight.harmful * 2) / (insight.helpful + insight.harmful + 1)).toFixed(2));
+                    const lines = [
+                        insight.title,
+                        ``,
+                        `ID: ${insight.id}`,
+                        `Tags: ${insight.tags.join(', ')}`,
+                        `Stats: Helpful ${insight.helpful} / Harmful ${insight.harmful} (Trust: ${trustScore})`,
+                        `Created: ${insight.created}`,
+                        `Last Used: ${insight.lastUsed}`,
+                    ];
+                    if (insight.sourceUrl) {
+                        lines.push(`Source: ${insight.sourceUrl}`);
+                    }
+                    if (trustScore < 0) {
+                        lines.push(`⚠️ Warning: Low trust score`);
+                    }
+                    lines.push(``, `Content:`, insight.content);
+                    return {
+                        content: [{ type: 'text', text: lines.join('\n') }],
+                    };
+                }
+                else {
+                    return {
+                        content: [{ type: 'text', text: detailResult.message }],
+                        isError: true,
+                    };
+                }
+            }
+            case 'mark_helpful': {
+                const { id } = args;
+                const helpfulResult = await markHelpful(id);
+                // Return human-readable format
+                if (helpfulResult.success) {
+                    return {
+                        content: [{ type: 'text', text: helpfulResult.message }],
+                    };
+                }
+                else {
+                    return {
+                        content: [{ type: 'text', text: helpfulResult.message }],
+                        isError: true,
+                    };
+                }
+            }
+            case 'mark_harmful': {
+                const { id } = args;
+                const harmfulResult = await markHarmful(id);
+                // Return human-readable format
+                if (harmfulResult.success) {
+                    return {
+                        content: [{ type: 'text', text: harmfulResult.message }],
+                    };
+                }
+                else {
+                    return {
+                        content: [{ type: 'text', text: harmfulResult.message }],
+                        isError: true,
+                    };
+                }
+            }
+            case 'search_insights': {
+                const { query, limit } = args;
+                const searchResult = await searchInsights(query, limit);
+                // Return human-readable text format instead of JSON
+                if (searchResult.success && Array.isArray(searchResult.data)) {
+                    const entries = searchResult.data;
+                    if (entries.length === 0) {
+                        return {
+                            content: [{ type: 'text', text: searchResult.message }],
+                        };
+                    }
+                    const lines = [`${searchResult.message}\n`];
+                    for (const entry of entries) {
+                        lines.push(`[${entry.id}] ${entry.title}`);
+                        let statsLine = `Tags: ${entry.tags.join(', ') || 'none'} | Stats: Helpful ${entry.helpful} / Harmful ${entry.harmful} (Trust: ${entry.trustScore})`;
+                        if (entry.warning) {
+                            statsLine += ` ⚠️ ${entry.warning}`;
+                        }
+                        lines.push(statsLine);
+                        if (entry.sourceUrl) {
+                            lines.push(`Source: ${entry.sourceUrl}`);
+                        }
+                        if (entry.contentPreview) {
+                            const preview = entry.contentTruncated
+                                ? entry.contentPreview + '...'
+                                : entry.contentPreview;
+                            lines.push(`> ${preview}`);
+                        }
+                        lines.push('');
+                    }
+                    return {
+                        content: [{ type: 'text', text: lines.join('\n').trim() }],
+                    };
+                }
+                else {
+                    // Handle error case
+                    return {
+                        content: [{ type: 'text', text: searchResult.message }],
+                        isError: true,
+                    };
+                }
+            }
+            case 'delete_insight': {
+                const { id } = args;
+                const deleteResult = await deleteInsight(id);
+                if (deleteResult.success) {
+                    return {
+                        content: [{ type: 'text', text: deleteResult.message }],
+                    };
+                }
+                else {
+                    return {
+                        content: [{ type: 'text', text: deleteResult.message }],
+                        isError: true,
+                    };
+                }
+            }
+            case 'export_memory': {
+                const { format } = args;
+                const exportResult = await exportMemory(format ?? 'json');
+                if (exportResult.success) {
+                    const resultData = exportResult.data;
+                    return {
+                        content: [{
+                                type: 'text',
+                                text: `${exportResult.message}\n\n${resultData.data}`,
+                            }],
+                    };
+                }
+                else {
+                    return {
+                        content: [{ type: 'text', text: exportResult.message }],
+                        isError: true,
+                    };
+                }
+            }
+            default:
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Unknown tool: ${name}`,
+                        },
+                    ],
+                    isError: true,
+                };
+        }
+    }
+    catch (error) {
+        log.error('Tool execution error:', error);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Error executing tool: ${error.message}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+// Start the server
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    log.info('MCP Learning Memory server running');
+}
+main().catch((error) => {
+    log.error('Server error:', error);
+    process.exit(1);
+});

package/dist/logger.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Logger that ONLY uses console.error
+ * Never use console.error - it breaks MCP protocol
+ */
+export declare const log: {
+    info: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+};

package/dist/logger.js

@@ -0,0 +1,8 @@
+/**
+ * Logger that ONLY uses console.error
+ * Never use console.error - it breaks MCP protocol
+ */
+export const log = {
+    info: (...args) => console.error('[INFO]', ...args),
+    error: (...args) => console.error('[ERROR]', ...args),
+};

package/dist/storage.d.ts

@@ -0,0 +1,7 @@
+/**
+ * File storage with atomic writes
+ */
+import type { Memory } from './types.js';
+export declare function getMemoryPath(): string;
+export declare function loadMemory(): Promise<Memory>;
+export declare function saveMemory(memory: Memory): Promise<void>;

package/dist/storage.js

@@ -0,0 +1,95 @@
+/**
+ * File storage with atomic writes
+ */
+import { promises as fs } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import { log } from './logger.js';
+export function getMemoryPath() {
+    const xdgDataHome = process.env.XDG_DATA_HOME || join(homedir(), '.local', 'share');
+    const aceDir = join(xdgDataHome, 'ace-flash-memory');
+    return join(aceDir, 'memory.json');
+}
+function isValidInsight(data) {
+    if (typeof data !== 'object' || data === null)
+        return false;
+    const obj = data;
+    const hasRequiredFields = typeof obj.id === 'string' &&
+        typeof obj.title === 'string' &&
+        Array.isArray(obj.tags) &&
+        obj.tags.every((tag) => typeof tag === 'string') &&
+        typeof obj.content === 'string' &&
+        typeof obj.helpful === 'number' &&
+        typeof obj.harmful === 'number' &&
+        typeof obj.created === 'string' &&
+        typeof obj.lastUsed === 'string';
+    if (!hasRequiredFields)
+        return false;
+    // sourceUrl is optional, but if present must be a string
+    if (obj.sourceUrl !== undefined && typeof obj.sourceUrl !== 'string') {
+        return false;
+    }
+    return true;
+}
+function isValidMemory(data) {
+    if (typeof data !== 'object' || data === null)
+        return false;
+    const obj = data;
+    if (!Array.isArray(obj.insights))
+        return false;
+    // Validate each insight in the array
+    return obj.insights.every(isValidInsight);
+}
+async function createBackupAndReturnEmpty(memoryPath, reason) {
+    log.error(reason);
+    // Use ISO timestamp format (matching documentation examples)
+    // Replace colons and dots with hyphens for filesystem compatibility
+    const isoTimestamp = new Date().toISOString().replace(/:/g, '-').replace(/\./g, '-');
+    const randomSuffix = Math.random().toString(36).slice(2, 11);
+    const backupPath = `${memoryPath}.corrupt.${isoTimestamp}.${randomSuffix}`;
+    try {
+        await fs.rename(memoryPath, backupPath);
+        log.info(`Corrupted file backed up to: ${backupPath}`);
+    }
+    catch (backupError) {
+        log.error('Failed to create backup:', backupError);
+        // Even if backup fails, we still return empty memory to allow recovery
+    }
+    return { insights: [] };
+}
+export async function loadMemory() {
+    const memoryPath = getMemoryPath();
+    try {
+        const data = await fs.readFile(memoryPath, 'utf-8');
+        const parsed = JSON.parse(data);
+        if (!isValidMemory(parsed)) {
+            return await createBackupAndReturnEmpty(memoryPath, 'Memory file has invalid structure, creating backup and starting fresh');
+        }
+        return parsed;
+    }
+    catch (error) {
+        const nodeError = error;
+        if (nodeError.code === 'ENOENT') {
+            log.info('Memory file not found, creating new one');
+            return { insights: [] };
+        }
+        // Handle corrupted JSON (SyntaxError from JSON.parse)
+        if (error instanceof SyntaxError) {
+            return await createBackupAndReturnEmpty(memoryPath, 'Memory file is corrupted (invalid JSON), creating backup and starting fresh');
+        }
+        throw error;
+    }
+}
+export async function saveMemory(memory) {
+    const memoryPath = getMemoryPath();
+    const xdgDataHome = process.env.XDG_DATA_HOME || join(homedir(), '.local', 'share');
+    const memoryDir = join(xdgDataHome, 'ace-flash-memory');
+    // Use unique temp file: process.pid + random suffix to avoid collisions
+    const tmpPath = `${memoryPath}.tmp.${process.pid}.${Math.random().toString(36).slice(2, 11)}`;
+    // Ensure directory exists
+    await fs.mkdir(memoryDir, { recursive: true });
+    // Atomic write: write to unique .tmp then rename
+    await fs.writeFile(tmpPath, JSON.stringify(memory, null, 2), 'utf-8');
+    await fs.rename(tmpPath, memoryPath);
+    log.info('Memory saved successfully');
+}

package/dist/tools.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Tool implementations for MCP server
+ */
+import type { ToolResponse, ListIndexParams } from './types.js';
+export declare function addInsight(title: string, tags: string[], content: string, overwrite?: boolean, sourceUrl?: string): Promise<ToolResponse>;
+export declare function listIndex(params?: ListIndexParams): Promise<ToolResponse>;
+export declare function getDetail(id: string): Promise<ToolResponse>;
+export declare function markHelpful(id: string): Promise<ToolResponse>;
+export declare function markHarmful(id: string): Promise<ToolResponse>;
+export declare function searchInsights(query: string, limit?: number): Promise<ToolResponse>;
+export declare function deleteInsight(id: string): Promise<ToolResponse>;
+export declare function exportMemory(format?: 'json' | 'markdown'): Promise<ToolResponse>;