greptile-mcp: Instructions file for Claude Code

CLAUDE.md

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

Project Overview

This is a Greptile MCP (Model Context Protocol) server that provides AI-powered code search and querying capabilities. It's designed to integrate with the Greptile API to index repositories and answer natural language questions about codebases.

Build and Development Commands

Installation

# Local development setup
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e .

# Create environment file
cp .env.example .env
# Edit .env with your GREPTILE_API_KEY and GITHUB_TOKEN

Running the Server

# Run locally (SSE transport - default)
python -m src.main

# Run with stdio transport (for MCP client integration)
TRANSPORT=stdio python -m src.main

# Run with Docker
docker build -t greptile-mcp .
docker run --rm --env-file .env -p 8080:8080 greptile-mcp

Testing

# Run tests (if test framework is available)
python -m pytest src/tests/

# Test individual components
python -m pytest src/tests/test_server.py
python -m pytest src/tests/test_client.py

Code Quality

# Code formatting and linting (using ruff)
ruff check src/
ruff format src/

Architecture

Core Components

1. src/main.py - Main MCP server implementation using FastMCP (Refactored Architecture)

   • Defines 4 main tools: greptile_help, index_repository, query_repository, get_repository_info
   • Uses modular service and handler architecture for better maintainability
   • Maintains full backward compatibility with original implementation

2. src/services/ - Service layer for business logic

   • greptile_service.py - Greptile API client management and operations
   • session_service.py - Session and conversation context management

3. src/handlers/ - Handler layer for tool implementations

   • index_handler.py - Repository indexing operations
   • query_handler.py - Natural language query processing
   • search_handler.py - File search operations
   • info_handler.py - Repository information retrieval