Stimulus Docs MCP Server

An MCP server to access up to date documentation for Stimulus JS.

⚠️ This is Experimental Software

This MCP is in early development. It may contain bugs, have limited functionality, or undergo breaking changes without notice. Use at your own risk and expect potential instability.

Building the MCP Server

Prerequisites

• Node.js: Minimum version 18.0.0 or higher
• npm: Comes bundled with Node.js

Build Instructions

1. Clone this repository and navigate to the project directory
2. Install dependencies:

   npm install
   

3. Build the project using the provided script:

   npm run build
   

This will compile the TypeScript source code and create the executable in the build/ directory.

Usage

With Claude Desktop

1. First, build the MCP server following the instructions above
2. Follow the instructions at https://modelcontextprotocol.io/quickstart/user to add a new MCP server.
3. Add the following configuration:

{
  "mcpServers": {
    "stimulus-docs": {
      "command": "node",
      "args": ["/path/to/your/stimulus-docs-mcp-server/build/index.js"],
      "env": {}
    }
  }
}

3. Replace /path/to/your/stimulus-docs-mcp-server with the actual path to this project
4. Restart Claude Desktop
5. The Stimulus documentation tools should now be available in your Claude conversations

With VS Code

1. Build the MCP server following the instructions above
2. Follow the instructions at https://code.visualstudio.com/docs/copilot/chat/mcp-servers
3. Using your preferred method based on the instructions above, configure the MCP server by pointing it to the built executable:

   {
    "stimulus-docs": {
        "type": "stdio",
        "command": "node",
        "args": [
            "path/to/your/stimulus-docs-mcp-server"
          ]
    }
   }
   

4. Replace path/to/your/stimulus-docs-mcp-server with the path to the index.js file built in step 1.
5. The Stimulus documentation will be accessible through the MCP client interface

Troubleshooting

Claude

You may see the following errors when opening Claude after configuring the MCP:

MCP stimulus-docs: spawn node ENOENT (2)

Could not connect to MCP server stimulus-docs

MCP stimulus-docs: Server disconnected. For troubleshooting guidance [...]

This is because the path to the node executable can not be found. If that's the case, instead of "command": "node" use the complete path to the node. If you use mise it may be something like:

"command": "/Users/<YOUR USER NAME/.local/share/mise/installs/node/20.18.3/bin/node

Documentation Source & Caching Strategy

This MCP server fetches the latest Stimulus documentation directly from the official stimulus-site repository on GitHub. To ensure optimal performance and reduce API calls, the server implements the following caching strategy:

How It Works

1. Fresh Content Detection: The server checks the latest commit SHA and timestamp from the GitHub repository
2. Cache Key Generation: A unique cache key is generated using the commit SHA (first 7 characters) and timestamp
3. Caching: Documentation files are cached locally using the cache key as the folder structure
4. Cache Validation: Before fetching from GitHub, the server checks if content is already cached for the current commit
5. Fallback Strategy: If GitHub is unavailable, the server falls back to local documentation files

Cache Structure

cache/
  {commit-sha}-{timestamp}/
    handbook/
      01_introduction.md
      02_hello_stimulus.md
      ...
    reference/
      actions.md
      targets.md
      ...

Benefits

• Always Up-to-Date: Content is automatically updated when the Stimulus repository changes
• Performance: Cached content loads instantly without network requests
• Reliability: Local fallback ensures the server works even when GitHub is unavailable
• Efficient: Only fetches new content when the repository has been updated

The local documentation files in src/docs/ serve as a backup and ensure the MCP server remains functional even without internet connectivity.

All credit for the documentation content goes to the Stimulus team and contributors.

Available Tools

This MCP server provides access to the complete Stimulus documentation, organized into:

Handbook:

• The Origin of Stimulus
• Introduction
• Hello Stimulus Tutorial
• Building Something Real
• Designing for Resilience
• Managing State
• Working with External Resources
• Installing Stimulus

Reference:

• Actions
• Controllers
• CSS Classes
• Lifecycle Callbacks
• Outlets
• Targets
• Using TypeScript
• Values

Each documentation section is available as a separate tool that can be called to retrieve the relevant content.