Skip to main content
Glama
deenesjakoruzh
sosacrazy126

greptile-mcp

by sosacrazy126
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

Servidor MCP de Greptile [COMPLETO]

Hoja de trucos del comando de ejecución rápida

✅ ESTADO DEL PROYECTO: TODAS LAS TAREAS COMPLETADAS (11/11)

Consulte PROJECT_COMPLETION.md para obtener un resumen del trabajo completado y USER_GUIDE.md para obtener instrucciones de uso.

Ambiente

Configuración e instalación

Comando Ejecutar

Local (Python)

python -m venv .venv && source .venv/bin/activate && pip install -e .

python -m src.main

Estibador

docker build -t greptile-mcp .

docker run --rm --env-file .env -p 8050:8050 greptile-mcp

Herrería

npm install -g smithery

smithery deploy (ver smithery.yaml)

Complete .env usando .env.example y configure su GREPTILE_API_KEY y GITHUB_TOKEN antes de ejecutar.

Para conocer los requisitos previos completos, el uso avanzado del agente, la integración y la resolución de problemas: consulte la documentación completa en docs/README.md y los detalles del agente en AGENT_USAGE.md .

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

insignia de herrería

Características

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

  1. index_repository : Indexa un repositorio para búsqueda y consulta de código.

    • Procesar un repositorio para que se pueda buscar

    • Actualizar los índices existentes cuando cambian los repositorios

    • Configurar las preferencias de notificación

  2. query_repository : consulta repositorios para obtener respuestas con referencias de código.

    • Haga preguntas en lenguaje natural sobre el código base

    • Obtenga respuestas detalladas que hagan referencia a ubicaciones de códigos específicos

    • Compatibilidad con el historial de conversaciones con identificadores de sesión

  3. search_repository : busca repositorios de archivos relevantes sin generar una respuesta completa.

    • Encuentre archivos relacionados con conceptos o características específicos

    • Obtenga coincidencias contextuales clasificadas por relevancia

    • Más rápido que las consultas completas cuando solo se necesitan ubicaciones de archivos

  4. get_repository_info : obtiene información sobre un repositorio indexado.

    • Comprobar el estado y el progreso de la indexación

    • Verificar qué repositorios están disponibles para realizar consultas

    • Obtener metadatos sobre repositorios indexados

Related MCP server: mcp-meilisearch

Despliegue de herrería

El servidor Greptile MCP admite la implementación mediante Smithery. El archivo de configuración smithery.yaml se incluye en la raíz del proyecto.

Configuración de herrería

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"
      baseUrl:
        type: string
        description: "Base URL for Greptile API"
        default: "https://api.greptile.com/v2"
      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 herrería

Para implementar usando Smithery:

  1. Instalar Smithery: npm install -g smithery

  2. Implementar el servidor: smithery deploy

  3. Configure su cliente Smithery con las claves API necesarias

Documentación adicional

Para obtener instrucciones de uso detalladas de los agentes de IA, consulte la Guía de uso de agentes .

Prerrequisitos

  • Python 3.12+

  • Clave API de Greptile (desde https://app.greptile.com/settings/api )

  • Token de acceso personal (PAT) de GitHub o GitLab con permisos repo (o lectura equivalente) para los repositorios que desea indexar

  • Docker (recomendado para implementación)

Paquetes de Python necesarios

  • 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 (para desarrollo o pruebas locales)

  1. Clonar este repositorio:

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

  2. Crear un entorno virtual (recomendado):

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

  3. Instalar dependencias:

    pip install -e .

  4. Cree un archivo .env basado en .env.example :

    cp .env.example .env

  5. Configure sus variables de entorno en el archivo .env :

    GREPTILE_API_KEY=your_api_key_here
GITHUB_TOKEN=your_github_token_here

Uso de Docker (recomendado para la implementación)

  1. Clonar el repositorio:

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

  2. Cree un archivo .env basado en .env.example y configure sus variables de entorno.

  3. Construya la imagen de Docker:

    docker build -t greptile-mcp .

Ejecución del servidor

Usando pip

Transporte SSE (predeterminado)

Asegúrese de que TRANSPORT=sse y PORT=8050 (o el puerto elegido) estén configurados en su archivo .env .

python -m src.main

El servidor escuchará en http://<HOST>:<PORT>/sse .

Transporte de Studio

Establezca TRANSPORT=stdio en su archivo .env . Con stdio, el cliente MCP normalmente inicia el proceso del servidor MCP.

# Usually invoked by an MCP client, not directly
TRANSPORT=stdio python -m src.main

Usando Docker

Transporte SSE (predeterminado)

# Mounts the .env file for configuration and maps the port
docker run --rm --env-file .env -p 8050:8050 greptile-mcp

El servidor escuchará en http://localhost:8050/sse (o la IP del host si no es localhost).

Transporte de Studio

Configure su cliente MCP para ejecutar el contenedor Docker con TRANSPORT=stdio .

# Example of running with stdio transport
docker run --rm -i --env-file .env -e TRANSPORT=stdio greptile-mcp

Integración con clientes MCP

Ejemplo de configuración de SSE

Agregue esto a la configuración de su cliente MCP (por ejemplo, mcp_config.json ):

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

Ejemplo de configuración de Python con Stdio

Asegúrese de que TRANSPORT=stdio esté configurado en el entorno donde se ejecuta el comando:

{
  "mcpServers": {
    "greptile": {
      "transport": "stdio",
      "command": "/path/to/your/greptile-mcp/.venv/bin/python",
      "args": ["-m", "src.main"],
      "env": {
        "TRANSPORT": "stdio",
        "GREPTILE_API_KEY": "YOUR-GREPTILE-API-KEY",
        "GITHUB_TOKEN": "YOUR-GITHUB-TOKEN",
        "GREPTILE_BASE_URL": "https://api.greptile.com/v2"
      }
    }
  }
}

Ejemplo de configuración de Docker con Stdio

{
  "mcpServers": {
    "greptile": {
      "transport": "stdio",
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "TRANSPORT=stdio",
        "-e", "GREPTILE_API_KEY",
        "-e", "GITHUB_TOKEN",
        "-e", "GREPTILE_BASE_URL",
        "greptile-mcp"
      ],
      "env": {
        "GREPTILE_API_KEY": "YOUR-GREPTILE-API-KEY",
        "GITHUB_TOKEN": "YOUR-GITHUB-TOKEN",
        "GREPTILE_BASE_URL": "https://api.greptile.com/v2"
      }
    }
  }
}

Guía de uso detallada

Flujo de trabajo para el análisis de código base

  1. Repositorios de índices que desea analizar utilizando index_repository

  2. Verifique el estado de indexación con get_repository_info para garantizar que el procesamiento esté completo

  3. Consulta los repositorios usando lenguaje natural con query_repository

  4. Encuentre archivos específicos relacionados con características o conceptos usando search_repository

Gestión de sesiones para el contexto de conversación

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

  1. Generar un ID de sesión único al comienzo de una conversación

  2. Reutilice el mismo ID de sesión para todas las consultas de seguimiento relacionadas

  3. 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 de Smithery : Los agentes que se conectan a través de Smithery deben generar y mantener sus propios ID de sesión. El servidor MCP de Greptile no genera ID de sesión automáticamente. El ID de sesión debe formar parte del estado de conversación del agente.

Mejores prácticas

  • Rendimiento de indexación : Los repositorios pequeños indexan más rápido. Para repositorios mono grandes, considere indexar ramas o etiquetas específicas.

  • Optimización de consultas : Sea específico en sus consultas. Incluya términos técnicos relevantes para obtener mejores resultados.

  • Selección de repositorio : al consultar varios repositorios, enumérelos en orden de relevancia para obtener los mejores resultados.

  • Gestión de sesiones : utilice identificadores de sesión para preguntas de seguimiento a fin de mantener el contexto en todas las consultas.

Referencia de API

1. Repositorio de índices

Indexa un repositorio para que pueda buscarse en futuras consultas.

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, "principal")

  • 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 se complete la indexación

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. Repositorio de consultas

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

Parámetros:

  • query (cadena): La consulta en lenguaje natural sobre el código base

  • repositories (matriz): Lista de repositorios para 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 utilizar 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 el repositorio

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

Parámetros:

  • query (cadena): La consulta de búsqueda sobre el código base

  • repositories (matriz): Lista de repositorios para buscar

  • session_id (cadena, opcional): ID de sesión para continuar una conversación

  • genius (booleano, opcional): si se deben utilizar capacidades de búsqueda mejoradas

Ejemplo:

// Tool Call: search_repository
{
  "query": "Find files related to authentication middleware",
  "repositories": [
    {
      "remote": "github",
      "repository": "greptileai/greptile", 
      "branch": "main"
    }
  ],
  "session_id": null,
  "genius": true
}

Respuesta:

{
  "sources": [
    {
      "repository": "greptileai/greptile",
      "remote": "github",
      "branch": "main",
      "filepath": "/src/auth/middleware.js",
      "linestart": 1,
      "lineend": 45,
      "summary": "Authentication middleware implementation"
    },
    {
      "repository": "greptileai/greptile",
      "remote": "github",
      "branch": "main",
      "filepath": "/src/auth/jwt.js",
      "linestart": 1,
      "lineend": 78,
      "summary": "JWT token handling functions"
    }
  ]
}

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

Ejemplo:

// Tool Call: get_repository_info
{
  "remote": "github",
  "repository": "greptileai/greptile",
  "branch": "main"
}

Respuesta:

{
  "repository": "greptileai/greptile",
  "remote": "github",
  "branch": "main",
  "private": false,
  "status": "COMPLETED",
  "filesProcessed": 234,
  "numFiles": 234,
  "sha": "a1b2c3d4e5f6..."
}

Ejemplos de integración

1. Integración con Claude.ai a través de la API antrópica

from anthropic import Anthropic
import json
import requests

# Set up Anthropic client
anthropic = Anthropic(api_key="your_anthropic_key")

# Function to call Greptile MCP
def query_code(question, repositories):
    response = requests.post(
        "http://localhost:8050/tools/greptile/query_repository",
        json={
            "query": question,
            "repositories": repositories,
            "genius": True
        }
    )
    return json.loads(response.text)

# Ask Claude with enhanced code context
def ask_claude_with_code_context(question, repositories):
    # Get code context from Greptile
    code_context = query_code(question, repositories)
    
    # Format the context for Claude
    formatted_context = f"Code Analysis Result:\n{code_context['message']}\n\nRelevant Files:\n"
    for source in code_context.get('sources', []):
        formatted_context += f"- {source['filepath']} (lines {source['linestart']}-{source['lineend']})\n"
    
    # Send to Claude with context
    message = anthropic.messages.create(
        model="claude-3-opus-20240229",
        max_tokens=1000,
        messages=[
            {"role": "user", "content": f"Based on this code context:\n\n{formatted_context}\n\nQuestion: {question}"}
        ]
    )
    
    return message.content

# Example usage
answer = ask_claude_with_code_context(
    "How does the authentication system work?",
    [{"remote": "github", "repository": "greptileai/greptile", "branch": "main"}]
)
print(answer)

2. Integración con un chatbot basado en LLM

from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse
import httpx
import json

app = FastAPI()

# Greptile MCP endpoint
GREPTILE_MCP_URL = "http://localhost:8050/tools/greptile"

@app.post("/chat")
async def chat_endpoint(request: Request):
    data = await request.json()
    user_message = data.get("message", "")
    
    # Check if this is a code-related question
    if "code" in user_message or "repository" in user_message or "function" in user_message:
        # Query the repository through Greptile MCP
        async with httpx.AsyncClient() as client:
            response = await client.post(
                f"{GREPTILE_MCP_URL}/query_repository",
                json={
                    "query": user_message,
                    "repositories": [
                        {"remote": "github", "repository": "your-org/your-repo", "branch": "main"}
                    ],
                    "genius": True
                }
            )
            
            greptile_result = response.json()
            
            # Process the result and return to the user
            answer = greptile_result.get("message", "")
            sources = greptile_result.get("sources", [])
            
            return JSONResponse({
                "message": answer,
                "code_references": sources
            })
    
    # For non-code questions, use your regular LLM
    return JSONResponse({
        "message": "This appears to be a general question. I'll handle it normally."
    })

# Run with: uvicorn app:app --reload

3. Herramienta de consulta de código de línea de comandos

#!/usr/bin/env python3
import argparse
import json
import requests
import sys

def main():
    parser = argparse.ArgumentParser(description="Query code repositories using natural language")
    parser.add_argument("query", help="The natural language query about the code")
    parser.add_argument("--repo", "-r", required=True, help="Repository in format github:owner/repo:branch")
    parser.add_argument("--genius", "-g", action="store_true", help="Use enhanced query capabilities")
    args = parser.parse_args()
    
    # Parse the repository string
    try:
        remote, repo_path = args.repo.split(":", 1)
        if ":" in repo_path:
            repo, branch = repo_path.split(":", 1)
        else:
            repo = repo_path
            branch = "main"
    except ValueError:
        print("Error: Repository must be in format 'github:owner/repo:branch' or 'github:owner/repo'")
        sys.exit(1)
        
    # Prepare the request
    payload = {
        "query": args.query,
        "repositories": [
            {
                "remote": remote,
                "repository": repo,
                "branch": branch
            }
        ],
        "genius": args.genius
    }
    
    # Make the request
    try:
        response = requests.post(
            "http://localhost:8050/tools/greptile/query_repository",
            json=payload
        )
        response.raise_for_status()
    except requests.exceptions.RequestException as e:
        print(f"Error: {e}")
        sys.exit(1)
    
    # Process the response
    result = response.json()
    
    # Display the answer
    print("\n=== ANSWER ===\n")
    print(result.get("message", "No answer found"))
    
    # Display the sources
    sources = result.get("sources", [])
    if sources:
        print("\n=== CODE REFERENCES ===\n")
        for i, source in enumerate(sources, 1):
            print(f"{i}. {source['filepath']} (lines {source.get('linestart', '?')}-{source.get('lineend', '?')})")
            print(f"   Repository: {source['repository']} ({source['branch']})")
            if 'summary' in source:
                print(f"   Summary: {source['summary']}")
            print()

if __name__ == "__main__":
    main()

Solución de problemas

Problemas comunes

1. Fallos de autenticación

Síntoma : recibe el error 401 Unauthorized o Repository not found with configured credentials .

Soluciones :

  • Verifique que su clave API de Greptile sea válida y esté configurada correctamente en el archivo .env

  • Comprueba si tu token de GitHub/GitLab ha expirado (normalmente expiran después de un período determinado)

  • Asegúrese de que su token de GitHub/GitLab tenga el alcance repo para acceder a los repositorios

  • Pruebe su token de GitHub directamente con la API de GitHub para verificar que funciona

Prueba del token de GitHub :

curl -H "Authorization: token YOUR_GITHUB_TOKEN" https://api.github.com/user

2. Repositorio no encontrado

Síntoma : la API devuelve un error 404 o el mensaje "Repositorio no encontrado".

Soluciones :

  • Verifique que el repositorio exista y sea accesible con su token de GitHub/GitLab

  • Verifique nuevamente el formato del repositorio (debe ser owner/repo )

  • Para repositorios privados, asegúrese de que su token tenga los permisos de acceso adecuados

  • Verifique que el nombre de la sucursal sea correcto

3. Problemas de conexión

Síntoma : No se puede conectar al servidor MCP.

Soluciones :

  • Comprueba si el servidor está en ejecución ( ps aux | grep src.main )

  • Verifique que el puerto no esté siendo utilizado por otra aplicación

  • Compruebe la configuración de red y la configuración del firewall

  • Pruebe un puerto diferente cambiando el valor PORT en su archivo .env

4. Problemas con Docker

Síntoma : el contenedor Docker no se inicia o no funciona correctamente.

Soluciones :

  • Comprobar los registros de Docker: docker logs <container_id>

  • Verifique que el archivo .env esté montado correctamente

  • Asegúrese de que la asignación de puertos sea correcta en su comando docker run

  • Compruebe si la configuración de red de Docker permite las conexiones necesarias

Registros y depuración

Para habilitar un registro más detallado, configure las siguientes variables de entorno:

# Add to your .env file
DEBUG=true
LOG_LEVEL=debug

Para solucionar problemas de interacciones específicas de MCP, examine los registros del servidor MCP:

# Run with enhanced logging
LOG_LEVEL=debug python -m src.main

Configuración avanzada

Variables de entorno

Variable

Descripción

Por defecto

TRANSPORT

Método de transporte ( sse o stdio )

sse

HOST

Host al que vincularse para el transporte SSE

0.0.0.0

PORT

Puerto para transporte SSE

8050

GREPTILE_API_KEY

Su clave API de Greptile

(requerido)

GITHUB_TOKEN

Token de acceso personal de GitHub/GitLab

(requerido)

GREPTILE_BASE_URL

URL base de la API de Greptile

https://api.greptile.com/v2

DEBUG

Habilitar el modo de depuración

false

LOG_LEVEL

Nivel de registro

info

Puntos finales de API personalizados

Si necesita utilizar un punto final de API de Greptile personalizado (por ejemplo, para instalaciones empresariales), modifique la variable de entorno GREPTILE_BASE_URL :

GREPTILE_BASE_URL=https://greptile.your-company.com/api/v2

Ajuste del rendimiento

Para implementaciones de producción, considere estas optimizaciones de rendimiento:

  1. Configuración del trabajador : al utilizar el transporte SSE con Uvicorn, configure la cantidad de trabajadores adecuada:

    # For CPU-bound applications: workers = 1-2 × CPU cores
uvicorn src.main:app --workers 4

  2. Configuración de tiempo de espera : ajuste los tiempos de espera para repositorios grandes:

    # Add to .env
GREPTILE_TIMEOUT=120.0  # Default is 60.0 seconds

  3. Optimización de la memoria : para implementaciones grandes, tenga en cuenta los límites de recursos del contenedor:

    docker run --rm --env-file .env -p 8050:8050 --memory="1g" --cpus="1.0" greptile-mcp

Contribuyendo

¡Agradecemos sus contribuciones! No dude en enviar una solicitud de incorporación de cambios.

  1. Bifurcar el repositorio

  2. Crea tu rama de funciones ( git checkout -b feature/amazing-feature )

  3. Confirme sus cambios ( git commit -m 'Add some amazing feature' )

  4. Empujar a la rama ( git push origin feature/amazing-feature )

  5. Abrir una solicitud de extracción

Configuración de desarrollo

Para el desarrollo, instale dependencias adicionales:

pip install -e ".[dev]"

Ejecutar pruebas:

pytest

Licencia

Este proyecto está licenciado bajo la licencia MIT: consulte el archivo de LICENCIA para obtener más detalles.

Desarrollado por ( https://github.com/sosacrazy126 )

Available Tools

5 tools
get_repository_infoC

Get information about an indexed repository including status and metadata

ParametersJSON Schema
NameRequiredDescriptionDefault
remoteYesRepository host
repositoryYesRepository in owner/repo format
branchYesBranch that was indexed

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It states the tool retrieves information, implying it's read-only, but doesn't disclose behavioral traits like authentication requirements, rate limits, error conditions, or what 'indexed' means operationally. The description is minimal and lacks context about the tool's behavior beyond its basic function.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that front-loads the core purpose. Every word earns its place, with no redundant or vague language. It's appropriately sized for a simple retrieval tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations and no output schema, the description is incomplete for a tool with 3 required parameters. It doesn't explain what 'indexed' entails, what 'status and metadata' includes, or the response format. For a retrieval tool with structured inputs, more context is needed to guide effective use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with clear descriptions for all parameters (e.g., 'Repository host', 'Repository in owner/repo format', 'Branch that was indexed'). The description adds no additional semantic meaning beyond the schema, such as explaining format constraints or relationships between parameters. Baseline 3 is appropriate as the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Get' and the resource 'information about an indexed repository', specifying it includes 'status and metadata'. This distinguishes it from sibling tools like 'index_repository' (which creates) and 'query_repository' (which searches content), but doesn't explicitly differentiate from 'greptile_env_check' or 'greptile_help' in terms of scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., that the repository must already be indexed), exclusions, or compare to siblings like 'query_repository' for different types of information needs. Usage is implied but not explicitly stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

greptile_env_checkB

Check environment variable configuration and setup status

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states what the tool does but doesn't describe how it behaves—for example, whether it's a read-only check, what output format to expect, if it has side effects, or any error conditions. This leaves significant gaps in understanding the tool's operational characteristics.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that directly states the tool's function without any wasted words. It's appropriately sized for a simple tool and front-loaded with the core purpose, making it easy for an agent to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (0 parameters, no output schema, no annotations), the description is adequate but has clear gaps. It explains what the tool does but lacks details on behavioral traits, usage context, or output expectations, which are important even for simple tools to ensure correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has 0 parameters, and the input schema has 100% description coverage (though empty). The description doesn't need to add parameter information, so it appropriately focuses on the tool's purpose. A baseline score of 4 is applied since no parameters exist, and the description doesn't attempt to explain nonexistent parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose as checking environment variable configuration and setup status, which is a specific verb+resource combination. However, it doesn't differentiate itself from sibling tools like 'get_repository_info' or 'greptile_help', which might also provide status information, so it doesn't reach the highest score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention any prerequisites, exclusions, or specific contexts for usage, leaving the agent to infer when this check is appropriate compared to other tools on the server.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

greptile_helpA

Get comprehensive help and usage examples for all Greptile MCP tools

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It states the tool provides 'comprehensive help and usage examples,' which suggests it's a read-only, informational resource without side effects. However, it lacks details on behavioral traits like response format, potential rate limits, or error handling, which would be useful given the absence of annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that clearly conveys the tool's function without any wasted words. It's front-loaded with the core purpose ('Get comprehensive help and usage examples') and specifies the scope ('for all Greptile MCP tools'), making it easy to understand at a glance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (0 parameters, no output schema, no annotations), the description is adequate but could be more complete. It covers the basic purpose but doesn't address potential context like what 'comprehensive help' includes, whether it's interactive, or how it integrates with sibling tools. For a help tool in this environment, more detail on output or usage scenarios would enhance completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has 0 parameters, and schema description coverage is 100%, so there's no need for parameter details in the description. The baseline for 0 parameters is 4, as the description appropriately focuses on the tool's purpose without unnecessary parameter explanations.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Get comprehensive help and usage examples for all Greptile MCP tools.' It specifies the verb ('Get') and resource ('help and usage examples'), and the scope ('for all Greptile MCP tools') is well-defined. However, it doesn't explicitly differentiate from sibling tools like 'greptile_env_check' which might also provide system information.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage context—when users need help or examples for Greptile tools—but doesn't provide explicit guidance on when to use this tool versus alternatives. There's no mention of prerequisites, timing, or comparisons to sibling tools like 'get_repository_info' or 'query_repository', leaving usage somewhat open to interpretation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

index_repositoryC

Index a repository to make it searchable for future queries

ParametersJSON Schema
NameRequiredDescriptionDefault
remoteYesRepository host (github or gitlab)
repositoryYesRepository in owner/repo format
branchYesBranch to index
reloadNoForce reprocessing of previously indexed repository
notifyNoSend email notification when indexing completes

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden but offers limited behavioral insight. It mentions the outcome ('make it searchable') but omits critical details: whether indexing is idempotent, time-consuming, or requires specific permissions; what 'searchable' entails (e.g., content types indexed); or side effects like notifications. The 'reload' and 'notify' parameters hint at reprocessing and notifications, but the description doesn't explain these behaviors.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that front-loads the core action ('index a repository') and purpose ('make it searchable'). It avoids redundancy and waste, though it could be slightly more informative without losing conciseness. Structure is clear but minimal.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations, no output schema, and a mutation tool (indexing implies write operation), the description is incomplete. It lacks details on behavioral traits (e.g., idempotency, performance), output format, error handling, or dependencies. For a 5-parameter tool that modifies state, more context is needed to guide safe and effective use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema fully documents all 5 parameters (remote, repository, branch, reload, notify). The description adds no parameter-specific information beyond implying indexing scope, but doesn't detail how parameters interact (e.g., 'reload' vs. initial indexing). Baseline is 3 since the schema handles parameter documentation adequately.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('index') and resource ('repository') with a specific purpose ('to make it searchable for future queries'). It distinguishes from siblings like 'get_repository_info' (read-only info) and 'query_repository' (search after indexing), though it doesn't explicitly name alternatives. The purpose is specific but could be more precise about what 'indexing' entails.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides minimal guidance, stating the tool makes repositories searchable for future queries, which implies it should be used before querying. However, it lacks explicit when-to-use rules (e.g., prerequisites, timing), when-not-to-use scenarios (e.g., if already indexed), or named alternatives like 'reload' parameter for reprocessing. No sibling tools are referenced for comparison.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

query_repositoryC

Query repositories using natural language to get detailed answers with code references

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesNatural language query about the codebase
repositoriesNoList of repositories to query
session_idNoSession ID for conversation continuity (auto-generated if not provided)
streamNoEnable streaming response
geniusNoUse enhanced query capabilities
timeoutNoRequest timeout in milliseconds
previous_messagesNoPrevious conversation messages for context

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions 'natural language querying' and 'detailed answers with code references,' but fails to describe critical behaviors such as authentication requirements, rate limits, error handling, or what constitutes a 'detailed answer.' For a complex tool with 7 parameters, this is a significant gap in transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that clearly states the tool's core functionality without unnecessary details. It's front-loaded with the main purpose and avoids redundancy, making it easy for an agent to parse quickly. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (7 parameters, no annotations, no output schema), the description is insufficient. It lacks information on behavioral traits, output format, error conditions, and how it differs from siblings. For a query tool that likely returns structured data, the absence of output details and usage context makes it incomplete for effective agent operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage, so each parameter is documented in the schema itself. The description adds no additional semantic context beyond implying natural language input for the 'query' parameter. This meets the baseline of 3, as the schema handles the heavy lifting, but the description doesn't enhance understanding of parameter usage or interactions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Query repositories using natural language to get detailed answers with code references.' It specifies the action (query), resource (repositories), and outcome (detailed answers with code references). However, it doesn't explicitly differentiate from sibling tools like 'get_repository_info' or 'index_repository', which prevents a perfect score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'get_repository_info' for metadata or 'index_repository' for preparation, nor does it specify scenarios where this tool is preferred. This lack of comparative context leaves the agent without clear usage direction.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 5 tool updates
    • First observedget_repository_info
    • First observedgreptile_env_check
    • First observedgreptile_help
    • First observedindex_repository
    • First observedquery_repository
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.4/5.0

Scored across 5 tools

Disambiguation5/5

Each tool has a clearly distinct purpose with no overlap. get_repository_info retrieves metadata, greptile_env_check verifies setup, greptile_help provides documentation, index_repository prepares data, and query_repository performs searches. An agent can easily differentiate them.

Naming Consistency3/5

The naming is mixed: three tools use a verb_noun pattern (get_repository_info, index_repository, query_repository), while two use a noun_verb pattern (greptile_env_check, greptile_help). This inconsistency is noticeable but still readable, as all names are descriptive and in snake_case.

Tool Count5/5

With 5 tools, this server is well-scoped for its purpose of repository indexing and querying. Each tool earns its place by covering essential functions like setup, indexing, querying, and help, without being overly sparse or bloated.

Completeness4/5

The tool set covers the core workflow for a repository search service: environment setup, indexing, querying, and metadata retrieval, with a help tool for guidance. A minor gap is the lack of tools for managing indexed repositories (e.g., delete or update), but agents can work around this.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers