mcp-adr-analysis-server
Version:
MCP server for analyzing Architectural Decision Records and project architecture
297 lines • 9.55 kB
TypeScript
/**
* 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