Project Tracker MCP Server

Instructions

Implementation Reference

• src/mcp/tools/index.ts:13-16 (registration)

  Registration of the 'Risk Assessment' tool in the mcpTools array, imported from './risk_assessment' and exported for use by the MCP server.

  import { riskAssessmentTool } from './risk_assessment';
  
  // EXPANSION: Consolidated tool registry for MCP server
  export const mcpTools = [naturalLanguageQueryTool, workloadAnalysisTool, riskAssessmentTool];

• src/mcp/tools/risk_assessment.ts:673-678 (schema)

  Zod input schema defining the required 'projectId' parameter for the tool.

  parameters: z.object({
    projectId: z
      .string()
      .min(1, 'Project ID is required')
      .max(50, 'Project ID too long')
      .describe('Project ID to assess (e.g., "project-1", "alpha-initiative")'),

• src/mcp/tools/risk_assessment.ts:680-754 (handler)

  The MCP tool handler function that instantiates RiskAssessmentProcessor, calls assessProjectRisk, formats the response as MCP content, and handles errors.

  handler: async ({ projectId }: { projectId: string }) => {
    try {
      const processor = new RiskAssessmentProcessor(process.env.MCP_DEBUG_MODE === 'true');
      const assessment = await processor.assessProjectRisk(projectId);
  
      // SAFETY: Ensure assessment is valid
      if (!assessment) {
        throw new Error('Risk assessment returned null or undefined');
      }
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(
              {
                project_id: assessment.projectId || projectId,
                project_name: assessment.projectName || projectId,
                summary: `${assessment.projectName || projectId}: ${assessment.riskLevel || 'UNKNOWN'} risk (${assessment.riskScore || 0}/100)`,
                risk_level: assessment.riskLevel || 'MEDIUM',
                risk_score: assessment.riskScore || 0,
                progress: assessment.progress || 0,
                overdue_tasks: assessment.overdueTasks || 0,
                blocked_tasks: assessment.blockedTasks || 0,
                risk_breakdown: assessment.riskBreakdown || {
                  schedule: 0,
                  resource: 0,
                  scope: 0,
                  quality: 0,
                  dependencies: 0,
                },
                patterns_detected: (assessment.patterns || []).length,
                trend: assessment.trend || {
                  direction: 'STABLE',
                  velocity: 0,
                  forecastedRisk: 0,
                  trendFactors: [],
                },
                early_warnings: assessment.earlyWarnings || [],
                insights: assessment.insights || [],
                recommendations: assessment.recommendations || [],
                mitigation_strategies: assessment.mitigationStrategies || [],
                monitoring_recommendations: assessment.monitoringRecommendations || [],
                requires_attention:
                  (assessment.riskScore || 0) > 70 || (assessment.earlyWarnings || []).length > 0,
              },
              null,
              2,
            ),
          },
        ],
      };
    } catch (error) {
      console.error(`[RiskAssessment] Handler failed:`, error);
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(
              {
                project_id: projectId,
                project_name: projectId,
                success: false,
                error: (error as Error).message,
                summary: `Failed to assess risk for ${projectId}`,
                insights: ['Risk assessment unavailable'],
                recommendations: ['Check system connectivity and project ID validity'],
              },
              null,
              2,
            ),
          },
        ],
      };
    }

• src/mcp/tools/risk_assessment.ts:84-128 (helper)

  Core helper method in RiskAssessmentProcessor class that performs the comprehensive risk assessment logic including caching, API calls, pattern detection, trend analysis, and enhancement.

  async assessProjectRisk(projectId: string): Promise<EnhancedRiskAssessment> {
    const startTime = Date.now();
  
    try {
      this.debug(`Assessing risk for project: ${projectId}`);
  
      // CACHE: Check for recent assessment
      const cacheKey = `risk:assessment:${projectId}`;
      let cachedAssessment = await CacheService.get<EnhancedRiskAssessment>(cacheKey);
  
      if (cachedAssessment) {
        this.debug(`Retrieved cached risk assessment for ${projectId}`);
        return cachedAssessment;
      }
  
      // Stage 1: Get base risk assessment
      const baseAssessment = await this.apiClient.getRiskAssessment(projectId);
  
      // Stage 2: Enhance with pattern detection
      const enhancedAssessment = await this.enhanceRiskAssessment(baseAssessment);
  
      // Stage 3: Add trend analysis
      enhancedAssessment.trend = await this.analyzeTrend(enhancedAssessment);
  
      // Stage 4: Detect risk patterns
      enhancedAssessment.patterns = await this.detectRiskPatterns(enhancedAssessment);
  
      // Stage 5: Generate early warnings
      enhancedAssessment.earlyWarnings = this.generateEarlyWarnings(enhancedAssessment);
  
      // Stage 6: Add comparative analysis
      enhancedAssessment.comparison = await this.generateProjectComparison(enhancedAssessment);
  
      // CACHE: Store enhanced assessment
      await CacheService.set(cacheKey, enhancedAssessment, this.RISK_CACHE_TTL);
  
      const processingTime = Date.now() - startTime;
      this.debug(`Risk assessment completed for ${projectId} in ${processingTime}ms`);
  
      return enhancedAssessment;
    } catch (error) {
      this.debug(`Risk assessment failed for ${projectId}: ${error}`);
      throw error;
    }
  }