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

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

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

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

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

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

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

Функции

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

1. index_repository : индексирует репозиторий для поиска кода и запросов.

   • Обработать репозиторий, чтобы сделать его доступным для поиска

   • Обновляйте существующие индексы при изменении репозиториев

   • Настройте параметры уведомлений

2. query_repository : Запрос к репозиториям для получения ответов со ссылками на код.

   • Задавайте вопросы на естественном языке о кодовой базе

   • Получите подробные ответы, которые ссылаются на конкретные места кода.

   • Поддержка истории разговоров с идентификаторами сеансов

3. search_repository : Поиск релевантных файлов в репозиториях без генерации полного ответа.

   • Найдите файлы, связанные с определенными концепциями или функциями

   • Получите контекстные совпадения, ранжированные по релевантности

   • Быстрее, чем полные запросы, когда нужны только местоположения файлов

4. get_repository_info : Получить информацию об индексированном репозитории.

   • Проверьте статус и ход индексации

   • Проверьте, какие репозитории доступны для запроса

   • Получить метаданные об индексированных репозиториях

Related MCP server: Graphiti MCP Server

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

Сервер 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:

1. Установить Smithery: npm install -g smithery

2. Развертывание сервера: smithery deploy

3. Настройте свой клиент 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 (для разработки или локального тестирования)

1. Клонируйте этот репозиторий:

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

2. Создать виртуальную среду (рекомендуется):

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

3. Установить зависимости:

   pip install -e .

4. Создайте файл .env на основе .env.example :

   cp .env.example .env

5. Настройте переменные среды в файле .env :

   GREPTILE_API_KEY=your_api_key_here
   GITHUB_TOKEN=your_github_token_here

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

1. Клонируйте репозиторий:

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

2. Создайте файл .env на основе .env.example и настройте переменные среды.

3. Создайте образ 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"
      }
    }
  }
}

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

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

1. Индексные репозитории, которые вы хотите проанализировать с помощью index_repository

2. Проверьте статус индексации с помощью get_repository_info , чтобы убедиться, что обработка завершена.

3. Запросите репозитории , используя естественный язык с помощью query_repository

4. Найдите определенные файлы, связанные с функциями или концепциями, с помощью search_repository

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

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

1. Генерируйте уникальный идентификатор сеанса в начале разговора

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

3. Создайте новый идентификатор сеанса при начале нового разговора.

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

# 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

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

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

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

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

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

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

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

1. Конфигурация воркеров : при использовании транспорта SSE с Uvicorn настройте соответствующее количество воркеров:

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

2. Настройки тайм-аута : настройте тайм-ауты для больших репозиториев:

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

3. Оптимизация памяти : для крупных развертываний учитывайте ограничения ресурсов контейнера:

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

Внося вклад

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

1. Форк репозитория

2. Создайте ветку функций ( git checkout -b feature/amazing-feature )

3. Зафиксируйте свои изменения ( git commit -m 'Add some amazing feature' )

4. Отправить в ветку ( git push origin feature/amazing-feature )

5. Открыть запрос на извлечение

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

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

pip install -e ".[dev]"

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

pytest

Лицензия

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

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