DeepSource MCP Server

Instructions

Implementation Reference

• src/handlers/projects.ts:81-97 (handler)

  Main handler function for the 'projects' tool. Instantiates repository factory, fetches all projects, maps to simplified format, and returns JSON response.

  export async function handleProjects(): Promise<ApiResponse> {
    try {
      const apiKey = getApiKey();
      const repositoryFactory = new RepositoryFactory({ apiKey });
      const projectRepository = repositoryFactory.createProjectRepository();
  
      const handler = createProjectsHandler({
        projectRepository,
        logger,
      });
  
      return handler();
    } catch (error) {
      // Handle configuration errors and other setup issues
      return MCPErrorFormatter.createErrorResponse(error, 'projects-setup');
    }
  }

• src/server/tool-definitions.ts:12-25 (schema)

  Zod schema definition for the 'projects' tool, specifying name, description, empty input schema, and output as array of project objects with key and name.

  export const projectsToolSchema = {
    name: 'projects',
    description:
      'List all available DeepSource projects. Returns a list of project objects with "key" and "name" properties.',
    inputSchema: {},
    outputSchema: {
      projects: z.array(
        z.object({
          key: z.string(),
          name: z.string(),
        })
      ),
    },
  };

• src/server/tool-registration.ts:40-56 (registration)

  Handler wrapper in TOOL_HANDLERS record for 'projects' tool, adds logging and calls the core handleProjects function.

  projects: async (params: unknown) => {
    logger.info('=== PROJECTS HANDLER START ===');
    logger.info('Projects handler called with params:', { params, type: typeof params });
    try {
      // Params currently unused but may be used for future filtering
      const result = await handleProjects();
      logger.info('=== PROJECTS HANDLER SUCCESS ===', { result });
      return result;
    } catch (error) {
      logger.error('=== PROJECTS HANDLER ERROR ===', {
        error,
        message: error instanceof Error ? error.message : String(error),
        stack: error instanceof Error ? error.stack : undefined,
      });
      throw error;
    }
  },

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

  Function that registers all tools including 'projects' by creating ToolDefinition from schemas and TOOL_HANDLERS, then calling registry.registerTools.

  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),
    });
  }