Stimulus Docs MCP Server

# Stimulus Docs MCP Server An MCP server to access up to date documentation for [Stimulus JS](http://stimulus.hotwired.dev/). ⚠️ **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: ```bash npm install ``` 3. Build the project using the provided script: ```bash 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: ```json { "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: ```json { "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](https://github.com/hotwired/stimulus-site) 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.