@claudetools/tools 0.1.0

package/dist/logger.js

@@ -0,0 +1,401 @@
+// =============================================================================
+// ClaudeTools Memory MCP Server - Structured Logger
+// =============================================================================
+// File-based logging for real-time monitoring of MCP operations
+// =============================================================================
+import * as fs from 'fs';
+import * as path from 'path';
+// Emojis for visual scanning
+const CATEGORY_ICONS = {
+    TOOL: '🔧',
+    API: '🌐',
+    MEMORY: '🧠',
+    SEARCH: '🔍',
+    INJECT: '💉',
+    EXTRACT: '📤',
+    STORE: '💾',
+    QUERY: '❓',
+    IMPACT: '💥',
+    PATTERN: '🔬',
+    CONFIG: '⚙️',
+    REGISTRATION: '📝',
+    ERROR: '❌',
+};
+const LEVEL_ICONS = {
+    DEBUG: '🔹',
+    INFO: '🔷',
+    WARN: '⚠️',
+    ERROR: '❌',
+};
+class MCPLogger {
+    logFile;
+    logDir;
+    enabled;
+    constructor() {
+        // Log to .logs directory in project root
+        this.logDir = path.join(process.cwd(), '.logs');
+        this.logFile = path.join(this.logDir, 'mcp-server.log');
+        this.enabled = process.env.MCP_LOGGING !== 'false';
+        // Ensure log directory exists
+        if (this.enabled) {
+            try {
+                if (!fs.existsSync(this.logDir)) {
+                    fs.mkdirSync(this.logDir, { recursive: true });
+                }
+            }
+            catch {
+                // If we can't create dir, disable logging
+                this.enabled = false;
+            }
+        }
+    }
+    formatTimestamp() {
+        const now = new Date();
+        return now.toISOString();
+    }
+    formatForFile(entry) {
+        const icon = CATEGORY_ICONS[entry.category] || '📝';
+        const levelIcon = LEVEL_ICONS[entry.level];
+        // Format timestamp as readable time only (HH:MM:SS)
+        const time = new Date(entry.timestamp).toLocaleTimeString('en-AU', {
+            hour12: false,
+            hour: '2-digit',
+            minute: '2-digit',
+            second: '2-digit',
+        });
+        // Build human-readable message
+        let line = `${time} ${levelIcon} ${icon} ${entry.message}`;
+        // Add duration as natural language
+        if (entry.duration !== undefined) {
+            if (entry.duration < 100) {
+                line += ` — instant`;
+            }
+            else if (entry.duration < 500) {
+                line += ` — ${entry.duration}ms`;
+            }
+            else if (entry.duration < 1000) {
+                line += ` — took ${entry.duration}ms`;
+            }
+            else {
+                line += ` — took ${(entry.duration / 1000).toFixed(1)}s`;
+            }
+        }
+        // Format data as natural language (no JSON)
+        if (entry.data && Object.keys(entry.data).length > 0) {
+            const details = this.formatDataAsNaturalLanguage(entry.data);
+            if (details) {
+                line += `\n      ${details}`;
+            }
+        }
+        return line;
+    }
+    formatDataAsNaturalLanguage(data) {
+        const parts = [];
+        for (const [key, value] of Object.entries(data)) {
+            // Skip tool name (already in message)
+            if (key === 'tool')
+                continue;
+            // Format different types naturally
+            if (key === 'args' && typeof value === 'object' && value !== null) {
+                const args = value;
+                const argParts = [];
+                for (const [argKey, argVal] of Object.entries(args)) {
+                    if (typeof argVal === 'string') {
+                        // Truncate long strings
+                        const str = argVal.length > 80 ? argVal.slice(0, 77) + '...' : argVal;
+                        argParts.push(`${argKey}: "${str}"`);
+                    }
+                    else if (typeof argVal === 'number') {
+                        argParts.push(`${argKey}: ${argVal}`);
+                    }
+                    else if (typeof argVal === 'boolean') {
+                        argParts.push(`${argKey}: ${argVal ? 'yes' : 'no'}`);
+                    }
+                    else if (Array.isArray(argVal)) {
+                        argParts.push(`${argKey}: [${argVal.length} items]`);
+                    }
+                }
+                if (argParts.length > 0) {
+                    parts.push(`with ${argParts.join(', ')}`);
+                }
+            }
+            else if (key === 'method') {
+                parts.push(`using ${value}`);
+            }
+            else if (key === 'queryLength') {
+                parts.push(`(${value} chars)`);
+            }
+            else if (typeof value === 'string' && value.length < 100) {
+                parts.push(`${key}: ${value}`);
+            }
+            else if (typeof value === 'number') {
+                parts.push(`${key}: ${value}`);
+            }
+        }
+        return parts.join(' • ');
+    }
+    write(entry) {
+        if (!this.enabled)
+            return;
+        try {
+            const line = this.formatForFile(entry) + '\n';
+            fs.appendFileSync(this.logFile, line);
+        }
+        catch {
+            // Silently fail if we can't write
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Core Logging Methods
+    // ---------------------------------------------------------------------------
+    debug(category, message, data) {
+        this.write({
+            timestamp: this.formatTimestamp(),
+            level: 'DEBUG',
+            category,
+            message,
+            data,
+        });
+    }
+    info(category, message, data) {
+        this.write({
+            timestamp: this.formatTimestamp(),
+            level: 'INFO',
+            category,
+            message,
+            data,
+        });
+    }
+    warn(category, message, data) {
+        this.write({
+            timestamp: this.formatTimestamp(),
+            level: 'WARN',
+            category,
+            message,
+            data,
+        });
+    }
+    error(category, message, error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        this.write({
+            timestamp: this.formatTimestamp(),
+            level: 'ERROR',
+            category,
+            message: `${message}: ${errorMessage}`,
+        });
+    }
+    // ---------------------------------------------------------------------------
+    // Structured Operation Logging (Human-Readable)
+    // ---------------------------------------------------------------------------
+    toolCall(toolName, args) {
+        // Format tool name in a friendly way
+        const friendlyName = toolName.replace(/_/g, ' ');
+        const sanitized = this.sanitizeArgs(args);
+        // Build a natural language description
+        let description = `Starting ${friendlyName}`;
+        // Add context from args
+        if (sanitized.query && typeof sanitized.query === 'string') {
+            const query = sanitized.query;
+            const preview = query.length > 50 ? query.slice(0, 47) + '...' : query;
+            description = `Searching for "${preview}"`;
+        }
+        else if (sanitized.function_name) {
+            description = `Analysing function "${sanitized.function_name}"`;
+        }
+        else if (sanitized.entity1 && sanitized.relationship && sanitized.entity2) {
+            description = `Storing: ${sanitized.entity1} → ${sanitized.relationship} → ${sanitized.entity2}`;
+        }
+        else if (sanitized.code && typeof sanitized.code === 'string') {
+            description = `Checking ${(sanitized.code).length} characters of code`;
+        }
+        this.info('TOOL', description);
+    }
+    toolResult(toolName, success, duration, resultSummary) {
+        const friendlyName = toolName.replace(/_/g, ' ');
+        if (success) {
+            const message = resultSummary ? resultSummary : `${friendlyName} completed`;
+            this.write({
+                timestamp: this.formatTimestamp(),
+                level: 'INFO',
+                category: 'TOOL',
+                message,
+                duration,
+            });
+        }
+        else {
+            this.write({
+                timestamp: this.formatTimestamp(),
+                level: 'ERROR',
+                category: 'TOOL',
+                message: `${friendlyName} failed`,
+                duration,
+            });
+        }
+    }
+    apiRequest(method, endpoint) {
+        // Make endpoint human-readable
+        const path = endpoint.replace('/api/v1/', '').replace(/\//g, ' → ');
+        this.debug('API', `${method} request to ${path}`);
+    }
+    apiResponse(method, endpoint, status, duration) {
+        const level = status >= 400 ? 'ERROR' : 'DEBUG';
+        const path = endpoint.replace('/api/v1/', '').replace(/\//g, ' → ');
+        const outcome = status >= 400 ? 'failed' : 'succeeded';
+        this.write({
+            timestamp: this.formatTimestamp(),
+            level,
+            category: 'API',
+            message: `${method} ${path} ${outcome} (${status})`,
+            duration,
+        });
+    }
+    searchQuery(query, method) {
+        const preview = query.length > 50 ? query.slice(0, 47) + '...' : query;
+        this.info('SEARCH', `Looking for "${preview}" using ${method}`);
+    }
+    searchResults(factsFound, entitiesFound, duration) {
+        let message;
+        if (factsFound === 0 && entitiesFound === 0) {
+            message = 'No results found';
+        }
+        else if (factsFound === 0) {
+            message = `Found ${entitiesFound} ${entitiesFound === 1 ? 'entity' : 'entities'}, no facts`;
+        }
+        else if (entitiesFound === 0) {
+            message = `Found ${factsFound} ${factsFound === 1 ? 'fact' : 'facts'}, no entities`;
+        }
+        else {
+            message = `Found ${factsFound} ${factsFound === 1 ? 'fact' : 'facts'} and ${entitiesFound} ${entitiesFound === 1 ? 'entity' : 'entities'}`;
+        }
+        this.write({
+            timestamp: this.formatTimestamp(),
+            level: 'INFO',
+            category: 'SEARCH',
+            message,
+            duration,
+        });
+    }
+    memoryStore(entity1, relation, entity2) {
+        // Make the relationship human-readable
+        const readableRelation = relation.toLowerCase().replace(/_/g, ' ');
+        this.info('STORE', `Remembered: "${entity1}" ${readableRelation} "${entity2}"`);
+    }
+    queryDependencies(functionName, direction, resultsCount, duration) {
+        let message;
+        if (direction === 'forward') {
+            message = resultsCount === 0
+                ? `"${functionName}" doesn't call any other functions`
+                : `"${functionName}" calls ${resultsCount} other ${resultsCount === 1 ? 'function' : 'functions'}`;
+        }
+        else {
+            message = resultsCount === 0
+                ? `Nothing calls "${functionName}"`
+                : `${resultsCount} ${resultsCount === 1 ? 'function calls' : 'functions call'} "${functionName}"`;
+        }
+        this.write({
+            timestamp: this.formatTimestamp(),
+            level: 'INFO',
+            category: 'QUERY',
+            message,
+            duration,
+        });
+    }
+    impactAnalysis(functionName, analysisType, riskLevel, totalAffected, duration) {
+        const riskEmoji = riskLevel === 'CRITICAL' ? '🚨' : riskLevel === 'HIGH' ? '⚠️' : riskLevel === 'MEDIUM' ? '📋' : '✅';
+        let message;
+        if (totalAffected === 0) {
+            message = `${riskEmoji} Changing "${functionName}" is safe — no dependencies`;
+        }
+        else {
+            message = `${riskEmoji} Changing "${functionName}" affects ${totalAffected} ${totalAffected === 1 ? 'place' : 'places'} — ${riskLevel.toLowerCase()} risk`;
+        }
+        this.write({
+            timestamp: this.formatTimestamp(),
+            level: 'INFO',
+            category: 'IMPACT',
+            message,
+            duration,
+        });
+    }
+    patternCheck(codeLength, warningsFound, securityScore, perfScore, duration) {
+        let message;
+        if (warningsFound === 0) {
+            message = `Code looks good — no issues found`;
+        }
+        else {
+            message = `Found ${warningsFound} ${warningsFound === 1 ? 'issue' : 'issues'}`;
+        }
+        // Add scores as context
+        const secLabel = securityScore >= 80 ? 'secure' : securityScore >= 50 ? 'some concerns' : 'needs attention';
+        const perfLabel = perfScore >= 80 ? 'efficient' : perfScore >= 50 ? 'acceptable' : 'could be faster';
+        message += ` — Security: ${secLabel} (${securityScore}/100), Performance: ${perfLabel} (${perfScore}/100)`;
+        this.write({
+            timestamp: this.formatTimestamp(),
+            level: 'INFO',
+            category: 'PATTERN',
+            message,
+            duration,
+        });
+    }
+    contextInjection(query, factsIncluded, tokenBudget, duration) {
+        const preview = query.length > 35 ? query.slice(0, 32) + '...' : query;
+        let message;
+        if (factsIncluded === 0) {
+            message = `No relevant context found for "${preview}"`;
+        }
+        else {
+            message = `Providing ${factsIncluded} ${factsIncluded === 1 ? 'piece' : 'pieces'} of context for "${preview}"`;
+        }
+        this.write({
+            timestamp: this.formatTimestamp(),
+            level: 'INFO',
+            category: 'INJECT',
+            message,
+            duration,
+        });
+    }
+    // ---------------------------------------------------------------------------
+    // Utility
+    // ---------------------------------------------------------------------------
+    sanitizeArgs(args) {
+        const sanitized = {};
+        for (const [key, value] of Object.entries(args)) {
+            if (typeof value === 'string' && value.length > 200) {
+                sanitized[key] = value.slice(0, 200) + `... (${value.length} chars)`;
+            }
+            else {
+                sanitized[key] = value;
+            }
+        }
+        return sanitized;
+    }
+    // Start a timing context
+    startTimer() {
+        const start = Date.now();
+        return () => Date.now() - start;
+    }
+    // Log separator for visual clarity
+    separator(label) {
+        if (label) {
+            this.write({
+                timestamp: this.formatTimestamp(),
+                level: 'INFO',
+                category: 'TOOL',
+                message: `${'─'.repeat(20)} ${label} ${'─'.repeat(20)}`,
+            });
+        }
+    }
+    // Clear log file
+    clear() {
+        if (this.enabled) {
+            try {
+                fs.writeFileSync(this.logFile, '');
+            }
+            catch {
+                // Silently fail
+            }
+        }
+    }
+}
+// Singleton export
+export const mcpLogger = new MCPLogger();

package/dist/prompts.d.ts

@@ -0,0 +1,2 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+export declare function registerPromptHandlers(server: Server): void;

package/dist/prompts.js

@@ -0,0 +1,64 @@
+// =============================================================================
+// MCP Prompt Handlers
+// =============================================================================
+import { ListPromptsRequestSchema, GetPromptRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+export function registerPromptHandlers(server) {
+    server.setRequestHandler(ListPromptsRequestSchema, async () => ({
+        prompts: [
+            {
+                name: 'recall',
+                description: 'Recall information from memory about a specific topic',
+                arguments: [
+                    {
+                        name: 'topic',
+                        description: 'The topic to recall information about',
+                        required: true,
+                    },
+                ],
+            },
+            {
+                name: 'remember',
+                description: 'Store important information to memory',
+                arguments: [
+                    {
+                        name: 'information',
+                        description: 'The information to remember',
+                        required: true,
+                    },
+                ],
+            },
+        ],
+    }));
+    server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        if (name === 'recall') {
+            const topic = args?.topic || 'general';
+            return {
+                messages: [
+                    {
+                        role: 'user',
+                        content: {
+                            type: 'text',
+                            text: `Search your memory for information about: ${topic}\n\nUse the memory_search tool to find relevant facts and entities.`,
+                        },
+                    },
+                ],
+            };
+        }
+        if (name === 'remember') {
+            const information = args?.information || '';
+            return {
+                messages: [
+                    {
+                        role: 'user',
+                        content: {
+                            type: 'text',
+                            text: `Store this information to memory:\n\n${information}\n\nUse the memory_store_fact tool to save any specific facts, or memory_add for general conversation context.`,
+                        },
+                    },
+                ],
+            };
+        }
+        throw new Error(`Unknown prompt: ${name}`);
+    });
+}

package/dist/resources.d.ts

@@ -0,0 +1,2 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+export declare function registerResourceHandlers(server: Server): void;

package/dist/resources.js

@@ -0,0 +1,79 @@
+// =============================================================================
+// MCP Resource Handlers
+// =============================================================================
+import { ListResourcesRequestSchema, ReadResourceRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { getSummary, getEntities, getContext } from './helpers/api-client.js';
+import { formatContextForClaude } from './helpers/formatter.js';
+import { getDefaultProjectId } from './helpers/config.js';
+export function registerResourceHandlers(server) {
+    server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+        resources: [
+            {
+                uri: `memory://summary`,
+                name: 'Memory Summary',
+                description: 'Current state of the memory system',
+                mimeType: 'text/plain',
+            },
+            {
+                uri: `memory://entities`,
+                name: 'Entity List',
+                description: 'All known entities in the memory system',
+                mimeType: 'application/json',
+            },
+            {
+                uri: `memory://context`,
+                name: 'Current Context',
+                description: 'Recent facts and entities from memory',
+                mimeType: 'text/markdown',
+            },
+        ],
+    }));
+    server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+        const uri = request.params.uri;
+        try {
+            // Get project ID (may throw if not configured)
+            const projectId = getDefaultProjectId();
+            if (uri === 'memory://summary') {
+                const summary = await getSummary(projectId);
+                return {
+                    contents: [
+                        {
+                            uri,
+                            mimeType: 'text/plain',
+                            text: summary,
+                        },
+                    ],
+                };
+            }
+            if (uri === 'memory://entities') {
+                const entities = await getEntities(projectId);
+                return {
+                    contents: [
+                        {
+                            uri,
+                            mimeType: 'application/json',
+                            text: JSON.stringify(entities, null, 2),
+                        },
+                    ],
+                };
+            }
+            if (uri === 'memory://context') {
+                const context = await getContext(projectId);
+                return {
+                    contents: [
+                        {
+                            uri,
+                            mimeType: 'text/markdown',
+                            text: formatContextForClaude(context),
+                        },
+                    ],
+                };
+            }
+            throw new Error(`Unknown resource: ${uri}`);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : 'Unknown error';
+            throw new Error(`Failed to read resource: ${message}`);
+        }
+    });
+}

package/dist/setup.d.ts

@@ -0,0 +1 @@
+export declare function runSetup(): Promise<void>;