DeepSource MCP Server

Instructions

Implementation Reference

• src/handlers/dependency-vulnerabilities.ts:35-123 (handler)

  Core handler implementation that creates the tool handler function. Fetches dependency vulnerabilities from DeepSource API using client, processes and enriches data with risk assessments, handles pagination, and formats output.

  export const createDependencyVulnerabilitiesHandler = createBaseHandlerFactory(
    'dependency_vulnerabilities',
    async (
      deps: BaseHandlerDeps,
      { projectKey, first, after, last, before }: DeepsourceDependencyVulnerabilitiesParams
    ) => {
      const apiKey = deps.getApiKey();
      deps.logger.debug('API key retrieved from config', {
        length: apiKey.length,
        prefix: `${apiKey.substring(0, 5)}...`,
      });
  
      const client = new DeepSourceClient(apiKey);
  
      deps.logger.info('Fetching dependency vulnerabilities', {
        projectKey,
      });
  
      const params: { first?: number; after?: string; last?: number; before?: string } = {};
      if (first !== undefined) params.first = first;
      if (after !== undefined) params.after = after;
      if (last !== undefined) params.last = last;
      if (before !== undefined) params.before = before;
  
      const vulnerabilities = await client.getDependencyVulnerabilities(projectKey, params);
  
      deps.logger.info('Successfully fetched dependency vulnerabilities', {
        count: vulnerabilities.items.length,
        totalCount: vulnerabilities.totalCount,
        hasNextPage: vulnerabilities.pageInfo?.hasNextPage,
        hasPreviousPage: vulnerabilities.pageInfo?.hasPreviousPage,
      });
  
      const vulnerabilitiesData = {
        vulnerabilities: vulnerabilities.items.map((vulnerability: VulnerabilityOccurrence) => ({
          id: vulnerability.id,
          title: vulnerability.vulnerability.summary || vulnerability.vulnerability.identifier,
          severity: vulnerability.vulnerability.severity,
          cvssScore:
            vulnerability.vulnerability.cvssV3BaseScore ||
            vulnerability.vulnerability.cvssV2BaseScore,
          packageName: vulnerability.package.name,
          packageVersion: vulnerability.packageVersion.version,
          fixedIn:
            vulnerability.vulnerability.fixedVersions.length > 0
              ? vulnerability.vulnerability.fixedVersions[0]
              : null,
          description:
            vulnerability.vulnerability.details || vulnerability.vulnerability.summary || '',
          identifiers: [
            vulnerability.vulnerability.identifier,
            ...vulnerability.vulnerability.aliases,
          ],
          references: vulnerability.vulnerability.referenceUrls,
          // Add metadata to help with risk assessment
          risk_assessment: {
            severity_level: getSeverityLevel(vulnerability.vulnerability.severity),
            cvss_description: describeCvssScore(
              vulnerability.vulnerability.cvssV3BaseScore ||
                vulnerability.vulnerability.cvssV2BaseScore ||
                null
            ),
            fixed_version_available: vulnerability.vulnerability.fixedVersions.length > 0,
            remediation_advice: getRemediationAdvice(vulnerability),
          },
        })),
        pageInfo: {
          hasNextPage: vulnerabilities.pageInfo?.hasNextPage || false,
          hasPreviousPage: vulnerabilities.pageInfo?.hasPreviousPage || false,
          startCursor: vulnerabilities.pageInfo?.startCursor || null,
          endCursor: vulnerabilities.pageInfo?.endCursor || null,
        },
        totalCount: vulnerabilities.totalCount,
        // Provide helpful information and guidance
        usage_examples: {
          pagination: {
            next_page: 'For forward pagination, use first and after parameters',
            previous_page: 'For backward pagination, use last and before parameters',
          },
          related_tools: {
            issues: 'Use the project_issues tool to get code issues in the project',
            compliance: 'Use the compliance_report tool to get security compliance reports',
          },
        },
      };
  
      return wrapInApiResponse(vulnerabilitiesData);
    }
  );

• src/server/tool-definitions.ts:467-520 (schema)

  Zod-based input and output schema definition for the dependency_vulnerabilities MCP tool, including pagination parameters and detailed vulnerability output structure.

  export const dependencyVulnerabilitiesToolSchema = {
    name: 'dependency_vulnerabilities',
    description: 'Get dependency vulnerabilities from a DeepSource project',
    inputSchema: {
      projectKey: z.string().describe('DeepSource project key to fetch vulnerabilities for'),
      first: z.number().optional().describe('Number of items to retrieve (forward pagination)'),
      after: z
        .string()
        .optional()
        .describe('Cursor to start retrieving items after (forward pagination)'),
      last: z.number().optional().describe('Number of items to retrieve (backward pagination)'),
      before: z
        .string()
        .optional()
        .describe('Cursor to start retrieving items before (backward pagination)'),
      page_size: z
        .number()
        .optional()
        .describe('Number of items per page (alias for first, for convenience)'),
      max_pages: z
        .number()
        .optional()
        .describe('Maximum number of pages to fetch (enables automatic multi-page fetching)'),
    },
    outputSchema: {
      vulnerabilities: z.array(
        z.object({
          id: z.string(),
          title: z.string(),
          severity: z.string(),
          cvssScore: z.number().nullable(),
          packageName: z.string(),
          packageVersion: z.string(),
          fixedIn: z.string().nullable(),
          description: z.string(),
          identifiers: z.record(z.string(), z.array(z.string())),
          references: z.array(z.string()),
          risk_assessment: z.object({
            severity_level: z.string(),
            cvss_description: z.string(),
            fixed_version_available: z.boolean(),
            remediation_advice: z.string(),
          }),
        })
      ),
      pageInfo: z.object({
        hasNextPage: z.boolean(),
        hasPreviousPage: z.boolean(),
        startCursor: z.string().nullable(),
        endCursor: z.string().nullable(),
      }),
      totalCount: z.number(),
    },
  };

• src/index-registry.ts:148-154 (registration)

  Registers the dependency_vulnerabilities tool in the MCP ToolRegistry, using the schema and a handler that adapts parameters before delegating to the main handler function.

  toolRegistry.registerTool({
    ...dependencyVulnerabilitiesToolSchema,
    handler: async (params) => {
      const adaptedParams = adaptDependencyVulnerabilitiesParams(params);
      return handleDeepsourceDependencyVulnerabilities(adaptedParams);
    },
  });

• src/client/security-client.ts:61-106 (helper)

  SecurityClient method that performs the GraphQL query to DeepSource API to retrieve dependency vulnerabilities data, extracts and maps the response.

  async getDependencyVulnerabilities(
    projectKey: string,
    params: PaginationParams = {}
  ): Promise<PaginatedResponse<VulnerabilityOccurrence>> {
    try {
      this.logger.info('Fetching dependency vulnerabilities from DeepSource API', {
        projectKey,
      });
  
      const project = await this.findProjectByKey(projectKey);
      if (!project) {
        return BaseDeepSourceClient.createEmptyPaginatedResponse<VulnerabilityOccurrence>();
      }
  
      const normalizedParams = BaseDeepSourceClient.normalizePaginationParams(params);
      const query = SecurityClient.buildVulnerabilitiesQuery();
  
      const response = await this.executeGraphQL(query, {
        login: project.repository.login,
        name: project.repository.name,
        provider: project.repository.provider,
        ...normalizedParams,
      });
  
      if (!response.data) {
        throw new Error('No data received from GraphQL API');
      }
  
      const vulnerabilities = this.extractVulnerabilitiesFromResponse(response.data);
  
      this.logger.info('Successfully fetched dependency vulnerabilities', {
        count: vulnerabilities.length,
      });
  
      return {
        items: vulnerabilities,
        pageInfo: {
          hasNextPage: false, // Simplified for now
          hasPreviousPage: false,
        },
        totalCount: vulnerabilities.length,
      };
    } catch (error) {
      return this.handleVulnerabilitiesError(error);
    }
  }

• src/adapters/handler-adapters.ts:136-157 (helper)

  Adapter function that converts raw MCP tool parameters to the typed parameters expected by the handler.

  export function adaptDependencyVulnerabilitiesParams(
    params: unknown
  ): DeepsourceDependencyVulnerabilitiesParams {
    const typedParams = params as Record<string, unknown>;
    const result: DeepsourceDependencyVulnerabilitiesParams = {
      projectKey: typedParams.projectKey as string, // Handler still expects string
    };
  
    const first = typedParams.first as number | undefined;
    if (first !== undefined) result.first = first;
  
    const last = typedParams.last as number | undefined;
    if (last !== undefined) result.last = last;
  
    const after = typedParams.after as string | undefined;
    if (after !== undefined) result.after = after;
  
    const before = typedParams.before as string | undefined;
    if (before !== undefined) result.before = before;
  
    return result;
  }