small-app-dev-mcp

面向小规模、个人开发的 iOS 应用，安全且轻松地处理 Git / GitHub / GitHub Actions / 发布流程的 MCP 服务器。

这个 MCP 不是“用于增加 Git 操作的 MCP”，而是“用于安全发布小规模应用的 MCP”。 它不是直接公开 Git 命令的包装器，而是像 prepare_release、start_hotfix 那样，只将具有意义的操作单元作为 Tool 公开。develop 分支、多个 release 分支、必须 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 服务器启动前提是：将目标应用的仓库作为工作目录，或通过 APP_DEV_PROJECT_DIR 环境变量指定该路径。一个 MCP 服务器进程只处理一个应用仓库。

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

GitHub Token

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

即使未设置 GITHUB_TOKEN（或 GH_TOKEN），MCP 服务器本身也能启动。get_app_status / prepare_release / start_hotfix / sync_release 等仅通过本地 Git 操作即可完成的 Tool 可以直接使用，只有 CI 状态确认、PR 创建、分支保护等需要 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 工具

setup_repository / create_release_pr / start_hotfix / finish_hotfix / sync_release 可通过 dry_run: true 仅显示“将要做什么”的预览。

setup_repository 设置的 main 分支保护：

• 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 へ同期

当 Hotfix 被合并到 main 后，如果尚未同步到 release，get_app_status 和 prepare_release 会始终发出警告（提示执行 sync_release）。

刻意不做的事情

• 对 main 的直接 push、force push、分支删除（Tool 内部也完全不使用）

• 自动提交・自动发布到 App Store / Google Play（在 GitHub 侧准备就绪后即停止）

• App Store 描述、截图、隐私、IAP、审核提交的管理（这是 appstore-connect-mcp 的职责）

• develop 分支、多个 release 分支、必须 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 被合并，且被合并的分支是 release 或 hotfix/* 时触发（feature/*、chore/*、docs/* 等普通合并不触发）。在 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) 组合使用。