GitHub Project Management MCP Server

Пользовательский MCP-сервер (Model Context Protocol), который позволяет ИИ-ассистентам программно управлять досками GitHub Project V2 через Model Context Protocol. Создан на Python 3.12 и FastMCP, общается через stdio-транспорт и работает внутри автономного Docker-контейнера.

Расположение

project/
├── mcp/                    ← This directory (root-level, independent of the app)
│   ├── Dockerfile
│   ├── requirements.txt
│   ├── server.py           # FastMCP entry point
│   ├── config.py
│   ├── auth.py
│   ├── capabilities.py     # Tool → permission mapping
│   ├── profiles.py         # Multi-target profile system
│   ├── tools/              # MCP tool definitions
│   ├── services/           # Business logic
│   ├── clients/            # GraphQL + gh CLI clients
│   ├── models/             # Pydantic models
│   ├── graphql/            # Query/mutation strings
│   ├── tests/              # Unit + contract tests
│   ├── scripts/            # Validation, preflight, secret scanning
│   │   ├── validate.sh     # ← Run before every push
│   │   ├── preflight.sh    # Environment prerequisites
│   │   ├── scan_secrets.sh # Token pattern detection
│   │   └── smoke_build.sh  # Minimal build verification
│   ├── profiles/           # Target config (.env files, no secrets)
│   ├── docs/               # Detailed documentation
│   ├── LICENSE             # MIT
│   ├── CONTRIBUTING.md
│   └── SECURITY.md

Примечание: Этот MCP-сервер является автономным компонентом со своим собственным Dockerfile, зависимостями и жизненным циклом.

Related MCP server: my_pm_tools

Как это работает

MCP Client → docker run --rm -i github-project-mcp:latest → stdin/stdout JSON-RPC → GitHub API

1. Клиент MCP вызывает инструмент (например: create_project_item)

2. Выполняется docker run --rm -i github-project-mcp:latest python server.py

3. Сервер проверяет аутентификацию и ожидает команды через stdin

4. Клиент отправляет JSON-RPC через stdin и получает ответы через stdout

5. По завершении контейнер автоматически уничтожается (--rm)

Docker — Сборка и управление

Сборка образа

# Desde la raíz del proyecto
docker build -t github-project-mcp:latest ./mcp

Docker Compose (локальная разработка)

Самый простой способ настроить и запустить MCP локально:

# 1. Crear tu configuración local (una sola vez)
cp mcp/.env.example mcp/.env
# Editar mcp/.env con tu GITHUB_TOKEN y target (org/repo/project)

# 2. Construir y verificar
cd mcp/
make build
make verify

Цели Makefile

Все цели выполняются внутри Docker — без зависимостей на хосте.

cd mcp/
make help         # Mostrar todos los targets disponibles
make build        # Construir imagen Docker
make verify       # Validar auth + scopes + config
make test         # Ejecutar unit tests
make validate     # CI completo (build + syntax + tests + tools + secrets)
make tools        # Contar herramientas registradas (>= 100)
make syntax       # Verificar sintaxis Python
make secrets      # Escanear credenciales en código
make shell        # Shell interactivo dentro del contenedor
make clean        # Eliminar imágenes

Примечание: Если make недоступен на хосте, цели можно вызывать напрямую через Docker. Пример: docker run --rm --env-file .env github-project-mcp:latest python3 scripts/verify_setup.py

Каждый участник клонирует репозиторий, создаёт свой .env, и MCP работает без установки чего-либо, кроме Docker.

Проверка наличия образа

docker images | grep github-project-mcp

Ручное тестирование (smoke test)

docker run --rm -i \
  -e GITHUB_TOKEN="<your_token>" \
  github-project-mcp:latest \
  python server.py

Сервер выведет в stderr: github-project-management MCP server ready. Authentication validated successfully. Затем будет ожидать JSON-RPC через stdin. Нажмите Ctrl+C для выхода.

Пересборка после изменений

docker build -t github-project-mcp:latest ./mcp --no-cache

Скрипт управления

Скрипт ./scripts/dev/start.sh поддерживает аргумент mcp для управления образом:

./scripts/dev/start.sh mcp build      # Construir/reconstruir la imagen
./scripts/dev/start.sh mcp test       # Ejecutar smoke test
./scripts/dev/start.sh mcp status     # Verificar si la imagen existe

Примечание: MCP не является постоянным сервисом. Ему не нужны up/down/restart. Он запускается по требованию каждый раз, когда клиент использует инструмент.

Интеграция с IDE

MCP совместим с любым клиентом, поддерживающим протокол MCP через stdio. Конфигурация зависит от IDE — общий паттерн:

{
  "mcpServers": {
    "github-project-management": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "GITHUB_TOKEN",
        "--env-file", "mcp/.env",
        "github-project-mcp:latest",
        "python", "server.py"
      ]
    }
  }
}

Для конфигурации, специфичной для конкретной IDE, см. docs/SETUP.md.

Зарегистрированные инструменты (100)

Основные операции

Управление issues

Операции с доской

Планирование и рабочие процессы

Метаданные

Архитектура

Tool Layer (FastMCP tool definitions)
    ↓
Service Layer (business logic, orchestration)
    ↓
Client Layer (GraphQL + gh CLI + caching)
    ↓
GitHub APIs (GraphQL v4 + REST v3)

Стратегия делегирования

Переменные окружения

Устранение неполадок

MCP не подключается

# Verificar que la imagen existe
docker images | grep github-project-mcp

# Si no existe, construir
docker build -t github-project-mcp:latest ./mcp

# Verificar token
echo $GITHUB_TOKEN | head -c 20

Переподключение MCP

Если MCP отключается от IDE, используйте опцию переподключения соответствующего MCP-клиента.

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

• Убедитесь, что GITHUB_TOKEN доступен в окружении контейнера

• Токены github_pat_* (fine-grained) требуют разрешения: Issues (RW), Projects (RW), Metadata (R)

• Классические токены требуют scopes: repo, project, read:org

Связанная документация

Расположение исходников и синхронизация

Этот каталог (mcp/) является каноническим источником истины для MCP-пакета.

Репозиторий содержит синхронизированную копию по адресу:

• app/backend/app/mcp/github_project/ — встроена в бэкенд для Docker-сборок

Процесс синхронизации

1. Вносите все изменения здесь — сначала в mcp/.

2. Скопируйте изменённые файлы во встроенный путь:

   cp mcp/<file> app/backend/app/mcp/github_project/<file>

3. Проверьте с помощью автоматической проверки:

   ./mcp/scripts/check_sync.sh

Скрипт синхронизации сравнивает все общие .py-файлы (исключая __init__.py, который намеренно отличается в копии бэкенда, и файлы только для инфраструктуры, такие как Dockerfile и requirements.txt). CI запускает эту проверку при каждом push — расхождение приводит к сбою сборки.

Файлы, намеренно отличающиеся в копии бэкенда

Тестовый набор бэкенда проверяет встроенную копию; проверка синтаксиса должна компилировать оба дерева.

Усиленное поведение во время выполнения

Все настройки используют префикс GH_PROJECT_ и проверяются при запуске:

Кэш метаданных записывается атомарно, использует права только для владельца (0600), отклоняет будущие временные метки и не переиспользуется при изменении организации или номера проекта. Диагностика CLI и GraphQL скрывает значения, похожие на токены, и ограничивается перед возвратом MCP-клиенту.

Проверка только через Docker

Запустите проверку без Python-инструментов на хосте:

# Compile both source copies through a Python container
tar -C . -cf - mcp app/backend/app/mcp \
  | docker run --rm -i python:3.12-slim sh -c \
    'mkdir -p /tmp/factib && tar -xf - -C /tmp/factib && \
     python -m compileall -q /tmp/factib/mcp /tmp/factib/app/backend/app/mcp'

# Run the backend MCP tests using the existing backend image
tar -C . -cf - app/backend/app app/backend/tests/mcp \
  | docker run --rm -i -e PYTHONPATH=/tmp/factib/app/backend backend:latest sh -c \
    'mkdir -p /tmp/factib && tar -xf - -C /tmp/factib && cd /tmp/factib/app/backend && \
     pytest -q --confcutdir=/tmp/factib/app/backend/tests/mcp tests/mcp'

Локальная проверка (перед push)

Всегда запускайте перед созданием PR или push изменений. Это зеркалирует конвейер CI локально и выявляет проблемы до того, как они попадут в GitHub Actions.

Быстрый старт

# Full validation (builds image + runs all checks):
./mcp/scripts/validate.sh

# Quick mode (reuses cached image, skips rebuild):
./mcp/scripts/validate.sh --quick

# Auto-fix known issues (e.g., BOM characters):
./mcp/scripts/validate.sh --fix

Что проверяется

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

Частые проблемы и их решения

Полный реестр из 200 пунктов, включая реализованные и запланированные работы, находится в docs/HARDENING_200.md.

Расширенный набор возможностей: 60 дополнительных инструментов

Сервер предоставляет 100+ инструментов в общей сложности: исходные 40 операционных инструментов плюс 60 узконаправленных возможностей из tools/capability_suite.py.

Инструменты, которые могут вызывать масштабные изменения, по умолчанию возвращают план dry_run. Прямые инструменты работы с комментариями выполняют одну видимую операцию с комментарием за вызов. Каталог возможностей проверяет 60 уникальных дополнений во время импорта, а проверка Docker подтверждает 100 зарегистрированных инструментов FastMCP в обеих копиях исходников.

Распространение

Docker-образ

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

docker build -t github-project-mcp:latest ./mcp

Конвейер CI/CD

Рабочий процесс mcp-ci.yaml запускается автоматически при:

• Пуше в main, когда изменяются файлы в mcp/

• Pull request, затрагивающих пути mcp/

Этапы конвейера:

1. Сборка — проверка сборки Docker-образа

2. Проверка синтаксиса — AST-разбор всех Python-файлов

3. Модульные тесты — выполнение набора pytest

4. Проверка количества инструментов — гарантирует ≥100 зарегистрированных инструментов

Версионирование

Этот сервер MCP следует семантическому версионированию. Историю релизов см. в CHANGELOG.md.