connectiq-mcp-server

ConnectIQ MCP Server

An MCP (Model Context Protocol) server that provides access to Garmin ConnectIQ SDK documentation, sample code, device information, and project configuration.

Features

• API Documentation Search: Search the Toybox API documentation for classes, methods, properties, and constants
• Device Information: Get specifications and capabilities for supported Garmin devices
• Sample Code Access: Browse and read sample project source code from the SDK
• Sample Code Search: Full-text search across sample source files to find implementation patterns
• Project Configuration: Access app types, permissions, languages, and activity sports
• Developer Guide Access: Search and read developer guides from developer.garmin.com covering Monkey C, core topics, UX guidelines, and more

Installation

npm install
npm run build

Configuration

The server auto-detects the ConnectIQ SDK installation based on your operating system.

Default Paths (Auto-Detection)

The server automatically looks for ConnectIQ in the standard location:

OS	Default Path
macOS	~/Library/Application Support/Garmin/ConnectIQ
Windows	%APPDATA%\Garmin\ConnectIQ
Linux	~/.Garmin/ConnectIQ

If ConnectIQ is installed in the default location and configured with Garmin SDK Manager, the server will auto-detect the current SDK from current-sdk.cfg.

Option 1: Automatic (Recommended)

If you have ConnectIQ SDK Manager installed and configured, just run:

npx connectiq-mcp-server

Option 2: Specify Version

To use a specific SDK version:

# Environment variable
export CONNECTIQ_VERSION="8.4"  # Matches 8.4.x (e.g., 8.4.0, 8.4.1)
npx connectiq-mcp-server

# Command line
npx connectiq-mcp-server --version=8.4
# or short form
npx connectiq-mcp-server -v 8.4

Version matching supports prefixes: 8 matches any 8.x.x, 8.4 matches any 8.4.x.

Option 3: Custom ConnectIQ Path

If ConnectIQ is installed in a non-standard location:

# Environment variable
export CONNECTIQ_PATH="/custom/path/to/ConnectIQ"
export CONNECTIQ_VERSION="8.4"  # Optional
npx connectiq-mcp-server

# Command line
npx connectiq-mcp-server --connectiq-path="/custom/path/to/ConnectIQ" --version=8.4
# or short form
npx connectiq-mcp-server -c "/custom/path/to/ConnectIQ" -v 8.4

Transport Mode

By default the server uses stdio transport. To run as an HTTP server instead, use the --http flag:

npx connectiq-mcp-server --http
npx connectiq-mcp-server --http --port=8080
npx connectiq-mcp-server --http --host=0.0.0.0 --port=3000

Flag	Description	Default
--http	Enable HTTP transport mode	off (stdio)
--port <number>	Port to listen on (HTTP mode)	3000
--host <address>	Host address to bind to (HTTP mode)	127.0.0.1

Both transport modes share the same service layer, caching, and tool implementations.

Devices Path (Auto-Discovered)

The Devices/ folder (sibling to Sdks/) is automatically discovered for richer device information. When found, getDeviceInfo returns enhanced data including vector fonts, display configurations, and firmware details.

Usage with Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json):

Auto-detect (recommended if SDK Manager is configured):

{
  "mcpServers": {
    "connectiq": {
      "type": "stdio",
      "command": "npx",
      "args": ["connectiq-mcp-server"]
    }
  }
}

With specific version:

{
  "mcpServers": {
    "connectiq": {
      "type": "stdio",
      "command": "npx",
      "args": ["connectiq-mcp-server"],
      "env": {
        "CONNECTIQ_VERSION": "8.4"
      }
    }
  }
}

With custom path:

{
  "mcpServers": {
    "connectiq": {
      "type": "stdio",
      "command": "npx",
      "args": ["connectiq-mcp-server"],
      "env": {
        "CONNECTIQ_PATH": "/custom/path/to/ConnectIQ",
        "CONNECTIQ_VERSION": "8.4"
      }
    }
  }
}

HTTP Mode

Start the server separately, then point Claude Desktop at the HTTP endpoint:

{
  "mcpServers": {
    "connectiq": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

Available Tools

searchApiDocs

Search ConnectIQ Toybox API documentation. Supports fuzzy matching for typo tolerance.

Parameters:

• query (required): Search term (module, class, method, or constant name)
• module (optional): Filter by Toybox module (e.g., "System", "WatchUi")
• limit (optional): Maximum results to return (default: 20)
• detailLevel (optional): Result detail level (default: "summary")
  • summary: Core fields only (type, name, description, signature, since) - for browsing/discovery
  • full: Complete details including parameters, throws, notes, supportedDevices, code examples, and enum members - for implementation
• type (optional): Filter by element types - array of: "module", "class", "method", "property", "constant", "enum"
• includeDeprecated (optional): Include deprecated APIs in results (default: true)
• minApiLevel (optional): Minimum API level (e.g., "3.0.0")
• device (optional): Filter by supported device (partial match, e.g., "fenix", "vivoactive")

{
  "query": "getDeviceSettings",
  "module": "System",
  "limit": 10,
  "type": ["method", "property"],
  "minApiLevel": "3.0.0",
  "device": "fenix"
}

{
  "query": "onUpdate",
  "module": "WatchUi",
  "detailLevel": "full"
}

getDeviceInfo

Get specifications and capabilities for a specific Garmin device. Returns screen dimensions, supported features, and app types.

Parameters:

• deviceId (required): Device identifier (e.g., "fenix847mm", "edge1040", "vivoactive5")
• fields (optional): Field sections to include - array of: "all", "spec", "memory", "features", "fonts", "gps", "icons", "identity" (default: ["all"])
  • spec: Screen/display fields (width, height, shape, displayType, bitsPerPixel, orientation, deviceFamily, deviceGroup, display config)
  • memory: Storage and app type memory limits (appStorageCapacity, appTypes with memoryLimit, memoryLimit)
  • features: Touch, microphone, music, graphics capabilities, glance/complications support, flashlight configuration
  • fonts: Font data, vector fonts, and font scaling limits
  • gps: Constellation/GPS configuration
  • icons: Launcher and complication icon dimensions, device image URL
  • identity: Part numbers, part number details with firmware info, hardware part number

{
  "deviceId": "fenix847mm",
  "fields": ["spec", "memory"]
}

listDevices

List all available Garmin devices supported by the ConnectIQ SDK. Supports text search and advanced filtering with AND logic.

Parameters:

• query (optional): Search by device name or ID

Screen Filters:

• screenWidth (optional): Filter with operator (e.g., ">400", ">=260", "=454")
• screenHeight (optional): Filter with operator
• screenShape (optional): "round", "rectangle", "semiround", or "semi-octagon"
• displayType (optional): Filter by display type (e.g., "amoled", "mip")

Memory Filters:

• appStorageCapacity (optional): Filter with operator (e.g., ">1000000")
• appTypeMemoryLimit (optional): Filter by app type memory limit
  • appType: App type name (e.g., "watchFace", "widget")
  • limit: Memory limit filter (e.g., ">32768")

Feature Filters:

• hasTouch (optional): Filter by touch screen support
• alphaBlendingSupport (optional): Filter by alpha blending support
• enhancedGraphicSupport (optional): Filter by enhanced graphics support
• screenRotationSupport (optional): Filter by screen rotation support
• controlBarSupport (optional): Filter by control bar support (Edge devices)

Classification Filters:

• deviceFamily (optional): Filter by device family (e.g., "round-454x454")
• deviceGroup (optional): Filter by device group/API level
• hasVectorFonts (optional): Filter by vector font support

{
  "query": "fenix",
  "screenShape": "round",
  "screenWidth": ">=400",
  "hasTouch": true
}

{
  "displayType": "amoled",
  "appTypeMemoryLimit": {
    "appType": "watchFace",
    "limit": ">=65536"
  }
}

listSamples

Search and filter ConnectIQ SDK sample projects. Supports full-text search with fuzzy matching.

Parameters:

• query (optional): Search by name, description, or API usage
• appType (optional): Filter by app type ("watchface", "datafield", "widget", "watch-app")
• targetDevices (optional): Filter by target device IDs (e.g., ["fenix7", "fr965"])
• permissions (optional): Filter by required permissions (e.g., ["Positioning", "Communications"])
• apiModules (optional): Filter by Toybox API modules used (e.g., ["Toybox.Position", "Toybox.WatchUi"])
• minSdkVersion (optional): Filter by minimum SDK version (e.g., "3.0.0")
• limit (optional): Maximum results to return (default: 50)

{
  "appType": "datafield",
  "permissions": ["Positioning"]
}

{
  "query": "sensor",
  "apiModules": ["Toybox.Sensor"],
  "limit": 10
}

getSampleCode

Read source code from a ConnectIQ SDK sample project, or list available files when file parameter is omitted. Useful for understanding implementation patterns and best practices.

Parameters:

• project (required): Sample project name (e.g., "SimpleDataField", "Analog")
• file (optional): File path within the project (e.g., "source/SimpleDataFieldView.mc"). Omit to list available files.

{
  "project": "SimpleDataField",
  "file": "source/SimpleDataFieldView.mc"
}

{
  "project": "SimpleDataField"
}

searchSampleCode

Search file contents of ConnectIQ SDK sample projects. Find code examples, API usage patterns, and implementation details. Returns matching lines with context.

Parameters:

• query (required): Search term to find in sample code (supports fuzzy matching)
• project (optional): Filter by specific sample project name
• extension (optional): Filter by file type (".mc", ".xml", ".jungle", ".json")
• limit (optional): Maximum number of results to return (default: 20)
• contextLines (optional): Number of context lines before/after each match (default: 2)

{
  "query": "onUpdate",
  "extension": ".mc",
  "limit": 10
}

{
  "query": "Toybox.Position",
  "project": "Positioning"
}

searchDevGuides

Search ConnectIQ developer guides from developer.garmin.com. Covers Monkey C language, core topics (UI, sensors, BLE, backgrounding, debugging), UX guidelines, FAQ, and more.

Parameters:

• query (required): Search term to find in developer guides
• category (optional): Filter by guide category (e.g., "Core Topics", "Monkey C", "UX Guide")
• limit (optional): Maximum number of results to return (default: 10)

{
  "query": "backgrounding",
  "category": "Core Topics"
}

{
  "query": "custom fonts",
  "limit": 5
}

getDevGuide

Get the full content of a ConnectIQ developer guide page. Use searchDevGuides first to find relevant guides, then use this tool with the slug to read the full content.

Parameters:

• slug (required): Guide slug (e.g., "core-topics/backgrounding", "monkey-c/functions")

{
  "slug": "core-topics/backgrounding"
}

{
  "slug": "monkey-c/functions"
}

getProjectConfig

Get ConnectIQ project configuration including app types, permissions, supported languages, activity sports/subsports, permission maps, activity mappings, and project templates.

Parameters:

• section (optional): Configuration section to retrieve (default: "all")
  • all: Everything
  • appTypes: Available app types
  • permissions: Available permissions
  • languages: Supported languages
  • sports: Activity sports and subsports
  • permissionMaps: Permissions available per app type
  • activityMap: Valid subsports for each sport type
  • placeholders: New project file placeholders
  • templates: Project templates for new project creation

{
  "section": "permissions"
}

{
  "section": "templates"
}

Available Resources

The server exposes resources via the connectiq:// protocol:

• connectiq://api/{module} - API documentation for a Toybox module (e.g., connectiq://api/System)
• connectiq://samples/{project} - Sample project information and file listing
• connectiq://samples/{project}/{file} - Specific file from a sample project
• connectiq://devices/{deviceId} - Device specifications as JSON
• connectiq://guides/{slug} - Developer guide content (markdown)

Available Prompts

The server provides pre-built prompt templates for common ConnectIQ development tasks:

review-connectiq-code

Review Monkey C code for best practices, potential issues, and optimization opportunities.

Parameters:

• code (required): The Monkey C code to review
• appType (optional): App type for context (watchface, widget, datafield, watch-app, audio-content-provider, background)
• targetDevice (optional): Target device ID for device-specific recommendations (e.g., fenix847mm, vivoactive5)

explain-api

Get detailed explanations of ConnectIQ APIs with usage examples and best practices.

Parameters:

• apiName (required): API element to explain (e.g., 'WatchUi.View', 'Graphics.Dc', 'System.getTimer')
• context (optional): Additional context about your use case

device-compatibility

Analyze code for compatibility issues across multiple target devices.

Parameters:

• code (required): The Monkey C code to analyze
• targetDevices (required): Comma-separated list of device IDs (e.g., 'fenix847mm,vivoactive5,edge1040')

optimize-memory

Analyze code for memory optimization opportunities with device-specific memory limits.

Parameters:

• code (required): The Monkey C code to analyze
• appType (required): App type to determine memory limits (watchface, widget, datafield, watch-app)
• targetDevice (optional): Target device ID for device-specific memory limits

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

# Run the server
npm start

# Clean build artifacts
npm run clean

Testing

The project uses Vitest for testing.

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage report
npm run test:coverage

Test files are located in test/unit/ and follow the *.test.ts naming convention.

Code Quality

The project uses ESLint for linting and Prettier for code formatting.

# Run ESLint
npm run lint

# Run ESLint with auto-fix
npm run lint:fix

# Format code with Prettier
npm run format

# Check formatting without changes
npm run format:check

Project Structure

src/
├── index.ts                    # Server entry point
├── config/
│   └── ConfigManager.ts        # SDK path resolution
├── schemas/
│   ├── SchemaFactory.ts        # Dynamic Zod schema generation from SDK data
│   ├── SchemaInferenceEngine.ts # Runtime type inference from JSON samples
│   ├── DataSampler.ts          # Diversity-based SDK file sampling
│   └── index.ts                # Barrel export
├── handlers/
│   ├── toolHandlers.ts         # MCP tool registration (9 tools)
│   ├── resourceHandlers.ts     # MCP resource registration
│   ├── promptHandlers.ts       # MCP prompt registration (4 prompts)
│   └── handlerUtils.ts         # Shared handler utilities
├── services/
│   ├── ApiDocService.ts        # Toybox API search with caching
│   ├── DeviceInfoService.ts    # Device specs
│   ├── SampleService.ts        # Sample code browsing
│   ├── SampleCodeSearchService.ts # Full-text search in sample code
│   ├── ProjectInfoService.ts   # App types/permissions/templates
│   └── DevGuideService.ts      # Developer guide search and retrieval
├── parsers/
│   ├── HtmlParser.ts           # HTML doc parsing
│   ├── HtmlParserSchemas.ts    # Zod schemas for parsed HTML
│   └── XmlParser.ts            # XML config parsing
├── utils/
│   ├── AsyncFileCache.ts       # Async file cache with TTL
│   ├── IndexCache.ts           # Persistent search index caching
│   ├── ParsingQualityMetrics.ts # API doc parsing quality metrics
│   ├── DeviceFilter.ts         # Device filtering with numeric operators
│   ├── MarkdownConverter.ts    # HTML to Markdown conversion
│   ├── logging.ts              # MCP protocol logging
│   ├── versionUtils.ts         # Version comparison utilities
│   └── index.ts                # Barrel export
└── types/
    └── index.ts                # Shared interfaces

data/
└── guides/                     # Scraped developer guides (markdown)

test/
├── fixtures/
│   ├── mockConfig.ts           # Test configuration mocks
│   └── htmlFixtures.ts         # HTML parsing test fixtures
└── unit/
    ├── config/                 # ConfigManager tests
    ├── handlers/               # Tool and resource handler tests
    ├── parsers/                # Parser tests
    ├── services/               # Service tests
    ├── schemas/                # Schema generation tests
    └── utils/                  # Utility tests

License

MIT