Greptile

Servidor MCP Greptile

Uma implementação de servidor MCP (Model Context Protocol) que se integra à API Greptile para fornecer recursos de busca e consulta de código a agentes de IA.

Recursos

O servidor fornece quatro ferramentas essenciais do Greptile que permitem que agentes de IA interajam com bases de código:

1. index_repository: Indexar um repositório para busca e consulta de código.
   • Processar um repositório para torná-lo pesquisável
   • Atualizar índices existentes quando os repositórios mudam
   • Configurar preferências de notificação
2. query_repository: Consultar repositórios para obter respostas com referências de código.
   • Fazer perguntas em linguagem natural sobre a base de código
   • Obter respostas detalhadas que referenciam locais específicos do código
   • Suporte a histórico de conversas com IDs de sessão
3. search_repository: Buscar em repositórios arquivos relevantes sem gerar uma resposta completa.
   • Encontrar arquivos relacionados a conceitos ou recursos específicos
   • Obter correspondências contextuais classificadas por relevância
   • Mais rápido que consultas completas quando apenas locais de arquivos são necessários
4. get_repository_info: Obter informações sobre um repositório indexado.
   • Verificar status e progresso da indexação
   • Confirmar quais repositórios estão disponíveis para consulta
   • Obter metadados sobre repositórios indexados

Implantação com Smithery

O servidor MCP Greptile suporta implantação via Smithery. Um arquivo de configuração smithery.yaml está incluído na raiz do projeto.

Configuração do Smithery

A configuração do Smithery é definida em smithery.yaml e suporta as seguintes opções:

build: dockerfile: Dockerfile

startCommand: type: stdio configSchema: type: object required: - greptileApiKey - githubToken properties: greptileApiKey: type: string description: "Chave de API para acessar a API Greptile" githubToken: type: string description: "Token de Acesso Pessoal do GitHub para acesso ao repositório" host: type: string description: "Host ao qual vincular ao usar transporte SSE" default: "0.0.0.0" port: type: string description: "Porta para escutar ao usar transporte SSE" default: "8050"

Usando com Smithery

Para implantar usando Smithery:

1. Instale o Smithery: npm install -g smithery
2. Implante o servidor: smithery deploy
3. Configure seu cliente Smithery com as chaves de API necessárias

Pré-requisitos

• Python 3.12+
• Chave de API Greptile (de https://app.greptile.com/settings/api)
• Token de Acesso Pessoal (PAT) do GitHub ou GitLab com permissões repo (ou leitura equivalente) para os repositórios que você pretende indexar
• Docker (recomendado para implantação)

Pacotes Python Necessários

• fastmcp - Implementação do servidor MCP
• httpx - Cliente HTTP assíncrono
• python-dotenv - Gerenciamento de variáveis de ambiente
• uvicorn - Servidor ASGI para transporte SSE

Instalação

Usando pip

1. Clone este repositório:
   git clone https://github.com/sosacrazy126/greptile-mcp.git
   cd greptile-mcp
2. Crie um ambiente virtual:
   python -m venv .venv
   source .venv/bin/activate # No Windows use .venv\Scripts\activate
3. Instale as dependências:
   pip install -r requirements.txt
4. Defina suas variáveis de ambiente:
   export GREPTILE_API_KEY=sua_chave_api_aqui
   export GITHUB_TOKEN=seu_token_github_aqui

Usando Docker

1. Clone o repositório:
   git clone https://github.com/sosacrazy126/greptile-mcp.git
   cd greptile-mcp
2. Construa a imagem Docker:
   docker build -t greptile-mcp .

Executando o Servidor

O servidor MCP Greptile suporta dois modos de operação:

1. Modo MCP (Padrão)

Servidor MCP tradicional para integração direta com clientes MCP.

Usando pip

python -m src.main

Usando Docker

docker run --rm -e GREPTILE_API_KEY=sua_chave -e GITHUB_TOKEN=seu_token -p 8050:8050 greptile-mcp

2. Modo HTTP/JSON-RPC (Novo)

Servidor HTTP que fornece interface JSON-RPC 2.0 para aplicações web e clientes REST.

Usando pip

python -m src.main_http

Usando Docker (Modo HTTP)

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

Modo de Desenvolvimento (com recarga automática)

python -m src.main_http --dev

Recursos do Modo HTTP

• API compatível com JSON-RPC 2.0 em /json-rpc
• Documentação interativa em /docs (Swagger UI)
• Documentação alternativa em /redoc
• Endpoint de verificação de saúde em /health
• Documentação de métodos em /api/methods
• Limitação de taxa (100 solicitações/hora por IP)
• Suporte a CORS para aplicações web

Exemplos de Uso HTTP

Usando curl

Indexar um repositório

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" }'

Consultar um repositório

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

Usando JavaScript/fetch

// Indexar um repositório 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('Resultado da indexação:', indexResult);

// Consultar o repositório 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: 'Como funciona o ciclo de vida do componente?', repositories: [ { remote: 'github', repository: 'facebook/react', branch: 'main' } ] }, id: '2' }) });

const queryResult = await queryResponse.json(); console.log('Resultado da consulta:', queryResult);

Usando Python requests

import requests import json

Configuração

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

Indexar um repositório

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("Resultado da indexação:", response.json())

Consultar o repositório

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

response = requests.post(base_url, headers=headers, json=query_payload) print("Resultado da consulta:", response.json())

Integração com Clientes MCP

Configure seu cliente MCP para conectar ao servidor:

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

Guia de Uso Detalhado

Fluxo de Trabalho para Análise de Base de Código

1. Indexe os repositórios que deseja analisar usando index_repository
2. Verifique o status da indexação com get_repository_info para garantir que o processamento foi concluído
3. Consulte os repositórios usando linguagem natural com query_repository
4. Encontre arquivos específicos relacionados a recursos ou conceitos usando search_repository

Gerenciamento de Sessão para Contexto de Conversa

Ao interagir com o servidor MCP Greptile por meio de qualquer cliente (incluindo Smithery), o gerenciamento adequado de sessão é crucial para manter o contexto da conversa:

1. Gere um ID de sessão único no início de uma conversa
2. Reutilize o mesmo ID de sessão para todas as perguntas de acompanhamento relacionadas
3. Crie um novo ID de sessão ao iniciar uma nova conversa

Exemplo de gerenciamento de ID de sessão:

Gerar um ID de sessão único

import uuid session_id = str(uuid.uuid4())

Consulta inicial

initial_response = query_repository( query="Como a autenticação é implementada?", repositories=[{"remote": "github", "repository": "owner/repo", "branch": "main"}], session_id=session_id # Incluir o ID da sessão )

Consulta de acompanhamento usando o MESMO ID de sessão

followup_response = query_repository( query="Você pode fornecer mais detalhes sobre a verificação JWT?", repositories=[{"remote": "github", "repository": "owner/repo", "branch": "main"}], session_id=session_id # Reutilizar o mesmo ID de sessão )

Importante para Integração com Smithery: Agentes que se conectam via Smithery devem gerar e manter seus próprios IDs de sessão. O servidor MCP Greptile NÃO gera IDs de sessão automaticamente. O ID de sessão deve fazer parte do estado da conversa do agente.

Melhores Práticas

• Desempenho de Indexação: Repositórios menores indexam mais rápido. Para monorepos grandes, considere indexar branches ou tags específicas.
• Otimização de Consultas: Seja específico em suas consultas. Inclua termos técnicos relevantes para melhores resultados.
• Seleção de Repositórios: Ao consultar vários repositórios, liste-os em ordem de relevância para obter os melhores resultados.
• Gerenciamento de Sessão: Use IDs de sessão para perguntas de acompanhamento e mantenha o contexto entre consultas.

Referência da API

1. Indexar Repositório

Indexa um repositório para torná-lo pesquisável em consultas futuras.

Parâmetros:

• remote (string): O host do repositório, "github" ou "gitlab"
• repository (string): O repositório no formato proprietário/repositório (ex.: "greptileai/greptile")
• branch (string): O branch a ser indexado (ex.: "main")
• reload (boolean, opcional): Se deve forçar o reprocessamento de um repositório previamente indexado
• notify (boolean, opcional): Se deve enviar uma notificação por e-mail quando a indexação for concluída

Exemplo:

// Chamada de Ferramenta: index_repository { "remote": "github", "repository": "greptileai/greptile", "branch": "main", "reload": false, "notify": false }

Resposta:

{ "message": "Trabalho de Indexação Enviado para: greptileai/greptile", "statusEndpoint": "https://api.greptile.com/v2/repositories/github:main:greptileai%2Fgreptile" }

2. Consultar Repositório

Consulta repositórios com linguagem natural para obter respostas com referências de código.

Parâmetros:

• query (string): A consulta em linguagem natural sobre a base de código
• repositories (array): Lista de repositórios a consultar, cada um no formato:
  {
  "remote": "github",
  "repository": "owner/repo",
  "branch": "main"
  }
• session_id (string, opcional): ID da sessão para continuar uma conversa
• stream (boolean, opcional): Se deve transmitir a resposta
• genius (boolean, opcional): Se deve usar recursos aprimorados de consulta

Exemplo:

// Chamada de Ferramenta: query_repository { "query": "Como a autenticação é tratada nesta base de código?", "repositories": [ { "remote": "github", "repository": "greptileai/greptile", "branch": "main" } ], "session_id": null, "stream": false, "genius": true }

Resposta:

{ "message": "A autenticação nesta base de código é tratada usando tokens JWT...", "sources": [ { "repository": "greptileai/greptile", "remote": "github", "branch": "main", "filepath": "/src/auth/jwt.js", "linestart": 14, "lineend": 35, "summary": "Middleware de validação de token JWT" } ] }

3. Buscar no Repositório

Busca em repositórios para encontrar arquivos relevantes sem gerar uma resposta completa.

Parâmetros:

• query (string): A consulta de busca sobre o codebase
• repositories (array): Lista de repositórios para buscar
• session_id (string, opcional): ID da sessão para continuar uma conversa
• genius (boolean, opcional): Se deve usar recursos de busca aprimorados

4. Obter Informações do Repositório

Obtém informações sobre um repositório específico que foi indexado.

Parâmetros:

• remote (string): O host do repositório, "github" ou "gitlab"
• repository (string): O repositório no formato proprietário/repositório
• branch (string): O branch que foi indexado

Variáveis de Ambiente

Variável	Descrição	Padrão
GREPTILE_API_KEY	Sua chave de API do Greptile	(obrigatório)
GITHUB_TOKEN	Token de acesso pessoal do GitHub/GitLab	(obrigatório)
HOST	Host para vincular	0.0.0.0
PORT	Porta para escutar	8050

Licença

Este projeto está licenciado sob a Licença MIT.

---

Construído por @sosacrazy126