FTC Toolchain

An MCP server that lets AI agents (Codex, Claude Code, Claude Desktop, or any MCP client) work on FTC robots: search official SDK samples and Pedro Pathing docs, scaffold OpModes, build TeamCode with Gradle, deploy to a REV Control Hub over WiFi, and read robot logs — the full code → robot → debug loop.

Install

Requirements: Node 18+, git, adb (Android platform-tools), and the Android SDK + JDK 17+ if you want to build (an Android Studio install provides both).

Codex

# Register the server (available in every project)
codex mcp add ftc-toolchain -- npx -y ftc-toolchain

# Fetch the reference material the knowledge tools read (one time)
npx ftc-toolchain setup

Start a new Codex task and ask it to “list the FTC sample OpModes” to confirm the server is live.

Claude Code

# Register the server (available in every project)
claude mcp add ftc-toolchain -- npx -y ftc-toolchain

# Fetch the reference material the knowledge tools read (one time)
npx ftc-toolchain setup

Start a new Claude session and ask it to “list the FTC sample OpModes” to confirm it is live.

Claude Desktop / other MCP clients

{
  "mcpServers": {
    "ftc-toolchain": {
      "command": "npx",
      "args": ["-y", "ftc-toolchain"],
      "env": { "FTC_TOOLCHAIN_PROJECT_DIR": "/path/to/your/FtcRobotController" }
    }
  }
}

Then run npx ftc-toolchain setup once so the knowledge tools have their reference data.

From source (development)

git clone https://github.com/Sanjit-K/ftc-toolchain && cd ftc-toolchain
npm install && npm run build
npm run setup      # clones FTC samples + Pedro docs into refs/

Opening this directory in Claude Code picks up .mcp.json automatically.

Reference material: the knowledge tools (list_samples, search_docs, …) read the official FtcRobotController samples and Pedro Pathing docs. ftc-toolchain setup clones them into ~/.ftc-toolchain/refs (override with FTC_TOOLCHAIN_REFS). The project/robot tools work without this step.

Choose how to deploy

Use deploy_robot as the normal high-level deployment tool. It supports two connection methods.

Option 1: direct USB-C

Use this when the programming computer is near the robot. Connect the Control Hub or Robot Controller phone by USB, approve any device prompt, and verify it appears in adb_devices. Then ask:

deploy_robot(connection: "usb")

ftc-toolchain builds a fresh APK, installs it on the attached ADB device, and restarts Robot Controller. If more than one Android device is attached, pass the serial shown by adb_devices. Internet stays connected throughout the deployment.

Option 2: automatic Wi-Fi switching

No phone tether or extra router is required. ftc-toolchain can build while the computer is on internet Wi-Fi, return a job ID to Codex or Claude, then run the network-sensitive part as a local background job:

1. Switch to the saved Control Hub Wi-Fi.
2. Connect to 192.168.43.1:5555 with ADB.
3. Install the freshly built APK and restart Robot Controller.
4. Restore the original internet Wi-Fi even when deployment fails.
5. Let the AI read the saved result after it reconnects.

Before the first automatic deployment, manually join the Control Hub once so macOS or Windows saves its SSID and password. Return to internet Wi-Fi, then ask the AI to call:

deploy_robot(connection: "wifi-switch", robotSsid: "YOUR-CONTROL-HUB-SSID")

The tool builds before disconnecting and waits 10 seconds before changing networks, giving the MCP response time to reach the AI. The AI connection may pause for roughly 20–60 seconds. Once it returns, call wifi_deploy_status with the returned job ID—or omit the ID to read the latest job.

Use dryRun: true to preview every path and network involved without building, switching Wi-Fi, or deploying. Both macOS and Windows are supported. On Windows, the Control Hub must appear as a saved netsh wlan profile. On macOS, it must be a remembered Wi-Fi network available to networksetup.

This is for development and pits only. Disconnect programming computers before a match and follow the current FTC competition manual.

Tools

Start a new session with inspect_project. It reports which FTC project is selected, Git changes, OpModes, documented subsystems, Pedro readiness, hardware-name collisions, the latest APK, reference data, and Android SDK setup—plus the next concrete actions.

Knowledge

| Tool | What it does | |---|---| | list_samples | List the 66 official FTC sample OpModes (drive, sensors, AprilTag vision, ...) | | get_sample | Full Java source of a sample | | search_docs | Keyword search across Pedro Pathing docs + SDK samples | | get_doc | Fetch a Pedro Pathing doc page as markdown | | reference_status | Show local reference counts, commits, branches, dates, and cache location | | update_references | Fast-forward clean FTC SDK and Pedro documentation checkouts |

Project

| Tool | What it does | |---|---| | inspect_project | One-shot readiness check for project path, SDK, Git, OpModes, subsystem docs, Pedro, hardware names, APK, references, and Android tooling | | check_project_hygiene | Read-only pre-competition audit for duplicate names, orphaned files, broken docs, stale builds, TODOs, and Git state | | create_project | Clone a fresh FtcRobotController SDK project | | list_opmodes | List @TeleOp/@Autonomous classes in TeamCode | | list_generated_files | Inventory files scaffolded by ftc-toolchain, grouped by artifact type | | list_backups | Browse project-scoped recovery snapshots made before overwrites | | restore_backup | Preview or restore selected backup files; confirmed restores back up current versions first | | create_opmode | Scaffold an OpMode: linear-teleop, mecanum-teleop, linear-auto, pedro-auto, pedro-teleop | | install_pedro | Add Pedro Pathing to a project (Gradle deps, compileSdk 34, Constants.java scaffold) |

Subsystems — the recommended way to structure robot code: one plain class per mechanism, with a living markdown knowledge base the LLM reads and updates.

All code generators support dryRun: true. This performs the same validation and returns the exact target paths and generated source without touching the filesystem. Use it to review a proposed OpMode, subsystem, calculation helper, or TeleOp before creation or overwrite.

When overwrite: true replaces an existing generated target, ftc-toolchain first copies the old version to ~/.ftc-toolchain/backups (or $FTC_TOOLCHAIN_HOME/backups). The backup stays outside the robot repository. list_generated_files inventories marked scaffolds, but the marker only records origin—team edits are expected and must be preserved.

Use list_backups to find a snapshot and restore_backup to inspect it. Restore is preview-only unless confirm: true; before a confirmed rollback, the files currently in the project are backed up again, so recovery is reversible.

| Tool | What it does | |---|---| | create_subsystem | Scaffold a subsystem class (hardcoded config-name constants, action methods, stop()) with optional injected subsystem dependencies and dashboard-tunable constants, + a bench-test TeleOp + a markdown doc | | document_subsystem | Write/update a subsystem's knowledge-base doc (functions, tuning, config names, quirks) | | list_subsystems / get_subsystem | Read the robot's architecture from docs/ | | create_teleop | Generate a TeleOp plus a separate <Name>Controls.java holding only the button bindings, wiring drive + subsystem actions + automations | | create_calculation | Scaffold a stateless helper class (e.g. live trajectory math) | | hardware_manifest | Aggregate every config name across subsystems and flag duplicates/typos vs. the Driver Station config | | validate_hardware | Pre-flight config check for incompatible device types, shared names, and unresolved constants |

Robot

| Tool | What it does | |---|---| | deploy_robot | Preferred deployment tool: choose direct USB for an attached ADB device or automatic Wi-Fi switching for a saved Control Hub network | | wifi_deploy_start | Lower-level Wi-Fi path: build while online, then launch a local macOS/Windows job that switches networks, deploys, and restores the original Wi-Fi | | wifi_deploy_status | Read the latest or selected background deployment state and its complete switch/deploy/recovery timeline after internet reconnects | | adb_devices / adb_connect | Find / connect to the robot (Control Hub default: 192.168.43.1:5555) | | robot_status | Read device identity, Android/RC app versions, battery service, and storage health | | restart_robot_controller | Restart the RC app without rebuilding or reinstalling code | | build | Gradle build with optional clean/timeout/stacktrace controls, contextual errors, and verified APK metadata | | deploy | Install the APK and restart the Robot Controller app | | build_and_deploy | Build first (optionally clean), verify the APK, then install only that successful artifact | | clear_robot_logs | Clear logcat before reproducing a problem for a clean debugging capture | | robot_logs | Filtered logcat from the robot (crashes, OpMode exceptions, SDK events) |

Typical agent session

1. search_docs("mecanum field centric") / get_sample(...) → find reference code
2. create_opmode(className: "CompTeleOp", template: "mecanum-teleop")
3. deploy_robot(connection: "usb") nearby, or deploy_robot(connection: "wifi-switch", robotSsid: "YOUR-CONTROL-HUB-SSID") wirelessly
4. Fix any compiler errors returned before a background Wi-Fi switch begins
5. Driver tests the OpMode → reconnect with adb_connect when needed, then use robot_logs(filter: "CompTeleOp")

Subsystem workflow

The intended way to build a robot: describe each mechanism to the LLM and let it scaffold subsystems + maintain their docs.

1. "We have a rolling intake — one motor, spins in, spits out." → create_subsystem(name: "RollingIntake", group: "intake", motors: [{name: "intakeMotor", config: "intake"}], methods: ["spinIn", "spitOut"]) → writes RollingIntake.java, TestRollingIntake.java (bench test), and docs/subsystems/RollingIntake.md.
2. Fill in the method bodies (the LLM can, using get_sample/search_docs for reference).
3. document_subsystem to record tuning values, sensor thresholds, and quirks as you dial them in.
4. hardware_manifest before a competition to confirm every config name in code matches the Driver Station configuration — and that two subsystems aren't fighting over one name.
5. A future session runs list_subsystems / get_subsystem and instantly knows the robot.

Sub-subsystems live under a shared group, e.g. group: "shooting.turret" → teamcode/shooting/turret/. Calculation-heavy logic goes in create_calculation helpers so it stays out of the subsystem and OpMode files.

Subsystem composition & tuning. A subsystem can depend on other subsystems — dependencies: [{type: "ColorSensor"}, {type: "IntakeFlap"}] injects them into the constructor (config names stay hardcoded, so the constructor only receives siblings). Declare constants (PID gains, servo positions, RPM setpoints) and the tunable ones become live-editable dashboard fields: the class is annotated @Configurable (Panels, from install_pedro) with public static fields, so you tune them while the robot runs. Pass dashboard: "ftcdashboard" for FTC Dashboard's @Config, or "none".

Building a TeleOp

Describe how driving should feel and what should be automated; create_teleop writes two files:

• <Name>Controls.java — nothing but the bindings (intakeIn → driver.right_bumper). A driver can open this and remap buttons without reading any robot logic or touching an LLM.
• <Name>.java — the TeleOp: constructs the subsystems, wires the drivetrain, applies each binding, and stubs out the automations you described.

"Mecanum drive, hold right bumper to intake / left bumper to outtake, operator Y toggles the shooter, left trigger is slow mode, and auto-sort balls by color." becomes one create_teleop call. Bindings are hold (while held), press (rising edge), or toggle. Competing actions on one mechanism (intake in vs. out) share an exclusiveGroup so they compile to a single if/else-if/else with one idle call — no fighting over the motor. Automations (multi-step or sensor-driven) come out as clearly-marked stub methods to fill in.

Configuration

| Env var | Meaning | |---|---| | FTC_TOOLCHAIN_PROJECT_DIR | Default FTC SDK project used by project/robot tools | | FTC_TOOLCHAIN_PROJECT_DIR | Default FtcRobotController project location | | FTC_TOOLCHAIN_REFS | Location of the reference clones (default: ./refs) | | FTC_TOOLCHAIN_HOME | Toolchain cache, backups, jobs, and workspace root (default: ~/.ftc-toolchain) | | ADB_PATH | Explicit path to adb if not on PATH |

Notes

• Pedro Pathing constants must be tuned. install_pedro scaffolds Constants.java with placeholder values for a mecanum drivetrain + goBILDA Pinpoint localizer; run the tuning OpModes (see search_docs "tuning") before trusting any path.
• The Control Hub's WiFi password and SSID are shown on the Driver Station under Program & Manage.
• Deploying replaces the Robot Controller app's code but keeps robot configurations. If adb install reports a signature mismatch, one adb uninstall com.qualcomm.ftcrobotcontroller is needed (this clears configs).

Development

npm test            # build + MCP smoke test (no robot needed)
npx ftc-toolchain doctor [projectPath] # diagnose local project/tooling readiness
npx ftc-toolchain setup --update       # refresh cached FTC samples and Pedro docs
node scripts/test-build.mjs [projectPath]           # real Gradle build through the build tool
node scripts/test-pedro-build.mjs [projectPath]     # install_pedro + all templates + full build
node scripts/test-subsystem-build.mjs [projectPath] # scaffold intake/spindexer/turret subsystems + a full TeleOp + build

Website and docs

The open-source marketing site and documentation live in website/. It is a Next.js/vinext app with the landing page at / and quickstart documentation at /docs.

cd website
npm install
npm run dev

The website content brief is versioned in website.md.