QUICKSTART
From install to first build.
FTC Toolchain runs locally and gives your MCP-compatible AI a set of focused tools for working inside an FtcRobotController project.
Install Node 18+ and Android Studio. You only need adb when deploying to a physical Control Hub.
1. Add the MCP server
Codex
$ codex mcp add ftc-toolchain -- npx -y ftc-toolchainClaude Code
$ claude mcp add ftc-toolchain -- npx -y ftc-toolchain2. Set up your project
$ cd ~/FtcRobotController
$ npx ftc-toolchain setup3. Ask for a mechanism
“Preview an intake subsystem with one motor called intakeMotor. Add spinIn, spinOut, and stop.”
Every code generator supports dryRun: true, so your AI can show the exact Java, docs, and target paths before writing anything. Approve the shape, then create it and run a build.
Complete tool reference
All 35 MCP tools are listed below. These descriptions closely mirror the metadata the LLM receives when it decides which tool to call.
Knowledge
list_samplesLists official FtcRobotController sample OpModes for drive code, sensors, AprilTag vision, gamepads, telemetry, and other SDK features. Filter by Basic, Concept, Robot, Sensor, Sample, or Utility.get_sampleReturns the complete Java source of an official FTC sample OpMode by the name returned from list_samples, such as BasicOmniOpMode_Linear.search_docsSearches Pedro Pathing documentation and official FTC sample OpModes. Use it for path following, tuning, localization, coordinates, hardware APIs, and SDK behavior; small technical-term typos are tolerated.get_docReturns a complete Pedro Pathing documentation page as Markdown using an ID returned by search_docs, such as pathing/tuning/localization/pinpoint.reference_statusReports local FTC sample and Pedro documentation counts, Git branches, commits, commit dates, cache age, and the exact reference-library location without using the network.update_referencesFast-forwards the cached official FTC SDK samples and Pedro docs checkouts, then refreshes the search cache. Refuses to touch either checkout when it contains local changes.Project
inspect_projectStart here when entering a robot project or debugging setup. Summarizes the resolved project path, SDK, Git state, OpModes, subsystem docs, Pedro setup, hardware-name collisions, latest APK, reference library, Android SDK, and next actions.check_project_hygieneRuns a read-only pre-competition audit for duplicate Driver Station names, orphaned generated file pairs, broken subsystem-doc links, incompatible hardware types, stale or missing APKs, disabled OpModes, TODOs, and uncommitted Git changes.create_projectClones a fresh official FtcRobotController SDK project into the ftc-toolchain workspace or a specified destination. Skip this when the team already has a project and pass that path to other tools.list_opmodesLists every @TeleOp and @Autonomous class in TeamCode, including its Java class, Driver Station display name, relative file path, type, and whether it is @Disabled.list_generated_filesInventories Java and robot-documentation files marked as scaffolded by ftc-toolchain, grouped by artifact kind. Markers identify origin only—team edits are expected and must be preserved.list_backupsLists project-scoped recovery snapshots created automatically before ftc-toolchain overwrites files, including each backup ID and every contained relative path.restore_backupPreviews restoring all or selected relative paths from an ftc-toolchain backup. Nothing changes unless confirm is true; a confirmed restore first backs up the current versions and never deletes unrelated files.create_opmodeScaffolds a Java OpMode in TeamCode from linear TeleOp, mecanum TeleOp, linear autonomous, Pedro autonomous, or Pedro TeleOp templates. Supports custom display name, group, package, safe preview, and explicit overwrite.install_pedroInstalls Pedro Pathing into an FTC SDK project: adds the Maven repository and dependencies, raises compileSdk to 34 when needed, and scaffolds mecanum + Pinpoint Constants.java. Every generated constant must be tuned afterward.Robot architecture
create_subsystemScaffolds one plain FTC subsystem class with HardwareMap construction, typed hardware fields, config-name constants, injected subsystem dependencies, action methods, and a real safety stop(). It can also create a bench-test TeleOp and living Markdown documentation.document_subsystemWrites or updates docs/subsystems/<Name>.md and refreshes docs/ROBOT.md. Use it to preserve functions, hardware names, tuning values, quirks, wiring notes, and mechanical constraints for future sessions.list_subsystemsLists the robot’s documented subsystems from the docs/ knowledge base with their summaries and file paths. Use it first to understand the existing robot architecture.get_subsystemReturns one subsystem’s knowledge-base document—hardware, config names, functions, tuning, and quirks—and can append the matching Java source when includeSource is true.create_calculationScaffolds a stateless, static-only Java helper for reusable calculations such as live trajectory math. Supports package grouping, safe preview, and explicit overwrite so math stays out of OpModes and subsystem classes.hardware_manifestScans TeamCode for every robot-configuration name used by hardwareMap and generated subsystem constructors, reports each type and source file, and flags names shared across files for Driver Station cross-checking.validate_hardwareRuns a hardware preflight that flags one Driver Station name requested as incompatible device types, cross-file sharing, and unresolved constants, then reports whether errors must be fixed before running an OpMode.create_teleopGenerates a TeleOp plus a separate <Name>Controls.java containing only controller bindings. Supports mecanum or Pedro drive, subsystem construction, hold/press/toggle actions, exclusive groups, safety guards, slow mode, automation stubs, dry-run preview, and explicit overwrite.Build, deploy & debug
deploy_robotPreferred high-level deployment entry point. Choose usb to build and install on a Control Hub or Robot Controller already visible to adb over a physical cable, or wifi-switch to build online and queue the saved-network switch, ADB install, app restart, and original-Wi-Fi restoration workflow.wifi_deploy_startBuilds TeamCode while internet is available, then starts a local background job that switches macOS or Windows to a saved Control Hub Wi-Fi profile, connects ADB, installs the APK, restarts Robot Controller, and restores the original Wi-Fi even after failure. Returns the job ID before disconnecting.wifi_deploy_statusReads the latest or specified background Wi-Fi deployment after internet reconnects. Reports queued, switching, deploying, returning, succeeded, or failed state with the complete local build, deployment, and recovery timeline.adb_devicesLists Android devices visible to adb, including connected REV Control Hubs and Robot Controller phones, with guidance when no device is attached.adb_connectConnects adb to a REV Control Hub or Robot Controller phone over Wi-Fi. The default target is 192.168.43.1:5555 when the laptop is joined to the Control Hub access point.robot_statusReturns a read-only snapshot of the selected device: adb serial, model, Android version, Robot Controller app version, Android battery-service level and temperature, and data-storage usage. A serial is required when multiple devices are connected.restart_robot_controllerForce-stops and restarts the Robot Controller app without rebuilding or reinstalling an APK. Use it when the Driver Station is stale or an OpMode left the app unhealthy.buildCompiles :TeamCode:assembleDebug with Gradle, optionally cleaning first and using a custom timeout or stacktrace. Returns verified APK path, size, and duration on success, or contextual compiler/Gradle errors on failure.deployInstalls an already-built TeamCode debug APK on the selected robot with adb install -r, then restarts the Robot Controller app. Run build first; specify serial when multiple devices are attached.build_and_deployThe safest competition-day path: builds TeamCode first, verifies that the expected fresh APK exists, installs only after that build succeeds, and restarts the Robot Controller app. Supports clean, timeout, stacktrace, and device-serial options.clear_robot_logsClears the selected robot’s logcat buffer before reproducing a crash or bad behavior. Reproduce the problem, then call robot_logs for a clean signal.robot_logsReturns recent logcat from the selected robot after deployment or an OpMode failure. Limit the line count, filter case-insensitively by OpMode/RobotCore/Exception text, or request error-level entries only.Human-editable bindings
Generated TeleOps keep button mappings separate from subsystem logic. Drivers can remap controls without touching how the mechanism works.
Robot knowledge base
FTC Toolchain maintains a plain-text docs/ directory describing hardware names, subsystem commands, and project structure. A new AI session can inspect it before making changes.
Two ways to deploy
Use deploy_robot and choose the connection that fits where you are working.
Direct USB-C
Connect the Control Hub or Robot Controller phone to the programming computer, approve any device prompt, and confirm it appears in adb_devices.
“Deploy to the robot using USB.”
The USB path builds a fresh APK, installs it on the attached ADB device, and restarts Robot Controller without interrupting internet. Pass the device serial when more than one Android device is connected.
Automatic Wi-Fi switching
No phone tether is needed. Build on internet Wi-Fi, then let a local job switch to the Control Hub, deploy, and return to the original network. The AI may disconnect briefly, but the worker keeps running without internet and saves its result locally.
Join the Control Hub manually once so macOS or Windows saves its SSID and password. Then reconnect to your normal internet Wi-Fi.
Preview without changing anything
“Preview a Wi-Fi-switch deployment to FTC-12345.”
Build, switch, deploy, and return
“Deploy to the saved Wi-Fi network FTC-12345.”
The Wi-Fi path builds first, returns its job ID, waits 10 seconds, switches networks, deploys through ADB, and restores the original Wi-Fi in a recovery block. After internet returns, wifi_deploy_status reads the result. It works on macOS and Windows.
Disconnect programming computers before a match and follow the current FTC competition manual.
Troubleshooting
Gradle sync does not appear+
Open the FtcRobotController folder itself in Android Studio, not its parent directory.
The docs folder is missing in Android Studio+
Switch the project browser from Android view to Project view.
Deploy fails with a signature mismatch+
Uninstall the existing Robot Controller package with adb, then deploy again.
Configuration
FTC_TOOLCHAIN_PROJECT_DIRDefault FTC project locationFTC_TOOLCHAIN_REFSAdditional local reference sourcesFTC_TOOLCHAIN_HOMECache, backups, jobs, and workspace rootADB_PATHCustom Android Debug Bridge path