DeepSource MCP Server

Instructions

Implementation Reference

• src/handlers/project-issues.ts:35-133 (handler)

  Core handler factory for the 'project_issues' tool. Creates a handler that fetches issues from a DeepSource project using the API client, applies filters and pagination parameters, formats the response with pagination metadata, and wraps it in ApiResponse.
  export const createProjectIssuesHandler = createBaseHandlerFactory( 'project_issues', async ( deps: BaseHandlerDeps, { projectKey, path, analyzerIn, tags, first, after, last, before, page_size, max_pages, }: DeepsourceProjectIssuesParams ) => { 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 project issues', { projectKey, hasFilterPath: Boolean(path), hasAnalyzerFilter: Boolean(analyzerIn), hasTagsFilter: Boolean(tags), maxPages: max_pages, }); const params: IssueFilterParams = {}; if (path !== undefined) params.path = path; if (analyzerIn !== undefined) params.analyzerIn = analyzerIn; if (tags !== undefined) params.tags = tags; if (first !== undefined) params.first = first; if (after !== undefined) params.after = after; if (last !== undefined) params.last = last; if (before !== undefined) params.before = before; if (page_size !== undefined) params.page_size = page_size; if (max_pages !== undefined) params.max_pages = max_pages; const issues = await client.getIssues(projectKey, params); deps.logger.info('Successfully fetched project issues', { count: issues.items.length, totalCount: issues.totalCount, hasNextPage: issues.pageInfo?.hasNextPage, hasPreviousPage: issues.pageInfo?.hasPreviousPage, }); // Create pagination metadata for user-friendly response const paginationMetadata = createPaginationMetadata(issues); const issuesData = { issues: issues.items.map((issue: DeepSourceIssue) => ({ id: issue.id, title: issue.title, shortcode: issue.shortcode, category: issue.category, severity: issue.severity, status: issue.status, issue_text: issue.issue_text, file_path: issue.file_path, line_number: issue.line_number, tags: issue.tags, })), // Include both formats for backward compatibility and user convenience pageInfo: { hasNextPage: issues.pageInfo?.hasNextPage || false, hasPreviousPage: issues.pageInfo?.hasPreviousPage || false, startCursor: issues.pageInfo?.startCursor || null, endCursor: issues.pageInfo?.endCursor || null, }, pagination: paginationMetadata, totalCount: issues.totalCount, // Provide helpful guidance on filtering and pagination usage_examples: { filtering: { by_path: 'Use the path parameter to filter issues by file path', by_analyzer: 'Use the analyzerIn parameter to filter by specific analyzers', by_tags: 'Use the tags parameter to filter by specific tags', }, pagination: { next_page: max_pages ? 'Multi-page fetching enabled with max_pages parameter' : 'For forward pagination, use first and after parameters', previous_page: 'For backward pagination, use last and before parameters', page_size: 'Use page_size parameter as a convenient alias for first', multi_page: 'Use max_pages to automatically fetch multiple pages (e.g., max_pages: 5)', }, }, }; return wrapInApiResponse(issuesData); } );
• src/server/tool-definitions.ts:174-236 (schema)

  Zod-based input and output schema definition for the project_issues tool, specifying parameters like projectKey, path, analyzerIn, tags, pagination options, and the structure of the issues response.
  export const projectIssuesToolSchema = { name: 'project_issues', description: 'Get issues from a DeepSource project with filtering capabilities', inputSchema: { projectKey: z.string().describe('DeepSource project key to fetch issues for'), path: z.string().optional().describe('Filter issues by file path'), analyzerIn: z.array(z.string()).optional().describe('Filter issues by analyzer shortcodes'), tags: z.array(z.string()).optional().describe('Filter issues by tags'), 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: { issues: z.array( z.object({ id: z.string(), title: z.string(), shortcode: z.string(), category: z.string(), severity: z.string(), status: z.string(), issue_text: z.string(), file_path: z.string(), line_number: z.number(), tags: z.array(z.string()), }) ), pageInfo: z.object({ hasNextPage: z.boolean(), hasPreviousPage: z.boolean(), startCursor: z.string().nullable(), endCursor: z.string().nullable(), }), pagination: z .object({ has_more_pages: z.boolean(), next_cursor: z.string().optional(), previous_cursor: z.string().optional(), total_count: z.number().optional(), page_size: z.number(), pages_fetched: z.number().optional(), limit_reached: z.boolean().optional(), }) .optional() .describe('User-friendly pagination metadata'), totalCount: z.number(), }, };
• src/index-registry.ts:140-146 (registration)

  Registers the project_issues tool in the MCP ToolRegistry using the predefined schema and an async handler that adapts incoming parameters and delegates to the DeepSource project issues handler.
  toolRegistry.registerTool({ ...projectIssuesToolSchema, handler: async (params) => { const adaptedParams = adaptProjectIssuesParams(params); return handleDeepsourceProjectIssues(adaptedParams); }, });
• src/adapters/handler-adapters.ts:103-131 (helper)

  Helper function that adapts raw parameters from the MCP tool call (unknown type) to the strongly-typed DeepsourceProjectIssuesParams interface required by the handler.
  export function adaptProjectIssuesParams(params: unknown): DeepsourceProjectIssuesParams { const typedParams = params as Record<string, unknown>; const result: DeepsourceProjectIssuesParams = { projectKey: typedParams.projectKey as string, // Handler still expects string }; const path = typedParams.path as string | undefined; if (path !== undefined) result.path = path; const analyzerIn = typedParams.analyzerIn as string[] | undefined; if (analyzerIn !== undefined) result.analyzerIn = analyzerIn; const tags = typedParams.tags as string[] | undefined; if (tags !== undefined) result.tags = tags; 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; }