small-app-dev-mcp

소규모·개인 개발 iOS 앱을 위해, Git / GitHub / GitHub Actions / 릴리스 운영을 안전하고 간단하게 다루기 위한 MCP 서버입니다.

이 MCP는 'Git 조작을 늘리기 위한 MCP'가 아니라, '소규모 앱을 안전하게 릴리스하기 위한 MCP'입니다. Git 명령어를 그대로 노출하는 래퍼가 아니라, prepare_release나 start_hotfix처럼 의미 있는 작업 단위만 Tool로 공개합니다. develop branch·복수 release branch·필수 Review·CODEOWNERS 같은 대규모 팀용 Git Flow는 대상이 아닙니다. 1명~몇 명이 하나의 앱을 지속적으로 업데이트하는 프로젝트 전용입니다.

구성

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 프로젝트 자동 감지)을 분리해 두어, 향후 team-app-dev-mcp 같은 대규모 팀용 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 スコープが必要

GITHUB_TOKEN（또는 GH_TOKEN）가 미설정이어도 MCP 서버 자체는 기동합니다. get_app_status / prepare_release / start_hotfix / sync_release 등 로컬 Git 조작만으로 완결되는 Tool은 그대로 사용할 수 있고, CI 상태 확인·PR 작성·branch protection 등 GitHub API가 필요한 처리만 GITHUB_TOKEN not set을 반환합니다.

MCP 설정 예

Claude Code 등 stdio를 지원하는 MCP 클라이언트에서 다음과 같이 등록합니다.

{
  "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 선택이 애매한 경우에도 덮어쓸 수 있습니다.

v0.1 MVP Tools

setup_repository / create_release_pr / start_hotfix / finish_hotfix / sync_release는 dry_run: true로 '무엇을 하는지' 미리보기만 표시할 수 있습니다.

setup_repository가 설정하는 main의 branch protection:

• 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는 Hotfix가 main에 merge된 후 release에 동기화되지 않은 경우 항상 경고를 표시합니다（sync_release 실행을 권장）.

의도적으로 하지 않는 것

• main으로의 직접 push·force push·branch 삭제（Tool 내부에서도 일절 사용하지 않음）

• App Store / Google Play에 자동 submit·자동 공개（GitHub 쪽 준비가 완료되는 데서 멈춤）

• App Store Description·Screenshots·Privacy·IAP·Review submission 관리（appstore-connect-mcp 측의 책임）

• develop branch, 복수 release branch, 필수 Review, CODEOWNERS 등 대규모 팀용 운영

• Android / Flutter / React Native 대응, AI Release Notes, UI Dashboard, multi-user·organization 관리

이들은 사양서의 스코프 밖이며, 필요해지면 별도의 team-app-dev-mcp로 구현합니다.

GitHub Actions 동작

• CI (ci.yml): main으로의 PR 및 release로의 push에서 발화합니다. Checkout → Build만 수행（v0.1에서는 테스트 실행을 하지 않음）. 목적은 깨진 코드가 main에 들어가는 것을 막는 것입니다.

• Release (release.yml): main으로의 PR이 merge되고, 병합된 브랜치가 release 또는 hotfix/*인 경우에만 발화합니다（feature/*・chore/*・docs/* 등 일반 merge는 대상 외）. Checkout → Build → Archive 가능 상태 확인 → Release preparation summary 출력에서 멈춥니다. 실제 심사 제출·공개는 하지 않습니다.

setup_repository가 생성하는 ci.yml / release.yml은 감지된 Xcode 프로젝트/scheme을 내장한 상태로 생성됩니다. 프로젝트/scheme을 자동 감지할 수 없으면 플레이스홀더가 포함된 workflow를 작성하지 않고, 생성을 건너뛰어 .appdev.yml에 수동 지정을 안내합니다.

알려진 제약 (v0.1)

• iOS + GitHub만을 상정

• CI workflow는 빌드만（테스트 타겟 자동 감지·실행은 하지 않음）

• run_preflight / check_ci / generate_release_notes 등은 v0.2 이후

• App Store Connect 쪽 작업（Version 생성·Submit 등）은 스코프 밖. 별도 MCP (appstore-connect-mcp)와 조합하여 사용하는 전제