Greptile

Búsqueda y consulta de código utilizando la API de Greptile.

Documentación

Servidor MCP de Greptile

Una implementación de servidor MCP (Model Context Protocol) que se integra con la API de Greptile para proporcionar capacidades de búsqueda y consulta de código a agentes de IA.

Características

El servidor proporciona cuatro herramientas esenciales de Greptile que permiten a los agentes de IA interactuar con bases de código:

index_repository: Indexar un repositorio para búsqueda y consulta de código.
query_repository: Consultar repositorios para obtener respuestas con referencias de código.
- Hacer preguntas en lenguaje natural sobre la base de código
  - Obtener respuestas detalladas que referencian ubicaciones específicas de código
  - Soporte para historial de conversación con IDs de sesión
search_repository: Buscar en repositorios archivos relevantes sin generar una respuesta completa.
- Encontrar archivos relacionados con conceptos o características específicas
  - Obtener coincidencias contextuales ordenadas por relevancia
  - Más rápido que las consultas completas cuando solo se necesitan ubicaciones de archivos
get_repository_info: Obtener información sobre un repositorio indexado.
- Verificar el estado y progreso de indexación
  - Confirmar qué repositorios están disponibles para consultas
  - Obtener metadatos sobre repositorios indexados

Despliegue con Smithery

El servidor MCP de Greptile admite el despliegue mediante Smithery. Se incluye un archivo de configuración smithery.yaml en la raíz del proyecto.

Configuración de Smithery

La configuración de Smithery se define en smithery.yaml y admite las siguientes opciones:

build:
  dockerfile: Dockerfile

startCommand:
  type: stdio
  configSchema:
    type: object
    required:
      - greptileApiKey
      - githubToken
    properties:
      greptileApiKey:
        type: string
        description: "API key for accessing the Greptile API"
      githubToken:
        type: string
        description: "GitHub Personal Access Token for repository access"
      host:
        type: string
        description: "Host to bind to when using SSE transport"
        default: "0.0.0.0"
      port:
        type: string
        description: "Port to listen on when using SSE transport"
        default: "8050"

Uso con Smithery

Para desplegar usando Smithery:

Instalar Smithery: npm install -g smithery
Desplegar el servidor: smithery deploy
Configurar tu cliente de Smithery con las claves de API requeridas

Requisitos previos

Python 3.12+
Clave de API de Greptile (de https://app.greptile.com/settings/api)
Token de acceso personal (PAT) de GitHub o GitLab con permisos de repo (o lectura equivalente) para los repositorios que deseas indexar
Docker (recomendado para el despliegue)

Paquetes de Python requeridos

fastmcp - Implementación del servidor MCP
httpx - Cliente HTTP asíncrono
python-dotenv - Gestión de variables de entorno
uvicorn - Servidor ASGI para transporte SSE

Instalación

Usando pip

Clonar este repositorio:

git clone https://github.com/sosacrazy126/greptile-mcp.git
cd greptile-mcp

Crear un entorno virtual:

python -m venv .venv
source .venv/bin/activate  # On Windows use \`.venv\Scripts\activate\`

Instalar dependencias:
```
pip install -r requirements.txt
```

Configurar tus variables de entorno:

export GREPTILE_API_KEY=your_api_key_here
export GITHUB_TOKEN=your_github_token_here

Usando Docker

Clonar el repositorio:

git clone https://github.com/sosacrazy126/greptile-mcp.git
cd greptile-mcp

Construir la imagen de Docker:
```
docker build -t greptile-mcp .
```

Ejecutar el servidor

El servidor MCP de Greptile admite dos modos de operación:

1. Modo MCP (predeterminado)

Servidor MCP tradicional para integración directa con clientes MCP.

Usando pip

python -m src.main

Usando Docker

docker run --rm -e GREPTILE_API_KEY=your_key -e GITHUB_TOKEN=your_token -p 8050:8050 greptile-mcp

2. Modo HTTP/JSON-RPC (nuevo)

Servidor HTTP que proporciona una interfaz JSON-RPC 2.0 para aplicaciones web y clientes REST.

Usando pip

python -m src.main_http

Usando Docker (modo HTTP)

docker run --rm -e GREPTILE_API_KEY=your_key -e GITHUB_TOKEN=your_token -p 8080:8080 greptile-mcp python -m src.main_http

Modo de desarrollo (con recarga automática)

python -m src.main_http --dev

Características del modo HTTP

API compatible con JSON-RPC 2.0 en /json-rpc
Documentación interactiva en /docs (interfaz Swagger)
Documentación alternativa en /redoc
Punto de verificación de salud en /health
Documentación de métodos en /api/methods
Límite de velocidad (100 solicitudes/hora por IP)
Soporte CORS para aplicaciones web

Ejemplos de uso del modo HTTP

Usando curl

# Index a repository
curl -X POST http://localhost:8080/json-rpc \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "index_repository",
    "params": {
      "remote": "github",
      "repository": "facebook/react",
      "branch": "main"
    },
    "id": "1"
  }'

# Query a repository
curl -X POST http://localhost:8080/json-rpc \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "query_repository",
    "params": {
      "query": "How does useState work?",
      "repositories": [
        {
          "remote": "github",
          "repository": "facebook/react",
          "branch": "main"
        }
      ]
    },
    "id": "2"
  }'

Usando JavaScript/fetch

// Index a repository
const indexResponse = await fetch('http://localhost:8080/json-rpc', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    method: 'index_repository',
    params: {
      remote: 'github',
      repository: 'facebook/react',
      branch: 'main'
    },
    id: '1'
  })
});

const indexResult = await indexResponse.json();
console.log('Index result:', indexResult);

// Query the repository
const queryResponse = await fetch('http://localhost:8080/json-rpc', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    method: 'query_repository',
    params: {
      query: 'How does the component lifecycle work?',
      repositories: [
        {
          remote: 'github',
          repository: 'facebook/react',
          branch: 'main'
        }
      ]
    },
    id: '2'
  })
});

const queryResult = await queryResponse.json();
console.log('Query result:', queryResult);

Usando Python requests

import requests
import json

# Configuration
base_url = "http://localhost:8080/json-rpc"
headers = {"Content-Type": "application/json"}

# Index a repository
index_payload = {
    "jsonrpc": "2.0",
    "method": "index_repository",
    "params": {
        "remote": "github",
        "repository": "facebook/react",
        "branch": "main"
    },
    "id": "1"
}

response = requests.post(base_url, headers=headers, json=index_payload)
print("Index result:", response.json())

# Query the repository
query_payload = {
    "jsonrpc": "2.0",
    "method": "query_repository",
    "params": {
        "query": "Explain React hooks",
        "repositories": [
            {
                "remote": "github",
                "repository": "facebook/react",
                "branch": "main"
            }
        ]
    },
    "id": "2"
}

response = requests.post(base_url, headers=headers, json=query_payload)
print("Query result:", response.json())

Integración con clientes MCP

Configura tu cliente MCP para conectarse al servidor:

{
  "mcpServers": {
    "greptile": {
      "transport": "sse",
      "url": "http://localhost:8050/sse"
    }
  }
}

Guía de uso detallada

Flujo de trabajo para análisis de bases de código

Indexar repositorios que deseas analizar usando index_repository
Verificar el estado de indexación con get_repository_info para asegurarte de que el procesamiento esté completo
Consultar los repositorios usando lenguaje natural con query_repository
Encontrar archivos específicos relacionados con características o conceptos usando search_repository

Gestión de sesiones para contexto de conversación

Al interactuar con el servidor MCP de Greptile a través de cualquier cliente (incluido Smithery), la gestión adecuada de sesiones es crucial para mantener el contexto de la conversación:

Generar un ID de sesión único al inicio de una conversación
Reutilizar el mismo ID de sesión para todas las consultas de seguimiento relacionadas
Crear un nuevo ID de sesión al iniciar una nueva conversación

Ejemplo de gestión de ID de sesión:

# Generate a unique session ID
import uuid
session_id = str(uuid.uuid4())

# Initial query
initial_response = query_repository(
    query="How is authentication implemented?",
    repositories=[{"remote": "github", "repository": "owner/repo", "branch": "main"}],
    session_id=session_id  # Include the session ID
)

# Follow-up query using the SAME session ID
followup_response = query_repository(
    query="Can you provide more details about the JWT verification?",
    repositories=[{"remote": "github", "repository": "owner/repo", "branch": "main"}],
    session_id=session_id  # Reuse the same session ID
)

Importante para la integración con Smithery: Los agentes que se conectan a través de Smithery deben generar y mantener sus propios IDs de sesión. El servidor MCP de Greptile NO genera automáticamente IDs de sesión. El ID de sesión debe ser parte del estado de conversación del agente.

Mejores prácticas

Rendimiento de indexación: Los repositorios más pequeños se indexan más rápido. Para monorepos grandes, considera indexar ramas o etiquetas específicas.
Optimización de consultas: Sé específico en tus consultas. Incluye términos técnicos relevantes para obtener mejores resultados.
Selección de repositorios: Al consultar múltiples repositorios, enuméralos en orden de relevancia para obtener los mejores resultados.
Gestión de sesiones: Usa IDs de sesión para preguntas de seguimiento y mantener el contexto entre consultas.

Referencia de la API

1. Indexar repositorio

Indexa un repositorio para hacerlo buscable en consultas futuras.

Parámetros:

remote (cadena): El host del repositorio, ya sea "github" o "gitlab"
repository (cadena): El repositorio en formato propietario/repositorio (por ejemplo, "greptileai/greptile")
branch (cadena): La rama a indexar (por ejemplo, "main")
reload (booleano, opcional): Si se debe forzar el reprocesamiento de un repositorio previamente indexado
notify (booleano, opcional): Si se debe enviar una notificación por correo electrónico cuando la indexación esté completa

Ejemplo:

// Tool Call: index_repository
{
  "remote": "github",
  "repository": "greptileai/greptile",
  "branch": "main",
  "reload": false,
  "notify": false
}

Respuesta:

{
  "message": "Indexing Job Submitted for: greptileai/greptile",
  "statusEndpoint": "https://api.greptile.com/v2/repositories/github:main:greptileai%2Fgreptile"
}

2. Consultar repositorio

Consulta repositorios con lenguaje natural para obtener respuestas con referencias de código.

Parámetros:

query (cadena): La consulta en lenguaje natural sobre la base de código
repositories (matriz): Lista de repositorios a consultar, cada uno con el formato:
```
{
  "remote": "github",
  "repository": "owner/repo",
  "branch": "main"
}
```
session_id (cadena, opcional): ID de sesión para continuar una conversación
stream (booleano, opcional): Si se debe transmitir la respuesta
genius (booleano, opcional): Si se deben usar capacidades de consulta mejoradas

Ejemplo:

// Tool Call: query_repository
{
  "query": "How is authentication handled in this codebase?",
  "repositories": [
    {
      "remote": "github",
      "repository": "greptileai/greptile",
      "branch": "main"
    }
  ],
  "session_id": null,
  "stream": false,
  "genius": true
}

Respuesta:

{
  "message": "Authentication in this codebase is handled using JWT tokens...",
  "sources": [
    {
      "repository": "greptileai/greptile",
      "remote": "github",
      "branch": "main",
      "filepath": "/src/auth/jwt.js",
      "linestart": 14,
      "lineend": 35,
      "summary": "JWT token validation middleware"
    }
  ]
}

3. Buscar en repositorio

Busca en repositorios para encontrar archivos relevantes sin generar una respuesta completa.

Parámetros:

query (cadena): La consulta de búsqueda sobre la base de código
repositories (matriz): Lista de repositorios a buscar
session_id (cadena, opcional): ID de sesión para continuar una conversación
genius (booleano, opcional): Si se deben usar capacidades de búsqueda mejoradas

4. Obtener información del repositorio

Obtiene información sobre un repositorio específico que ha sido indexado.

Parámetros:

remote (cadena): El host del repositorio, ya sea "github" o "gitlab"
repository (cadena): El repositorio en formato propietario/repositorio
branch (cadena): La rama que fue indexada

Variables de entorno

Variable	Descripción	Predeterminado
`GREPTILE_API_KEY`	Tu clave de API de Greptile	(requerida)
`GITHUB_TOKEN`	Token de acceso personal de GitHub/GitLab	(requerido)
`HOST`	Host al que vincularse	`0.0.0.0`
`PORT`	Puerto en el que escuchar	`8050`

Licencia

Este proyecto está licenciado bajo la Licencia MIT.