DeepSource MCP Server

Instructions

Implementation Reference

• src/handlers/quality-metrics.ts:255-275 (handler)

  Top-level handler function for the "quality_metrics" tool. Orchestrates dependency injection (repository factory, logger), invokes the core handler logic, and handles errors.

  export async function handleDeepsourceQualityMetrics(params: DeepsourceQualityMetricsParams) {
    try {
      const baseDeps = createDefaultHandlerDeps({ logger });
      const apiKey = baseDeps.getApiKey();
      const repositoryFactory = new RepositoryFactory({ apiKey });
      const qualityMetricsRepository = repositoryFactory.createQualityMetricsRepository();
  
      const deps: QualityMetricsHandlerDeps = {
        qualityMetricsRepository,
        logger,
      };
  
      const handler = createQualityMetricsHandlerWithRepo(deps);
      const result = await handler(params);
  
      return result;
    } catch (error) {
      // Handle configuration errors and other setup issues
      return MCPErrorFormatter.createErrorResponse(error, 'quality-metrics-setup');
    }
  }

• src/handlers/quality-metrics.ts:77-170 (handler)

  Core handler logic (handleQualityMetrics) that fetches metrics from the domain repository, applies filtering, formats response with threshold analysis, and returns MCP-compliant content.

  export function createQualityMetricsHandlerWithRepo(deps: QualityMetricsHandlerDeps) {
    return async function handleQualityMetrics(params: DeepsourceQualityMetricsParams) {
      try {
        const { projectKey, shortcodeIn } = params;
  
        // Validate required parameters using MCP error handling
        validateNonEmptyString(projectKey, 'projectKey');
  
        const projectKeyBranded = asProjectKey(projectKey);
        deps.logger.info('Fetching quality metrics from repository', { projectKey, shortcodeIn });
  
        // Get metrics from repository with server-side filtering if shortcodes specified
        const filteredMetrics = shortcodeIn
          ? await deps.qualityMetricsRepository.findByProjectWithFilter(
              projectKeyBranded,
              shortcodeIn
            )
          : await deps.qualityMetricsRepository.findByProject(projectKeyBranded);
  
        deps.logger.info('Successfully fetched quality metrics', {
          count: filteredMetrics.length,
          projectKey,
        });
  
        const metricsData = {
          metrics: filteredMetrics.map((domainMetric: QualityMetrics) => ({
            name: domainMetric.configuration.name,
            shortcode: domainMetric.configuration.shortcode,
            description: domainMetric.configuration.description,
            positiveDirection: domainMetric.configuration.positiveDirection,
            unit: domainMetric.configuration.unit,
            minValueAllowed: domainMetric.configuration.minAllowed,
            maxValueAllowed: domainMetric.configuration.maxAllowed,
            isReported: domainMetric.configuration.isReported,
            isThresholdEnforced: domainMetric.configuration.isThresholdEnforced,
            items: [
              {
                id: domainMetric.repositoryId,
                key: domainMetric.configuration.metricKey,
                threshold: domainMetric.configuration.threshold?.value ?? null,
                latestValue: domainMetric.currentValue?.value ?? null,
                latestValueDisplay: domainMetric.currentValue?.displayValue ?? null,
                thresholdStatus: domainMetric.thresholdStatus,
                // Add helpful metadata for threshold values
                thresholdInfo:
                  domainMetric.configuration.threshold &&
                  domainMetric.currentValue &&
                  domainMetric.configuration.threshold.value !== null &&
                  domainMetric.currentValue.value !== null
                    ? {
                        difference:
                          domainMetric.currentValue.value -
                          domainMetric.configuration.threshold.value,
                        percentDifference:
                          domainMetric.configuration.threshold.value !== 0
                            ? `${(((domainMetric.currentValue.value - domainMetric.configuration.threshold.value) / domainMetric.configuration.threshold.value) * 100).toFixed(2)}%`
                            : 'N/A',
                        isPassing: domainMetric.isCompliant,
                      }
                    : null,
              },
            ],
          })),
          // Add helpful examples for threshold management
          usage_examples: {
            filtering:
              'To filter metrics by type, use the shortcodeIn parameter with specific metric codes (e.g., ["LCV", "BCV"])',
            updating_threshold: 'To update a threshold, use the update_metric_threshold tool',
            updating_settings:
              'To update metric settings (e.g., enable reporting or threshold enforcement), use the update_metric_setting tool',
          },
        };
  
        return {
          content: [
            {
              type: 'text' as const,
              text: JSON.stringify(metricsData),
            },
          ],
        };
      } catch (error) {
        deps.logger.error('Error in handleQualityMetrics', {
          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',
        });
  
        // Use MCP-compliant error formatting
        return MCPErrorFormatter.createErrorResponse(error, 'quality-metrics-fetch');
      }
    };
  }

• src/server/tool-definitions.ts:30-72 (schema)

  Zod-based input and output schema definition for the quality_metrics tool, including parameter descriptions and structured response validation.

  export const qualityMetricsToolSchema = {
    name: 'quality_metrics',
    description: 'Get quality metrics from a DeepSource project with optional filtering',
    inputSchema: {
      projectKey: z.string().describe('DeepSource project key to fetch quality metrics for'),
      shortcodeIn: z
        .array(z.nativeEnum(MetricShortcode))
        .optional()
        .describe('Optional filter for specific metric shortcodes'),
    },
    outputSchema: {
      metrics: z.array(
        z.object({
          name: z.string(),
          shortcode: z.string(),
          description: z.string(),
          positiveDirection: z.string(),
          unit: z.string(),
          minValueAllowed: z.number().nullable(),
          maxValueAllowed: z.number().nullable(),
          isReported: z.boolean(),
          isThresholdEnforced: z.boolean(),
          items: z.array(
            z.object({
              id: z.string(),
              key: z.string(),
              threshold: z.number().nullable(),
              latestValue: z.number().nullable(),
              latestValueDisplay: z.string().nullable(),
              thresholdStatus: z.string(),
              thresholdInfo: z
                .object({
                  difference: z.number(),
                  percentDifference: z.string(),
                  isPassing: z.boolean(),
                })
                .nullable(),
            })
          ),
        })
      ),
    },
  };

• src/server/tool-registration.ts:271-306 (registration)

  Main registration function that creates ToolDefinition objects from toolSchemas (including quality_metrics) and their corresponding handlers, then registers them with the ToolRegistry used by MCP server.

  export function registerDeepSourceTools(registry: ToolRegistry): void {
    logger.info('=== REGISTER DEEPSOURCE TOOLS START ===');
    logger.info('Registering DeepSource tools', {
      toolSchemasType: typeof toolSchemas,
      toolSchemasIsArray: Array.isArray(toolSchemas),
      toolSchemasLength: Array.isArray(toolSchemas) ? toolSchemas.length : 'not an array',
      toolSchemaNames: Array.isArray(toolSchemas) ? toolSchemas.map((s) => s.name) : 'not an array',
    });
  
    const toolDefinitions: ToolDefinition[] = [];
  
    // Create tool definitions from schemas and handlers
    for (const schema of toolSchemas) {
      logger.debug(`Processing schema: ${schema.name}`);
      const handler = TOOL_HANDLERS[schema.name];
      if (!handler) {
        logger.warn(`No handler found for tool: ${schema.name}`);
        continue;
      }
  
      logger.debug(`Creating tool definition for: ${schema.name}`);
      const toolDef = createToolDefinition(schema, handler);
      toolDefinitions.push(toolDef);
      logger.debug(`Successfully created tool definition for: ${schema.name}`);
    }
  
    logger.info(`Prepared ${toolDefinitions.length} tool definitions for registration`);
  
    // Register all tools
    registry.registerTools(toolDefinitions);
  
    logger.info('=== REGISTER DEEPSOURCE TOOLS COMPLETE ===', {
      registeredCount: toolDefinitions.length,
      registeredTools: toolDefinitions.map((t) => t.name),
    });
  }

• src/server/tool-registration.ts:57-69 (registration)

  TOOL_HANDLERS entry for quality_metrics: adapts raw MCP parameters to handler-specific format and invokes the main handler function.

  quality_metrics: async (params: unknown) => {
    const typedParams = params as Record<string, unknown>;
    const metricsParams: { projectKey: string; shortcodeIn?: MetricShortcode[] } = {
      projectKey: typedParams.projectKey as string,
    };
  
    const shortcodeIn = typedParams.shortcodeIn as MetricShortcode[] | undefined;
    if (shortcodeIn) {
      metricsParams.shortcodeIn = shortcodeIn;
    }
  
    return handleDeepsourceQualityMetrics(metricsParams);
  },