mcp-adr-analysis-server 2.1.20 → 2.1.27

package/dist/src/utils/research-task-integration.d.ts

@@ -0,0 +1,297 @@
+/**
+ * MCP Tasks Integration for Research Orchestrator
+ *
+ * This module provides standardized task tracking for research operations,
+ * implementing ADR-020: MCP Tasks Integration Strategy.
+ *
+ * Key features:
+ * - Creates MCP Tasks for research operations
+ * - Returns research plans for LLM delegation (non-blocking)
+ * - Tracks progress through research phases
+ * - Supports cancellation between phases
+ *
+ * @see ADR-020: MCP Tasks Integration Strategy
+ * @see https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/tasks
+ */
+import { type AdrTask, type TaskResult, type TaskManager } from './task-manager.js';
+/**
+ * Research phases that map to MCP Task phases
+ */
+export declare const RESEARCH_PHASES: readonly ["initialization", "project_files_search", "knowledge_graph_query", "environment_analysis", "web_search", "synthesis"];
+export type ResearchPhase = (typeof RESEARCH_PHASES)[number];
+/**
+ * Research task context for tracking state across research steps
+ */
+export interface ResearchTaskContext {
+    taskId: string;
+    currentPhase: ResearchPhase;
+    question: string;
+    projectPath: string;
+    cancelled: boolean;
+    projectFilesResult?: {
+        filesFound: number;
+        relevantFiles: string[];
+        confidence: number;
+    };
+    knowledgeGraphResult?: {
+        nodesFound: number;
+        relationshipsFound: number;
+        confidence: number;
+    };
+    environmentResult?: {
+        capabilitiesFound: number;
+        relevantData: Record<string, unknown>;
+        confidence: number;
+    };
+    webSearchResult?: {
+        resultsFound: number;
+        sources: string[];
+        confidence: number;
+    };
+    synthesizedAnswer?: string;
+    overallConfidence?: number;
+}
+/**
+ * Options for creating a research task
+ */
+export interface CreateResearchTaskOptions {
+    question: string;
+    projectPath: string;
+    includeWebSearch?: boolean;
+    confidenceThreshold?: number;
+}
+/**
+ * Result from research task execution
+ */
+export interface ResearchTaskResult extends TaskResult {
+    data?: {
+        answer: string;
+        confidence: number;
+        sources: ResearchSource[];
+        phasesCompleted: ResearchPhase[];
+    };
+}
+/**
+ * Research source from a phase
+ */
+export interface ResearchSource {
+    type: 'project_files' | 'knowledge_graph' | 'environment' | 'web_search';
+    confidence: number;
+    data: unknown;
+    timestamp: string;
+}
+/**
+ * Research plan phase - describes a tool to execute
+ */
+export interface ResearchPlanPhase {
+    phase: ResearchPhase;
+    tool: string;
+    params: Record<string, unknown>;
+    purpose: string;
+    condition?: string;
+    expectedOutput: string;
+}
+/**
+ * Research plan returned for LLM delegation
+ */
+export interface ResearchPlan {
+    taskId: string;
+    question: string;
+    phases: ResearchPlanPhase[];
+    synthesisInstructions: string;
+    expectedResultFormat: string;
+}
+/**
+ * Research Task Manager - Provides MCP Tasks integration for research operations
+ *
+ * This class wraps the TaskManager to provide research-specific functionality:
+ * - Creates tasks with research phases
+ * - Returns research plans for LLM delegation (non-blocking)
+ * - Tracks research progress through multiple phases
+ * - Supports cancellation between phases
+ */
+export declare class ResearchTaskManager {
+    private taskManager;
+    private activeContexts;
+    constructor(taskManager?: TaskManager);
+    /**
+     * Initialize the research task manager
+     */
+    initialize(): Promise<void>;
+    /**
+     * Create a new research task and return a research plan for LLM delegation
+     *
+     * This method does NOT execute research - it returns a plan that the calling
+     * LLM should execute using atomic tools.
+     *
+     * @returns The created task, context, and research plan for LLM delegation
+     */
+    createResearchTask(options: CreateResearchTaskOptions): Promise<{
+        task: AdrTask;
+        context: ResearchTaskContext;
+        plan: ResearchPlan;
+    }>;
+    /**
+     * Generate a research plan for LLM delegation
+     *
+     * This creates a structured plan that tells the calling LLM what tools
+     * to use and in what order to complete the research.
+     */
+    private generateResearchPlan;
+    /**
+     * Get research task context
+     */
+    getContext(taskId: string): ResearchTaskContext | undefined;
+    /**
+     * Start a research phase
+     */
+    startPhase(taskId: string, phase: ResearchPhase, message?: string): Promise<void>;
+    /**
+     * Update phase progress
+     */
+    updatePhaseProgress(taskId: string, phase: ResearchPhase, phaseProgress: number, message?: string): Promise<void>;
+    /**
+     * Complete a research phase
+     */
+    completePhase(taskId: string, phase: ResearchPhase, _message?: string): Promise<void>;
+    /**
+     * Fail a research phase
+     */
+    failPhase(taskId: string, phase: ResearchPhase, error: string): Promise<void>;
+    /**
+     * Store project files search result
+     */
+    storeProjectFilesResult(taskId: string, result: {
+        filesFound: number;
+        relevantFiles: string[];
+        confidence: number;
+    }): Promise<void>;
+    /**
+     * Store knowledge graph query result
+     */
+    storeKnowledgeGraphResult(taskId: string, result: {
+        nodesFound: number;
+        relationshipsFound: number;
+        confidence: number;
+    }): Promise<void>;
+    /**
+     * Store environment analysis result
+     */
+    storeEnvironmentResult(taskId: string, result: {
+        capabilitiesFound: number;
+        relevantData: Record<string, unknown>;
+        confidence: number;
+    }): Promise<void>;
+    /**
+     * Store web search result
+     */
+    storeWebSearchResult(taskId: string, result: {
+        resultsFound: number;
+        sources: string[];
+        confidence: number;
+    }): Promise<void>;
+    /**
+     * Store synthesized answer
+     */
+    storeSynthesizedAnswer(taskId: string, answer: string, confidence: number): Promise<void>;
+    /**
+     * Check if task is cancelled
+     */
+    isCancelled(taskId: string): Promise<boolean>;
+    /**
+     * Cancel a research task
+     */
+    cancelTask(taskId: string, reason?: string): Promise<void>;
+    /**
+     * Complete a research task successfully
+     */
+    completeTask(taskId: string, result: ResearchTaskResult): Promise<void>;
+    /**
+     * Fail a research task
+     */
+    failTask(taskId: string, error: string): Promise<void>;
+    /**
+     * Get task status
+     */
+    getTaskStatus(taskId: string): Promise<{
+        task: AdrTask | null;
+        context: ResearchTaskContext | undefined;
+    }>;
+}
+export declare function getResearchTaskManager(): ResearchTaskManager;
+/**
+ * Reset the global ResearchTaskManager (for testing)
+ */
+export declare function resetResearchTaskManager(): Promise<void>;
+/**
+ * Helper function to create a research task and get the LLM delegation plan
+ *
+ * This is the primary entry point for research operations. It:
+ * 1. Creates an MCP Task for tracking
+ * 2. Returns a research plan for the calling LLM to execute
+ * 3. The LLM executes each phase using atomic tools
+ * 4. The LLM reports progress back via the tracker interface
+ *
+ * @example
+ * ```typescript
+ * const { taskId, plan, tracker } = await createResearchWithDelegation({
+ *   question: 'How does authentication work in this codebase?',
+ *   projectPath: '/path/to/project',
+ * });
+ *
+ * // LLM receives the plan and executes each phase:
+ * // Phase 1: searchCodebase({ query: question, ... })
+ * // Phase 2: query_knowledge_graph({ question, ... })
+ * // etc.
+ *
+ * // After each phase, LLM reports progress:
+ * await tracker.storeProjectFilesResult({ filesFound: 10, ... });
+ * await tracker.completePhase('project_files_search');
+ *
+ * // Finally, LLM synthesizes and completes:
+ * await tracker.storeSynthesizedAnswer(answer, confidence);
+ * await tracker.complete({ success: true, data: { answer, ... } });
+ * ```
+ */
+export declare function createResearchWithDelegation(options: CreateResearchTaskOptions): Promise<{
+    taskId: string;
+    plan: ResearchPlan;
+    tracker: ResearchTaskTracker;
+}>;
+/**
+ * Task tracker interface provided to LLM for research execution
+ */
+export interface ResearchTaskTracker {
+    taskId: string;
+    startPhase: (phase: ResearchPhase, message?: string) => Promise<void>;
+    updatePhaseProgress: (phase: ResearchPhase, progress: number, message?: string) => Promise<void>;
+    completePhase: (phase: ResearchPhase, message?: string) => Promise<void>;
+    failPhase: (phase: ResearchPhase, error: string) => Promise<void>;
+    storeProjectFilesResult: (result: {
+        filesFound: number;
+        relevantFiles: string[];
+        confidence: number;
+    }) => Promise<void>;
+    storeKnowledgeGraphResult: (result: {
+        nodesFound: number;
+        relationshipsFound: number;
+        confidence: number;
+    }) => Promise<void>;
+    storeEnvironmentResult: (result: {
+        capabilitiesFound: number;
+        relevantData: Record<string, unknown>;
+        confidence: number;
+    }) => Promise<void>;
+    storeWebSearchResult: (result: {
+        resultsFound: number;
+        sources: string[];
+        confidence: number;
+    }) => Promise<void>;
+    storeSynthesizedAnswer: (answer: string, confidence: number) => Promise<void>;
+    isCancelled: () => Promise<boolean>;
+    cancel: (reason?: string) => Promise<void>;
+    complete: (result: ResearchTaskResult) => Promise<void>;
+    fail: (error: string) => Promise<void>;
+    getContext: () => ResearchTaskContext;
+}
+//# sourceMappingURL=research-task-integration.d.ts.map

package/dist/src/utils/research-task-integration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"research-task-integration.d.ts","sourceRoot":"","sources":["../../../src/utils/research-task-integration.ts"],"names":[],"mappings":"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"}