garmin-sdk-docs-mcp

Garmin SDK Documentation MCP Server

Overview

This is a Multimodal Conversation Plugin (MCP) for Claude that provides access to Garmin Connect IQ SDK documentation via an OpenAI vector store. The MCP allows Claude to search through your Garmin SDK documentation using natural language queries, enhancing its ability to provide accurate, context-specific information about Garmin SDK development.

Features

• 🔍 Natural Language Search: Allows Claude to search Garmin SDK documentation using conversational queries
• 📚 Documentation Access: Provides Claude with access to your entire Garmin SDK documentation corpus
• 🔄 Relevance Scoring: Returns search results ranked by relevance
• 🔧 Configurable Results: Adjustable number of results returned per query
• 🛠️ Utility Scripts: Tools for preparing and processing documentation for the vector store

Prerequisites

• Node.js v18+ installed
• An OpenAI API key
• A populated OpenAI vector store containing Garmin SDK documentation
• Claude Desktop with MCP support
• Python 3.8+ (for utility scripts)

Setup Instructions

1. Setting Up the Project

Option A: Local Installation

1. Clone or download this repository to your local machine

2. Install dependencies:

   cd FINAL-Garmin_MCP
   npm install

3. Configure environment variables:

   • Rename .env.template to .env if it doesn't already exist
   • Add your OpenAI API key and vector store ID to the .env file:

     OPENAI_API_KEY=your-openai-api-key-here
     VECTOR_STORE_ID=your-vector-store-id-here
     

4. Build the project:

   npm run build

   Or simply run the included build.bat file

Option B: Using npx (No Local Build Required)

1. Install the package globally (if published to npm):

   npm install -g garmin-sdk-docs-mcp

2. Run directly with npx:

   npx garmin-sdk-docs-mcp

3. Configure in Claude Desktop:

   • Instead of pointing to a local file, use the global command:

     "garmin-sdk-docs": {
       "command": "npx",
       "args": [
         "garmin-sdk-docs-mcp"
       ],
       "env": {
         "OPENAI_API_KEY": "your-api-key",
         "VECTOR_STORE_ID": "your-vector-store-id"
       }
     }

2. Creating and Populating a Vector Store

If you don't already have a vector store populated with Garmin SDK documentation, this repository includes utility scripts to help you prepare your documentation:

1. Install Python dependencies:

   cd utils
   pip install -r requirements.txt

2. Process your documentation:

   • Use merge-pdfs.bat to combine multiple PDFs if needed
   • Use chunk-pdf.bat to split the PDF into overlapping text chunks
   • Use upload-to-vector-store.bat to upload the chunks to OpenAI

See the Utils README for detailed instructions on using these utilities.

3. Configuring Claude Desktop

1. Find your Claude Desktop MCP configuration file:

   • Usually located in the Claude Desktop application settings folder

2. Add the MCP configuration:

   • Use the provided claude-mcp-config-example.json as a reference
   • Add a section for the Garmin SDK MCP:

     "garmin-sdk-docs": {
       "command": "node",
       "args": [
         "path/to/FINAL-Garmin_MCP/dist/index.js"
       ],
       "env": {
         "OPENAI_API_KEY": "your-openai-api-key",
         "VECTOR_STORE_ID": "your-vector-store-id"
       }
     }

   • Make sure to use the full absolute path to the index.js file
   • Add your actual OpenAI API key and vector store ID

3. Restart Claude Desktop to apply the changes

4. Testing the MCP

1. Test Direct API Connection:

   • Run the included test script to verify your OpenAI API key and vector store are working:

     node test-search.js "watch face"

   • Or simply run the included run-test.bat file

2. Test With Claude:

   • Open Claude Desktop
   • Ask questions about Garmin Connect IQ SDK development, such as:
     • "How do I create a watch face in Garmin Connect IQ?"
     • "What's the process for implementing heart rate monitoring in a Garmin app?"
     • "Explain the widget architecture in Garmin Connect IQ"

Project Structure

1. Source Code:

   • src/index.ts - The main MCP server implementation
   • All TypeScript configuration with proper type handling

2. Configuration Files:

   • package.json - Dependencies and project scripts
   • tsconfig.json - TypeScript compiler settings
   • .env - Environment variables for API key and vector store ID

3. Build and Test Scripts:

   • build.bat - Script to build the TypeScript project
   • test-search.js - Standalone script to test vector store connectivity
   • run-test.bat - Helper to run the test script easily

4. Utilities:

   • utils/merge_pdfs.py - Utility to merge multiple PDFs into a single file
   • utils/chunk_pdf.py - Utility to split PDFs into chunks for vector store embedding
   • utils/upload_to_vector_store.py - Utility to upload chunks to OpenAI vector store
   • Interactive batch files for easy use of these utilities

5. Documentation:

   • Comprehensive README files with setup and usage instructions

How it Works

1. MCP Protocol Implementation:

   • The server implements the Model Context Protocol (MCP) which allows Claude to:
     • Discover available tools (search_garmin_docs)
     • Call the search tool with parameters
     • Receive formatted search results

2. Search Process:

   • When Claude needs information about Garmin SDK, it calls the search_garmin_docs tool
   • The MCP server sends a query to OpenAI's vector search API
   • Results are retrieved from your vector store based on semantic relevance
   • The server formats the results and returns them to Claude

3. Document Processing:

   • PDF documentation is split into overlapping chunks (~2000 tokens with 400 token overlap)
   • These chunks are uploaded to OpenAI's vector store
   • When searched, the most semantically relevant chunks are returned

Customization

Adjusting Search Parameters

You can modify the search behavior by editing src/index.ts:

• Change the default number of results (currently 5)
• Adjust the formatting of search results
• Change the model used for search (currently "gpt-4o-mini")

Adding Additional Tools

You can extend the MCP server by adding more tools beyond document search:

1. Add new tool definitions using the server.tool() method
2. Implement the tool's functionality
3. Rebuild the project

Troubleshooting

Common Issues and Solutions

1. "No search results found" response:

   • Check that your vector store ID is correct
   • Verify that your vector store contains the expected documentation
   • Try a different, more general search query
   • Run the test script to check direct API connectivity

2. Connection errors:

   • Verify your OpenAI API key is valid
   • Check your internet connection
   • Look for any error messages in the Claude Desktop logs

3. MCP not found by Claude:

   • Ensure the path in the MCP configuration is correct
   • Verify that the built JavaScript file exists at the specified location
   • Restart Claude Desktop after making configuration changes

Technical Details

Dependencies

• @modelcontextprotocol/sdk - MCP protocol implementation
• openai - OpenAI API client for vector search
• zod - Schema validation for MCP tools
• dotenv - Environment variable management

Resources

• Model Context Protocol Documentation
• OpenAI Vector Store Documentation
• OpenAI API Reference
• Garmin Connect IQ SDK Documentation

Security Notes

• The OpenAI API key is stored in your MCP configuration file - ensure this file has appropriate access controls
• The MCP server has access to your OpenAI account with the provided API key
• Consider using a scoped API key with limited permissions for this specific purpose

License

This project is licensed under the MIT License - see the LICENSE file for details.