|
| 1 | +# AGENTS — How AI Should Work in This Repo |
| 2 | + |
| 3 | +> **This is the single source of truth for any AI agent (OpenCode, Codex, Claude Code, Cursor, Copilot, etc.) working in this repository.** |
| 4 | +> If you are an AI, read this whole file before editing anything. If you are a human, this tells you what to expect from AI. |
| 5 | +
|
| 6 | +**Version:** 1.0.0 · **Applies to:** `YanxReal/Xcode-MPC` · **Stack:** `index.js` single-file MCP server, Yarn 4, Make, `StdioServerTransport` |
| 7 | + |
| 8 | +--- |
| 9 | + |
| 10 | +## 1. Bilingual Rule — NON-NEGOTIABLE |
| 11 | + |
| 12 | +This repo is **bilingual by design**: |
| 13 | + |
| 14 | +| Language | Canonical files | Audience | |
| 15 | +|---|---|---| |
| 16 | +| **English (primary)** | `README.md`, `docs/*.md` | International, GitHub default | |
| 17 | +| **Español (mirror)** | `README.es.md`, `docs/es/*.md` | Hispanohablante | |
| 18 | + |
| 19 | +**Rule:** *Every change to a user-facing Markdown file MUST be mirrored in both languages in the same commit.* |
| 20 | + |
| 21 | +- If you edit `README.md`, you **must** edit `README.es.md` with the equivalent Spanish translation. |
| 22 | +- If you edit `docs/installation.md`, you **must** edit `docs/es/installation.md`. |
| 23 | +- If you edit `docs/tools.md`, you **must** edit `docs/es/tools.md`, etc. |
| 24 | +- Do **not** leave one language behind. A PR that touches `docs/opencode.md` but not `docs/es/opencode.md` will be rejected. |
| 25 | + |
| 26 | +**How to translate:** |
| 27 | +- Keep structure identical (same headings, order, tables). Only language changes. |
| 28 | +- Preserve code blocks, JSON/TOML, `shellEscape` examples, and `index.js:line` references verbatim — do not translate code. |
| 29 | +- Keep badges, links, and `{{placeholders}}` intact. Translate only prose. |
| 30 | +- When in doubt, copy the English structure and translate paragraph by paragraph to Spanish. |
| 31 | + |
| 32 | +**Verification (run before commit):** |
| 33 | +```bash |
| 34 | +# Both READMEs must have same tool count |
| 35 | +grep -c "47 tools" README.md |
| 36 | +grep -c "47 herramientas" README.es.md |
| 37 | +# Both docs sets must exist |
| 38 | +ls docs/*.md docs/es/*.md |
| 39 | +# No 25/31/43 leftovers |
| 40 | +grep -r "25 tools\|31 tools\|43 tools" --include="*.md" docs/ README* && echo "FAIL: stale count" || echo "OK" |
| 41 | +``` |
| 42 | + |
| 43 | +--- |
| 44 | + |
| 45 | +## 2. Language Switcher |
| 46 | + |
| 47 | +Every file has a switcher at the top: |
| 48 | + |
| 49 | +- English files: `> 🌐 **Language:** **English** | [Español](es/... or README.es.md)` |
| 50 | +- Spanish files: `> 🌐 **Idioma:** [English](../... or README.md) | **Español**` |
| 51 | + |
| 52 | +If you create a **new doc** `docs/new-feature.md`, you **must** also create `docs/es/new-feature.md` with the mirrored switcher: |
| 53 | +- `docs/new-feature.md` → `[Español](es/new-feature.md)` |
| 54 | +- `docs/es/new-feature.md` → `[English](../new-feature.md)` |
| 55 | + |
| 56 | +Same for `README.md` ↔ `README.es.md`. |
| 57 | + |
| 58 | +--- |
| 59 | + |
| 60 | +## 3. Project Conventions |
| 61 | + |
| 62 | +### 3.1 Single-File Server |
| 63 | +- `index.js` is **intentionally monolithic** (~2250 lines, single file). Do not split into `src/` without explicit human approval. |
| 64 | +- Keep `#!/usr/bin/env node`, `import { Server } from "@modelcontextprotocol/sdk/server/index.js"` and `import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"` at the top. |
| 65 | +- Use `promisify(exec)` with `MAX_BUFFER=10MB`, `shellEscape`, `expandTilde`, `runCommand`, `formatResult`, `textContent`/`errorContent` helpers. |
| 66 | +- Every tool needs: `TOOLS` entry (`name`, `description`, `inputSchema` with `additionalProperties:false`) + `async handle_*` + `HANDLERS` registration + `try/catch` in `CallToolRequestSchema`. |
| 67 | + |
| 68 | +### 3.2 Adding a New Tool |
| 69 | +1. Define in `TOOLS` (`index.js:142` area) with JSON Schema. |
| 70 | +2. Implement `handle_new_tool` before `// Dispatcher` with validation, `fs.access`, `shellEscape`, and `return textContent` / `errorContent`. |
| 71 | +3. Register in `HANDLERS` map and bump `Server version` (`1.3.0` → `1.3.1` for patch, `1.4.0` for feature) and log `47→48 herramientas registradas`. |
| 72 | +4. Update `package.json:version` + `description` (`47 herramientas`). |
| 73 | +5. Update **both** `README.md` + `README.es.md`: Features table, Tools section (numbered), TOC anchor, smoke count. |
| 74 | +6. Update **both** `docs/tools.md` + `docs/es/tools.md`: add section `## 13. ...` with JSON examples. |
| 75 | +7. Run `make lint && make test` (must be `47→48 tools`). |
| 76 | +8. Commit bilingual docs together. |
| 77 | + |
| 78 | +### 3.3 Yarn 4 + Make |
| 79 | +- `packageManager: "yarn@4.18.0"`, `nodeLinker: node-modules` in `.yarnrc.yml`, vendored `.yarn/releases/yarn-4.18.0.cjs` must stay committed. |
| 80 | +- Always use `make install` (not `yarn install` directly in docs examples for beginners), `make lint`, `make doctor`, `make test`, `make inspect`. |
| 81 | +- `yarn.lock` must be committed; `yarn install --immutable` in CI. |
| 82 | + |
| 83 | +### 3.4 Versioning & Docs Counts |
| 84 | +- Current: **47 tools**, **1.3.0**, **2250 lines**. When you add a tool, search-replace `47 → 48` in `README*`, `docs/**/tools.md`, `docs/**/development.md`, `docs/**/architecture.md`, `SECURITY.md`, `package.json`, and `index.js` log. |
| 85 | +- Never leave `25`/`31`/`43` leftovers — the `AGENTS.md` check above must pass. |
| 86 | + |
| 87 | +--- |
| 88 | + |
| 89 | +## 4. Behavior & Tone |
| 90 | + |
| 91 | +- **Objective & concise.** No fluff, no excessive praise. State facts, show `file:line`, show commands. |
| 92 | +- **Verify before claiming.** Run `node --check index.js`, `make test`, or `python3 scripts/smoke_test.py` before saying “it works”. |
| 93 | +- **Evidence > speculation.** If your finding contradicts a prior claim, state the discrepancy and trust the file. |
| 94 | +- **No TODO comments.** Deliver complete, runnable code (`// TODO: ...` is forbidden). |
| 95 | +- **Ask before destructive actions.** `make clean` / `rm -rf ~/Library/Developer/Xcode/DerivedData` / `git push --force` require explicit user confirmation. |
| 96 | + |
| 97 | +--- |
| 98 | + |
| 99 | +## 5. Multi-Client Support |
| 100 | + |
| 101 | +The same `index.js` (stdio) must work with **all three clients** without changes: |
| 102 | + |
| 103 | +| Client | Config | Verify | |
| 104 | +|---|---|---| |
| 105 | +| **OpenCode** | `~/.config/opencode/opencode.jsonc` → `mcp.xcode.command: ["node", "/.../index.js"]` | Restart OpenCode → `list xcode tools` | |
| 106 | +| **Codex** | `~/.codex/config.toml` → `[mcp_servers.xcode] command="node"` | `codex mcp list` | |
| 107 | +| **Claude Code** | `claude mcp add xcode -- node /.../index.js` or `.mcp.json` | `claude mcp list` | |
| 108 | + |
| 109 | +If you change MCP transport or args, test all three. Document in **both** `README.md` and `README.es.md`. |
| 110 | + |
| 111 | +--- |
| 112 | + |
| 113 | +## 6. Commit & PR Rules |
| 114 | + |
| 115 | +- Commit messages: `feat: ...`, `fix: ...`, `docs: ...`, `chore: ...` in **English** (even if docs are bilingual). |
| 116 | +- Every commit that touches `*.md` must show `README.md` + `README.es.md` or `docs/*.md` + `docs/es/*.md` together. Example: |
| 117 | + ``` |
| 118 | + docs: add asset_generate_appicon (47→48) |
| 119 | + ``` |
| 120 | +- PR template: check `make lint && make test` OK, and confirm bilingual sync. |
| 121 | +- Never commit `node_modules`, `.yarn/cache`, `DerivedData`, `*.ipa`, `.env`. |
| 122 | + |
| 123 | +--- |
| 124 | + |
| 125 | +## 7. Checklist Before Push (AI must run) |
| 126 | + |
| 127 | +```bash |
| 128 | +make lint |
| 129 | +make test # must show 47 tools |
| 130 | +grep -r "25 tools\|31 tools\|43 tools" --include="*.md" . && echo "FAIL" || echo "OK bilingual counts" |
| 131 | +ls docs/es/*.md | wc -l # must equal ls docs/*.md | wc -l |
| 132 | +node --check index.js |
| 133 | +``` |
| 134 | + |
| 135 | +If any check fails, fix before `git push`. |
| 136 | + |
| 137 | +--- |
| 138 | + |
| 139 | +## 8. If You Are Unsure |
| 140 | + |
| 141 | +- Ask the user (in their language: if they wrote in Spanish, answer in Spanish) before guessing URLs, tool counts, or Apple API names. |
| 142 | +- Prefer editing existing files over creating new ones. Never create `*.md` unless explicitly requested, except the required mirror in `docs/es/`. |
| 143 | + |
| 144 | +**Remember:** *Bilingual sync is not optional — it is the definition of “done” in this repo.* |
| 145 | + |
| 146 | +--- |
| 147 | + |
| 148 | +*Maintained by [@YanxReal](https://github.com/YanxReal) — last updated 2026-08-27 for 47 tools, v1.3.0, Yarn 4 + Make + CI + Vision/UI.* |
0 commit comments