get_project_insights

Instructions

Implementation Reference

• src/tools/context-aggregation.ts:259-305 (handler)

  Handler function that parses args, fetches project data via supabaseService, runs each requested insight type (progress, bottlenecks, team_performance, documentation_health, ai_readiness), optionally generates recommendations, and returns an overall health score.

  export const getProjectInsights = requireAuth(async (args: any) => {
    const { project_id, insight_types, include_recommendations } = GetProjectInsightsSchema.parse(args)
    
    logger.info('Getting project insights', { project_id, insight_types })
  
    const project = await supabaseService.getProject(project_id)
    const projectContext = await supabaseService.getProjectContext(project_id)
  
    const insights: any = {
      project_overview: {
        id: project.id,
        name: project.name,
        status: project.status,
        created_at: project.created_at,
        updated_at: project.updated_at
      }
    }
  
    // Generate requested insights
    for (const insightType of insight_types) {
      switch (insightType) {
        case 'progress':
          insights.progress_analysis = analyzeProjectProgress(projectContext)
          break
        case 'bottlenecks':
          insights.bottleneck_analysis = identifyProjectBottlenecks(projectContext)
          break
        case 'team_performance':
          insights.team_performance = analyzeTeamPerformance(projectContext)
          break
        case 'documentation_health':
          insights.documentation_health = analyzeDocumentationHealth(projectContext)
          break
        case 'ai_readiness':
          insights.ai_readiness = assessProjectAIReadiness(projectContext)
          break
      }
    }
  
    if (include_recommendations) {
      insights.recommendations = generateProjectRecommendations(insights, projectContext)
    }
  
    insights.overall_health_score = calculateOverallHealthScore(insights)
  
    return insights
  })

• src/tools/context-aggregation.ts:27-31 (schema)

  Zod schema defining input validation: project_id (uuid, required), insight_types (array of enums, default [progress,bottlenecks]), and include_recommendations (boolean, default true).

  const GetProjectInsightsSchema = z.object({
    project_id: z.string().uuid(),
    insight_types: z.array(z.enum(['progress', 'bottlenecks', 'team_performance', 'documentation_health', 'ai_readiness'])).default(['progress', 'bottlenecks']),
    include_recommendations: z.boolean().default(true)
  })

• src/tools/context-aggregation.ts:229-257 (registration)

  MCPTool registration object with name 'get_project_insights', description, and inputSchema for MCP tool discovery.

  export const getProjectInsightsTool: MCPTool = {
    name: 'get_project_insights',
    description: 'Get deep analytics and insights for a specific project',
    inputSchema: {
      type: 'object',
      properties: {
        project_id: {
          type: 'string',
          format: 'uuid',
          description: 'The project ID to analyze'
        },
        insight_types: {
          type: 'array',
          items: {
            type: 'string',
            enum: ['progress', 'bottlenecks', 'team_performance', 'documentation_health', 'ai_readiness']
          },
          default: ['progress', 'bottlenecks'],
          description: 'Types of insights to generate'
        },
        include_recommendations: {
          type: 'boolean',
          default: true,
          description: 'Whether to include actionable recommendations'
        }
      },
      required: ['project_id']
    }
  }

• src/tools/context-aggregation.ts:724-730 (registration)

  Exports the handler under the key 'get_project_insights' in contextAggregationHandlers, which is merged into the main allHandlers in src/index.ts.

  export const contextAggregationHandlers = {
    get_smart_context: getSmartContext,
    get_workspace_overview: getWorkspaceOverview,
    get_project_insights: getProjectInsights,
    find_related_content: findRelatedContent,
    generate_context_summary: generateContextSummary
  }

• src/index.ts:539-546 (helper)

  Resource routing: when a resource URI matches '/project/{id}/health', it calls get_project_insights with all insight types enabled.

  const projectHealthMatch = path.match(/^\/project\/([^\/]+)\/health$/)
  if (projectHealthMatch) {
    return await this.allHandlers.get_project_insights({ 
      project_id: projectHealthMatch[1],
      insight_types: ['progress', 'bottlenecks', 'team_performance', 'documentation_health'],
      include_recommendations: true
    })
  }