ftc-mcp 1.0.0 → 1.1.0

package/build/knowledge/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Centralized knowledge index for progressive discovery.
+ *
+ * Inspired by Cloudflare's Code Mode pattern: instead of enumerating every
+ * possible value in tool descriptions (which wastes context tokens), this
+ * module provides runtime lookup functions. Tool descriptions stay compact
+ * and options are returned dynamically when needed.
+ */
+interface ResourceEntry {
+    name: string;
+    key: string;
+}
+interface CategoryDef {
+    source: Record<string, string>;
+    label: string;
+    entries: Record<string, ResourceEntry>;
+}
+export declare const CATEGORIES: Record<string, CategoryDef>;
+export declare function getResource(category: string, slug: string): string | null;
+export declare function listResources(category: string): Array<{
+    uri: string;
+    name: string;
+}>;
+export declare function buildSearchIndex(): Array<{
+    category: string;
+    key: string;
+    content: string;
+}>;
+export declare function getExample(topic: string): string | null;
+export declare function listExamples(): string[];
+export declare function lookupDeviceReference(device: string): string | null;
+export {};

package/build/knowledge/index.js

@@ -0,0 +1,313 @@
+"use strict";
+/**
+ * Centralized knowledge index for progressive discovery.
+ *
+ * Inspired by Cloudflare's Code Mode pattern: instead of enumerating every
+ * possible value in tool descriptions (which wastes context tokens), this
+ * module provides runtime lookup functions. Tool descriptions stay compact
+ * and options are returned dynamically when needed.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CATEGORIES = void 0;
+exports.getResource = getResource;
+exports.listResources = listResources;
+exports.buildSearchIndex = buildSearchIndex;
+exports.getExample = getExample;
+exports.listExamples = listExamples;
+exports.lookupDeviceReference = lookupDeviceReference;
+const pedro_js_1 = require("./pedro.js");
+const dashboard_js_1 = require("./dashboard.js");
+const hardware_js_1 = require("./hardware.js");
+const ftc_sdk_js_1 = require("./ftc-sdk.js");
+const gradle_js_1 = require("./gradle.js");
+const roadrunner_js_1 = require("./roadrunner.js");
+const ftclib_js_1 = require("./ftclib.js");
+const vision_js_1 = require("./vision.js");
+const panels_js_1 = require("./panels.js");
+const examples_js_1 = require("./examples.js");
+// ── Category Index ──────────────────────────────────────────────────────
+// Maps: category → slug → { name, knowledgeKey }
+// All hardware URIs are flattened to ftc://{category}/{slug} (no nested paths)
+exports.CATEGORIES = {
+    sdk: {
+        source: ftc_sdk_js_1.FTC_SDK_KNOWLEDGE,
+        label: "FTC SDK",
+        entries: {
+            "overview": { name: "FTC Overview", key: "overview" },
+            "opmode-patterns": { name: "OpMode Patterns", key: "opmodePatterns" },
+            "hardware-map": { name: "Hardware Map", key: "hardwareMap" },
+            "gamepad-api": { name: "Gamepad API", key: "gamepadApi" },
+            "best-practices": { name: "Best Practices", key: "bestPractices" },
+            "dev-environment": { name: "Dev Environment Setup", key: "devEnvironment" },
+        },
+    },
+    pedro: {
+        source: pedro_js_1.PEDRO_KNOWLEDGE,
+        label: "Pedro Pathing",
+        entries: {
+            "api-reference": { name: "Pedro API Reference", key: "apiReference" },
+            "constants-pattern": { name: "Pedro Constants Pattern", key: "constantsPattern" },
+            "coordinate-system": { name: "Pedro Coordinate System", key: "coordinateSystem" },
+            "auto-structure": { name: "Pedro Auto Structure", key: "autoStructure" },
+            "teleop-structure": { name: "Pedro TeleOp Structure", key: "teleopStructure" },
+            "callbacks": { name: "Pedro Callbacks", key: "callbacks" },
+        },
+    },
+    dashboard: {
+        source: dashboard_js_1.DASHBOARD_KNOWLEDGE,
+        label: "FTC Dashboard",
+        entries: {
+            "config-pattern": { name: "Dashboard Config Pattern", key: "configPattern" },
+            "telemetry": { name: "Dashboard Telemetry", key: "telemetry" },
+            "canvas": { name: "Dashboard Canvas", key: "canvas" },
+            "camera": { name: "Dashboard Camera", key: "camera" },
+            "setup": { name: "Dashboard Setup", key: "setup" },
+            "api": { name: "Dashboard API", key: "api" },
+        },
+    },
+    gradle: {
+        source: gradle_js_1.GRADLE_KNOWLEDGE,
+        label: "Gradle",
+        entries: {
+            "project-structure": { name: "Gradle Project Structure", key: "projectStructure" },
+            "adding-libraries": { name: "Adding Libraries", key: "addingLibraries" },
+            "all-library-coords": { name: "All Library Coordinates", key: "allLibraryCoords" },
+            "common-issues": { name: "Common Gradle Issues", key: "commonIssues" },
+            "build-process": { name: "Build Process", key: "buildProcess" },
+            "build-and-deploy": { name: "Build and Deploy", key: "buildAndDeploy" },
+        },
+    },
+    hardware: {
+        source: hardware_js_1.HARDWARE_KNOWLEDGE,
+        label: "Hardware",
+        entries: {
+            "motors-api": { name: "Motors API", key: "motorsApi" },
+            "motor-run-modes": { name: "Motor Run Modes", key: "motorRunModes" },
+            "motor-specs": { name: "Motor Specs", key: "motorSpecs" },
+            "servos-api": { name: "Servos API", key: "servosApi" },
+            "sensors-imu": { name: "IMU Sensor", key: "sensorsImu" },
+            "sensors-distance": { name: "Distance Sensor", key: "sensorsDistance" },
+            "sensors-color": { name: "Color Sensor", key: "sensorsColor" },
+            "sensors-digital": { name: "Digital Sensors", key: "sensorsDigital" },
+            "sensors-encoder": { name: "Encoders", key: "sensorsEncoder" },
+            "pinpoint": { name: "GoBilda Pinpoint", key: "pinpoint" },
+            "otos": { name: "SparkFun OTOS", key: "otos" },
+            "rev-hub": { name: "REV Hub", key: "revHub" },
+            "bulk-reads": { name: "Bulk Reads", key: "bulkReads" },
+            "caching-hardware": { name: "Caching Hardware", key: "cachingHardware" },
+            "optimization-summary": { name: "Optimization Summary", key: "optimizationSummary" },
+            "custom-wrappers": { name: "Custom Wrappers", key: "customWrappers" },
+            "command-pipeline": { name: "Command Pipeline", key: "commandPipeline" },
+            "write-optimization": { name: "Write Optimization", key: "writeOptimization" },
+            "loop-time-budget": { name: "Loop Time Budget", key: "loopTimeBudget" },
+            "vision": { name: "Vision", key: "vision" },
+        },
+    },
+    roadrunner: {
+        source: roadrunner_js_1.ROADRUNNER_KNOWLEDGE,
+        label: "Road Runner",
+        entries: {
+            "api-reference": { name: "Road Runner API", key: "apiReference" },
+        },
+    },
+    "command-base": {
+        source: ftclib_js_1.FTCLIB_KNOWLEDGE,
+        label: "Command-Base (SolversLib)",
+        entries: {
+            "setup": { name: "Command-Base Setup", key: "setup" },
+            "api": { name: "Command-Base API", key: "apiReference" },
+            "subsystems": { name: "Command-Base Subsystem Patterns", key: "subsystemPatterns" },
+            "commands": { name: "Command-Base Command Patterns", key: "commandPatterns" },
+            "triggers": { name: "Command-Base Triggers & GamepadEx", key: "triggers" },
+            "organization": { name: "Command-Base Project Organization", key: "organization" },
+            "pedro-integration": { name: "Command-Base Pedro Integration", key: "pedroIntegration" },
+            "extras": { name: "Command-Base SolversLib Extras", key: "extras" },
+        },
+    },
+    vision: {
+        source: vision_js_1.VISION_KNOWLEDGE,
+        label: "Vision",
+        entries: {
+            "overview": { name: "Vision Overview", key: "overview" },
+            "visionportal-setup": { name: "VisionPortal Setup", key: "visionPortalSetup" },
+            "apriltag-detection": { name: "AprilTag Detection", key: "aprilTagDetection" },
+            "camera-controls": { name: "Camera Controls", key: "cameraControls" },
+            "limelight": { name: "Limelight 3A Guide", key: "limelight" },
+            "megatag": { name: "MegaTag Localization", key: "megaTag" },
+            "color-detection": { name: "Color Detection", key: "colorDetection" },
+            "optimization": { name: "Vision Optimization", key: "visionOptimization" },
+            "multi-camera": { name: "Multi-Camera Setup", key: "multiCamera" },
+            "patterns": { name: "Vision Patterns", key: "visionPatterns" },
+        },
+    },
+    panels: {
+        source: panels_js_1.PANELS_KNOWLEDGE,
+        label: "Panels",
+        entries: {
+            "overview": { name: "Panels Overview", key: "overview" },
+            "setup": { name: "Panels Setup", key: "setup" },
+            "configurables": { name: "Panels Configurables", key: "configurables" },
+            "telemetry": { name: "Panels Telemetry", key: "telemetry" },
+            "field": { name: "Panels Field Drawing", key: "field" },
+            "limelight": { name: "Panels Limelight", key: "limelight" },
+            "plugins": { name: "Panels Plugins", key: "plugins" },
+            "gamepads": { name: "Panels Gamepads", key: "gamepads" },
+        },
+    },
+};
+// ── Resource Lookup ─────────────────────────────────────────────────────
+function getResource(category, slug) {
+    const cat = exports.CATEGORIES[category];
+    if (!cat)
+        return null;
+    const entry = cat.entries[slug];
+    if (!entry)
+        return null;
+    return cat.source[entry.key] ?? null;
+}
+function listResources(category) {
+    const cat = exports.CATEGORIES[category];
+    if (!cat)
+        return [];
+    return Object.entries(cat.entries).map(([slug, entry]) => ({
+        uri: `ftc://${category}/${slug}`,
+        name: entry.name,
+    }));
+}
+// ── Full-Text Search ────────────────────────────────────────────────────
+function buildSearchIndex() {
+    const index = [];
+    for (const [category, catDef] of Object.entries(exports.CATEGORIES)) {
+        for (const [slug, entry] of Object.entries(catDef.entries)) {
+            const content = catDef.source[entry.key];
+            if (content) {
+                index.push({ category, key: slug, content });
+            }
+        }
+    }
+    return index;
+}
+// ── Example Lookup ──────────────────────────────────────────────────────
+function getExample(topic) {
+    return examples_js_1.EXAMPLES[topic] ?? null;
+}
+function listExamples() {
+    return Object.keys(examples_js_1.EXAMPLES);
+}
+// ── Hardware/Vision Device Alias Lookup ─────────────────────────────────
+// Allows flexible device name queries (e.g., "DcMotorEx", "motor", "imu")
+const HW_ALIASES = {
+    "dcmotor": ["motorsApi", "motorRunModes", "motorSpecs"],
+    "dcmotorex": ["motorsApi", "motorRunModes", "motorSpecs"],
+    "motor": ["motorsApi", "motorRunModes", "motorSpecs"],
+    "motors": ["motorsApi", "motorRunModes", "motorSpecs"],
+    "servo": ["servosApi"],
+    "crservo": ["servosApi"],
+    "imu": ["sensorsImu"],
+    "pinpoint": ["pinpoint"],
+    "otos": ["otos"],
+    "colorsensor": ["sensorsColor"],
+    "distancesensor": ["sensorsDistance"],
+    "distance": ["sensorsDistance"],
+    "touchsensor": ["sensorsDigital"],
+    "touch": ["sensorsDigital"],
+    "digital": ["sensorsDigital"],
+    "bulk-reads": ["bulkReads"],
+    "bulkread": ["bulkReads"],
+    "bulkreads": ["bulkReads"],
+    "bulk-read": ["bulkReads"],
+    "caching": ["cachingHardware"],
+    "caching-hardware": ["cachingHardware"],
+    "cachinghardware": ["cachingHardware"],
+    "custom-wrappers": ["customWrappers"],
+    "wrappers": ["customWrappers"],
+    "customwrappers": ["customWrappers"],
+    "encoder": ["sensorsEncoder"],
+    "encoders": ["sensorsEncoder"],
+    "rev-hub": ["revHub"],
+    "revhub": ["revHub"],
+    "lynx": ["revHub"],
+    "optimization": ["optimizationSummary"],
+    "pipeline": ["commandPipeline"],
+    "command-pipeline": ["commandPipeline"],
+    "commandpipeline": ["commandPipeline"],
+    "lynxcommand": ["commandPipeline"],
+    "lynx-command": ["commandPipeline"],
+    "usb": ["commandPipeline"],
+    "write-optimization": ["writeOptimization"],
+    "writeoptimization": ["writeOptimization"],
+    "write-caching": ["writeOptimization", "cachingHardware"],
+    "queueing": ["commandPipeline", "writeOptimization"],
+    "queuing": ["commandPipeline", "writeOptimization"],
+    "loop-time": ["loopTimeBudget"],
+    "looptime": ["loopTimeBudget"],
+    "loop-budget": ["loopTimeBudget"],
+    "performance": ["optimizationSummary", "commandPipeline", "writeOptimization", "loopTimeBudget"],
+};
+const VISION_ALIASES = {
+    "vision": ["overview", "visionPortalSetup", "aprilTagDetection"],
+    "visionportal": ["visionPortalSetup"],
+    "vision-portal": ["visionPortalSetup"],
+    "apriltag": ["aprilTagDetection"],
+    "april-tag": ["aprilTagDetection"],
+    "camera": ["cameraControls"],
+    "camera-controls": ["cameraControls"],
+    "cameracontrols": ["cameraControls"],
+    "exposure": ["cameraControls"],
+    "gain": ["cameraControls"],
+    "focus": ["cameraControls"],
+    "white-balance": ["cameraControls"],
+    "whitebalance": ["cameraControls"],
+    "limelight": ["limelight", "megaTag"],
+    "limelight3a": ["limelight", "megaTag"],
+    "limelight-3a": ["limelight", "megaTag"],
+    "megatag": ["megaTag"],
+    "megatag2": ["megaTag"],
+    "mega-tag": ["megaTag"],
+    "localization": ["megaTag"],
+    "color-detection": ["colorDetection"],
+    "colordetection": ["colorDetection"],
+    "color-detect": ["colorDetection"],
+    "hsv": ["colorDetection"],
+    "opencv": ["colorDetection"],
+    "contour": ["colorDetection"],
+    "visionprocessor": ["colorDetection"],
+    "vision-processor": ["colorDetection"],
+    "vision-optimization": ["visionOptimization"],
+    "visionoptimization": ["visionOptimization"],
+    "decimation": ["visionOptimization", "aprilTagDetection"],
+    "fps": ["visionOptimization"],
+    "resolution": ["visionOptimization"],
+    "motion-blur": ["visionOptimization", "cameraControls"],
+    "multi-camera": ["multiCamera"],
+    "multicamera": ["multiCamera"],
+    "dual-camera": ["multiCamera"],
+    "dualcamera": ["multiCamera"],
+    "multiportal": ["multiCamera"],
+    "vision-patterns": ["visionPatterns"],
+    "visionpatterns": ["visionPatterns"],
+    "drive-to-tag": ["visionPatterns"],
+    "init-detection": ["visionPatterns"],
+    "snapscript": ["megaTag"],
+    "python-pipeline": ["megaTag"],
+};
+function lookupDeviceReference(device) {
+    const deviceLower = device.toLowerCase();
+    // Check hardware aliases
+    const hwKeys = HW_ALIASES[deviceLower];
+    if (hwKeys) {
+        const hw = hardware_js_1.HARDWARE_KNOWLEDGE;
+        const sections = hwKeys.map(k => hw[k]).filter(Boolean);
+        if (sections.length > 0)
+            return sections.join("\n\n---\n\n");
+    }
+    // Check vision aliases
+    const visionKeys = VISION_ALIASES[deviceLower];
+    if (visionKeys) {
+        const vis = vision_js_1.VISION_KNOWLEDGE;
+        const sections = visionKeys.map(k => vis[k]).filter(Boolean);
+        if (sections.length > 0)
+            return sections.join("\n\n---\n\n");
+    }
+    return null;
+}

package/build/prompts/registry.js

@@ -22,7 +22,7 @@ function registerPrompts(server) {
 
 Follow these steps IN ORDER:
 
-1. Call the scan_ftc_project tool to understand the current project state (existing files, Gradle config, dependencies already present).
+1. Call the scan_project tool to understand the current project state (existing files, Gradle config, dependencies already present).
 
 2. Read these resources for Gradle setup guidance:
    - ftc://gradle/project-structure — understand the FTC Gradle layout
@@ -82,7 +82,7 @@ Important: Always use the exact library coordinates from the resources. Do not g
 
 Follow these steps:
 
-1. Call scan_ftc_project to understand the current project — existing OpModes, subsystems, Constants file, hardware names.
+1. Call scan_project to understand the current project — existing OpModes, subsystems, Constants file, hardware names.
 
 2. Read the appropriate pathing resources:
 ${pathing === "roadrunner" ? `   - ftc://roadrunner/api-reference — Road Runner trajectory API` : `   - ftc://pedro/api-reference — Pedro Pathing follower and path building API
@@ -128,15 +128,15 @@ Important: The auto should be competition-ready with proper error handling, stat
 
 Follow these steps:
 
-1. Call scan_ftc_project to find existing subsystems, hardware config names, and Constants files.
+1. Call scan_project to find existing subsystems, hardware config names, and Constants files.
 
 2. Read the relevant resources:
    - ftc://sdk/gamepad-api — gamepad button/stick API and edge detection
    - ftc://sdk/opmode-patterns — LinearOpMode vs OpMode patterns
    - ftc://hardware/bulk-reads — set up bulk read caching (MANUAL mode, clear each loop)
    - ftc://dashboard/telemetry — MultipleTelemetry for dual DS + Dashboard output
-${drive === "pedro" ? `   - ftc://pedro/teleop-structure — Pedro TeleOp drive integration` : `   - ftc://hardware/motors/api — motor control for mecanum math`}
-${drive === "field-centric" ? `   - ftc://hardware/sensors/imu — IMU heading for field-centric calculation` : ""}
+${drive === "pedro" ? `   - ftc://pedro/teleop-structure — Pedro TeleOp drive integration` : `   - ftc://hardware/motors-api — motor control for mecanum math`}
+${drive === "field-centric" ? `   - ftc://hardware/sensors-imu — IMU heading for field-centric calculation` : ""}
 
 3. Generate the TeleOp OpMode:
    - Drive control:
@@ -179,11 +179,11 @@ ${drive === "field-centric" ? `   - ftc://hardware/sensors/imu — IMU heading f
 
 Follow these steps:
 
-1. Call scan_ftc_project to see existing subsystems and hardware configuration names.
+1. Call scan_project to see existing subsystems and hardware configuration names.
 
 2. Read the relevant resources:
-   - ftc://hardware/motors/api and ftc://hardware/servos/api — motor and servo control API
-   - ftc://hardware/motors/run-modes — RUN_TO_POSITION, RUN_USING_ENCODER, etc.
+   - ftc://hardware/motors-api and ftc://hardware/servos-api — motor and servo control API
+   - ftc://hardware/motor-run-modes — RUN_TO_POSITION, RUN_USING_ENCODER, etc.
    - ftc://dashboard/config-pattern — @Config annotation for live tuning
 
 3. Generate the subsystem class:
@@ -227,7 +227,7 @@ Important: The class should be self-contained, testable, and follow FTC best pra
 
 Follow these steps:
 
-1. Call scan_ftc_project to find existing PID controllers and subsystem code.
+1. Call scan_project to find existing PID controllers and subsystem code.
 
 2. Read the relevant resources:
    - ftc://dashboard/config-pattern — expose PID coefficients as @Config public static
@@ -273,7 +273,7 @@ Follow these steps:
 
 Follow these steps:
 
-1. Call scan_ftc_project to analyze the full project — all OpModes, subsystems, and hardware usage.
+1. Call scan_project to analyze the full project — all OpModes, subsystems, and hardware usage.
 
 2. Read the performance resources:
    - ftc://hardware/bulk-reads — understand REV Hub bulk read caching modes
@@ -329,7 +329,7 @@ Follow these steps:
 
 Follow these steps:
 
-1. Call scan_ftc_project to find the target class and understand the current code.
+1. Call scan_project to find the target class and understand the current code.
 
 2. Read the dashboard resources:
    - ftc://dashboard/config-pattern — the @Config annotation pattern and requirements
@@ -381,7 +381,7 @@ Important: Remind the user that Dashboard serves a web UI at http://192.168.43.1
 
 Follow these steps:
 
-1. Call scan_ftc_project to analyze the current project state.
+1. Call scan_project to analyze the current project state.
 
 2. Read the command-base resources:
    - ftc://command-base/setup — SolversLib vs FTCLib, Gradle installation, import mapping
@@ -463,7 +463,7 @@ Important: Use SolversLib imports (com.seattlesolvers.solverslib.*), NOT FTCLib
 
 Follow these steps:
 
-1. Call scan_ftc_project to check the current project state and Gradle configuration.
+1. Call scan_project to check the current project state and Gradle configuration.
 
 2. Read the development environment resource:
    - ftc://sdk/dev-environment — prerequisites (JDK 17, Android SDK, ANDROID_HOME), IDE-specific setup instructions for VS Code, Android Studio, and IntelliJ
@@ -528,7 +528,7 @@ Important: The Gradle wrapper handles everything. Android Studio is optional —
 
 Follow these steps:
 
-1. Call scan_ftc_project to check the current project state, existing vision code, and hardware names.
+1. Call scan_project to check the current project state, existing vision code, and hardware names.
 
 2. Read the vision overview to understand the options:
    - ftc://vision/overview — USB webcam vs Limelight comparison, when to use each
@@ -601,7 +601,7 @@ Important: Set manual camera controls for competition consistency. Always have a
 
 Follow these steps:
 
-1. Call scan_ftc_project to see the current Gradle configuration and what's already installed.
+1. Call scan_project to see the current Gradle configuration and what's already installed.
 
 2. Read the Gradle resources:
    - ftc://gradle/project-structure — understand which files to edit

package/build/resources/registry.d.ts

@@ -1,2 +1,13 @@
+/**
+ * MCP Resource Registration — Template-Based
+ *
+ * Inspired by Cloudflare's progressive discovery pattern: instead of registering
+ * 70+ individual resources (each adding to context window overhead), we register
+ * 9 category-level resource templates. Each template provides a list callback for
+ * resource discovery and a read callback for content retrieval.
+ *
+ * This reduces the resource listing from ~70 entries to 9 templates, saving
+ * significant tokens in the MCP protocol's resource listing.
+ */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 export declare function registerResources(server: McpServer): void;