mcp-server-simulator-ios-idb: Instructions file for Codex

AGENTS.md

Repository-local guidance for AI coding agents and human contributors working on mcp-server-simulator-ios-idb — an MCP server that lets LLMs control iOS simulators via natural language instructions executed through idb and xcrun simctl.

For component responsibilities, the execution flow, the session model, and the checklist for adding a new command, read ARCHITECTURE.md. This file intentionally does not duplicate it.

Build, test, and run

Actual scripts defined in package.json (there is no lint script in this repository):

Command	What it does
npm run build	Compiles TypeScript to dist/ with tsc
npm test	Runs Jest with ts-jest (NODE_OPTIONS=--experimental-vm-modules)
npm run test:coverage	Same as npm test with coverage
npm start	Runs node dist/index.js (the MCP stdio server)

⚠️ Dependency installation has heavy side effects

npm install and npm ci both trigger the postinstall script (scripts/install_dependencies.sh), which:

1. Hard-fails unless running on macOS with Homebrew available.
2. Runs brew tap facebook/fb && brew install idb-companion.
3. Hard-fails unless a Python virtual environment is already active ($VIRTUAL_ENV must be set), then runs python3 -m pip install --upgrade pip followed by python3 -m pip install fb-idb into it.

Do not run these installers as part of agent work unless installing dependencies is explicitly the task. Before running them manually, create and activate the venv (python3 -m venv venv && source venv/bin/activate) and keep it active whenever the server runs.

Language and module conventions

• TypeScript ESM, "module": "NodeNext" / "moduleResolution": "NodeNext" (tsconfig.json), targeting ES2020 with strict: true.
• Relative imports must end in .js (e.g. import { IDBManager } from '../idb/IDBManager.js') — this is required by NodeNext ESM resolution even for .ts source files. Do not write extensionless relative imports.
• Node.js >= 20; package.json declares "os": "darwin" in its engines field.
• Keep the SPDX copyright and license header lines at the top of source files, consistent with existing files and REUSE.toml.