GitHub Model Context Protocol (MCP) Server with Tool-Calling Evaluation

Промышленный FastMCP-сервер GitHub, предоставляющий операции чтения и операции записи с подтверждением, в паре с оценочным стендом из 30 сценариев, оценивающим выбор инструментов, точность аргументов и безопасность подтверждения деструктивных действий.

Краткое резюме и матрица оценки

Вызов инструментов LLM-агентом требует строгих границ безопасности. Этот MCP-сервер обеспечивает подтверждение на уровне сервера для всех изменяющих действий: неподтверждённые запросы возвращают предварительные просмотры (dry-run) вместо выполнения изменений в GitHub.

Результаты бенчмарка (30 размеченных сценариев)

Оценка по бенчмарку из 30 сценариев, проверяющему стандартные вызовы инструментов, недостаточно определённые/неоднозначные запросы и деструктивные действия с подтверждением:

Related MCP server: github-mcp-tool

Архитектура инструментов и операции

flowchart TD
    A[User Request] --> B[LLM Tool-Calling Engine]
    B --> C{Tool Category}
    
    C -- Read Tool --> D[Execute GitHub API Call Directly]
    D --> E[Return API Payload]
    
    C -- Write / Destructive --> F{confirm == true ?}
    F -- Yes --> G[Execute State Mutation on GitHub]
    G --> H[Return Success / Number / URL]
    
    F -- No --> I[Return Dry-Run Preview of Mutation]

Доступные инструменты

Операции чтения (немедленное выполнение)

• list_issues(owner, repo, state): Список открытых/закрытых задач в репозитории.

• get_issue(owner, repo, issue_number): Получение подробных метаданных для одной задачи.

• list_pull_requests(owner, repo, state): Список pull request'ов в репозитории.

• get_pull_request(owner, repo, pr_number): Получение сведений и информации о возможности слияния для PR.

• search_code(query, owner, repo): Поиск по кодовой базе GitHub глобально или в пределах репозитория.

Деструктивные операции (с подтверждением)

• create_issue(owner, repo, title, body, confirm=False): Создаёт задачу только при подтверждении; в противном случае возвращает предварительный просмотр.

• close_issue(owner, repo, issue_number, confirm=False): Закрывает задачу только при подтверждении; в противном случае возвращает предварительный просмотр.

• add_comment(owner, repo, issue_number, body, confirm=False): Оставляет комментарий к задаче/PR только при подтверждении; в противном случае возвращает предварительный просмотр.

• merge_pull_request(owner, repo, pr_number, confirm=False): Выполняет слияние PR только при подтверждении; в противном случае возвращает предварительный просмотр.

Структура проекта

├── app/
│   ├── __init__.py          # Public MCP server & client exports
│   ├── server.py            # FastMCP server definition & tool routing
│   └── github_client.py     # GitHub REST API client with dry-run previews
├── eval/
│   ├── __init__.py          # Evaluation package
│   ├── tool_schemas.py      # OpenAI-compatible function definitions & prompt
│   ├── test_set.json        # 30 labeled evaluation test cases
│   └── run_eval.py          # Benchmark harness scoring tool, args, and confirm flags
├── requirements.txt         # Dependencies (mcp, requests, openai)
├── WRITEUP.md               # Detailed evaluation report & iteration analysis
└── README.md

Быстрый старт и использование

1. Установка

git clone https://github.com/vishalmurugan1986/github-mcp-server.git
cd github-mcp-server

pip install -r requirements.txt

2. Настройка окружения

export NVIDIA_API_KEY="nvapi-your-key-here"
# Optional: real GitHub write access
export GITHUB_TOKEN="ghp_your_personal_access_token"

3. Запуск MCP-сервера

python -m app.server

Подключите MCP-клиент (например, Claude Desktop или пользовательских агентов) через стандартный ввод-вывод.

4. Запуск набора оценки вызова инструментов

python -m eval.run_eval

Результаты сохраняются в eval/results.json и выводятся с полной разбивкой по метрикам.

Принципы безопасности

1. Многоуровневое подтверждение: вместо того чтобы полагаться исключительно на инструкции в промпте, защитные проверки подтверждения жёстко прописаны непосредственно в app/github_client.py. Неподтверждённый запрос не может привести к случайному изменению.

2. Отказ при неоднозначности: модели предписано отказываться от выполнения и задавать уточняющие вопросы всякий раз, когда репозитории, номера задач или параметры не указаны, что позволяет избежать галлюцинаций с заполнителями.