small-app-dev-mcp

Ein MCP-Server für die sichere und einfache Handhabung von Git / GitHub / GitHub Actions / Release-Abläufen bei kleinen, von Einzelpersonen entwickelten iOS-Apps.

Dieses MCP ist kein „MCP zur Erweiterung von Git-Operationen“, sondern ein „MCP zum sicheren Veröffentlichen kleiner Apps“. Es ist kein Wrapper, der Git-Befehle direkt offenlegt, sondern stellt nur sinnvolle Operationseinheiten als Tools zur Verfügung, wie prepare_release oder start_hotfix. Git Flow für große Teams – develop branch, mehrere release branches, verpflichtende Reviews, CODEOWNERS – ist nicht abgedeckt. Es ist ausschließlich für Projekte gedacht, in denen eine bis wenige Personen eine einzelne App kontinuierlich aktualisieren.

Aufbau

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

git-core kapselt die Low-Level-Implementierung (Git-Operationen, GitHub-API-Client, PR/Actions-Abruf, automatische Erkennung von iOS-Projekten) und kann künftig auch von einem MCP für große Teams wie team-app-dev-mcp wiederverwendet werden.

Branch-Modell

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

Installation

Die Versionen von Node / pnpm werden über mise (.mise.toml) fixiert.

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

Zielrepository

Es wird davon ausgegangen, dass der MCP-Server mit dem Repository der Ziel-App als working directory gestartet wird oder dass der Pfad über die Umgebungsvariable APP_DEV_PROJECT_DIR angegeben wird. Ein MCP-Server-Prozess verwaltet nur ein einziges App-Repository.

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

GitHub Token

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

Auch wenn GITHUB_TOKEN (oder GH_TOKEN) nicht gesetzt ist, startet der MCP-Server selbst. Tools, die ausschließlich mit lokalen Git-Operationen auskommen, wie get_app_status / prepare_release / start_hotfix / sync_release, können weiterhin verwendet werden. Nur Vorgänge, die die GitHub-API benötigen – CI-Statusabfrage, PR-Erstellung, branch protection – geben GITHUB_TOKEN not set zurück.

Beispiel für die MCP-Konfiguration

Über einen stdio-fähigen MCP-Client wie Claude Code wird der Server wie folgt registriert:

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

Wenn sich im Stammverzeichnis des Zielprojekts keine .appdev.yml befindet, erstellt setup_repository sie (automatisch erkennbare Felder können weggelassen werden).

.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

Die Prioritätsreihenfolge der Einstellungen ist explizite Angabe in .appdev.yml > automatische Erkennung > default. Wenn project.path / project.scheme gesetzt werden, können damit auch mehrdeutige xcworkspace/xcodeproj- oder scheme-Auswahlen überschrieben werden.

v0.1 MVP-Tools

setup_repository / create_release_pr / start_hotfix / finish_hotfix / sync_release können mit dry_run: true nur eine Vorschau darüber anzeigen, was sie tun würden.

Die von setup_repository konfigurierte branch protection für main:

• Require pull request before merging: true

• Required approving reviews: 0 (PR ist erforderlich, aber Reviews durch andere sind nicht verpflichtend — da es in kleinen/persönlichen Projekten oft keine Reviewer gibt. „PR ist erforderlich“ und „Review ist erforderlich“ sind separate Einstellungen.)

• Require status checks: true

• Allow force pushes: false

• Allow deletions: false

Grundlegender Betriebsablauf

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

Hotfix-Ablauf

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 und prepare_release warnen immer, wenn nach einem Merge eines Hotfix in main noch nicht mit release synchronisiert wurde (und erinnern an die Ausführung von sync_release).

Was bewusst nicht gemacht wird

• Direkte Pushes auf main, force push und das Löschen von Branches (wird auch in den Tools intern nie verwendet)

• Automatisches Einreichen und Veröffentlichen im App Store / bei Google Play (es wird angehalten, sobald die Vorbereitungen auf GitHub-Seite abgeschlossen sind)

• Verwaltung von App-Store-Beschreibung, Screenshots, Datenschutz, In-App-Käufen und Review-Einreichung (Verantwortung von appstore-connect-mcp)

• Betrieb für große Teams: develop branch, mehrere release branches, verpflichtende Reviews, CODEOWNERS usw.

• Android / Flutter / React Native-Unterstützung, KI-Release-Notes, UI-Dashboard, Multi-User- und Organisationsverwaltung

Dies liegt außerhalb des Umfangs dieses Pflichtenhefts und wird bei Bedarf als separates team-app-dev-mcp umgesetzt.

Verhalten von GitHub Actions

• CI (ci.yml): Wird bei PRs auf main und bei Pushes auf release ausgelöst. Nur Checkout → Build (in v0.1 werden keine Tests ausgeführt). Ziel ist es, zu verhindern, dass defekter Code in main gelangt.

• Release (release.yml): Wird nur ausgelöst, wenn ein PR auf main gemergt wird und der gemergte Branch release oder hotfix/* ist (normale Merges wie feature/*, chore/*, docs/* sind ausgenommen). Checkout → Build → Prüfung, ob ein Archiv möglich ist → Ausgabe der Release preparation summary, dann Stopp. Eine tatsächliche Einreichung zur Prüfung oder Veröffentlichung findet nicht statt.

Die von setup_repository generierten ci.yml / release.yml werden mit den erkannten Xcode-Projekten/Schemes erzeugt. Wenn das Projekt/scheme nicht automatisch erkannt werden kann, wird kein Workflow mit Platzhaltern geschrieben; die Generierung wird übersprungen und stattdessen zur manuellen Angabe in .appdev.yml aufgefordert.

Bekannte Einschränkungen (v0.1)

• Nur iOS + GitHub werden unterstützt

• Der CI-Workflow erstellt nur den Build (Testtargets werden nicht automatisch erkannt oder ausgeführt)

• run_preflight / check_ci / generate_release_notes und weitere folgen ab v0.2

• Operationen auf App-Store-Connect-Seite (Versionserstellung, Submit usw.) liegen außerhalb des Umfangs. Es ist vorgesehen, sie mit einem separaten MCP (appstore-connect-mcp) zu kombinieren.