small-app-dev-mcp

Servidor MCP para manejar de forma segura y sencilla Git / GitHub / GitHub Actions / operaciones de lanzamiento para aplicaciones iOS de desarrollo personal y a pequeña escala.

Este MCP no es un «MCP para aumentar las operaciones de Git», sino un «MCP para lanzar aplicaciones a pequeña escala de forma segura». No es un envoltorio que exponga comandos Git directamente; expone como Tool solo unidades de operación con significado, como prepare_release o start_hotfix. Quedan fuera de alcance el Git Flow para equipos grandes: develop branch, múltiples release branch, revisión obligatoria, CODEOWNERS, etc. Está pensado para proyectos en los que una o pocas personas actualizan continuamente una sola aplicación.

Estructura

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

git-core es una implementación de bajo nivel (operaciones de Git, cliente de la API de GitHub, obtención de PR/Actions, detección automática de proyectos iOS) y se ha separado para que en el futuro pueda reutilizarse desde MCP orientados a equipos grandes como team-app-dev-mcp.

Modelo de ramas

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

Instalación

Las versiones de Node / pnpm se fijan con 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)

Repositorio objetivo

El servidor MCP se inicia con el repositorio de la aplicación objetivo como directorio de trabajo, o especificando esa ruta con la variable de entorno APP_DEV_PROJECT_DIR. Un proceso de servidor MCP maneja solo un repositorio de aplicación.

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

Token de GitHub

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

El servidor MCP se inicia incluso si GITHUB_TOKEN (o GH_TOKEN) no está configurado. Las Tools que se completan solo con operaciones Git locales, como get_app_status / prepare_release / start_hotfix / sync_release, pueden usarse tal cual; solo las operaciones que requieren la API de GitHub, como la comprobación del estado de CI, la creación de PR y la protección de ramas, devuelven GITHUB_TOKEN not set.

Ejemplo de configuración de MCP

Desde un cliente MCP compatible con stdio, como Claude Code, regístrelo de la siguiente manera.

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

Si no existe .appdev.yml en la raíz del proyecto objetivo, setup_repository lo crea (los elementos que pueden detectarse automáticamente son opcionales).

.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

La prioridad de configuración es especificación explícita en .appdev.yml > detección automática > default. Si se escriben project.path / project.scheme, se puede sobrescribir incluso cuando la selección de xcworkspace/xcodeproj o scheme sea ambigua.

Herramientas MVP v0.1

setup_repository / create_release_pr / start_hotfix / finish_hotfix / sync_release pueden mostrar solo una vista previa de «lo que se hará» con dry_run: true.

Protección de la rama main que configura setup_repository:

• Require pull request before merging: true

• Required approving reviews: 0 (el PR es obligatorio, pero la revisión de otros no es obligatoria — en proyectos pequeños/individuales suele no haber revisores. «Exigir PR» y «exigir revisión» son ajustes distintos.)

• Require status checks: true

• Allow force pushes: false

• Allow deletions: false

Flujo de operación básico

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

Flujo de 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 y prepare_release siempre avisan si, después de fusionar un Hotfix en main, hay cambios sin sincronizar con release (instan a ejecutar sync_release).

Lo que no se hace a propósito

• Push directo a main, force push y eliminación de ramas (no se usan en absoluto dentro de las Tools)

• Envío y publicación automática a App Store / Google Play (se detiene una vez que la preparación del lado de GitHub está completa)

• Gestión de App Store Description, Screenshots, Privacy, IAP y Review submission (responsabilidad del lado de appstore-connect-mcp)

• Operaciones para equipos grandes: develop branch, múltiples release branch, revisión obligatoria, CODEOWNERS, etc.

• Soporte de Android / Flutter / React Native, AI Release Notes, UI Dashboard, gestión de multi-usuario y organizaciones

Estos quedan fuera del alcance de la especificación; si es necesario, se implementarán como un team-app-dev-mcp aparte.

Comportamiento de GitHub Actions

• CI (ci.yml): Se activa con los PR a main y con los push a release. Solo Checkout → Build (en v0.1 no se ejecutan pruebas). El objetivo es evitar que código roto entre en main.

• Release (release.yml): Se activa solo cuando un PR a main es fusionado y la rama fusionada es release o hotfix/* (quedan excluidos los merges normales de feature/*, chore/*, docs/*, etc.). Detiene tras Checkout → Build → comprobación de que es posible archivar → salida de Release preparation summary. No realiza el envío real a revisión ni la publicación.

Los ci.yml / release.yml que genera setup_repository se generan con el proyecto/scheme Xcode detectado incrustado. Si no se puede detectar automáticamente el proyecto/scheme, no se escribe un workflow con placeholders; se omite la generación y se insta a especificarlo manualmente en .appdev.yml.

Restricciones conocidas (v0.1)

• Se asume solo iOS + GitHub

• El workflow de CI es solo de compilación (no se detectan ni ejecutan targets de prueba)

• run_preflight / check_ci / generate_release_notes, etc., son a partir de v0.2

• Las operaciones del lado de App Store Connect (creación de Version, Submit, etc.) quedan fuera de alcance. Se prevé usarlo junto con otro MCP (appstore-connect-mcp)