@claudetools/tools 0.1.0

package/dist/helpers/tasks.js

@@ -0,0 +1,274 @@
+// =============================================================================
+// Task Management System
+// =============================================================================
+import { apiRequest } from './api-client.js';
+import { matchTaskToWorker } from './workers.js';
+export function parseJsonArray(value) {
+    if (!value)
+        return [];
+    if (Array.isArray(value))
+        return value;
+    if (typeof value === 'string') {
+        try {
+            const parsed = JSON.parse(value);
+            return Array.isArray(parsed) ? parsed : [];
+        }
+        catch {
+            return [];
+        }
+    }
+    return [];
+}
+export async function createTask(userId, projectId, taskData) {
+    // Filter out undefined values to avoid sending them to API
+    const cleanTaskData = {};
+    for (const [key, value] of Object.entries(taskData)) {
+        if (value !== undefined) {
+            cleanTaskData[key] = value;
+        }
+    }
+    return apiRequest(`/api/v1/tasks/${userId}/${projectId}`, 'POST', cleanTaskData);
+}
+export async function listTasks(userId, projectId, filters) {
+    const params = new URLSearchParams();
+    if (filters?.type)
+        params.set('type', filters.type);
+    if (filters?.status)
+        params.set('status', filters.status);
+    if (filters?.parent_id)
+        params.set('parent_id', filters.parent_id);
+    if (filters?.assigned_to)
+        params.set('assigned_to', filters.assigned_to);
+    if (filters?.limit)
+        params.set('limit', String(filters.limit));
+    if (filters?.offset)
+        params.set('offset', String(filters.offset));
+    const queryString = params.toString();
+    const url = `/api/v1/tasks/${userId}/${projectId}${queryString ? `?${queryString}` : ''}`;
+    return apiRequest(url);
+}
+export async function getTask(userId, projectId, taskId, full = false) {
+    const endpoint = full ? 'full' : '';
+    return apiRequest(`/api/v1/tasks/${userId}/${projectId}/${taskId}${endpoint ? `/${endpoint}` : ''}`);
+}
+export async function claimTask(userId, projectId, taskId, agentId, lockDurationMinutes = 30) {
+    return apiRequest(`/api/v1/tasks/${userId}/${projectId}/${taskId}/claim`, 'POST', {
+        agent_id: agentId,
+        lock_duration_minutes: lockDurationMinutes,
+    });
+}
+export async function releaseTask(userId, projectId, taskId, agentId, newStatus, workLog) {
+    return apiRequest(`/api/v1/tasks/${userId}/${projectId}/${taskId}/release`, 'POST', {
+        agent_id: agentId,
+        new_status: newStatus,
+        work_log: workLog,
+    });
+}
+export async function updateTaskStatus(userId, projectId, taskId, status, agentId) {
+    return apiRequest(`/api/v1/tasks/${userId}/${projectId}/${taskId}/status`, 'POST', {
+        status,
+        agent_id: agentId,
+    });
+}
+export async function addTaskContext(userId, projectId, taskId, contextType, content, addedBy, source) {
+    return apiRequest(`/api/v1/tasks/${userId}/${projectId}/${taskId}/context`, 'POST', {
+        context_type: contextType,
+        content,
+        added_by: addedBy,
+        source,
+    });
+}
+export async function getTaskSummary(userId, projectId) {
+    return apiRequest(`/api/v1/tasks/${userId}/${projectId}/summary`);
+}
+export async function heartbeatTask(userId, projectId, taskId, agentId, extendMinutes = 30) {
+    return apiRequest(`/api/v1/tasks/${userId}/${projectId}/${taskId}/heartbeat`, 'POST', {
+        agent_id: agentId,
+        extend_minutes: extendMinutes,
+    });
+}
+// -----------------------------------------------------------------------------
+// Orchestration Functions
+// -----------------------------------------------------------------------------
+/**
+ * Get all tasks ready for parallel dispatch
+ * - Filters for 'ready' status
+ * - Excludes already claimed tasks
+ * - Resolves dependencies (only returns unblocked tasks)
+ * - Matches each to appropriate expert worker
+ */
+export async function getDispatchableTasks(userId, projectId, epicId, maxParallel = 5) {
+    // Get all tasks with 'ready' status
+    const result = await listTasks(userId, projectId, {
+        status: 'ready',
+        parent_id: epicId,
+        limit: 50,
+    });
+    if (!result.success || !result.data.length) {
+        return [];
+    }
+    const dispatchable = [];
+    for (const task of result.data) {
+        // Skip if already claimed (has lock)
+        if (task.assigned_to && task.lock_expires_at) {
+            const lockExpires = new Date(task.lock_expires_at);
+            if (lockExpires > new Date()) {
+                continue; // Still locked
+            }
+        }
+        // Check dependencies (blocked_by)
+        const blockedBy = parseJsonArray(task.blocked_by);
+        if (blockedBy.length > 0) {
+            // Check if blocking tasks are done
+            let allBlockersComplete = true;
+            for (const blockerId of blockedBy) {
+                const blockerResult = await getTask(userId, projectId, blockerId);
+                if (blockerResult.success) {
+                    const blocker = blockerResult.data;
+                    if (blocker.status !== 'done') {
+                        allBlockersComplete = false;
+                        break;
+                    }
+                }
+            }
+            if (!allBlockersComplete) {
+                continue; // Still blocked
+            }
+        }
+        // Match to expert worker
+        const worker = matchTaskToWorker({
+            title: task.title,
+            description: task.description || undefined,
+            domain: task.domain || undefined,
+            tags: parseJsonArray(task.tags),
+        });
+        // Get task context
+        const fullTask = await getTask(userId, projectId, task.id, true);
+        const taskData = fullTask.data;
+        dispatchable.push({
+            task,
+            worker,
+            context: taskData.context || [],
+            parentContext: taskData.parent,
+            dependencies: [],
+        });
+        if (dispatchable.length >= maxParallel) {
+            break;
+        }
+    }
+    return dispatchable;
+}
+/**
+ * Get full execution context for a worker agent
+ */
+export async function getExecutionContext(userId, projectId, taskId) {
+    // Get full task data
+    const result = await getTask(userId, projectId, taskId, true);
+    if (!result.success) {
+        throw new Error(`Task not found: ${taskId}`);
+    }
+    const taskData = result.data;
+    const task = taskData.task;
+    // Match to worker
+    const worker = matchTaskToWorker({
+        title: task.title,
+        description: task.description || undefined,
+        domain: task.domain || undefined,
+        tags: parseJsonArray(task.tags),
+    });
+    // Get sibling tasks for context
+    let siblingTasks;
+    if (task.parent_id) {
+        const siblingResult = await listTasks(userId, projectId, { parent_id: task.parent_id, limit: 20 });
+        if (siblingResult.success) {
+            siblingTasks = siblingResult.data.filter(t => t.id !== taskId);
+        }
+    }
+    // Build system prompt
+    let systemPrompt = worker.promptTemplate + '\n\n';
+    systemPrompt += `# Task: ${task.title}\n\n`;
+    if (task.description) {
+        systemPrompt += `## Description\n${task.description}\n\n`;
+    }
+    // Add acceptance criteria
+    const criteria = parseJsonArray(task.acceptance_criteria);
+    if (criteria.length > 0) {
+        systemPrompt += `## Acceptance Criteria\n`;
+        criteria.forEach((c, i) => {
+            systemPrompt += `${i + 1}. ${c}\n`;
+        });
+        systemPrompt += '\n';
+    }
+    // Add parent context
+    if (taskData.parent) {
+        systemPrompt += `## Epic Context\n`;
+        systemPrompt += `**Epic:** ${taskData.parent.title}\n`;
+        if (taskData.parent.description) {
+            systemPrompt += `**Goal:** ${taskData.parent.description}\n`;
+        }
+        systemPrompt += '\n';
+    }
+    // Add attached context
+    if (taskData.context.length > 0) {
+        systemPrompt += `## Attached Context\n`;
+        for (const ctx of taskData.context) {
+            systemPrompt += `### ${ctx.context_type.toUpperCase()}${ctx.source ? ` (${ctx.source})` : ''}\n`;
+            systemPrompt += `${ctx.content}\n\n`;
+        }
+    }
+    // Add sibling task awareness
+    if (siblingTasks && siblingTasks.length > 0) {
+        systemPrompt += `## Related Tasks (for awareness)\n`;
+        for (const sibling of siblingTasks.slice(0, 5)) {
+            systemPrompt += `- ${sibling.title} [${sibling.status}]\n`;
+        }
+        systemPrompt += '\n';
+    }
+    return {
+        task,
+        worker,
+        systemPrompt,
+        context: taskData.context,
+        parentTask: taskData.parent,
+        siblingTasks,
+    };
+}
+/**
+ * Find newly unblocked tasks after a completion
+ */
+export async function resolveTaskDependencies(userId, projectId, completedTaskId, epicId) {
+    // Get all tasks that might be blocked by the completed task
+    const result = await listTasks(userId, projectId, {
+        status: 'ready', // or 'blocked'
+        parent_id: epicId,
+        limit: 50,
+    });
+    if (!result.success) {
+        return [];
+    }
+    const newlyUnblocked = [];
+    for (const task of result.data) {
+        const blockedBy = parseJsonArray(task.blocked_by);
+        // Check if this task was blocked by the completed task
+        if (blockedBy.includes(completedTaskId)) {
+            // Check if all other blockers are also done
+            let allBlockersComplete = true;
+            for (const blockerId of blockedBy) {
+                if (blockerId === completedTaskId)
+                    continue; // Already done
+                const blockerResult = await getTask(userId, projectId, blockerId);
+                if (blockerResult.success) {
+                    const blocker = blockerResult.data;
+                    if (blocker.status !== 'done') {
+                        allBlockersComplete = false;
+                        break;
+                    }
+                }
+            }
+            if (allBlockersComplete) {
+                newlyUnblocked.push(task);
+            }
+        }
+    }
+    return newlyUnblocked;
+}

package/dist/helpers/workers.d.ts

@@ -0,0 +1,18 @@
+export interface ExpertWorker {
+    id: string;
+    name: string;
+    description: string;
+    domains: string[];
+    capabilities: string[];
+    promptTemplate: string;
+}
+export declare const EXPERT_WORKERS: Record<string, ExpertWorker>;
+/**
+ * Match a task to the best expert worker based on domain patterns
+ */
+export declare function matchTaskToWorker(task: {
+    title: string;
+    description?: string;
+    domain?: string;
+    tags?: string[];
+}): ExpertWorker;

package/dist/helpers/workers.js

@@ -0,0 +1,146 @@
+// =============================================================================
+// Expert Worker Definitions (Orchestration System)
+// =============================================================================
+export const EXPERT_WORKERS = {
+    'schema-expert': {
+        id: 'schema-expert',
+        name: 'Database Schema Expert',
+        description: 'Specialises in database schema design, migrations, SQL, and data modelling',
+        domains: ['**/schema/**', '**/*.sql', '**/migrations/**', '**/models/**'],
+        capabilities: ['schema-design', 'sql-queries', 'migrations', 'indexing', 'data-modelling'],
+        promptTemplate: `You are a database schema expert. Your domain is limited to:
+- SQL schema files and migrations
+- Database table design and relationships
+- Index optimisation
+- Data modelling decisions
+
+Focus only on schema-related changes. Do not modify application code outside your domain.
+When complete, provide a concise summary of changes made.`,
+    },
+    'api-expert': {
+        id: 'api-expert',
+        name: 'API & Routes Expert',
+        description: 'Specialises in HTTP endpoints, route handlers, request/response handling',
+        domains: ['**/routes/**', '**/api/**', '**/handlers/**', '**/controllers/**'],
+        capabilities: ['rest-api', 'route-handlers', 'validation', 'error-handling', 'http-methods'],
+        promptTemplate: `You are an API and routes expert. Your domain is limited to:
+- HTTP route definitions and handlers
+- Request validation and parsing
+- Response formatting
+- Error handling for endpoints
+- API documentation
+
+Focus only on API-related changes. Do not modify schema or extraction code.
+When complete, provide a concise summary of endpoints created or modified.`,
+    },
+    'mcp-expert': {
+        id: 'mcp-expert',
+        name: 'MCP Server Expert',
+        description: 'Specialises in MCP tool definitions, handlers, and server configuration',
+        domains: ['**/mcp-server/**', '**/mcp/**', '**/*mcp*.ts'],
+        capabilities: ['mcp-tools', 'mcp-handlers', 'tool-definitions', 'mcp-resources'],
+        promptTemplate: `You are an MCP (Model Context Protocol) expert. Your domain is limited to:
+- MCP tool definitions and schemas
+- Tool handler implementations
+- MCP resources and prompts
+- Server configuration
+
+Focus only on MCP-related changes. Follow MCP SDK patterns exactly.
+When complete, provide a concise summary of tools added or modified.`,
+    },
+    'extraction-expert': {
+        id: 'extraction-expert',
+        name: 'Code Extraction Expert',
+        description: 'Specialises in AST parsing, code analysis, and fact extraction',
+        domains: ['**/extraction/**', '**/parsers/**', '**/analyzers/**', '**/*extractor*.ts'],
+        capabilities: ['ast-parsing', 'code-analysis', 'fact-extraction', 'language-support'],
+        promptTemplate: `You are a code extraction expert. Your domain is limited to:
+- AST parsing and traversal
+- Code pattern recognition
+- Fact and relationship extraction
+- Multi-language support
+
+Focus only on extraction logic. Follow the BaseExtractor pattern.
+When complete, provide a concise summary of extraction capabilities added.`,
+    },
+    'integration-expert': {
+        id: 'integration-expert',
+        name: 'Integration Expert',
+        description: 'Specialises in connecting systems, wiring components, and configuration',
+        domains: ['**/config/**', '**/index.ts', '**/main.ts', '**/wrangler.toml', '**/*.json'],
+        capabilities: ['system-integration', 'configuration', 'wiring', 'dependency-injection'],
+        promptTemplate: `You are an integration expert. Your domain is limited to:
+- Connecting components and systems
+- Configuration files and environment setup
+- Import/export wiring
+- Dependency management
+
+Focus on integration without modifying core implementation logic.
+When complete, provide a concise summary of integrations configured.`,
+    },
+    'general-expert': {
+        id: 'general-expert',
+        name: 'General Purpose Expert',
+        description: 'Handles tasks that do not fit other expert domains',
+        domains: ['**/*'],
+        capabilities: ['general-development', 'refactoring', 'documentation', 'testing'],
+        promptTemplate: `You are a general purpose development expert. Handle this task with care:
+- Follow existing code patterns
+- Make minimal necessary changes
+- Document your reasoning
+
+When complete, provide a concise summary of work done.`,
+    },
+};
+/**
+ * Match a task to the best expert worker based on domain patterns
+ */
+export function matchTaskToWorker(task) {
+    // If task has explicit domain pattern, match against worker domains
+    if (task.domain) {
+        for (const [_, worker] of Object.entries(EXPERT_WORKERS)) {
+            if (worker.id === 'general-expert')
+                continue; // Skip fallback
+            for (const pattern of worker.domains) {
+                // Simple glob matching - convert ** to regex
+                const regex = new RegExp(pattern
+                    .replace(/\*\*/g, '.*')
+                    .replace(/\*/g, '[^/]*')
+                    .replace(/\//g, '\\/'));
+                if (regex.test(task.domain)) {
+                    return worker;
+                }
+            }
+        }
+    }
+    // Keyword-based matching from title and description
+    const searchText = `${task.title} ${task.description || ''} ${(task.tags || []).join(' ')}`.toLowerCase();
+    const keywordMap = {
+        'schema': 'schema-expert',
+        'database': 'schema-expert',
+        'sql': 'schema-expert',
+        'migration': 'schema-expert',
+        'table': 'schema-expert',
+        'api': 'api-expert',
+        'route': 'api-expert',
+        'endpoint': 'api-expert',
+        'handler': 'api-expert',
+        'http': 'api-expert',
+        'mcp': 'mcp-expert',
+        'tool': 'mcp-expert',
+        'extraction': 'extraction-expert',
+        'extractor': 'extraction-expert',
+        'ast': 'extraction-expert',
+        'parser': 'extraction-expert',
+        'integration': 'integration-expert',
+        'config': 'integration-expert',
+        'wiring': 'integration-expert',
+    };
+    for (const [keyword, workerId] of Object.entries(keywordMap)) {
+        if (searchText.includes(keyword)) {
+            return EXPERT_WORKERS[workerId];
+        }
+    }
+    // Fallback to general expert
+    return EXPERT_WORKERS['general-expert'];
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export type { ExpertWorker } from './helpers/workers.js';
+export type { Task, TaskContext, DispatchableTask } from './helpers/tasks.js';
+export { EXPERT_WORKERS, matchTaskToWorker } from './helpers/workers.js';
+export { parseJsonArray, getDispatchableTasks, getExecutionContext, resolveTaskDependencies, createTask, listTasks, getTask, claimTask, releaseTask, updateTaskStatus, addTaskContext, getTaskSummary, heartbeatTask } from './helpers/tasks.js';
+export { injectContext } from './helpers/api-client.js';
+export declare function startServer(): Promise<void>;

package/dist/index.js

@@ -0,0 +1,75 @@
+// =============================================================================
+// ClaudeTools Memory MCP Server - Main Entry Point
+// =============================================================================
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { mcpLogger } from './logger.js';
+import { API_BASE_URL, getDefaultProjectIdAsync, AUTO_INJECT_CONTEXT, } from './helpers/config.js';
+// Tool definitions and handlers
+import { registerToolDefinitions } from './tools.js';
+import { registerToolHandlers } from './handlers/tool-handlers.js';
+// Resource and prompt handlers
+import { registerResourceHandlers } from './resources.js';
+import { registerPromptHandlers } from './prompts.js';
+// Re-export functions that are used by handlers
+export { EXPERT_WORKERS, matchTaskToWorker } from './helpers/workers.js';
+export { parseJsonArray, getDispatchableTasks, getExecutionContext, resolveTaskDependencies, createTask, listTasks, getTask, claimTask, releaseTask, updateTaskStatus, addTaskContext, getTaskSummary, heartbeatTask } from './helpers/tasks.js';
+export { injectContext } from './helpers/api-client.js';
+// =============================================================================
+// Server Initialization
+// =============================================================================
+const server = new Server({
+    name: 'claudetools-memory',
+    version: '1.0.0',
+}, {
+    capabilities: {
+        tools: {},
+        resources: {},
+        prompts: {},
+    },
+});
+// =============================================================================
+// Request Handler Registration
+// =============================================================================
+// Tools
+registerToolDefinitions(server);
+registerToolHandlers(server);
+// Resources
+registerResourceHandlers(server);
+// Prompts
+registerPromptHandlers(server);
+// =============================================================================
+// Server Start
+// =============================================================================
+export async function startServer() {
+    mcpLogger.separator('MCP Server Starting');
+    // Resolve project ID asynchronously (may auto-register)
+    let projectId;
+    try {
+        projectId = await getDefaultProjectIdAsync();
+        mcpLogger.info('TOOL', `Project ID resolved: ${projectId}`);
+    }
+    catch (error) {
+        mcpLogger.error('TOOL', `Failed to resolve project ID: ${error}`);
+        mcpLogger.warn('TOOL', 'Continuing startup - tools will fail until project is registered');
+        projectId = 'not-configured';
+    }
+    mcpLogger.info('TOOL', 'ClaudeTools Memory MCP Server v1.0.0', {
+        autoInject: AUTO_INJECT_CONTEXT,
+        apiUrl: API_BASE_URL,
+        projectId,
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    mcpLogger.info('TOOL', 'Server connected via stdio');
+    console.error(`ClaudeTools Memory MCP server running on stdio (auto-inject: ${AUTO_INJECT_CONTEXT ? 'enabled' : 'disabled'})`);
+}
+// Only run if this file is executed directly (not imported)
+// This check doesn't work reliably in ESM, so we'll rely on cli.ts
+// But we keep this for backward compatibility when running index.ts directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+    startServer().catch((error) => {
+        console.error('Fatal error:', error);
+        process.exit(1);
+    });
+}

package/dist/logger.d.ts

@@ -0,0 +1,32 @@
+export type LogCategory = 'TOOL' | 'API' | 'MEMORY' | 'SEARCH' | 'INJECT' | 'EXTRACT' | 'STORE' | 'QUERY' | 'IMPACT' | 'PATTERN' | 'CONFIG' | 'REGISTRATION' | 'ERROR';
+declare class MCPLogger {
+    private logFile;
+    private logDir;
+    private enabled;
+    constructor();
+    private formatTimestamp;
+    private formatForFile;
+    private formatDataAsNaturalLanguage;
+    private write;
+    debug(category: LogCategory, message: string, data?: Record<string, unknown>): void;
+    info(category: LogCategory, message: string, data?: Record<string, unknown>): void;
+    warn(category: LogCategory, message: string, data?: Record<string, unknown>): void;
+    error(category: LogCategory, message: string, error?: unknown): void;
+    toolCall(toolName: string, args: Record<string, unknown>): void;
+    toolResult(toolName: string, success: boolean, duration: number, resultSummary?: string): void;
+    apiRequest(method: string, endpoint: string): void;
+    apiResponse(method: string, endpoint: string, status: number, duration: number): void;
+    searchQuery(query: string, method: string): void;
+    searchResults(factsFound: number, entitiesFound: number, duration: number): void;
+    memoryStore(entity1: string, relation: string, entity2: string): void;
+    queryDependencies(functionName: string, direction: string, resultsCount: number, duration: number): void;
+    impactAnalysis(functionName: string, analysisType: string, riskLevel: string, totalAffected: number, duration: number): void;
+    patternCheck(codeLength: number, warningsFound: number, securityScore: number, perfScore: number, duration: number): void;
+    contextInjection(query: string, factsIncluded: number, tokenBudget: number, duration: number): void;
+    private sanitizeArgs;
+    startTimer(): () => number;
+    separator(label?: string): void;
+    clear(): void;
+}
+export declare const mcpLogger: MCPLogger;
+export {};