connectiq-mcp-server 1.0.3 → 1.1.1

package/.claude/commands/commit.md

@@ -10,9 +10,8 @@ description: Create a git commit
 
 ## Your task
 
-Based on the above changes, create a single git commit.
+Based on the above changes, create a single conventional git commit.
 
 ## Common Notes
 
-- Do not add "Generated with [Claude Code]..." to the commit message.
-- Do not mention Claude as a co-author.
+- Do not add "Generated with..." and "Co-authored-by..." to the commit message.

package/.claude/commands/create-pr.md

@@ -1,15 +1,16 @@
 ---
-allowed-tools: Bash(git log:*), Bash(gh pr list:*), Bash(gh issue list:*)
+allowed-tools: Bash(git log:*), Bash(git remote get-url:*)
 description: Create a GitHub pull request with proper description and metadata
 ---
 
 ## Context
 
+- Git origin url: !`git remote get-url origin`
 - Current git status: `mcp__git__git_status`
 - Commits ahead of main: !`git log --oneline main..HEAD`
 - Changed files: `mcp__git__git_diff` with target `main`
-- Existing open PRs: !`gh pr list --state open --limit 5`
-- Related issues that can be linked: !`gh issue list --limit 10`
+- Existing open PRs: `mcp__github__list_pull_requests`
+- Related issues that can be linked: `mcp__github__list_issues`
 
 ## Your task
 
@@ -27,7 +28,7 @@ Create a well-structured pull request with proper description, labels, and revie
    - List any breaking changes
 
 3. **Set up PR**
-   - Create (or update if already exists) PR with descriptive title
+   - Create PR with descriptive title using `mcp__github__create_pull_request` (or `mcp__github__update_pull_request` if updating an existing PR)
    - Add appropriate labels
    - Assign reviewers
    - Link related issues
@@ -38,5 +39,4 @@ Create a well-structured pull request with proper description, labels, and revie
 
 ## Common Notes
 
-- Do not add "Generated with [Claude Code]..." to the PR description.
-- Do not mention Claude as a co-author.
+- Do not add "Generated with..." and "Co-authored-by..." to the PR description.

package/.mcp.json

@@ -14,13 +14,23 @@
       "type": "stdio",
       "command": "./mcp/github/command.sh"
     },
+    "serena": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": [
+        "--from",
+        "git+https://github.com/oraios/serena",
+        "serena",
+        "start-mcp-server",
+        "--project",
+        ".",
+        "--context",
+        "claude-code"
+      ]
+    },
     "connectiq": {
       "command": "node",
-      "args": ["build/index.js"],
-      "env": {
-        "CONNECTIQ_SDK_PATH": "/Users/eugenes/Library/Application Support/Garmin/ConnectIQ/Sdks/connectiq-sdk-mac-8.4.0-2025-12-03-5122605dc",
-        "CONNECTIQ_DEVICES_PATH": "/Users/eugenes/Library/Application Support/Garmin/ConnectIQ/Devices"
-      }
+      "args": ["build/index.js"]
     }
   }
 }

package/.prettierignore

@@ -1,2 +1,3 @@
 node_modules/
 build/
+.serena/memories/

package/.serena/memories/code_style.md

@@ -0,0 +1,64 @@
+# Code Style and Conventions
+
+## TypeScript Configuration
+- **Target**: ES2022
+- **Module**: NodeNext with NodeNext resolution
+- **Strict mode**: Enabled
+- **Source maps**: Yes
+- **Declarations**: Yes (`.d.ts` files generated)
+
+## Prettier Settings
+- **Semicolons**: Required
+- **Quotes**: Double quotes (`"string"`)
+- **Tab width**: 2 spaces
+- **Tabs**: Spaces (no tabs)
+- **Trailing commas**: ES5 style
+- **Print width**: 80 characters
+
+## ESLint Rules
+- TypeScript recommended rules
+- Prettier integration (eslint-config-prettier)
+- Unused variables: Error (prefix with `_` to ignore, e.g., `_unused`)
+- Tests: `@typescript-eslint/no-explicit-any` disabled (mocking often requires `any`)
+
+## Naming Conventions
+- **Files**: camelCase (e.g., `ApiDocService.ts`, `toolHandlers.ts`)
+- **Classes**: PascalCase (e.g., `ApiDocService`, `ConfigManager`)
+- **Interfaces**: PascalCase (e.g., `DeviceInfo`, `SearchResult`)
+- **Functions**: camelCase (e.g., `registerTools`, `getModule`)
+- **Constants**: SCREAMING_SNAKE_CASE for top-level constants (e.g., `FIELD_WEIGHTS`)
+- **Variables**: camelCase
+
+## Type Definitions
+- All shared types in `src/types/index.ts`
+- Use interfaces for object shapes
+- Use type aliases for unions/complex types
+- Zod schemas for runtime validation (tool parameters)
+
+## Service Pattern
+- Services are classes instantiated once in `src/index.ts`
+- Constructor takes `ConnectIQConfig` for dependency injection
+- Methods are async where file I/O is involved
+- Use LRU caching for expensive operations
+
+## Testing Conventions
+- Framework: Vitest
+- Structure: `describe` blocks for grouping, `it` blocks for individual tests
+- Mocking: `vi.mock()` for module mocking, `vi.fn()` for function mocks
+- Fixtures: Shared fixtures in `test/fixtures/`
+- Test file naming: `*.test.ts` in `test/unit/` mirroring `src/` structure
+
+## Documentation
+- No excessive comments (code should be self-documenting)
+- JSDoc only for complex or non-obvious APIs
+- README.md for user-facing documentation
+
+## Error Handling
+- Use try/catch with descriptive error messages
+- Propagate errors with context (e.g., file paths)
+- Log to stderr for server startup errors
+- Use MCP logging for runtime errors
+
+## Commit Guidelines (from CLAUDE.md)
+- Do NOT add "Generated with [Claude Code]..." to commit messages
+- Do NOT mention Claude as a co-author

package/.serena/memories/project_overview.md

@@ -0,0 +1,71 @@
+# Project Overview
+
+## Purpose
+MCP (Model Context Protocol) server that provides Claude Desktop with access to Garmin ConnectIQ SDK documentation, device specifications, sample projects, and project configuration data.
+
+## Tech Stack
+- **Language**: TypeScript (ES2022, NodeNext modules)
+- **Runtime**: Node.js 18+
+- **Build**: TypeScript compiler (`tsc`)
+- **Testing**: Vitest with coverage support
+- **Linting**: ESLint 9 with typescript-eslint
+- **Formatting**: Prettier
+
+## Key Dependencies
+- `@modelcontextprotocol/sdk` - MCP protocol SDK
+- `cheerio` - HTML parsing for Toybox docs
+- `fast-xml-parser` - XML parsing for SDK config files
+- `lru-cache` - LRU caching for module docs
+- `minisearch` - Full-text search indexing
+- `turndown` - HTML to Markdown conversion
+- `zod` - Schema validation for tool parameters
+
+## Architecture
+
+**Entry Point**: `src/index.ts` - Creates MCP server, initializes config, registers handlers
+
+**Directory Structure**:
+```
+src/
+├── index.ts                  # Entry point, server setup
+├── config/
+│   └── ConfigManager.ts      # SDK path resolution (CLI → env → auto-detect)
+├── handlers/
+│   ├── toolHandlers.ts       # 6 MCP tools with Zod schemas
+│   ├── resourceHandlers.ts   # connectiq:// URI resources
+│   └── promptHandlers.ts     # 4 MCP prompts
+├── services/
+│   ├── ApiDocService.ts      # Toybox API doc parsing & search
+│   ├── DeviceInfoService.ts  # Device spec parsing
+│   ├── SampleService.ts      # SDK samples browsing
+│   └── ProjectInfoService.ts # App types, permissions, sports
+├── parsers/
+│   ├── HtmlParser.ts         # Cheerio-based doc parsing
+│   └── XmlParser.ts          # fast-xml-parser wrapper
+├── types/
+│   └── index.ts              # Shared TypeScript interfaces
+└── utils/
+    ├── logging.ts            # MCP protocol logging
+    ├── AsyncFileCache.ts     # Async file caching with TTL
+    └── MarkdownConverter.ts  # Turndown-based conversion
+```
+
+**Test Structure**:
+```
+test/
+├── unit/                     # Unit tests mirroring src/ structure
+│   ├── config/
+│   ├── handlers/
+│   ├── parsers/
+│   ├── services/
+│   └── utils/
+└── fixtures/                 # Shared test fixtures
+    └── mockConfig.ts
+```
+
+## Key Patterns
+- All tool parameters validated with Zod schemas (converted to JSON Schema for MCP)
+- Services use LRU caching for performance (module docs, device list, sample list)
+- Path traversal protection in sample file access via `resolve()` + `startsWith()` checks
+- Dependency injection: services instantiated in index.ts, passed to handlers
+- Error handling: try/catch with descriptive messages, console.error for config failures

package/.serena/memories/suggested_commands.md

@@ -0,0 +1,59 @@
+# Suggested Commands
+
+## Development
+
+```bash
+npm install          # Install dependencies
+npm run build        # Compile TypeScript to build/
+npm run dev          # Watch mode compilation
+npm run clean        # Remove build/ and coverage/ directories
+npm start            # Run the server (requires SDK path)
+```
+
+## Testing
+
+```bash
+npm test                     # Run all tests
+npm run test:watch           # Run tests in watch mode
+npm run test:coverage        # Run tests with coverage report
+
+# Run a single test file
+npx vitest run test/unit/services/ApiDocService.test.ts
+```
+
+## Code Quality
+
+```bash
+npm run lint         # Run ESLint
+npm run lint:fix     # Run ESLint with auto-fix
+npm run format       # Format code with Prettier
+npm run format:check # Check formatting without changes
+```
+
+## Running the Server
+
+The server auto-detects ConnectIQ SDK from OS defaults, or configure via:
+
+```bash
+# Option 1: Auto-detect (uses current-sdk.cfg)
+npx connectiq-mcp
+
+# Option 2: Environment variables
+CONNECTIQ_PATH="$HOME/Library/Application Support/Garmin/ConnectIQ" \
+CONNECTIQ_VERSION=8.4 npx connectiq-mcp
+
+# Option 3: CLI arguments
+npx connectiq-mcp --connectiq-path="/path/to/ConnectIQ" --version=8.4
+npx connectiq-mcp -c /path/to/ConnectIQ -v 8.4
+```
+
+## System Utilities (macOS/Darwin)
+
+```bash
+git status           # Check git status
+git diff             # View changes
+git log --oneline    # View commit history
+ls -la               # List files
+find . -name "*.ts"  # Find TypeScript files
+grep -r "pattern" .  # Search in files
+```

package/.serena/memories/task_completion.md

@@ -0,0 +1,56 @@
+# Task Completion Checklist
+
+When completing a task, run the following checks:
+
+## 1. Build Check
+```bash
+npm run build
+```
+Ensure TypeScript compiles without errors.
+
+## 2. Lint Check
+```bash
+npm run lint
+```
+Fix any linting errors. Auto-fix available:
+```bash
+npm run lint:fix
+```
+
+## 3. Format Check
+```bash
+npm run format:check
+```
+If formatting issues found, fix with:
+```bash
+npm run format
+```
+
+## 4. Run Tests
+```bash
+npm test
+```
+All tests must pass. For coverage report:
+```bash
+npm run test:coverage
+```
+
+## 5. Manual Verification (if applicable)
+If changes affect server behavior, test manually:
+```bash
+npm start
+# or with specific SDK path
+npx connectiq-mcp -c /path/to/ConnectIQ
+```
+
+## Summary Command
+Run all checks in sequence:
+```bash
+npm run build && npm run lint && npm run format:check && npm test
+```
+
+## Before Committing
+1. Stage only relevant changes
+2. Write clear, descriptive commit message
+3. Do NOT include "Generated with Claude" or Claude co-author attribution
+4. Verify build/lint/test pass before pushing

package/.serena/project.yml

@@ -0,0 +1,89 @@
+# list of languages for which language servers are started; choose from:
+#   al                  bash                clojure             cpp                 csharp
+#   csharp_omnisharp    dart                elixir              elm                 erlang
+#   fortran             fsharp              go                  groovy              haskell
+#   java                julia               kotlin              lua                 markdown
+#   matlab              nix                 pascal              perl                php
+#   powershell          python              python_jedi         r                   rego
+#   ruby                ruby_solargraph     rust                scala               swift
+#   terraform           toml                typescript          typescript_vts      vue
+#   yaml                zig
+#   (This list may be outdated. For the current list, see values of Language enum here:
+#   https://github.com/oraios/serena/blob/main/src/solidlsp/ls_config.py
+#   For some languages, there are alternative language servers, e.g. csharp_omnisharp, ruby_solargraph.)
+# Note:
+#   - For C, use cpp
+#   - For JavaScript, use typescript
+#   - For Free Pascal/Lazarus, use pascal
+# Special requirements:
+#   - csharp: Requires the presence of a .sln file in the project folder.
+#   - pascal: Requires Free Pascal Compiler (fpc) and optionally Lazarus.
+# When using multiple languages, the first language server that supports a given file will be used for that file.
+# The first language is the default language and the respective language server will be used as a fallback.
+# Note that when using the JetBrains backend, language servers are not used and this list is correspondingly ignored.
+languages:
+- typescript
+
+# the encoding used by text files in the project
+# For a list of possible encodings, see https://docs.python.org/3.11/library/codecs.html#standard-encodings
+encoding: "utf-8"
+
+# whether to use project's .gitignore files to ignore files
+ignore_all_files_in_gitignore: true
+
+# list of additional paths to ignore in all projects
+# same syntax as gitignore, so you can use * and **
+ignored_paths: []
+
+# whether the project is in read-only mode
+# If set to true, all editing tools will be disabled and attempts to use them will result in an error
+# Added on 2025-04-18
+read_only: false
+
+# list of tool names to exclude. We recommend not excluding any tools, see the readme for more details.
+# Below is the complete list of tools for convenience.
+# To make sure you have the latest list of tools, and to view their descriptions, 
+# execute `uv run scripts/print_tool_overview.py`.
+#
+#  * `activate_project`: Activates a project by name.
+#  * `check_onboarding_performed`: Checks whether project onboarding was already performed.
+#  * `create_text_file`: Creates/overwrites a file in the project directory.
+#  * `delete_lines`: Deletes a range of lines within a file.
+#  * `delete_memory`: Deletes a memory from Serena's project-specific memory store.
+#  * `execute_shell_command`: Executes a shell command.
+#  * `find_referencing_code_snippets`: Finds code snippets in which the symbol at the given location is referenced.
+#  * `find_referencing_symbols`: Finds symbols that reference the symbol at the given location (optionally filtered by type).
+#  * `find_symbol`: Performs a global (or local) search for symbols with/containing a given name/substring (optionally filtered by type).
+#  * `get_current_config`: Prints the current configuration of the agent, including the active and available projects, tools, contexts, and modes.
+#  * `get_symbols_overview`: Gets an overview of the top-level symbols defined in a given file.
+#  * `initial_instructions`: Gets the initial instructions for the current project.
+#     Should only be used in settings where the system prompt cannot be set,
+#     e.g. in clients you have no control over, like Claude Desktop.
+#  * `insert_after_symbol`: Inserts content after the end of the definition of a given symbol.
+#  * `insert_at_line`: Inserts content at a given line in a file.
+#  * `insert_before_symbol`: Inserts content before the beginning of the definition of a given symbol.
+#  * `list_dir`: Lists files and directories in the given directory (optionally with recursion).
+#  * `list_memories`: Lists memories in Serena's project-specific memory store.
+#  * `onboarding`: Performs onboarding (identifying the project structure and essential tasks, e.g. for testing or building).
+#  * `prepare_for_new_conversation`: Provides instructions for preparing for a new conversation (in order to continue with the necessary context).
+#  * `read_file`: Reads a file within the project directory.
+#  * `read_memory`: Reads the memory with the given name from Serena's project-specific memory store.
+#  * `remove_project`: Removes a project from the Serena configuration.
+#  * `replace_lines`: Replaces a range of lines within a file with new content.
+#  * `replace_symbol_body`: Replaces the full definition of a symbol.
+#  * `restart_language_server`: Restarts the language server, may be necessary when edits not through Serena happen.
+#  * `search_for_pattern`: Performs a search for a pattern in the project.
+#  * `summarize_changes`: Provides instructions for summarizing the changes made to the codebase.
+#  * `switch_modes`: Activates modes by providing a list of their names
+#  * `think_about_collected_information`: Thinking tool for pondering the completeness of collected information.
+#  * `think_about_task_adherence`: Thinking tool for determining whether the agent is still on track with the current task.
+#  * `think_about_whether_you_are_done`: Thinking tool for determining whether the task is truly completed.
+#  * `write_memory`: Writes a named memory (for future reference) to Serena's project-specific memory store.
+excluded_tools: []
+
+# initial prompt for the project. It will always be given to the LLM upon activating the project
+# (contrary to the memories, which are loaded on demand).
+initial_prompt: ""
+
+project_name: "connect-iq-mcp"
+included_optional_tools: []

package/CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.1.0] - 2026-01-17
+
+### Changed
+
+- Replace CONNECTIQ_SDK_PATH with CONNECTIQ_PATH environment variable (points to ConnectIQ root dir instead of SDK dir)
+- Add CONNECTIQ_VERSION environment variable for optional SDK version selection
+- Replace manual BM25 search implementation with MiniSearch library for improved search quality
+- Migrate to readdirp for efficient recursive directory traversal
+
+### Added
+
+- OS-specific auto-detection of ConnectIQ installation (macOS, Windows, Linux defaults)
+- Auto-discover Devices/ folder from ConnectIQ root directory
+- Read current-sdk.cfg for default SDK when no version specified
+- Add SearchFilters type for type/deprecated/minApiLevel filtering
+- Add tool output schemas and annotations in toolHandlers
+- Add mime library for proper MIME type detection in SampleService
+
+## [1.0.3] - 2026-01-16
+
+### Fixed
+
+- Fix authentication command for MCP Registry login
+
+## [1.0.2] - 2026-01-16
+
+### Fixed
+
+- Fix mcp-publisher download URL in publish workflow
+
+## [1.0.1] - 2026-01-16
+
+### Added
+
+- Add MCP Registry publishing workflow and server manifest
+- Add MCP prompts, async file cache, and migrate to McpServer API
+- Add comprehensive test suite and enhance device info support
+- Add ESLint for TypeScript linting
+- Add Prettier for code formatting
+- Initial release with ConnectIQ SDK documentation support

package/CLAUDE.md

@@ -28,9 +28,11 @@ npm run test:coverage # Run tests with coverage report
 npx vitest run test/unit/services/ApiDocService.test.ts
 ```
 
-The server requires the ConnectIQ SDK path via `CONNECTIQ_SDK_PATH` environment variable or `--sdk-path`/`-s` argument.
+The server auto-detects the ConnectIQ SDK based on OS defaults, or can be configured via:
+- `CONNECTIQ_PATH` environment variable or `--connectiq-path`/`-c` argument (ConnectIQ root directory)
+- `CONNECTIQ_VERSION` environment variable or `--version`/`-v` argument (optional, e.g., "8.4")
 
-Optionally, set `CONNECTIQ_DEVICES_PATH` (or `--devices-path`/`-d`) for richer device data including fonts and display details.
+If no version is specified, the server reads `current-sdk.cfg` to find the default SDK. The `Devices/` folder is automatically discovered for richer device data.
 
 ## Architecture
 
@@ -43,15 +45,15 @@ Optionally, set `CONNECTIQ_DEVICES_PATH` (or `--devices-path`/`-d`) for richer d
   - `resourceHandlers.ts` - Handles `connectiq://` URI resources
   - `promptHandlers.ts` - Registers 4 prompts (review-connectiq-code, explain-api, device-compatibility, optimize-memory)
 - `services/` - Business logic with caching
-  - `ApiDocService.ts` - Parses Toybox API HTML docs, search with relevance scoring, LRU cache (50 modules, 5 min TTL)
-  - `DeviceInfoService.ts` - Parses device XML from SDK `bin/devices/` directory
+  - `ApiDocService.ts` - Parses Toybox API HTML docs, MiniSearch full-text index with BM25+ scoring and fuzzy matching (built lazily on first search)
+  - `DeviceInfoService.ts` - Parses device data from SDK `resources/device-reference/` and optional `Devices/` folder
   - `SampleService.ts` - Browses SDK `samples/` directory with path traversal protection
   - `ProjectInfoService.ts` - Parses `bin/projectInfo.xml` for app types, permissions, sports
 - `parsers/` - Data extraction
   - `HtmlParser.ts` - Cheerio-based Toybox doc parsing
   - `XmlParser.ts` - fast-xml-parser wrapper for SDK config files
 - `types/index.ts` - Shared TypeScript interfaces
-- `utils/` - Shared utilities
+- `utils/` - Shared utilities (barrel export in `index.ts`)
   - `logging.ts` - MCP protocol logging wrapper (sends logs to client as notifications)
   - `AsyncFileCache.ts` - Generic async file caching with TTL
   - `MarkdownConverter.ts` - Turndown-based HTML to Markdown conversion