DeepSource MCP Server

Instructions

Implementation Reference

• src/index-registry.ts:131-137 (registration)

  Registers the 'compliance_report' tool with the ToolRegistry, using the schema and a handler that adapts parameters and calls the main handler function.

  toolRegistry.registerTool({
    ...complianceReportToolSchema,
    handler: async (params) => {
      const adaptedParams = adaptComplianceReportParams(params);
      return handleDeepsourceComplianceReport(adaptedParams);
    },
  });

• src/server/tool-definitions.ts:131-169 (schema)

  Defines the Zod schema for the 'compliance_report' tool, including input parameters (projectKey, reportType) and detailed output structure with analysis and recommendations.

  export const complianceReportToolSchema = {
    name: 'compliance_report',
    description: 'Get security compliance reports from a DeepSource project',
    inputSchema: {
      projectKey: z.string().describe('DeepSource project key to identify the project'),
      reportType: z.nativeEnum(ReportType).describe('Type of compliance report to fetch'),
    },
    outputSchema: {
      key: z.string(),
      title: z.string(),
      currentValue: z.number().nullable(),
      status: z.string(),
      securityIssueStats: z.array(
        z.object({
          key: z.string(),
          title: z.string(),
          occurrence: z.object({
            critical: z.number(),
            major: z.number(),
            minor: z.number(),
            total: z.number(),
          }),
        })
      ),
      trends: z.record(z.string(), z.unknown()).optional(),
      analysis: z.object({
        summary: z.string(),
        status_explanation: z.string(),
        critical_issues: z.number(),
        major_issues: z.number(),
        minor_issues: z.number(),
        total_issues: z.number(),
      }),
      recommendations: z.object({
        actions: z.array(z.string()),
        resources: z.array(z.string()),
      }),
    },
  };

• src/handlers/compliance-reports.ts:41-152 (handler)

  Core handler logic that fetches the compliance report from the repository using domain aggregate, formats it with security stats, analysis, and recommendations, and returns as JSON text content.

  return async function handleComplianceReport(params: DeepsourceComplianceReportParams) {
    try {
      const { projectKey, reportType } = params;
      const projectKeyBranded = asProjectKey(projectKey);
      deps.logger.info('Fetching compliance report from repository', { projectKey, reportType });
  
      // Get the compliance report from repository
      const domainReport = await deps.complianceReportRepository.findByProjectAndType(
        projectKeyBranded,
        reportType
      );
  
      if (!domainReport) {
        throw new Error(`Report of type '${reportType}' not found for project '${projectKey}'`);
      }
  
      deps.logger.info('Successfully fetched compliance report', {
        projectKey,
        reportType,
        status: domainReport.status,
      });
  
      const reportData = {
        key: `${domainReport.projectKey}:${domainReport.reportType}`,
        title: `${domainReport.reportType} Compliance Report`,
        currentValue: domainReport.summary.complianceScore.value,
        status:
          domainReport.status === 'READY'
            ? 'PASSING'
            : domainReport.status === 'ERROR'
              ? 'FAILING'
              : 'NOT_APPLICABLE',
        securityIssueStats: domainReport.categories.map((category) => ({
          key: category.name,
          title: category.name,
          occurrence: {
            critical: category.severity === 'CRITICAL' ? category.nonCompliant.count : 0,
            major: category.severity === 'MAJOR' ? category.nonCompliant.count : 0,
            minor: category.severity === 'INFO' ? category.nonCompliant.count : 0,
            total: category.issueCount.count,
          },
        })),
        trends: domainReport.trend ? [domainReport.trend] : [],
        // Include helpful analysis of the report
        analysis: {
          summary: `This report shows compliance with ${domainReport.reportType} security standards.`,
          status_explanation:
            domainReport.status === 'READY'
              ? 'Your project is currently meeting all required security standards.'
              : domainReport.status === 'ERROR'
                ? 'Your project has security issues that need to be addressed to meet compliance standards.'
                : 'This report is not applicable to your project.',
          critical_issues: domainReport.summary.severityDistribution.critical.count,
          major_issues: domainReport.summary.severityDistribution.major.count,
          minor_issues: domainReport.summary.severityDistribution.info.count,
          total_issues: domainReport.summary.totalIssues.count,
        },
        // Include recommendations based on the report
        recommendations: {
          actions:
            domainReport.status === 'ERROR'
              ? [
                  'Fix critical security issues first',
                  'Use project_issues to view specific issues',
                  'Implement security best practices for your codebase',
                ]
              : ['Continue monitoring security compliance', 'Run regular security scans'],
          resources: [
            reportType === ReportType.OWASP_TOP_10
              ? 'OWASP Top 10: https://owasp.org/www-project-top-ten/'
              : reportType === ReportType.SANS_TOP_25
                ? 'SANS Top 25: https://www.sans.org/top25-software-errors/'
                : reportType === ReportType.MISRA_C
                  ? 'MISRA-C: https://www.misra.org.uk/'
                  : 'Security best practices for your project',
          ],
        },
      };
  
      return {
        content: [
          {
            type: 'text' as const,
            text: JSON.stringify(reportData),
          },
        ],
      };
    } catch (error) {
      deps.logger.error('Error in handleComplianceReport', {
        errorType: typeof error,
        errorName: error instanceof Error ? error.name : 'Unknown',
        errorMessage: error instanceof Error ? error.message : String(error),
        errorStack: error instanceof Error ? error.stack : 'No stack available',
      });
  
      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
      deps.logger.debug('Returning error response', { errorMessage });
  
      return {
        isError: true,
        content: [
          {
            type: 'text' as const,
            text: JSON.stringify({
              error: errorMessage,
              details: 'Failed to retrieve compliance report',
            }),
          },
        ],
      };
    }
  };

• src/handlers/compliance-reports.ts:260-286 (handler)

  Top-level handler function called from registry; creates repository dependencies and delegates to the core domain handler.

  export async function handleDeepsourceComplianceReport(params: DeepsourceComplianceReportParams) {
    const baseDeps = createDefaultHandlerDeps({ logger });
    const apiKey = baseDeps.getApiKey();
    const repositoryFactory = new RepositoryFactory({ apiKey });
    const complianceReportRepository = repositoryFactory.createComplianceReportRepository();
  
    const deps: ComplianceReportHandlerDeps = {
      complianceReportRepository,
      logger,
    };
  
    const handler = createComplianceReportHandlerWithRepo(deps);
    const result = await handler(params);
  
    // If the domain handler returned an error response, throw an error for backward compatibility
    if (result.isError) {
      const firstContent = result.content[0];
      if (firstContent) {
        const errorData = JSON.parse(firstContent.text);
        throw new Error(errorData.error);
      } else {
        throw new Error('Unknown compliance report error');
      }
    }
  
    return result;
  }

• src/adapters/handler-adapters.ts:92-98 (helper)

  Adapter function that converts raw MCP tool parameters to typed DeepsourceComplianceReportParams for the handler.

  export function adaptComplianceReportParams(params: unknown): DeepsourceComplianceReportParams {
    const typedParams = params as Record<string, unknown>;
    return {
      projectKey: typedParams.projectKey as string, // Handler still expects string
      reportType: typedParams.reportType as ReportType,
    };
  }