deepsource-mcp-server CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Repository Overview

This repository is a Model Context Protocol (MCP) server that integrates with DeepSource's code quality analysis platform. It serves as a bridge between DeepSource's GraphQL API and MCP-compatible AI assistants like Claude, providing access to code quality metrics and analysis results.

Development Commands

Understanding MCP Servers

MCP servers are not standalone services - they communicate via stdio with MCP clients (like Claude Desktop). The server cannot be run directly with node or npm start in a meaningful way. Instead, use:

• Production: Configure in Claude Desktop or use npx deepsource-mcp-server
• Development: Use pnpm run inspect with the MCP Inspector tool
• Testing: Run the test suite with pnpm test

Quick Start

# Install dependencies
pnpm install

# Build the server
pnpm run build

# Debug with MCP Inspector (recommended for development)
pnpm run inspect

Building & Debugging

pnpm run build          # Compile TypeScript to JavaScript
pnpm run watch          # Watch mode - rebuild on changes
pnpm run clean          # Remove build artifacts (dist/)

# Debugging with MCP Inspector
pnpm run inspect        # Launch MCP Inspector to test the server interactively

Testing

# Basic testing
pnpm run test           # Run all tests
pnpm run test:watch     # Run tests in watch mode
pnpm run test:coverage  # Run tests with coverage report

# Run specific tests
pnpm test -- src/__tests__/specific-test.test.ts
pnpm test -- --testNamePattern="should handle errors"
pnpm test -- --verbose src/__tests__/specific-test.test.ts

# Run tests for a specific file pattern
pnpm test -- client      # Test all client files
pnpm test -- handler     # Test all handler files

Code Quality

# Type checking
pnpm run check-types    # Type check without building

# Linting
pnpm run lint           # Run ESLint
pnpm run lint:fix       # Auto-fix ESLint issues

# Formatting
pnpm run format         # Check if code is formatted
pnpm run format:fix     # Format all code with Prettier

# Full CI pipeline
pnpm run ci            # Run format, lint, type check, build, and test coverage