small-app-dev-mcp

Для iOS-приложений небольших команд и индивидуальной разработки — MCP-сервер для безопасного и простого управления Git / GitHub / GitHub Actions / процессом релизов.

Этот MCP — не «MCP для добавления Git-операций», а «MCP для безопасного релиза небольших приложений». Это не обёртка, открывающая Git-команды как есть: в качестве Tool публикуются только осмысленные единицы операций, такие как prepare_release и start_hotfix. Git Flow для крупных команд — develop branch, несколько release branch, обязательное ревью, CODEOWNERS — не поддерживается. Предназначено для проектов, в которых один или несколько человек постоянно обновляют одно приложение.

Структура

packages/
├── git-core/            # Git / GitHub / PR / Actions / project-detection / validation の共通ライブラリ
└── small-app-dev-mcp/   # MCPサーバー本体（v0.1 MVP）

git-core выделяет низкоуровневую реализацию (Git-операции, клиент GitHub API, получение PR/Actions, автоматическое обнаружение iOS-проектов) и может быть переиспользована в будущем из MCP для крупных команд, например team-app-dev-mcp.

Модель ветвления

main        常にリリース可能な正式版。直接pushしない。
release     次回リリース用の変更を蓄積する常設ブランチ。通常開発はここで行う。
hotfix/*    公開中バージョンの重大バグを緊急修正するときだけ、mainから作成する。

Установка

Версии Node / pnpm зафиксированы через mise (.mise.toml).

mise install     # .mise.toml が指定する node / pnpm を導入
pnpm install      # pnpm-workspace.yaml 経由でworkspace一括install
pnpm run build     # 各パッケージをビルド (pnpm -r --if-present run build)

Целевой репозиторий

MCP-сервер запускается с репозиторием целевого приложения в качестве рабочей директории (working directory) или с указанием этого пути через переменную окружения APP_DEV_PROJECT_DIR. Один процесс MCP-сервера работает только с одним репозиторием приложения.

export APP_DEV_PROJECT_DIR=/path/to/your/ios-app

Токен GitHub

export GITHUB_TOKEN=ghp_xxx   # repo スコープが必要

MCP-сервер запускается даже без установленного GITHUB_TOKEN (или GH_TOKEN). Tools, которые выполняются только локальными Git-операциями, — get_app_status / prepare_release / start_hotfix / sync_release и т.п. — работают как обычно; только операции, требующие GitHub API, такие как проверка статуса CI, создание PR, branch protection, возвращают GITHUB_TOKEN not set.

Пример настройки MCP

Из MCP-клиента, поддерживающего stdio, например Claude Code, регистрация выполняется следующим образом.

{
  "mcpServers": {
    "small-app-dev": {
      "command": "node",
      "args": ["/path/to/small-app-dev-mcp/packages/small-app-dev-mcp/dist/index.js"],
      "env": {
        "APP_DEV_PROJECT_DIR": "/path/to/your/ios-app",
        "GITHUB_TOKEN": "ghp_xxx"
      }
    }
  }
}

Если в корне целевого проекта нет .appdev.yml, setup_repository создаст его (пункты, которые могут быть определены автоматически, можно опустить).

.appdev.yml

version: 1

project:
  type: ios
  # 自動検出できる場合は省略可能
  # path: Yohaku.xcodeproj / Yohaku.xcworkspace
  # scheme: Yohaku

workflow:
  production_branch: main
  development_branch: release
  hotfix_prefix: hotfix/

branches:
  direct_commit:
    main: false
    release: true

release:
  merge_strategy: squash
  require:
    clean_worktree: true
    ci: true
  auto_submit_review: false
  auto_publish: false

hotfix:
  base_branch: main
  sync_back_to_release: true

github:
  require_pull_request_to_main: true
  block_force_push_main: true

Приоритет настроек: явное указание в .appdev.yml > автоматическое обнаружение > default. Указав project.path / project.scheme, можно переопределить выбор при неоднозначности xcworkspace/xcodeproj или scheme.

Инструменты MVP v0.1

setup_repository / create_release_pr / start_hotfix / finish_hotfix / sync_release при dry_run: true могут показать только предварительный просмотр того, что будет сделано.

Branch protection для main, устанавливаемая setup_repository:

• Require pull request before merging: true

• Required approving reviews: 0 (PR обязателен, но обязательное ревью другими людьми не требуется — в небольших/личных проектах часто нет ревьюеров. «Обязательность PR» и «обязательность ревью» — разные настройки)

• Require status checks: true

• Allow force pushes: false

• Allow deletions: false

Основной рабочий процесс

setup_repository
↓
main / release 運用をセットアップ
↓
普段は release で開発
↓
get_app_status
↓
prepare_release
↓
create_release_pr
↓
release → main を merge
↓
GitHub Actions Release workflow

Процесс Hotfix

main
↓
start_hotfix(name: "startup crash")   →  hotfix/startup-crash
↓
修正をcommit
↓
finish_hotfix(name: "startup crash")  →  hotfix/startup-crash → main のPR
↓
merge → Release workflow発火
↓
sync_release                          →  main の変更を release へ同期

get_app_status и prepare_release всегда выводят предупреждение, если после merge Hotfix в main изменения не синхронизированы с release (побуждая выполнить sync_release).

Намеренно не делается

• Прямой push в main, force push, удаление веток (не используются даже внутри Tools)

• Автоматическая отправка и публикация в App Store / Google Play (остановка на этапе готовности со стороны GitHub)

• Управление описанием App Store, скриншотами, политикой конфиденциальности, IAP и отправкой на ревью (это обязанность appstore-connect-mcp)

• Операции для крупных команд: develop branch, несколько release branch, обязательное ревью, CODEOWNERS и т.п.

• Поддержка Android / Flutter / React Native, AI Release Notes, UI Dashboard, multi-user и управление organization.

Это вне рамок спецификации; при необходимости будет реализовано как отдельный team-app-dev-mcp.

Работа GitHub Actions

• CI (ci.yml): запускается при PR в main и при push в release. Только Checkout → Build (в v0.1 тесты не выполняются). Цель — предотвратить попадание сломанного кода в main.

• Release (release.yml): запускается только когда PR в main смёржен, и смёрженная ветка — release или hotfix/* (обычные merge из feature/*, chore/*, docs/* и т.п. не учитываются). Выполняются Checkout → Build → проверка возможности архивации → вывод Release preparation summary, после чего процесс останавливается. Фактическая отправка на ревью и публикация не выполняется.

ci.yml / release.yml, генерируемые setup_repository, создаются с уже встроенными обнаруженными Xcode-проектом/scheme. Если проект/scheme не удаётся обнаружить автоматически, workflow с плейсхолдерами не создаётся — генерация пропускается и предлагается указать их вручную в .appdev.yml.

Известные ограничения (v0.1)

• Предполагается только iOS + GitHub

• CI workflow — только сборка (автоматическое обнаружение и запуск тестовых таргетов не выполняется)

• run_preflight / check_ci / generate_release_notes и т.п. — начиная с v0.2

• Операции на стороне App Store Connect (создание версии, Submit и т.п.) вне рамок. Предполагается использование в сочетании с отдельным MCP (appstore-connect-mcp).