JUCE Documentation MCP Server

An MCP (Model Context Protocol) server that provides access to JUCE Framework C++ class documentation.

Features

• Fetch documentation for specific JUCE classes
• List all available JUCE classes
• Search for classes by name
• Format documentation as markdown
• Expose documentation through MCP resources and tools
• Default docs source: https://docs.juce.com/master
• Switch docs source at runtime (master/develop/custom URL/local path)
• Optional local docs setup from a JUCE checkout path

Installation

# Clone the repository
git clone https://github.com/josmithiii/mcp-servers-jos.git
cd mcp-servers-jos/juce-docs-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

Usage

Quick Start (Simple Setup)

If you want the easiest setup, follow these steps exactly.

1. Build once:

cd /path/to/mcp-servers-jos/juce-docs-mcp-server
npm install
npm run build

2. Add this MCP server to your client:

# Codex
codex mcp add juce-docs -- node "$(pwd)/dist/index.js"

# Claude Code
claude mcp add --scope user juce-docs -- node "$(pwd)/dist/index.js"

3. Check current docs source (default is JUCE master):

• Run tool get-juce-docs-config with args:

{}

4. If you want JUCE develop docs instead of master:

• Run tool set-juce-docs-source with args:

{
  "source": "develop"
}

5. If you want local docs from your JUCE checkout (faster, no docs network fetches):

• Run tool setup-local-juce-docs with args:

{
  "jucePath": "~/Code/JUCE",
  "generateIfMissing": true
}

generateIfMissing is only needed if local docs are not generated yet.

6. Switch back to hosted stable docs anytime:

• Run tool set-juce-docs-source with args:

{
  "source": "master"
}

Notes:

• You only need npm run build again after pulling/changing this server code.
• Your docs source choice is saved and reused on next startup.
• Local docs follow whatever branch/tag your local JUCE checkout is on. If you checkout a beta/develop branch in ~/Code/JUCE, then regenerate docs, this MCP server will use those docs.

Single-Command Terminal Setup (Set Source While Adding MCP)

If you want to configure docs source in one terminal command (without calling MCP tools in chat), set environment variables when adding the server.

Goal: add the MCP server and choose docs source up front.

• Use master for stable hosted JUCE docs.
• Use local-path for local JUCE docs (faster, no docs network fetches, follows your local JUCE branch after docs regeneration).

Claude CLI note: put juce-docs before -e flags.

• Correct pattern: claude mcp add --scope user juce-docs -e KEY=value -- node "$(pwd)/dist/index.js"

set-juce-docs-source options are:

• source=master
• source=develop
• source=custom-url with url
• source=local-path with localDocsPath

Equivalent one-line terminal commands:

# Codex: stable JUCE docs (master)
codex mcp add juce-docs --env JUCE_DOCS_SOURCE=master -- node "$(pwd)/dist/index.js"

# Codex: develop docs
codex mcp add juce-docs --env JUCE_DOCS_SOURCE=develop -- node "$(pwd)/dist/index.js"

# Codex: custom docs URL
codex mcp add juce-docs \
  --env JUCE_DOCS_SOURCE=custom-url \
  --env JUCE_DOCS_BASE_URL=https://docs.juce.com/develop \
  -- node "$(pwd)/dist/index.js"

# Codex: local docs path (no docs network fetches)
codex mcp add juce-docs \
  --env JUCE_DOCS_SOURCE=local-path \
  --env JUCE_DOCS_LOCAL_PATH="$HOME/Code/JUCE/docs/doxygen/doc" \
  -- node "$(pwd)/dist/index.js"

# Claude Code: stable JUCE docs (master)
claude mcp add --scope user juce-docs -e JUCE_DOCS_SOURCE=master -- node "$(pwd)/dist/index.js"

# Claude Code: develop docs
claude mcp add --scope user juce-docs -e JUCE_DOCS_SOURCE=develop -- node "$(pwd)/dist/index.js"

# Claude Code: custom docs URL
claude mcp add --scope user juce-docs \
  -e JUCE_DOCS_SOURCE=custom-url \
  -e JUCE_DOCS_BASE_URL=https://docs.juce.com/develop \
  -- node "$(pwd)/dist/index.js"

# Claude Code: local docs path
claude mcp add --scope user juce-docs \
  -e JUCE_DOCS_SOURCE=local-path \
  -e JUCE_DOCS_LOCAL_PATH="$HOME/Code/JUCE/docs/doxygen/doc" \
  -- node "$(pwd)/dist/index.js"

Most common copy/paste options:

For local JUCE docs (from your local JUCE checkout, e.g. master branch):

# Codex
codex mcp add juce-docs \
  --env JUCE_DOCS_SOURCE=local-path \
  --env JUCE_DOCS_LOCAL_PATH="$HOME/Code/JUCE/docs/doxygen/doc" \
  -- node "$(pwd)/dist/index.js"

# Claude
claude mcp add --scope user juce-docs \
  -e JUCE_DOCS_SOURCE=local-path \
  -e JUCE_DOCS_LOCAL_PATH="$HOME/Code/JUCE/docs/doxygen/doc" \
  -- node "$(pwd)/dist/index.js"

If you want hosted master docs instead:

# Codex
codex mcp add juce-docs --env JUCE_DOCS_SOURCE=master -- node "$(pwd)/dist/index.js"

# Claude
claude mcp add --scope user juce-docs -e JUCE_DOCS_SOURCE=master -- node "$(pwd)/dist/index.js"

If juce-docs is already added, remove then re-add:

codex mcp remove juce-docs
claude mcp remove --scope user juce-docs

Add to MCP Clients (Auto-Start, Recommended)

When configured as a stdio MCP server, Codex/Claude/Cursor start this server automatically when needed. You do not need to run npm start manually.

# from juce-docs-mcp-server directory
codex mcp add juce-docs -- node "$(pwd)/dist/index.js"
claude mcp add --scope user juce-docs -- node "$(pwd)/dist/index.js"

Build/install cadence:

• Run npm install once per clone (or when dependencies change)
• Run npm run build after pulling/changing TypeScript source

Running the Server Manually (Optional)

npm start

This starts the MCP server using stdio. Manual start is mainly useful for local debugging or direct testing.

Adding the MCP service to Cursor (tested 2025-03-11)

1. Open Cursor / Settings / Cursor Settings
2. Select MCP
3. Set the Name to JUCE Docs (or whatever), and set the Type to Command
4. Set the Command to node /path/to/juce-docs-mcp-server/dist/index.js, replacing /path/to/juce-docs-mcp-server with the actual path into your clone
5. Restart Cursor to apply the changes (it will internally run node .../dist/index.js)

Cursor will start the configured command automatically; no separate npm start process is required.

Adding the MCP service to Visual Studio (Tested 2026-01-13)

Visual Studio 2022/2026 with GitHub Copilot extension supports MCP through a built-in configuration.

1. Access Settings: In the Copilot Chat window, click the Wrench icon, then click the "+" (Add Source) to manage MCP servers.
2. Configuration: Visual Studio uses a specific JSON structure. When prompted to edit .mcp.json, use the following template (ensure forward slashes / are used for paths):

{
  "inputs": [],
  "servers": {
    "juce-expert": {
      "type": "stdio",
      "command": "node",
      "args": [
        "C:/path/to/juce-docs-mcp-server/dist/index.js"
      ],
      "env": {
        "NODE_PATH": "C:/path/to/juce-docs-mcp-server/node_modules"
      }
    }
  }
}

3. Important Note on "Description": Unlike some other MCP clients, Visual Studio requires a non-empty description field for every tool. If a tool's description is missing, Visual Studio will fail to load it with a System.ArgumentException. Ensure your index.ts definitions include description strings.
4. Troubleshooting: If tools are not appearing, try reloading the Copilot Chat window or clearing the Copilot cache folder located in your solution's .vs directory.

Available Resources

• juce://class/{className} - Get documentation for a specific JUCE class
• juce://classes - List all available JUCE classes

Available Tools

• search-juce-classes - Search for JUCE classes by name
• get-juce-class-docs - Get documentation for a specific JUCE class
• get-juce-docs-config - Show current docs source and how to switch it
• set-juce-docs-source - Switch docs source (master/develop/custom/local)
• setup-local-juce-docs - Point to a local JUCE checkout and optionally generate docs

Available Prompts

• explore-juce - Interactive exploration of JUCE framework components
  • Use without arguments for an overview of main components
  • Add a topic to explore specific functionality (e.g., explore-juce audio)

Resources and Tools

In addition to prompts that direct your LLM (such as in Cursor) to use the MCP internally, you can also query it directly via "resource" and "tool" names:

1. Resources look like URLs that directly fetch specific content. They follow a URI-like pattern with the format protocol://path. These are defined in the server as direct resource endpoints. Example: juce://classes

2. Tools are MCP function calls by name (for example: search-juce-classes, set-juce-docs-source) plus arguments. Depending on the MCP client UI, these may also appear as slash-style commands.

In summary, when connected to an MCP client (such as via Cursor chat), you can access "resources" in the format protocol://path and "tools" by tool name plus arguments (with some clients also supporting slash-style syntax).

Examples

1. List all available classes: juce://classes
2. Get documentation for a specific class: juce://class/ValueTree
3. Search for all Audio classes: search-juce-classes with { "query": "Audio" }
4. Get docs for a class: get-juce-class-docs with { "className": "AudioProcessor" }

Docs Source Configuration

This server defaults to official JUCE master docs:

https://docs.juce.com/master

You can switch sources without editing code by calling MCP tools:

1. get-juce-docs-config to inspect current config
2. set-juce-docs-source with one of:
   • source=master
   • source=develop
   • source=custom-url + url=https://...
   • source=local-path + localDocsPath=/path/to/docs
3. setup-local-juce-docs with:
   • jucePath=/path/to/JUCE
   • generateIfMissing=true (optional)

Configuration is persisted in:

~/.juce-docs-mcp-server/config.json

You can override config via environment variables:

• JUCE_DOCS_SOURCE=master|develop|custom-url|local-path
• JUCE_DOCS_BASE_URL=https://... (for custom-url)
• JUCE_DOCS_LOCAL_PATH=/path/to/docs (for local-path)
• JUCE_DOCS_CONFIG_PATH=/custom/path/config.json (optional config location)

Tips for Effective JUCE Development

When working on a JUCE project, here's how to get the most out of the JUCE Documentation MCP Server:

Quick Reference Workflows

1. Exploring Components

   • Start with /search-juce-classes followed by a general category (Audio, GUI, etc.)
   • Use explore-juce audio (or other domain) to get an overview of related classes

2. Implementation Help

   • When implementing a specific feature, use juce://class/ClassName to get detailed documentation
   • Look for code examples in the class documentation

3. Method Reference

   • The class documentation includes all methods with signatures and descriptions
   • Use this when you need to understand parameter types or return values

Integration with Your Development Process

1. Keep Cursor Open Alongside Your IDE

   • Have Cursor with the MCP server running in a separate window
   • This gives you instant access to documentation without leaving your code editor

2. Use During Planning Phases

   • Before implementing a feature, explore available classes with /search-juce-classes
   • This helps you understand the JUCE approach before writing code

3. Debugging Assistance

   • When encountering unexpected behavior, check the class documentation
   • Look for notes about edge cases or implementation details

Specific JUCE Development Tips

1. Audio Processing

   • Start with AudioProcessor for plugin development
   • Use AudioSource for playback applications
   • Check dsp:: namespace classes for efficient signal processing

2. GUI Development

   • Base all custom components on the Component class
   • Use AudioAppComponent to combine audio and GUI functionality
   • Look at LookAndFeel for styling

3. Plugin Development

   • Reference AudioProcessor and AudioProcessorEditor for the core plugin architecture
   • Check AudioProcessorValueTreeState for parameter management

Implementation Details

The server processes JUCE Doxygen HTML in real-time from either:

• Official hosted docs (master, develop, or custom URL)
• A local docs directory (no network required)

It extracts:

1. Class list is fetched from the annotated class list page
2. Individual class documentation is parsed from class-specific pages
3. Documentation is formatted as markdown for consistent display
4. Class list results are cached in memory during server runtime

Error Handling

Common issues and solutions:

1. Class Not Found: If a class name is invalid or not found, the server will return a clear error message
2. Connection Issues: If the JUCE documentation site is unreachable, check your internet connection
3. Server Start Failure: Ensure the correct Node.js version is installed and the build step completed successfully
4. Cursor Integration: If the server isn't working in Cursor, verify the command path in MCP settings is correct

Development

# Run in development mode with auto-recompilation
npm run dev

Developer Notes

License

MIT