greptile-mcp

Сервер Greptile MCP [ЗАВЕРШЕНО]

Шпаргалка по командам быстрого запуска

✅ СТАТУС ПРОЕКТА: ВСЕ ЗАДАЧИ ВЫПОЛНЕНЫ (11/11)

Краткое описание выполненной работы см. в файле PROJECT_COMPLETION.md , а инструкции по использованию — в файле USER_GUIDE.md .

Среда	Настройка и установка	Выполнить команду
Локальный (Python)	`python -m venv .venv && source .venv/bin/activate && pip install -e .`	`python -m src.main`
Докер	`docker build -t greptile-mcp .`	`docker run --rm --env-file .env -p 8050:8050 greptile-mcp`
Кузнечное дело	`npm install -g smithery`	`smithery deploy` (см. smithery.yaml)

Заполните .env с помощью .env.example и задайте GREPTILE_API_KEY и GITHUB_TOKEN перед запуском.

Полные предварительные требования, расширенное использование агента, интеграция и устранение неполадок см. в полной документации в docs/README.md и сведения об агенте в AGENT_USAGE.md .

Реализация сервера MCP (Model Context Protocol), которая интегрируется с API Greptile для предоставления возможностей поиска кода и запросов агентам ИИ.

Функции

Сервер предоставляет четыре основных инструмента Greptile, которые позволяют агентам ИИ взаимодействовать с кодовыми базами:

index_repository : индексирует репозиторий для поиска кода и запросов.
- Обработать репозиторий, чтобы сделать его доступным для поиска
- Обновляйте существующие индексы при изменении репозиториев
- Настройте параметры уведомлений
query_repository : Запрос к репозиториям для получения ответов со ссылками на код.
- Задавайте вопросы на естественном языке о кодовой базе
- Получите подробные ответы, которые ссылаются на конкретные места кода.
- Поддержка истории разговоров с идентификаторами сеансов
search_repository : Поиск релевантных файлов в репозиториях без генерации полного ответа.
- Найдите файлы, связанные с определенными концепциями или функциями
- Получите контекстные совпадения, ранжированные по релевантности
- Быстрее, чем полные запросы, когда нужны только местоположения файлов
get_repository_info : Получить информацию об индексированном репозитории.
- Проверьте статус и ход индексации
- Проверьте, какие репозитории доступны для запроса
- Получить метаданные об индексированных репозиториях

Развертывание кузницы

Сервер Greptile MCP поддерживает развертывание через Smithery. Файл конфигурации smithery.yaml включен в корень проекта.

Конфигурация кузницы

Конфигурация Smithery определена в smithery.yaml и поддерживает следующие параметры:

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"

Использование с кузнечным делом

Для развертывания с помощью Smithery:

Установить Smithery: npm install -g smithery
Развертывание сервера: smithery deploy
Настройте свой клиент Smithery с помощью необходимых ключей API

Дополнительная документация

Подробные инструкции по использованию агентов ИИ см. в Руководстве по использованию агентов .

Предпосылки

Питон 3.12+
Ключ API Greptile (из https://app.greptile.com/settings/api )
GitHub или GitLab Personal Access Token (PAT) с разрешениями repo (или эквивалентными) для репозиториев, которые вы собираетесь индексировать
Docker (рекомендуется для развертывания)

Требуемые пакеты Python

fastmcp - реализация MCP-сервера
httpx - Асинхронный HTTP-клиент
python-dotenv - Управление переменными среды
uvicorn — сервер ASGI для транспорта SSE

Установка

Использование pip (для разработки или локального тестирования)

Клонируйте этот репозиторий:
git clone https://github.com/sosacrazy126/greptile-mcp.git cd greptile-mcp
Создать виртуальную среду (рекомендуется):
python -m venv .venv source .venv/bin/activate # On Windows use `.venv\Scripts\activate`
Установить зависимости:
pip install -e .
Создайте файл .env на основе .env.example :
cp .env.example .env
Настройте переменные среды в файле .env :
GREPTILE_API_KEY=your_api_key_here GITHUB_TOKEN=your_github_token_here

Использование Docker (рекомендуется для развертывания)

Клонируйте репозиторий:
git clone https://github.com/sosacrazy126/greptile-mcp.git cd greptile-mcp
Создайте файл .env на основе .env.example и настройте переменные среды.
Создайте образ Docker:
docker build -t greptile-mcp .

Запуск сервера

Использование пипа

Транспорт SSE (по умолчанию)

Убедитесь, что в файле .env установлены TRANSPORT=sse и PORT=8050 (или выбранный вами порт).

python -m src.main

Сервер будет прослушивать http://<HOST>:<PORT>/sse .

Stdio Транспорт

Установите TRANSPORT=stdio в вашем .env файле. С помощью stdio клиент MCP обычно раскручивает процесс сервера MCP.

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

Использование Докера

Транспорт SSE (по умолчанию)

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

Сервер будет прослушивать http://localhost:8050/sse (или IP-адрес хоста, если он не локальный).

Stdio Транспорт

Настройте клиент MCP для запуска контейнера Docker с помощью TRANSPORT=stdio .

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

Интеграция с клиентами MCP

Пример конфигурации SSE

Добавьте это в конфигурацию вашего клиента MCP (например, mcp_config.json ):

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

Пример конфигурации Python с Stdio

Убедитесь, что в среде, где выполняется команда, задан TRANSPORT=stdio :

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

Пример конфигурации Docker с 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"
      }
    }
  }
}

Подробное руководство по использованию

Рабочий процесс анализа кодовой базы

Индексные репозитории, которые вы хотите проанализировать с помощью index_repository
Проверьте статус индексации с помощью get_repository_info , чтобы убедиться, что обработка завершена.
Запросите репозитории , используя естественный язык с помощью query_repository
Найдите определенные файлы, связанные с функциями или концепциями, с помощью search_repository

Управление сеансом для контекста разговора

При взаимодействии с сервером Greptile MCP через любого клиента (включая Smithery) правильное управление сеансом имеет решающее значение для поддержания контекста разговора:

Генерируйте уникальный идентификатор сеанса в начале разговора
Повторно используйте один и тот же идентификатор сеанса для всех связанных последующих запросов.
Создайте новый идентификатор сеанса при начале нового разговора.

Пример управления идентификатором сеанса:

# 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
)

Важно для интеграции Smithery : Агенты, подключающиеся через Smithery, должны генерировать и поддерживать собственные идентификаторы сеансов. Сервер Greptile MCP НЕ генерирует идентификаторы сеансов автоматически. Идентификатор сеанса должен быть частью состояния разговора агента.

Лучшие практики

Производительность индексации : Меньшие репозитории индексируются быстрее. Для больших монорепозиториев рассмотрите возможность индексации определенных ветвей или тегов.
Оптимизация запросов : будьте конкретны в своих запросах. Включайте соответствующие технические термины для лучших результатов.
Выбор репозитория : при запросе нескольких репозиториев перечислите их в порядке релевантности, чтобы получить наилучшие результаты.
Управление сеансами : используйте идентификаторы сеансов для последующих вопросов, чтобы поддерживать контекст между запросами.

Ссылка на API

1. Индексный репозиторий

Индексирует репозиторий, чтобы сделать его доступным для поиска в будущих запросах.

Параметры:

remote (строка): Хост репозитория, либо «github», либо «gitlab»
repository (строка): репозиторий в формате владелец/репозиторий (например, «greptileai/greptile»)
branch (строка): ветвь для индексации (например, «main»)
reload (логическое значение, необязательно): следует ли принудительно выполнять повторную обработку ранее проиндексированного репозитория.
notify (логическое значение, необязательно): отправлять ли уведомление по электронной почте после завершения индексации

Пример:

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

Ответ:

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

2. Запросить репозиторий

Запрашивает репозитории на естественном языке, чтобы получить ответы со ссылками на код.

Параметры:

query (строка): запрос на естественном языке о кодовой базе
repositories (массив): Список репозиториев для запроса, каждый в формате:
{ "remote": "github", "repository": "owner/repo", "branch": "main" }
session_id (строка, необязательно): идентификатор сеанса для продолжения разговора
stream (логическое значение, необязательно): следует ли передавать ответ в потоковом режиме
genius (логическое значение, необязательно): следует ли использовать расширенные возможности запроса

Пример:

// 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
}

Ответ:

{
  "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. Поиск в репозитории

Выполняет поиск соответствующих файлов в репозиториях, не создавая полный ответ.

Параметры:

query (строка): поисковый запрос о кодовой базе
repositories (массив): Список репозиториев для поиска
session_id (строка, необязательно): идентификатор сеанса для продолжения разговора
genius (логическое значение, необязательно): использовать ли расширенные возможности поиска

Пример:

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

Ответ:

{
  "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. Получить информацию о репозитории

Получает информацию о конкретном репозитории, который был проиндексирован.

Параметры:

remote (строка): Хост репозитория, либо «github», либо «gitlab»
repository (строка): Репозиторий в формате владелец/репо
branch (строка): ветвь, которая была проиндексирована.

Пример:

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

Ответ:

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

Примеры интеграции

1. Интеграция с Claude.ai через Anthropic API

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. Интеграция с чат-ботом на базе 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. Инструмент запроса кода командной строки

#!/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()

Поиск неисправностей

Общие проблемы

1. Ошибки аутентификации

Симптом : вы получаете ошибку 401 Unauthorized или Repository not found with configured credentials .

Решения :

Убедитесь, что ваш ключ API Greptile действителен и правильно установлен в файле .env
Проверьте, не истек ли срок действия вашего токена GitHub/GitLab (обычно срок действия токена истекает через определенный период времени)
Убедитесь, что ваш токен GitHub/GitLab имеет область действия repo для доступа к репозиториям
Протестируйте свой токен GitHub напрямую с помощью API GitHub, чтобы убедиться в его работоспособности.

Тестирование токена GitHub :

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

2. Репозиторий не найден

Симптом : API возвращает ошибку 404 или сообщение «Репозиторий не найден».

Решения :

Убедитесь, что репозиторий существует и доступен с вашим токеном GitHub/GitLab.
Дважды проверьте формат репозитория (он должен быть owner/repo )
Для частных репозиториев убедитесь, что ваш токен имеет соответствующие права доступа.
Проверьте правильность названия филиала.

3. Проблемы с подключением

Симптом : невозможно подключиться к серверу MCP.

Решения :

Проверьте, запущен ли сервер ( ps aux | grep src.main )
Убедитесь, что порт не используется другим приложением.
Проверьте настройки сети и конфигурации брандмауэра.
Попробуйте другой порт, изменив значение PORT в файле .env

4. Проблемы с докером

Симптом : Docker-контейнер не запускается или не работает правильно.

Решения :

Проверьте логи Docker: docker logs <container_id>
Убедитесь, что файл .env правильно смонтирован.
Убедитесь, что в вашей команде docker run указано правильное сопоставление портов.
Проверьте, допускает ли сетевая конфигурация Docker требуемые соединения.

Журналы и отладка

Чтобы включить более подробное ведение журнала, установите следующие переменные среды:

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

Для устранения неполадок, связанных с определенными взаимодействиями MCP, проверьте журналы сервера MCP:

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

Расширенная конфигурация

Переменные среды

Переменная	Описание	По умолчанию
`TRANSPORT`	Метод транспортировки ( `sse` или `stdio` )	`sse`
`HOST`	Хост, к которому нужно привязаться для транспорта SSE	`0.0.0.0`
`PORT`	Порт для транспорта SSE	`8050`
`GREPTILE_API_KEY`	Ваш API-ключ Greptile	(необходимый)
`GITHUB_TOKEN`	Персональный токен доступа GitHub/GitLab	(необходимый)
`GREPTILE_BASE_URL`	Базовый URL-адрес API Greptile	`https://api.greptile.com/v2`
`DEBUG`	Включить режим отладки	`false`
`LOG_LEVEL`	Уровень ведения журнала	`info`

Пользовательские конечные точки API

Если вам необходимо использовать пользовательскую конечную точку API Greptile (например, для корпоративных установок), измените переменную среды GREPTILE_BASE_URL :

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

Настройка производительности

Для производственных развертываний рассмотрите следующие варианты оптимизации производительности:

Конфигурация воркеров : при использовании транспорта SSE с Uvicorn настройте соответствующее количество воркеров:
# For CPU-bound applications: workers = 1-2 × CPU cores uvicorn src.main:app --workers 4
Настройки тайм-аута : настройте тайм-ауты для больших репозиториев:
# Add to .env GREPTILE_TIMEOUT=120.0 # Default is 60.0 seconds
Оптимизация памяти : для крупных развертываний учитывайте ограничения ресурсов контейнера:
docker run --rm --env-file .env -p 8050:8050 --memory="1g" --cpus="1.0" greptile-mcp

Внося вклад

Вклады приветствуются! Пожалуйста, не стесняйтесь отправлять запрос на включение.

Форк репозитория
Создайте ветку функций ( git checkout -b feature/amazing-feature )
Зафиксируйте свои изменения ( git commit -m 'Add some amazing feature' )
Отправить в ветку ( git push origin feature/amazing-feature )
Открыть запрос на извлечение

Настройка разработки

Для разработки установите дополнительные зависимости:

pip install -e ".[dev]"

Проведите тесты:

pytest

Лицензия

Данный проект лицензирован по лицензии MIT — подробности см. в файле LICENSE.

Создано ( https://github.com/sosacrazy126 )

Integrations

Сервер Greptile MCP [ЗАВЕРШЕНО]

Функции

Развертывание кузницы

Конфигурация кузницы

Использование с кузнечным делом

Дополнительная документация

Предпосылки

Требуемые пакеты Python

Установка

Использование pip (для разработки или локального тестирования)

Использование Docker (рекомендуется для развертывания)

Запуск сервера

Использование пипа

Транспорт SSE (по умолчанию)

Stdio Транспорт

Использование Докера

Транспорт SSE (по умолчанию)

Stdio Транспорт

Интеграция с клиентами MCP

Пример конфигурации SSE

Пример конфигурации Python с Stdio

Пример конфигурации Docker с Stdio

Подробное руководство по использованию

Рабочий процесс анализа кодовой базы

Управление сеансом для контекста разговора

Лучшие практики

Ссылка на API

1. Индексный репозиторий

2. Запросить репозиторий

3. Поиск в репозитории

4. Получить информацию о репозитории

Примеры интеграции

1. Интеграция с Claude.ai через Anthropic API

2. Интеграция с чат-ботом на базе LLM

3. Инструмент запроса кода командной строки

Поиск неисправностей

Общие проблемы

1. Ошибки аутентификации

2. Репозиторий не найден

3. Проблемы с подключением

4. Проблемы с докером

Журналы и отладка

Расширенная конфигурация

Переменные среды

Пользовательские конечные точки API

Настройка производительности

Внося вклад

Настройка разработки

Лицензия

Related MCP Servers

blocknative-mcp

MCP Expr Lang

argocd-mcpofficial

mcp-linear

New MCP Servers