ios-vibe-mcp01 0.1.2

package/README.md

@@ -0,0 +1,161 @@
+# ios-vibe-mcp 🚀
+
+Transform any idea into a complete iOS application using AI in Cursor. Works with any LLM (Claude, GPT-4, Gemini, etc.).
+
+`ios-vibe-mcp` is an MCP (Model Context Protocol) server designed for vibe-coding iOS apps with SwiftUI. It generates project specs, architecture plans, coding steps, UI/UX guidance and test strategies — all as Markdown files.
+
+> Note: The tool is currently in MVP stage. The GitHub repository is private for now.
+
+---
+
+## 🚀 Quick Start
+
+### Installation
+
+Install and run with npx:
+
+```bash
+npx ios-vibe-mcp01
+```
+
+### Add to Cursor
+
+Add the following configuration to your Cursor `mcp.json` file and restart Cursor:
+
+```json
+{
+  "mcpServers": {
+    "ios-vibe-factory": {
+      "command": "npx",
+      "args": ["-y", "ios-vibe-mcp01"]
+    }
+  }
+}
+```
+
+## 🧠 Basic Usage (No JSON Required)
+
+You don’t need to write JSON. Just type commands in plain text inside Cursor chat.
+
+1. Generate project blueprint
+
+```
+plan: SwiftUI offline-first notes app with CoreData
+```
+
+Creates: `PROJECT_BLUEPRINT.md`, `TODO.md`, `IOS_RULES.md`, `RUNBOOK.md`, `BACKLOG.md`.
+
+2. Create architecture plan
+
+```
+architecture
+```
+
+Creates: `STAGE_ARCHITECTURE.md`.
+
+3. Generate coding plan
+
+```
+coding
+```
+
+Creates: `STAGE_CODING.md`.
+
+4. Generate UI/UX guide
+
+```
+uiux
+```
+
+Creates: `STAGE_UIUX.md`.
+
+5. Generate test strategy
+
+```
+test
+```
+
+Creates: `STAGE_TEST.md`.
+
+## 🛠️ Commands
+
+- `plan: <idea>` — Generates full product blueprint (`PROJECT_BLUEPRINT.md`)
+- `architecture` — Defines app structure & data layer (`STAGE_ARCHITECTURE.md`)
+- `coding` — Feature-by-feature coding roadmap (`STAGE_CODING.md`)
+- `uiux` — UX/UI checklist & design rules (`STAGE_UIUX.md`)
+- `test` — Testing strategy & critical flows (`STAGE_TEST.md`)
+- `review` — Consistency checks (`REVIEW_REPORT.md`)
+- `ship` — App Store readiness checklist (`SHIP_CHECKLIST.md`)
+
+## 🌟 Key Features
+
+- Command-based workflow for building iOS apps
+- SwiftUI-first architecture
+- Enforces MVVM + Repository pattern
+- Offline-first behavior (no Firebase by default)
+
+Generates: product spec, architecture spec, coding roadmap, UI/UX guide, test plan, App Store checklist.
+
+## 🏗️ How It Works
+
+Workflow: `plan → architecture → coding → uiux → test → review → ship` — each step generates a Markdown spec file and locks scope for the next step.
+
+### Files Generated
+
+- `PROJECT_BLUEPRINT.md` — Full product definition
+- `TODO.md` — Task list for entire app
+- `IOS_RULES.md` — Enforced iOS architecture rules
+- `RUNBOOK.md` — How to run and debug
+- `BACKLOG.md` — Scope lock for new ideas
+- `STAGE_ARCHITECTURE.md` — Folder structure + data layer
+- `STAGE_CODING.md` — Feature-by-feature coding plan
+- `STAGE_UIUX.md` — UX rules & components
+- `STAGE_TEST.md` — Testing strategy
+- `SHIP_CHECKLIST.md` — App Store readiness
+
+## 📱 Platforms Supported
+
+- iOS (SwiftUI)
+
+Storage:
+
+- CoreData (default)
+- SwiftData (experimental)
+
+## 📋 Requirements
+
+- Node.js 18+
+- Cursor IDE (with MCP enabled)
+- Any LLM (Claude, GPT-4, Gemini, etc.)
+- macOS + Xcode (for iOS development)
+
+## 👥 Perfect For
+
+- Beginners — Turn ideas into real iOS apps
+- Developers — Speed up SwiftUI development
+- Startups — Rapid MVP creation
+- Students — Learn by building real apps
+- Indie hackers — Vibe coding workflows
+
+## 🧪 Example Workflow
+
+```
+plan: expense tracker app
+architecture
+coding
+uiux
+test
+ship
+```
+
+## 🛡️ License
+
+MIT
+
+## 👤 Author
+
+Talha Pakdil
+
+GitHub: https://github.com/talhapakdil7
+
+LinkedIn: https://www.linkedin.com/in/talhapakdil

package/dist/index.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { registerIosVibeTool } from "./iosVibe.js";
+const server = new McpServer({
+    name: "iOS Vibe Factory",
+    version: "0.1.0",
+});
+registerIosVibeTool(server);
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error("Fatal MCP server error:", err);
+    process.exit(1);
+});

package/dist/iosVibe.js

@@ -0,0 +1,113 @@
+import { z } from "zod";
+import { renderFilesForCommand } from "./templates.js";
+import { validateWorkflow } from "./rules.js";
+const CommandSchema = z.enum(["plan", "architecture", "coding", "uiux", "test", "review", "ship"]);
+const InputSchema = z.object({
+    command: CommandSchema,
+    idea: z.string().optional(),
+    config: z
+        .object({
+        appName: z.string().default("MyApp"),
+        iosMin: z.string().default("17.0"),
+        storage: z.enum(["coredata", "swiftdata"]).default("coredata"),
+        tone: z.string().default("soft pink"),
+        constraints: z.array(z.string()).default(["offline-first", "no firebase", "mvvm", "repository"]),
+    })
+        .optional(),
+    state: z
+        .object({
+        projectBlueprintMd: z.string().optional(),
+        todoMd: z.string().optional(),
+        stageArchitectureMd: z.string().optional(),
+        stageCodingMd: z.string().optional(),
+        stageUiuxMd: z.string().optional(),
+        stageTestMd: z.string().optional(),
+        iosRulesMd: z.string().optional(),
+        runbookMd: z.string().optional(),
+        backlogMd: z.string().optional(),
+    })
+        .optional(),
+});
+/**
+ * Accepts both:
+ * 1) JSON input (object): { command: "plan", idea: "..." }
+ * 2) Human text input (string): "plan: ..." or "architecture" etc.
+ * Also supports { text: "plan: ..." } shape as a convenience.
+ */
+function normalizeInput(raw) {
+    const text = typeof raw === "string"
+        ? raw
+        : raw && typeof raw === "object" && "text" in raw && typeof raw.text === "string"
+            ? raw.text
+            : null;
+    if (!text)
+        return raw;
+    const t = text.trim();
+    // plan: <idea>
+    const planMatch = t.match(/^plan\s*:\s*(.+)$/i);
+    if (planMatch) {
+        return { command: "plan", idea: planMatch[1].trim() };
+    }
+    // Single-word commands
+    const lower = t.toLowerCase();
+    const allowed = ["architecture", "coding", "uiux", "test", "review", "ship"];
+    if (allowed.includes(lower)) {
+        return { command: lower };
+    }
+    // If user writes just "plan" without idea, let workflow validator handle it
+    if (/^plan$/i.test(t)) {
+        return { command: "plan", idea: "" };
+    }
+    // Fallback: keep original raw so Zod can throw a clear error
+    return raw;
+}
+export function registerIosVibeTool(server) {
+    server.tool("ios_vibe", {
+        // Keep this permissive so the tool can accept either object inputs
+        // or "text" wrappers depending on the client
+        command: z.string().optional(),
+        idea: z.string().optional(),
+        config: z.any().optional(),
+        state: z.any().optional(),
+        text: z.string().optional(),
+    }, async (raw) => {
+        const normalized = normalizeInput(raw);
+        const parsed = InputSchema.safeParse(normalized);
+        if (!parsed.success) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Invalid input: ${parsed.error.message}`,
+                    },
+                ],
+            };
+        }
+        const input = parsed.data;
+        // 1) Workflow gatekeeping
+        const flow = validateWorkflow(input);
+        if (!flow.ok) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Command blocked: ${flow.reason}\n\n` +
+                            `Fix: ${flow.fix}\n\n` +
+                            `Suggested next: ${flow.suggestedNext}`,
+                    },
+                ],
+            };
+        }
+        // 2) Generate files
+        const result = renderFilesForCommand(input);
+        // 3) MCP output
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    });
+}

package/dist/rules.js

@@ -0,0 +1,48 @@
+export function validateWorkflow(input) {
+    const s = input.state ?? {};
+    if (input.command === "plan") {
+        if (!input.idea || input.idea.trim().length < 10) {
+            return {
+                ok: false,
+                reason: "`plan` requires a non-trivial `idea` (>= 10 chars).",
+                fix: "Call ios_vibe with { command: 'plan', idea: '...' }",
+                suggestedNext: "plan",
+            };
+        }
+        return { ok: true };
+    }
+    // plan sonrası her şey için blueprint şart
+    if (!s.projectBlueprintMd || s.projectBlueprintMd.trim().length < 50) {
+        return {
+            ok: false,
+            reason: "Missing PROJECT_BLUEPRINT.md state. Run `plan` first (or pass blueprint in state).",
+            fix: "Call `plan`, write PROJECT_BLUEPRINT.md to disk, then pass it back in `state.projectBlueprintMd`.",
+            suggestedNext: "plan",
+        };
+    }
+    if (input.command === "coding" && (!s.stageArchitectureMd || s.stageArchitectureMd.trim().length < 50)) {
+        return {
+            ok: false,
+            reason: "`coding` requires STAGE_ARCHITECTURE.md (architecture step).",
+            fix: "Run `architecture` first and pass the generated STAGE_ARCHITECTURE.md back in state.",
+            suggestedNext: "architecture",
+        };
+    }
+    if (input.command === "uiux" && (!s.stageCodingMd || s.stageCodingMd.trim().length < 50)) {
+        return {
+            ok: false,
+            reason: "`uiux` works best after `coding` (needs screen & component plan).",
+            fix: "Run `coding` first and pass STAGE_CODING.md back in state.",
+            suggestedNext: "coding",
+        };
+    }
+    if (input.command === "test" && (!s.stageCodingMd || s.stageCodingMd.trim().length < 50)) {
+        return {
+            ok: false,
+            reason: "`test` requires at least STAGE_CODING.md to know critical flows.",
+            fix: "Run `coding` first and pass STAGE_CODING.md back in state.",
+            suggestedNext: "coding",
+        };
+    }
+    return { ok: true };
+}

package/dist/templates.js

@@ -0,0 +1,300 @@
+const md = (s) => s.trim() + "\n";
+export function renderFilesForCommand(input) {
+    const cfg = {
+        appName: input.config?.appName ?? "MyApp",
+        iosMin: input.config?.iosMin ?? "17.0",
+        storage: input.config?.storage ?? "coredata",
+        tone: input.config?.tone ?? "soft pink",
+        constraints: input.config?.constraints ?? ["offline-first", "no firebase", "mvvm", "repository"],
+    };
+    const files = [];
+    const warnings = [];
+    const iosRules = md(`
+# IOS_RULES.md
+
+## Non-negotiables
+- SwiftUI only
+- MVVM + Repository pattern
+- Storage: ${cfg.storage.toUpperCase()}
+- Offline-first by default
+- No Firebase (unless explicitly allowed)
+- Every screen must define: Loading / Empty / Error states
+- New feature requests go to BACKLOG.md (do not expand MVP silently)
+
+## Folder structure (fixed)
+- App/
+- Features/
+  - <Feature>/
+    - Views/
+    - ViewModels/
+    - Models/
+- Core/
+  - DesignSystem/
+  - Persistence/
+  - Utilities/
+- Resources/
+- Tests/
+`);
+    const runbook = md(`
+# RUNBOOK.md
+
+## Requirements
+- macOS + Xcode (CLI tools installed)
+- iOS ${cfg.iosMin}+
+
+## How to run
+- Open the Xcode project/workspace
+- Select a simulator
+- Run (Cmd+R)
+
+## Troubleshooting
+- Build fails: check Signing settings (for device) or run on Simulator first
+- If tests fail: run the failing test target only and re-check data seeding
+`);
+    const backlog = md(`
+# BACKLOG.md
+New ideas go here. Do not expand MVP scope without explicitly moving items into TODO.md.
+`);
+    // PLAN
+    if (input.command === "plan") {
+        const idea = input.idea ?? "";
+        const blueprint = md(`
+# PROJECT_BLUEPRINT.md — ${cfg.appName}
+
+## Product snapshot
+**One-liner:** ${idea}
+
+## Goals (MVP)
+- Deliver the core value in the simplest possible way
+- Offline-first experience
+- Clean MVVM + Repository structure
+
+## Non-goals (Scope lock)
+- Authentication / accounts
+- Backend sync
+- Social feed / chat
+- Payments
+
+## Constraints
+${cfg.constraints.map((c) => `- ${c}`).join("\n")}
+
+## Target platform
+- iOS ${cfg.iosMin}+
+- SwiftUI
+
+## Screens (initial)
+- Onboarding (optional): explain what app does
+- Home: main action + list
+- Detail: item details
+- Profile/Settings: app preferences
+
+## Data model (draft)
+- Entity: **UserProfile** (id, name, createdAt)
+- Entity: **Item** (id, title, note, createdAt, updatedAt)
+
+## Navigation map
+Onboarding → Home → Detail  
+Home → Settings
+
+## Done criteria
+- App runs on simulator
+- Core flow works end-to-end offline
+- Basic empty/error states exist
+- TODO checklist completed
+`);
+        const todo = md(`
+# TODO.md
+
+## 0) Scope lock ✅
+- [ ] Confirm Goals + Non-goals
+- [ ] Confirm screen list
+- [ ] Confirm data model entities
+- [ ] Confirm constraints
+
+## 1) Architecture
+- [ ] Create folder structure (App/Features/Core/Resources/Tests)
+- [ ] Setup ${cfg.storage.toUpperCase()} persistence layer
+- [ ] Define Repository protocols
+- [ ] Define Navigation skeleton
+
+## 2) Coding
+- [ ] Implement Home (View + VM + Repo)
+- [ ] Implement Detail (View + VM + Repo)
+- [ ] Implement Settings/Profile
+- [ ] Handle Loading/Empty/Error states
+
+## 3) UI/UX
+- [ ] Define design tokens (spacing/typography)
+- [ ] Build reusable components (PrimaryButton, EmptyStateView, etc.)
+- [ ] Microcopy pass (onboarding + empty states)
+
+## 4) Test
+- [ ] Unit tests for Repository + ViewModel
+- [ ] 1 UI test for critical flow
+- [ ] Final “ship checklist”
+`);
+        files.push({ path: "PROJECT_BLUEPRINT.md", content: blueprint }, { path: "TODO.md", content: todo }, { path: "IOS_RULES.md", content: iosRules }, { path: "RUNBOOK.md", content: runbook }, { path: "BACKLOG.md", content: backlog });
+        return {
+            files,
+            nextCommand: "architecture",
+            warnings,
+        };
+    }
+    // Always keep these
+    files.push({ path: "IOS_RULES.md", content: iosRules }, { path: "RUNBOOK.md", content: runbook }, { path: "BACKLOG.md", content: backlog });
+    if (input.command === "architecture") {
+        files.push({
+            path: "STAGE_ARCHITECTURE.md",
+            content: md(`
+# STAGE_ARCHITECTURE.md
+
+## Architecture decisions
+- SwiftUI + MVVM
+- Repository layer between VM and persistence
+- Persistence: ${cfg.storage.toUpperCase()}
+
+## Folder structure (create exactly)
+- App/
+- Features/
+  - Home/
+  - Detail/
+  - Settings/
+- Core/
+  - Persistence/
+  - DesignSystem/
+  - Utilities/
+- Resources/
+- Tests/
+
+## TODO (Architecture)
+- [ ] Create folders
+- [ ] Create PersistenceController (${cfg.storage})
+- [ ] Define ItemRepository protocol + default implementation
+- [ ] Define UserProfileRepository protocol + default implementation
+- [ ] Add app-level dependency container (simple struct)
+- [ ] Define navigation routes
+`),
+        });
+        return { files, nextCommand: "coding", warnings };
+    }
+    if (input.command === "coding") {
+        files.push({
+            path: "STAGE_CODING.md",
+            content: md(`
+# STAGE_CODING.md
+
+## Implementation order (feature-by-feature)
+1) Persistence + repositories
+2) Home (list + create)
+3) Detail (view/edit/delete)
+4) Settings/Profile (basic)
+
+## TODO (Coding)
+- [ ] Implement Core/Persistence stack
+- [ ] Implement repositories (CRUD)
+- [ ] HomeView + HomeViewModel
+- [ ] DetailView + DetailViewModel
+- [ ] SettingsView + SettingsViewModel
+- [ ] Wire navigation + previews
+- [ ] Edge states: Loading/Empty/Error
+`),
+        });
+        return { files, nextCommand: "uiux", warnings };
+    }
+    if (input.command === "uiux") {
+        files.push({
+            path: "STAGE_UIUX.md",
+            content: md(`
+# STAGE_UIUX.md
+
+## Visual direction
+- Tone: ${cfg.tone}
+- Simple, minimal, readable
+- Components first
+
+## Screen checklist (must have)
+For each screen:
+- Purpose
+- Primary action
+- Empty state copy
+- Error state copy
+- Loading state UI
+
+## TODO (UI/UX)
+- [ ] Define typography + spacing tokens
+- [ ] Create reusable components:
+  - PrimaryButton
+  - EmptyStateView
+  - ErrorBanner
+  - CardRow
+- [ ] Apply consistent navigation titles + toolbar actions
+`),
+        });
+        return { files, nextCommand: "test", warnings };
+    }
+    if (input.command === "test") {
+        files.push({
+            path: "STAGE_TEST.md",
+            content: md(`
+# STAGE_TEST.md
+
+## Test strategy
+- Unit: repositories + view models
+- UI: critical flow end-to-end
+
+## Critical flow (example)
+Home → create Item → open Detail → edit → back → delete
+
+## TODO (Tests)
+- [ ] Repo unit tests: create/update/delete
+- [ ] VM unit tests: state transitions (empty → loaded)
+- [ ] 1 UI test for critical flow
+- [ ] Run through RUNBOOK and confirm ship readiness
+`),
+        });
+        return { files, nextCommand: "review", warnings };
+    }
+    if (input.command === "review") {
+        files.push({
+            path: "REVIEW_REPORT.md",
+            content: md(`
+# REVIEW_REPORT.md
+
+## Consistency checks
+- [ ] Goals/Non-goals present
+- [ ] Screen list matches coding plan
+- [ ] Data model defined
+- [ ] Architecture rules repeated in IOS_RULES.md
+- [ ] TODO has checkboxes for all stages
+
+## Output
+If anything is missing, add it to TODO.md and/or BACKLOG.md.
+`),
+        });
+        return { files, nextCommand: "ship", warnings };
+    }
+    if (input.command === "ship") {
+        files.push({
+            path: "SHIP_CHECKLIST.md",
+            content: md(`
+# SHIP_CHECKLIST.md
+
+## App Store readiness
+- [ ] App name, subtitle, keywords
+- [ ] Screenshots list (per device size)
+- [ ] Privacy notes (data collected?)
+- [ ] Permissions text (if any)
+- [ ] Versioning + build number
+
+## Technical readiness
+- [ ] No crash on cold start
+- [ ] Works offline
+- [ ] Tests pass
+- [ ] Empty/error states done
+`),
+        });
+        return { files, nextCommand: "plan", warnings };
+    }
+    warnings.push("Unknown command");
+    return { files, nextCommand: "plan", warnings };
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "ios-vibe-mcp01",
+  "version": "0.1.2",
+  "description": "MCP server for vibe coding iOS apps with command-based workflow (plan, architecture, coding, uiux, test)",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "ios-vibe-mcp01": "dist/index.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/talhapakdil7/ios-vibe-mcp"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build",
+    "start": "node dist/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "cursor",
+    "ios",
+    "swiftui",
+    "vibe-coding",
+    "generator",
+    "ai-tools"
+  ],
+  "author": "Talha Pakdil",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.3",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.3",
+    "@types/node": "^20.11.30"
+  }
+}