memory-journal-mcp 3.0.0

package/src/index.ts

@@ -0,0 +1,53 @@
+/**
+ * memory-journal-mcp - Public API
+ * 
+ * Exports the main components for programmatic use.
+ */
+
+// Server
+export { createServer, SqliteAdapter } from './server/McpServer.js';
+
+// Types
+export type {
+    ToolGroup,
+    MetaGroup,
+    ToolFilterRule,
+    ToolFilterConfig,
+    ToolAnnotations,
+    ResourceAnnotations,
+    ToolDefinition,
+    ResourceDefinition,
+    PromptDefinition,
+    EntryType,
+    SignificanceType,
+    RelationshipType,
+    JournalEntry,
+    Tag,
+    Relationship,
+    Embedding,
+    GitHubProject,
+    GitHubIssue,
+    GitHubPullRequest,
+    GitHubWorkflowRun,
+    ProjectContext,
+    ServerConfig,
+} from './types/index.js';
+
+export { DEFAULT_CONFIG } from './types/index.js';
+
+// Filtering
+export {
+    TOOL_GROUPS,
+    META_GROUPS,
+    getAllToolNames,
+    getToolGroup,
+    parseToolFilter,
+    isToolEnabled,
+    filterTools,
+    getToolFilterFromEnv,
+    calculateTokenSavings,
+    getFilterSummary,
+} from './filtering/ToolFilter.js';
+
+// Logger
+export { logger } from './utils/logger.js';

package/src/server/McpServer.ts

@@ -0,0 +1,230 @@
+/**
+ * Memory Journal MCP Server - Main Server
+ * 
+ * MCP server implementation with tools, resources, and prompts.
+ */
+
+import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { Variables } from '@modelcontextprotocol/sdk/shared/uriTemplate.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+
+import { SqliteAdapter } from '../database/SqliteAdapter.js';
+import { VectorSearchManager } from '../vector/VectorSearchManager.js';
+import { GitHubIntegration } from '../github/GitHubIntegration.js';
+import { logger } from '../utils/logger.js';
+import {
+    parseToolFilter,
+    getToolFilterFromEnv,
+    getFilterSummary,
+    type ToolFilterConfig
+} from '../filtering/ToolFilter.js';
+import { getTools, callTool } from '../handlers/tools/index.js';
+import { getResources, readResource } from '../handlers/resources/index.js';
+import { getPrompts, getPrompt } from '../handlers/prompts/index.js';
+
+export interface ServerOptions {
+    transport: 'stdio' | 'http';
+    port?: number;
+    dbPath: string;
+    toolFilter?: string;
+}
+
+/**
+ * Create and start the MCP server
+ */
+export async function createServer(options: ServerOptions): Promise<void> {
+    const { transport, dbPath, toolFilter } = options;
+
+    // Initialize database (async for sql.js)
+    const db = new SqliteAdapter(dbPath);
+    await db.initialize();
+    logger.info('Database initialized', { module: 'McpServer', dbPath });
+
+    // Initialize vector search manager (lazy loading - model loads on first use)
+    const vectorManager = new VectorSearchManager(dbPath);
+    logger.info('Vector search manager created (lazy initialization)', { module: 'McpServer' });
+
+    // Initialize GitHub integration
+    const github = new GitHubIntegration();
+    logger.info('GitHub integration initialized', { module: 'McpServer', hasToken: github.isApiAvailable() });
+
+    // Parse tool filter
+    let filterConfig: ToolFilterConfig | null = null;
+    if (toolFilter) {
+        filterConfig = parseToolFilter(toolFilter);
+        logger.info('Tool filter applied', {
+            module: 'McpServer',
+            summary: getFilterSummary(filterConfig)
+        });
+    } else {
+        filterConfig = getToolFilterFromEnv();
+        if (filterConfig) {
+            logger.info('Tool filter from env', {
+                module: 'McpServer',
+                summary: getFilterSummary(filterConfig)
+            });
+        }
+    }
+
+    // Create MCP server
+    const server = new McpServer({
+        name: 'memory-journal-mcp',
+        version: '3.0.0-alpha.1',
+    });
+
+    // Get filtered tools and register them dynamically
+    const tools = getTools(db, filterConfig, vectorManager, github);
+    for (const tool of tools) {
+        const toolDef = tool as {
+            name: string;
+            description?: string;
+            inputSchema?: z.ZodType;
+            annotations?: Record<string, unknown>;
+        };
+
+        // Build tool options matching MCP SDK expectations
+        const toolOptions: Record<string, unknown> = {
+            description: toolDef.description ?? '',
+        };
+
+        if (toolDef.inputSchema) {
+            toolOptions['inputSchema'] = toolDef.inputSchema;
+        }
+
+        if (toolDef.annotations) {
+            toolOptions['annotations'] = toolDef.annotations;
+        }
+
+        server.registerTool(
+            toolDef.name,
+            toolOptions as { description?: string; inputSchema?: z.ZodType },
+            async (args: unknown) => {
+                try {
+                    const result = await callTool(toolDef.name, args as Record<string, unknown>, db, vectorManager, github);
+                    return {
+                        content: [{
+                            type: 'text' as const,
+                            text: typeof result === 'string' ? result : JSON.stringify(result, null, 2),
+                        }],
+                    };
+                } catch (error) {
+                    return {
+                        content: [{
+                            type: 'text' as const,
+                            text: `Error: ${error instanceof Error ? error.message : String(error)}`,
+                        }],
+                        isError: true,
+                    };
+                }
+            }
+        );
+    }
+
+    // Register resources
+    const resources = getResources();
+    for (const resource of resources) {
+        const resDef = resource as { uri: string; name: string; description?: string; mimeType?: string };
+
+        // Check if this is a template URI (contains {variable} patterns)
+        const isTemplate = resDef.uri.includes('{');
+
+        if (isTemplate) {
+            // Use ResourceTemplate for parametrized URIs
+            const template = new ResourceTemplate(
+                resDef.uri,
+                { list: undefined }  // No enumeration support needed
+            );
+            server.registerResource(
+                resDef.name,
+                template,
+                { description: resDef.description ?? '', mimeType: resDef.mimeType ?? 'application/json' },
+                async (uri: URL, _variables: Variables) => {
+                    const result = await readResource(uri.href, db, vectorManager, filterConfig, github);
+                    return {
+                        contents: [{
+                            uri: uri.href,
+                            mimeType: resDef.mimeType ?? 'application/json',
+                            text: typeof result === 'string' ? result : JSON.stringify(result, null, 2),
+                        }],
+                    };
+                }
+            );
+        } else {
+            server.registerResource(
+                resDef.name,
+                resDef.uri,
+                { description: resDef.description ?? '', mimeType: resDef.mimeType ?? 'application/json' },
+                async (uri: URL) => {
+                    const result = await readResource(uri.href, db, vectorManager, filterConfig, github);
+                    return {
+                        contents: [{
+                            uri: uri.href,
+                            mimeType: resDef.mimeType ?? 'application/json',
+                            text: typeof result === 'string' ? result : JSON.stringify(result, null, 2),
+                        }],
+                    };
+                }
+            );
+        }
+    }
+
+    // Register prompts
+    const prompts = getPrompts();
+    for (const prompt of prompts) {
+        const promptDef = prompt as {
+            name: string;
+            description?: string;
+            arguments?: { name: string; description: string; required?: boolean }[];
+        };
+
+        // Build Zod schema from prompt.arguments definitions
+        const zodShape: Record<string, z.ZodType> = {};
+        if (promptDef.arguments) {
+            for (const arg of promptDef.arguments) {
+                zodShape[arg.name] = arg.required === true
+                    ? z.string().describe(arg.description)
+                    : z.string().optional().describe(arg.description);
+            }
+        }
+
+        server.registerPrompt(
+            promptDef.name,
+            {
+                description: promptDef.description ?? '',
+                argsSchema: zodShape
+            },
+            (providedArgs) => {
+                const args = providedArgs as Record<string, string>;
+                const promptResult = getPrompt(promptDef.name, args, db);
+                // Map to MCP SDK expected format
+                const result = {
+                    messages: promptResult.messages.map(m => ({
+                        role: m.role as 'user' | 'assistant',
+                        content: m.content as { type: 'text'; text: string }
+                    }))
+                };
+                return Promise.resolve(result);
+            }
+        );
+    }
+
+    // Start server based on transport
+    if (transport === 'stdio') {
+        const stdioTransport = new StdioServerTransport();
+        await server.connect(stdioTransport);
+        logger.info('MCP server started on stdio', { module: 'McpServer' });
+    } else {
+        // HTTP transport - TODO: implement SSE transport
+        throw new Error('HTTP transport not yet implemented');
+    }
+
+    // Handle shutdown
+    process.on('SIGINT', () => {
+        logger.info('Shutting down...', { module: 'McpServer' });
+        db.close();
+        process.exit(0);
+    });
+}
+
+export { SqliteAdapter };

package/src/types/index.ts

@@ -0,0 +1,435 @@
+/**
+ * Memory Journal MCP Server - Type Definitions
+ * 
+ * Core types for the MCP server including tools, resources, prompts,
+ * database entities, and filtering.
+ */
+
+// ============================================================================
+// Tool Filtering Types
+// ============================================================================
+
+/**
+ * Tool group identifiers for Memory Journal
+ */
+export type ToolGroup =
+    | 'core'           // Entry CRUD: create, get_by_id, get_recent, create_minimal, test_simple
+    | 'search'         // Search: search_entries, search_by_date_range, semantic_search
+    | 'analytics'      // Analytics: get_statistics, get_cross_project_insights
+    | 'relationships'  // Relationships: link_entries, visualize_relationships
+    | 'export'         // Export: export_entries
+    | 'admin'          // Admin: update_entry, delete_entry
+    | 'github'         // Reserved for future GitHub-specific tools
+    | 'backup';        // Backup: backup_journal, list_backups, restore_backup
+
+/**
+ * Meta-group identifiers for common multi-group selections
+ */
+export type MetaGroup =
+    | 'starter'        // core + search (~8 tools)
+    | 'essential'      // core only (~5 tools)
+    | 'full'           // all groups (~16 tools)
+    | 'readonly';      // everything except admin
+
+/**
+ * Tool filter rule
+ */
+export interface ToolFilterRule {
+    /** Rule type: include or exclude */
+    type: 'include' | 'exclude';
+
+    /** Target: group name or tool name */
+    target: string;
+
+    /** Whether target is a group (true) or individual tool (false) */
+    isGroup: boolean;
+}
+
+/**
+ * Parsed tool filter configuration
+ */
+export interface ToolFilterConfig {
+    /** Original filter string */
+    raw: string;
+
+    /** Parsed rules in order */
+    rules: ToolFilterRule[];
+
+    /** Set of enabled tool names after applying rules */
+    enabledTools: Set<string>;
+}
+
+// ============================================================================
+// MCP 2025-11-25 Annotations
+// ============================================================================
+
+/**
+ * MCP Tool Annotations (MCP Spec 2025-11-25)
+ * 
+ * Behavioral hints for AI clients to understand tool characteristics.
+ */
+export interface ToolAnnotations {
+    /** Tool does not modify state (idempotent reads) */
+    readOnlyHint?: boolean;
+
+    /** Tool may permanently delete/destroy data */
+    destructiveHint?: boolean;
+
+    /** Repeated calls with same args produce same result */
+    idempotentHint?: boolean;
+
+    /** Tool interacts with external services (network, APIs) */
+    openWorldHint?: boolean;
+}
+
+/**
+ * MCP Resource Annotations (MCP Spec 2025-11-25)
+ */
+export interface ResourceAnnotations {
+    /** Intended audience: 'user' or 'assistant' */
+    audience?: ('user' | 'assistant')[];
+
+    /** Importance level from 0.0 (optional) to 1.0 (required) */
+    priority?: number;
+
+    /** ISO 8601 timestamp of last modification */
+    lastModified?: string;
+}
+
+// ============================================================================
+// Tool, Resource, Prompt Definitions
+// ============================================================================
+
+/**
+ * Tool definition for registration
+ */
+export interface ToolDefinition {
+    /** Unique tool name */
+    name: string;
+
+    /** Human-readable display title (MCP 2025-11-25) */
+    title: string;
+
+    /** Human-readable description */
+    description: string;
+
+    /** Tool group for filtering */
+    group: ToolGroup;
+
+    /** Zod schema for input validation */
+    inputSchema: unknown;
+
+    /** Behavioral hints for AI clients */
+    annotations: ToolAnnotations;
+
+    /** Tool handler function */
+    handler: (params: unknown) => Promise<unknown>;
+}
+
+/**
+ * Resource definition for MCP
+ */
+export interface ResourceDefinition {
+    /** Resource URI template */
+    uri: string;
+
+    /** Human-readable name */
+    name: string;
+
+    /** Human-readable display title */
+    title: string;
+
+    /** Description */
+    description: string;
+
+    /** MIME type */
+    mimeType: string;
+
+    /** Resource metadata annotations */
+    annotations?: ResourceAnnotations;
+
+    /** Resource handler - NOTE: db is passed at runtime, not in the definition */
+    handler: (uri: string) => Promise<unknown>;
+}
+
+/**
+ * Prompt definition for MCP
+ */
+export interface PromptDefinition {
+    /** Prompt name */
+    name: string;
+
+    /** Description */
+    description: string;
+
+    /** Argument definitions */
+    arguments?: {
+        name: string;
+        description: string;
+        required?: boolean;
+    }[];
+
+    /** Prompt handler */
+    handler: (args: Record<string, string>) => Promise<unknown>;
+}
+
+// ============================================================================
+// Database Entity Types
+// ============================================================================
+
+/**
+ * Entry types for journal entries
+ */
+export type EntryType =
+    | 'personal_reflection'
+    | 'project_decision'
+    | 'technical_achievement'
+    | 'bug_fix'
+    | 'feature_implementation'
+    | 'code_review'
+    | 'meeting_notes'
+    | 'learning'
+    | 'research'
+    | 'planning'
+    | 'retrospective'
+    | 'standup'
+    | 'other';
+
+/**
+ * Significance types for important entries
+ */
+export type SignificanceType =
+    | 'milestone'
+    | 'breakthrough'
+    | 'technical_breakthrough'
+    | 'decision'
+    | 'lesson_learned'
+    | 'blocker_resolved'
+    | 'release'
+    | null;
+
+/**
+ * Relationship types between entries
+ */
+export type RelationshipType =
+    | 'evolves_from'
+    | 'references'
+    | 'implements'
+    | 'clarifies'
+    | 'response_to';
+
+/**
+ * Journal entry entity
+ */
+export interface JournalEntry {
+    id: number;
+    entryType: EntryType;
+    content: string;
+    timestamp: string;
+    isPersonal: boolean;
+    significanceType: SignificanceType;
+    autoContext: string | null;
+    deletedAt: string | null;
+    tags: string[];
+}
+
+/**
+ * Tag entity
+ */
+export interface Tag {
+    id: number;
+    name: string;
+    usageCount: number;
+}
+
+/**
+ * Relationship entity
+ */
+export interface Relationship {
+    id: number;
+    fromEntryId: number;
+    toEntryId: number;
+    relationshipType: RelationshipType;
+    description: string | null;
+    createdAt: string;
+}
+
+/**
+ * Embedding entity for vector search
+ */
+export interface Embedding {
+    entryId: number;
+    embedding: Float32Array;
+    modelName: string;
+}
+
+// ============================================================================
+// GitHub Integration Types
+// ============================================================================
+
+/**
+ * GitHub project information
+ */
+export interface GitHubProject {
+    number: number;
+    title: string;
+    url: string;
+    state: 'OPEN' | 'CLOSED';
+}
+
+/**
+ * GitHub issue information
+ */
+export interface GitHubIssue {
+    number: number;
+    title: string;
+    url: string;
+    state: 'OPEN' | 'CLOSED';
+}
+
+/**
+ * GitHub pull request information
+ */
+export interface GitHubPullRequest {
+    number: number;
+    title: string;
+    url: string;
+    state: 'OPEN' | 'CLOSED' | 'MERGED';
+}
+
+/**
+ * GitHub workflow run information
+ */
+export interface GitHubWorkflowRun {
+    id: number;
+    name: string;
+    status: 'queued' | 'in_progress' | 'completed';
+    conclusion: 'success' | 'failure' | 'cancelled' | 'skipped' | null;
+    url: string;
+    headBranch: string;
+    headSha: string;
+    createdAt: string;
+    updatedAt: string;
+}
+
+/**
+ * Auto-captured project context
+ */
+export interface ProjectContext {
+    repoName: string | null;
+    branch: string | null;
+    commit: string | null;
+    remoteUrl: string | null;
+    projects: GitHubProject[];
+    issues: GitHubIssue[];
+    pullRequests: GitHubPullRequest[];
+    workflowRuns: GitHubWorkflowRun[];
+}
+
+// ============================================================================
+// Configuration Types
+// ============================================================================
+
+/**
+ * Server configuration
+ */
+export interface ServerConfig {
+    /** Path to SQLite database file */
+    dbPath: string;
+
+    /** GitHub personal access token */
+    githubToken?: string;
+
+    /** GitHub organization token (for org projects) */
+    githubOrgToken?: string;
+
+    /** Default organization name */
+    defaultOrg?: string;
+
+    /** Tool filter string */
+    toolFilter?: string;
+
+    /** Enable semantic search */
+    enableSemanticSearch: boolean;
+
+    /** Sentence transformer model name */
+    modelName: string;
+}
+
+/**
+ * Default configuration values
+ */
+export const DEFAULT_CONFIG: Partial<ServerConfig> = {
+    dbPath: './memory_journal.db',
+    enableSemanticSearch: true,
+    modelName: 'all-MiniLM-L6-v2',
+};
+
+// ============================================================================
+// Backup Types
+// ============================================================================
+
+/**
+ * Backup file information
+ */
+export interface BackupInfo {
+    /** Backup filename */
+    filename: string;
+
+    /** Full path to backup file */
+    path: string;
+
+    /** File size in bytes */
+    sizeBytes: number;
+
+    /** Backup creation time (ISO 8601) */
+    createdAt: string;
+}
+
+// ============================================================================
+// Health Status Types
+// ============================================================================
+
+/**
+ * Server health and diagnostics status
+ */
+export interface HealthStatus {
+    /** Database statistics */
+    database: {
+        path: string;
+        sizeBytes: number;
+        entryCount: number;
+        deletedEntryCount: number;
+        relationshipCount: number;
+        tagCount: number;
+    };
+
+    /** Backup information */
+    backups: {
+        directory: string;
+        count: number;
+        lastBackup: {
+            filename: string;
+            createdAt: string;
+            sizeBytes: number;
+        } | null;
+    };
+
+    /** Vector search index status */
+    vectorIndex: {
+        available: boolean;
+        indexedEntries: number;
+        modelName: string | null;
+    } | null;
+
+    /** Tool filter configuration */
+    toolFilter: {
+        active: boolean;
+        enabledCount: number;
+        totalCount: number;
+        filterString: string | null;
+    };
+
+    /** Health check timestamp (ISO 8601) */
+    timestamp: string;
+}