Skip to content

Commit a65beb0

Browse files
TMHSDigitalTMHSDigital
committed
polish: match README quality to reference repos
Made-with: Cursor
1 parent 42fa709 commit a65beb0

File tree

1 file changed

+192
-95
lines changed

1 file changed

+192
-95
lines changed

‎README.md‎

Lines changed: 192 additions & 95 deletions
Original file line numberDiff line numberDiff line change
@@ -1,92 +1,194 @@
1+
<p align="center">
2+
<img src="assets/logo.png" alt="Mobile App Developer Tools" width="120">
3+
</p>
4+
15
# Mobile App Developer Tools
26

37
**Go from zero to a running mobile app on your phone.**
48

5-
Version License: CC BY-NC-ND 4.0 CI Validate
9+
[![Version](https://img.shields.io/badge/version-0.1.0-0A84FF?style=for-the-badge&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0id2hpdGUiPjxwYXRoIGQ9Ik0xMiAyTDIyIDEyTDEyIDIyTDIgMTJaIi8+PC9zdmc+)](https://github.com/TMHSDigital/Mobile-App-Developer-Tools/releases)
10+
[![License: CC BY-NC-ND 4.0](https://img.shields.io/badge/License-CC%20BY--NC--ND%204.0-lightgrey?style=for-the-badge)](https://creativecommons.org/licenses/by-nc-nd/4.0/)
11+
[![CI](https://img.shields.io/github/actions/workflow/status/TMHSDigital/Mobile-App-Developer-Tools/ci.yml?branch=main&label=CI&logo=githubactions&style=for-the-badge)](https://github.com/TMHSDigital/Mobile-App-Developer-Tools/actions/workflows/ci.yml)
12+
[![Validate](https://img.shields.io/github/actions/workflow/status/TMHSDigital/Mobile-App-Developer-Tools/validate.yml?branch=main&label=Validate&logo=githubactions&style=for-the-badge)](https://github.com/TMHSDigital/Mobile-App-Developer-Tools/actions/workflows/validate.yml)
13+
[![CodeQL](https://img.shields.io/github/actions/workflow/status/TMHSDigital/Mobile-App-Developer-Tools/codeql.yml?branch=main&label=CodeQL&logo=githubactions&style=for-the-badge)](https://github.com/TMHSDigital/Mobile-App-Developer-Tools/actions/workflows/codeql.yml)
14+
15+
[![npm: mobile-mcp](https://img.shields.io/npm/v/@tmhs/mobile-mcp?style=for-the-badge&logo=npm&label=mobile-mcp)](https://www.npmjs.com/package/@tmhs/mobile-mcp)
16+
[![npm: mobile-dev-tools](https://img.shields.io/npm/v/@tmhs/mobile-dev-tools?style=for-the-badge&logo=npm&label=mobile-dev-tools)](https://www.npmjs.com/package/@tmhs/mobile-dev-tools)
17+
18+
**3 skills** · **1 rule** · **3 MCP tools**
619

7-
**3 skills** - **1 rule** - **3 MCP tools**
20+
[Skills](#skills) · [Rules](#rules) · [MCP Tools](#companion-mobile-mcp-server) · [Install](#installation) · [Roadmap](#roadmap)
21+
22+
<br>
823

924
---
1025

1126
## Overview
1227

13-
Mobile App Developer Tools is a **Cursor** plugin by **TMHSDigital** that packages agent skills, editor rules, and a TypeScript **MCP server** so you can scaffold, run, and debug mobile apps without leaving the IDE. Currently supports React Native/Expo. Flutter support is planned for v0.5.0.
28+
Mobile App Developer Tools is a **Cursor** plugin by **TMHSDigital** that packages agent skills, editor rules, and a TypeScript **MCP server** (`mcp-server/`) so you can scaffold, run, and debug mobile apps without leaving the IDE. Currently at **v0.1.0** with three skills, one rule, and three live MCP tools. Flutter support is planned for v0.5.0.
1429

15-
The first 30 minutes of mobile development is broken. You're Googling "how to set up Expo," fighting simulator configs, wondering why your app won't hot-reload on your phone, and drowning in framework choices before you've written a single line of business logic. This toolkit eliminates that friction.
30+
<br>
31+
<table>
32+
<tr>
33+
<td>
1634

17-
## Quick Start
35+
**What you get**
1836

19-
Install the plugin, then ask anything about mobile development:
37+
| Layer | Role |
38+
| --- | --- |
39+
| **Skills** | Guided workflows: project scaffolding, environment setup, device deployment |
40+
| **Rules** | Guardrails: `mobile-secrets` catches hardcoded API keys and signing credentials |
41+
| **MCP** | Three tools for environment checks, project creation, and device connection |
2042

21-
```
22-
"Create a new Expo app with TypeScript and file-based routing"
23-
"Check if my dev environment is ready for mobile development"
24-
"How do I run this app on my phone?"
25-
```
43+
</td>
44+
<td>
45+
46+
**Quick facts**
47+
48+
| Item | Detail |
49+
| --- | --- |
50+
| **License** | [CC-BY-NC-ND-4.0](LICENSE) |
51+
| **Author** | [TMHSDigital](https://github.com/TMHSDigital) |
52+
| **Repository** | [github.com/TMHSDigital/Mobile-App-Developer-Tools](https://github.com/TMHSDigital/Mobile-App-Developer-Tools) |
53+
| **Runtime** | Node 20+ for MCP server |
54+
| **Framework** | Expo (React Native) + TypeScript |
2655

27-
## How It Works
56+
</td>
57+
</tr>
58+
</table>
59+
<br>
60+
61+
### How it works
2862

2963
```mermaid
3064
flowchart LR
3165
A[User asks mobile dev question] --> B[Cursor loads a Skill]
3266
B --> C{MCP server configured?}
33-
C -- Yes --> D["mobile-mcp tools (3)"]
34-
C -- No --> E[Docs-only guidance]
35-
D --> F[Local environment / scaffolding]
36-
E --> G[Formatted answer in chat]
67+
C -->|Yes| D["mobile-mcp tools (3)"]
68+
C -->|No| E[Docs-only guidance]
69+
D --> F[Local env checks / scaffolding]
70+
E --> G[Answer in chat or code edits]
3771
F --> G
3872
```
3973

40-
**Skills** teach Cursor how to handle mobile dev prompts. **Rules** enforce best practices as you code. The **MCP server** provides real actions (environment checks, project scaffolding, device connection) so skills can do work, not give advice.
74+
<details>
75+
<summary>Expand: end-to-end mental model</summary>
76+
77+
1. Install the plugin (symlink into your Cursor plugins directory).
78+
2. Open a mobile dev task; **rules** such as `mobile-secrets` run as you edit.
79+
3. Invoke a **skill** by name (for example `mobile-project-setup` or `mobile-run-on-device`) when you need a structured workflow.
80+
4. Optionally wire **MCP** so tools like `checkDevEnvironment`, `scaffoldProject`, or `runOnDevice` can take real actions on your machine.
81+
82+
</details>
83+
84+
<br>
4185

4286
---
4387

4488
## Compatibility
4589

46-
| Component | Cursor | Claude Code | Other MCP clients |
47-
|-----------|--------|-------------|-------------------|
48-
| **CLAUDE.md** context | Yes | Yes | - |
49-
| **3 Skills** (SKILL.md) | Yes | Yes | - |
50-
| **1 Rule** (.mdc) | Yes | Via CLAUDE.md | - |
51-
| **3 MCP tools** | Yes | Yes | Yes |
90+
| Client | Skills | Rules | MCP server (`mcp-server/`) |
91+
| --- | --- | --- | --- |
92+
| **Cursor** | Yes (native plugin) | Yes (`.mdc` rules) | Yes, via MCP config |
93+
| **Claude Code** | Yes, copy `skills/` | Yes, via `CLAUDE.md` | Yes, any MCP-capable host |
94+
| **Other MCP clients** | Manual import | Manual import | Yes, stdio transport |
5295

5396
---
5497

55-
## Skills
98+
## Quick Start
5699

57-
**3 skills** for v0.1.0. All Expo-focused.
100+
**1. Clone**
58101

59-
| Skill | Framework | What it does |
60-
|-------|-----------|--------------|
61-
| mobile-project-setup | Expo | Guided project creation with TypeScript, file-based routing, ESLint |
62-
| mobile-dev-environment | Shared | Detect OS, check dependencies (Node, Watchman, Xcode, Android Studio), fix common issues |
63-
| mobile-run-on-device | Expo | Step-by-step for physical device via Expo Go, dev builds, QR code, tunnel mode |
102+
```bash
103+
git clone https://github.com/TMHSDigital/Mobile-App-Developer-Tools.git
104+
cd Mobile-App-Developer-Tools
105+
```
106+
107+
**2. Symlink the plugin (pick your OS)**
108+
109+
Windows PowerShell (run as Administrator if your policy requires it):
64110

65-
**Example prompts:**
111+
```powershell
112+
New-Item -ItemType SymbolicLink `
113+
-Path "$env:USERPROFILE\.cursor\plugins\mobile-app-developer-tools" `
114+
-Target (Resolve-Path .\Mobile-App-Developer-Tools)
115+
```
116+
117+
macOS / Linux:
118+
119+
```bash
120+
ln -s "$(pwd)" ~/.cursor/plugins/mobile-app-developer-tools
121+
```
122+
123+
**3. Build the MCP server**
124+
125+
```bash
126+
cd mcp-server
127+
npm install
128+
npm run build
129+
```
130+
131+
**4. Try it**
132+
133+
Open Cursor and ask:
66134

67135
```
68-
"Set up a new Expo project for a camera app"
69-
"Is my Mac ready for iOS development?"
70-
"My phone can't connect to the dev server - help"
136+
"Create a new Expo app with TypeScript and file-based routing"
137+
"Check if my dev environment is ready for mobile development"
138+
"How do I run this app on my phone?"
71139
```
72140

73141
---
74142

143+
## Skills
144+
145+
All 3 skills are production-ready. Names match the folder under `skills/`.
146+
147+
<details>
148+
<summary><strong>All 3 skills</strong></summary>
149+
150+
| Skill | Framework | What it does |
151+
| --- | --- | --- |
152+
| `mobile-project-setup` | Expo | Guided project creation with TypeScript, file-based routing, ESLint |
153+
| `mobile-dev-environment` | Shared | Detect OS, check dependencies (Node, Watchman, Xcode, Android Studio), fix common issues |
154+
| `mobile-run-on-device` | Expo | Step-by-step for physical device via Expo Go, dev builds, QR code, tunnel mode |
155+
156+
</details>
157+
158+
**Example prompts** - one per skill:
159+
160+
| Skill | Try this |
161+
| --- | --- |
162+
| `mobile-project-setup` | "Set up a new Expo project for a camera app" |
163+
| `mobile-dev-environment` | "Is my Mac ready for iOS development?" |
164+
| `mobile-run-on-device` | "My phone can't connect to the dev server - help" |
165+
166+
---
167+
75168
## Rules
76169

77-
**1 rule** for v0.1.0.
170+
All 1 rule is production-ready.
171+
172+
<details>
173+
<summary><strong>All 1 rule</strong></summary>
78174

79175
| Rule | Scope | What it catches |
80-
|------|-------|-----------------|
81-
| mobile-secrets | Always on | API keys, signing credentials, keystore passwords, Firebase config, `.p8`/`.p12` files, EAS tokens |
176+
| --- | --- | --- |
177+
| `mobile-secrets` | Always on | API keys, signing credentials, keystore passwords, Firebase config, `.p8`/`.p12` files, EAS tokens |
178+
179+
</details>
82180

83181
---
84182

85183
## Companion: Mobile MCP Server
86184

87-
The MCP server gives your AI assistant the ability to take real actions on your local machine.
185+
[![npm version](https://img.shields.io/npm/v/@tmhs/mobile-mcp?style=flat-square&logo=npm)](https://www.npmjs.com/package/@tmhs/mobile-mcp)
186+
187+
The MCP server gives your AI assistant the ability to take real actions on your local machine. No API keys required.
188+
189+
**Setup**
88190

89-
Add to your Cursor MCP config (`.cursor/mcp.json`):
191+
Add to `.cursor/mcp.json`:
90192

91193
```json
92194
{
@@ -100,61 +202,50 @@ Add to your Cursor MCP config (`.cursor/mcp.json`):
100202
}
101203
```
102204

103-
### MCP Tools (3)
205+
Or install globally via npm:
104206

105-
| Tool | Purpose |
106-
|------|---------|
107-
| mobile_checkDevEnvironment | Detect installed tools (Node, Expo CLI, Watchman, Xcode, Android Studio, JDK). Report what is missing with install instructions. |
108-
| mobile_scaffoldProject | Generate a new Expo project with TypeScript template and recommended config. |
109-
| mobile_runOnDevice | Start dev server and provide step-by-step instructions for connecting a physical device. |
110-
111-
---
112-
113-
## NPM Package
207+
```bash
208+
npx @tmhs/mobile-mcp
209+
```
114210

115-
The `@tmhs/mobile-dev-tools` package provides shared utilities for mobile development. Currently a stub to reserve the name. Full functionality coming in future releases.
211+
<details>
212+
<summary><strong>All 3 MCP tools</strong></summary>
116213

117-
```bash
118-
npm install -g @tmhs/mobile-dev-tools
214+
| Tool | Purpose |
215+
| --- | --- |
216+
| `mobile_checkDevEnvironment` | Detect installed tools (Node, Expo CLI, Watchman, Xcode, Android Studio, JDK). Report what is missing with install instructions. |
217+
| `mobile_scaffoldProject` | Generate a new Expo project with TypeScript template and recommended config. |
218+
| `mobile_runOnDevice` | Start dev server and provide step-by-step instructions for connecting a physical device. |
119219

120-
# CLI usage (coming soon)
121-
mobile-dev check-env
122-
mobile-dev scaffold --framework expo --template default
123-
```
220+
</details>
124221

125222
---
126223

127-
## Installation
224+
## NPM Package
128225

129-
> **Marketplace listing pending review.** Use manual installation.
226+
[![npm version](https://img.shields.io/npm/v/@tmhs/mobile-dev-tools?style=flat-square&logo=npm)](https://www.npmjs.com/package/@tmhs/mobile-dev-tools)
130227

131-
Clone the repo and symlink it to your local plugins directory:
228+
The `@tmhs/mobile-dev-tools` package provides shared CLI utilities for mobile development.
132229

133230
```bash
134-
git clone https://github.com/TMHSDigital/Mobile-App-Developer-Tools.git
231+
npm install -g @tmhs/mobile-dev-tools
232+
mobile-dev --help
135233
```
136234

137-
**Windows (PowerShell as Admin)**
138-
139-
```powershell
140-
New-Item -ItemType SymbolicLink `
141-
-Path "$env:USERPROFILE\.cursor\plugins\mobile-app-developer-tools" `
142-
-Target (Resolve-Path .\Mobile-App-Developer-Tools)
143-
```
235+
Full functionality (environment checker, template engine, store metadata validator) is coming in future releases. See [ROADMAP.md](ROADMAP.md).
144236

145-
**macOS / Linux**
237+
---
146238

147-
```bash
148-
ln -s "$(pwd)/Mobile-App-Developer-Tools" ~/.cursor/plugins/mobile-app-developer-tools
149-
```
239+
## Installation
150240

151-
Build the MCP server:
241+
| Step | Action |
242+
| --- | --- |
243+
| 1 | Clone [Mobile-App-Developer-Tools](https://github.com/TMHSDigital/Mobile-App-Developer-Tools) |
244+
| 2 | Symlink the repo per [Quick Start](#quick-start) |
245+
| 3 | Restart Cursor |
246+
| 4 | (Optional) Register MCP: point your client at `mcp-server/dist/index.js` after `npm run build` |
152247

153-
```bash
154-
cd mcp-server
155-
npm install
156-
npm run build
157-
```
248+
Plugin manifest: [`.cursor-plugin/plugin.json`](.cursor-plugin/plugin.json).
158249

159250
---
160251

@@ -165,38 +256,44 @@ No API keys are required for v0.1.0. All tools work locally.
165256
Future versions may use:
166257

167258
| Variable | Required | Description |
168-
|----------|----------|-------------|
169-
| EXPO_TOKEN | For EAS builds | Expo access token for CI/CD |
170-
| APPLE_ID | For iOS submission | Apple Developer account email |
171-
| GOOGLE_SERVICE_ACCOUNT | For Android submission | Play Console service account JSON |
259+
| --- | --- | --- |
260+
| `EXPO_TOKEN` | For EAS builds | Expo access token for CI/CD |
261+
| `APPLE_ID` | For iOS submission | Apple Developer account email |
262+
| `GOOGLE_SERVICE_ACCOUNT` | For Android submission | Play Console service account JSON |
172263

173264
---
174265

175266
## Roadmap
176267

268+
Summary aligned with [ROADMAP.md](ROADMAP.md):
269+
177270
| Version | Theme | Highlights | Status |
178-
|---------|-------|------------|--------|
179-
| **v0.1.0** | Zero to Phone | 3 skills, 1 rule, 3 MCP tools, project scaffolding, env check, device deploy | **Current** |
180-
| **v0.2.0** | Navigate & State | Navigation setup, state management, component generation | |
181-
| **v0.3.0** | Camera & AI | Camera integration, AI features, permissions | |
182-
| **v0.4.0** | Users & Data | Auth, push notifications, local storage, API integration | |
183-
| **v0.5.0** | Flutter | Flutter project setup, navigation, device deploy, state management | |
184-
| **v0.6.0** | Ship It | App store prep, iOS and Android submission | |
185-
| **v0.7.0** | Grow | Monetization, deep links, bundle analysis | |
186-
| **v1.0.0** | Stable | 22 skills, 7 rules, 18 MCP tools | |
187-
188-
See [ROADMAP.md](ROADMAP.md) for the full breakdown of each version.
271+
| --- | --- | --- | --- |
272+
| **v0.1.0** | Zero to Phone | 3 skills, 1 rule, 3 MCP tools | **Current** |
273+
| **v0.2.0** | Navigate & State | Navigation setup, state management, component generation | |
274+
| **v0.3.0** | Camera & AI | Camera integration, AI features, permissions | |
275+
| **v0.4.0** | Users & Data | Auth, push notifications, local storage, API integration | |
276+
| **v0.5.0** | Flutter | Flutter project setup, navigation, device deploy, state management | |
277+
| **v0.6.0** | Ship It | App store prep, iOS and Android submission | |
278+
| **v0.7.0** | Grow | Monetization, deep links, bundle analysis | |
279+
| **v1.0.0** | Stable | 22 skills, 7 rules, 18 MCP tools | |
189280

190281
---
191282

192283
## Contributing
193284

194-
Contributions welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on adding skills, rules, and MCP tools.
285+
Issues and PRs are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on adding skills, rules, and MCP tools.
286+
287+
---
195288

196289
## License
197290

198-
**CC-BY-NC-ND-4.0** - Copyright 2026 TM Hospitality Strategies. See [LICENSE](LICENSE).
291+
Copyright (c) TM Hospitality Strategies. Licensed under **CC-BY-NC-ND-4.0** - see [LICENSE](LICENSE).
199292

200293
---
201294

202-
Built by [TMHSDigital](https://github.com/TMHSDigital)
295+
<p align="center">
296+
297+
**Mobile App Developer Tools** · Built by [TMHSDigital](https://github.com/TMHSDigital) · [Repository](https://github.com/TMHSDigital/Mobile-App-Developer-Tools)
298+
299+
</p>

0 commit comments

Comments
 (0)