Greptile MCP Server

A WebSocket-based server that enables real-time code search and indexing capabilities across multiple repositories. It acts as a middleware between clients and the Greptile API, providing enhanced functionality for managing multiple search contexts and streaming results.

Features

• 🔌 WebSocket Server: Real-time communication with connection management and heartbeat mechanism
• 👥 Agent Management: Create and manage agent instances for different repositories
• 🔍 Repository Integration: Support repository indexing through Greptile API
• 🔎 Query Processing: Process and validate search queries with streaming results
• 🔐 Security: Secure WebSocket connections with API key authentication
• ⚙️ Configuration: Environment-based configuration with custom API endpoints
• 📊 Monitoring: Comprehensive logging system with performance metrics
• 📚 Client SDK: WebSocket client implementation with connection management

Installation

# Clone the repository
git clone https://github.com/yourusername/greptile-mcp.git

# Install dependencies
npm install

# Set up environment variables
cp .env.example .env
# Edit .env with your configuration

# Start the server
npm start

Environment Variables

# Server Configuration
PORT=3000
HOST=0.0.0.0
NODE_ENV=production

# Greptile API Configuration
GREPTILE_API_KEY=your-api-key
GITHUB_TOKEN=your-github-token
GREPTILE_BASE_URL=https://api.greptile.com/v2

# Authentication Configuration
AUTH_ENABLED=false
API_KEY=your-api-key-here
TOKEN_HEADER_NAME=X-API-Key

# Rate Limiting Configuration
RATE_LIMIT_ENABLED=true
RATE_LIMIT_WINDOW_MS=900000
RATE_LIMIT_MAX=100

# Logging Configuration
LOG_LEVEL=info
LOG_FORMAT=combined

Usage

Creating an Agent

curl -X POST http://localhost:3000/api/agents \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Demo Agent",
    "description": "Testing agent",
    "repositoryUrl": "https://github.com/facebook/react",
    "branch": "main"
  }'

WebSocket Connection

import WebSocket from 'ws';

const ws = new WebSocket('ws://localhost:3000');
const agentId = 'your-agent-id';

ws.on('open', () => {
  // Register the connection
  ws.send(JSON.stringify({
    type: 'register',
    agentId: agentId
  }));
});

ws.on('message', (data) => {
  const message = JSON.parse(data.toString());
  console.log('Received:', message);
});

Querying Code

// After registration
ws.send(JSON.stringify({
  type: 'query',
  query: 'Find function main',
  options: {
    stream: true,
    maxResults: 5,
    includeContext: true
  }
}));

Development

# Run in development mode
npm run dev

# Run tests
npm test

# Run linting
npm run lint

# Build for production
npm run build

Testing

The project includes comprehensive tests:

# Run all tests
npm test

# Run specific test file
npm test -- tests/server.test.js

# Run with coverage
npm run test:coverage

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Greptile API for providing the core search functionality
• ws for the WebSocket implementation
• All contributors who have helped with the project