small-app-dev-mcp

An MCP server for safely and easily handling Git / GitHub / GitHub Actions / release operations for small-scale, individual iOS app development.

This MCP is not "an MCP to increase Git operations" but "an MCP to safely release small-scale apps." It is not a wrapper that exposes Git commands as-is; only meaningful operation units such as prepare_release and start_hotfix are exposed as Tools. Git Flow for large teams—develop branch, multiple release branches, required reviews, CODEOWNERS, etc.—is out of scope. It is dedicated to projects where one to a few people continuously update a single app.

Structure

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

git-core is a low-level implementation (Git operations, GitHub API client, PR/Actions retrieval, iOS project auto-detection) extracted so that it can also be reused in the future by an MCP for large teams such as team-app-dev-mcp.

Related MCP server: ShipKit

Branch Model

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

Installation

Node / pnpm versions are pinned with 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)

Target Repository

The MCP server is intended to be started with the target app's repository as the working directory, or with its path specified via the APP_DEV_PROJECT_DIR environment variable. A single MCP server process handles only one app repository.

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

GitHub Token

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

The MCP server itself starts even if GITHUB_TOKEN (or GH_TOKEN) is not set. Tools that can be completed with only local Git operations, such as get_app_status / prepare_release / start_hotfix / sync_release, can be used as-is; only operations that require the GitHub API—CI status checks, PR creation, branch protection, etc.—return GITHUB_TOKEN not set.

MCP Configuration Example

Register it from a stdio-compatible MCP client such as Claude Code as follows:

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

If there is no .appdev.yml at the root of the target project, setup_repository creates it (items that can be auto-detected may be omitted).

.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

The priority order of settings is explicit specification in .appdev.yml > auto-detection > default. If project.path / project.scheme are set, you can override ambiguous xcworkspace/xcodeproj or scheme selection.

v0.1 MVP Tools

setup_repository / create_release_pr / start_hotfix / finish_hotfix / sync_release can show only a preview of "what they will do" with dry_run: true.

Branch protection for main set by setup_repository:

• Require pull request before merging: true

• Required approving reviews: 0 (PRs are required, but peer reviews are not—in small-scale/individual development there is often no reviewer. Requiring a PR and requiring a review are separate settings.)

• Require status checks: true

• Allow force pushes: false

• Allow deletions: false

Basic Operation Flow

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

Hotfix Flow

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 and prepare_release always warn when a hotfix has been merged into main but has not yet been synced to release (prompting you to run sync_release).

Intentionally Out of Scope

• Direct pushes to main, force pushes, and branch deletion (never used at all inside the tools)

• Automatic submission/publication to App Store / Google Play (stops once the GitHub-side preparation is complete)

• Management of App Store Description, Screenshots, Privacy, IAP, and Review submission (responsibility of appstore-connect-mcp)

• Large-team operations such as a develop branch, multiple release branches, required reviews, and CODEOWNERS

• Android / Flutter / React Native support, AI Release Notes, UI Dashboard, multi-user / organization management

These are outside the scope of this specification; if needed, they will be implemented as a separate team-app-dev-mcp.

GitHub Actions Behavior

• CI (ci.yml): Triggers on PRs to main and pushes to release. Only Checkout → Build (no test execution in v0.1). The purpose is to prevent broken code from entering main.

• Release (release.yml): Triggers only when a PR to main is merged and the merged branch is release or hotfix/* (normal merges of feature/*, chore/*, docs/*, etc. are excluded). Stops after Checkout → Build → verification that archiving is possible → output of a Release preparation summary. It does not perform actual submission for review or publication.

The ci.yml / release.yml generated by setup_repository are created with the detected Xcode project/scheme embedded. If the project/scheme cannot be auto-detected, it does not write a placeholder-filled workflow; it skips generation and prompts you to specify them manually in .appdev.yml.

Known Limitations (v0.1)

• Intended for iOS + GitHub only

• CI workflow is build-only (does not auto-detect or run test targets)

• run_preflight / check_ci / generate_release_notes, etc. are planned for v0.2 and later

• App Store Connect operations (Version creation, Submit, etc.) are out of scope. Intended to be used in combination with a separate MCP (appstore-connect-mcp).