Template Outlet MCP Server

🤖 Enable AI assistants like Claude to intelligently search and retrieve Alpine.js Template Outlet documentation

An MCP (Model Context Protocol) server that provides three powerful tools for accessing Template Outlet documentation: documentation search, code example retrieval, and section navigation.

✨ Features

• 🔍 Smart Documentation Search - Search through all Template Outlet docs with relevance ranking
• 📝 Code Example Access - Retrieve complete working examples instantly
• 📚 Documentation Navigation - Browse available sections and topics
• ⚡ Fast & Local - No external API calls, everything runs locally
• 🎯 Context-Aware - Returns relevant snippets with surrounding context
• 🚀 Performance Optimized - Built-in caching with 5-minute TTL for faster searches
• 🛡️ Robust Error Handling - Custom error classes with detailed error messages
• 🔧 Flexible Configuration - Multiple path resolution strategies with environment variable support
• 📦 Zero Configuration - Works out of the box with sensible defaults
• ✅ Type-Safe - Comprehensive JSDoc annotations for IDE support
• 🧪 Well Tested - Full unit test coverage with Vitest

📋 Requirements

• Node.js: 18.0.0 or higher
• npm: 7.0.0 or higher (comes with Node.js)
• Alpine.js Template Outlet documentation: The server needs access to the documentation files (see Configuration)

🚀 Quick Start

Get your MCP server running in 5 minutes!

Installation

The Template Outlet MCP server adheres to the Model Context Protocol (MCP) specification. To integrate it with an AI agent, you will typically need to provide a configuration that specifies how to invoke the server. The core configuration involves defining a server with a unique name, a command to execute it, and optional arguments.

Here are configuration examples for various MCP-compatible AI agents:

Standard Configuration (for most clients)

{
  "mcpServers": {
    "template-outlet": {
      "command": "npx",
      "args": ["-y", "@masum-nishat/template-outlet-mcp"]
    }
  }
}

Amp

Add via the Amp VS Code extension settings screen or by updating your settings.json file:

{
  "amp.mcpServers": {
    "template-outlet": {
      "command": "npx",
      "args": [
        "@masum-nishat/template-outlet-mcp"
      ]
    }
  }
}

Amp CLI Setup:

Add via the amp mcp addcommand below

  amp mcp add template-outlet -- npx @masum-nishat/template-outlet-mcp

Claude Code

Add one of the following configurations to your Claude Code project's .mcp.json (or global ~/.config/claude/mcp.json):

Using npx

{
  "mcpServers": {
    "template-outlet": {
      "command": "npx",
      "args": ["-y", "@masum-nishat/template-outlet-mcp"]
    }
  }
}

Claude Code CLI Setup:

Use the Claude Code CLI to add the Template Outlet MCP server:

  claude mcp add template-outlet npx @masum-nishat/template-outlet-mcp

Claude Desktop

Follow the MCP install guide, use the standard config.

Codex

Use the Codex CLI to add the Template Outlet MCP server:

  codex mcp add template-outlet npx "@masum-nishat/template-outlet-mcp"

Alternatively, create or edit the configuration file ~/.codex/config.toml and add:

[mcp_servers.template-outlet]
command = "npx"
args = ["@masum-nishat/template-outlet-mcp"]

For more information, see the Codex MCP documentation.

Cursor

Go to Cursor Settings -> MCP -> Add new MCP Server. Name to your liking, use command type with the command npx @masum-nishat/template-outlet-mcp. You can also verify config or add command like arguments via clicking Edit.

Factory

Use the Factory CLI to add the Template Outlet MCP server:

  droid mcp add template-outlet "npx @masum-nishat/template-outlet-mcp"

Alternatively, type /mcp within Factory droid to open an interactive UI for managing MCP servers.

For more information, see the Factory MCP documentation.

Gemini CLI

Follow the MCP install guide, use the standard config.

Goose

Go to Advanced settings -> Extensions -> Add custom extension. Name to your liking, use type STDIO, and set the command to npx @masum-nishat/template-outlet-mcp. Click "Add Extension".

Kiro

Follow the MCP Servers documentation. For example in .kiro/settings/mcp.json:

{
  "mcpServers": {
    "template-outlet": {
      "command": "npx",
      "args": [
        "@masum-nishat/template-outlet-mcp"
      ]
    }
  }
}

LM Studio

Go to Program in the right sidebar -> Install -> Edit mcp.json. Use the standard config.

opencode

Follow the MCP Servers documentation. For example in ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "template-outlet": {
      "type": "local",
      "command": [
        "npx",
        "@masum-nishat/template-outlet-mcp"
      ],
      "enabled": true
    }
  }
}

Qodo Gen

Open Qodo Gen chat panel in VSCode or IntelliJ → Connect more tools → + Add new MCP → Paste the standard config.

Click Save.

VS Code

Follow the MCP install guide, use the standard config. You can also install the Template Outlet MCP server using the VS Code CLI:

# For VS Code
code --add-mcp '{"name":"template-outlet","command":"npx","args":["@masum-nishat/template-outlet-mcp"]}'

After installation, the Template Outlet MCP server will be available for use with your GitHub Copilot agent in VS Code.

Warp

Go to Settings -> AI -> Manage MCP Servers -> + Add to add an MCP Server. Use the standard config.

Alternatively, use the slash command /add-mcp in the Warp prompt and paste the standard config from above:

{
  "mcpServers": {
    "template-outlet": {
      "command": "npx",
      "args": [
        "@masum-nishat/template-outlet-mcp"
      ]
    }
  }
}

Windsurf

Follow Windsurf MCP documentation. Use the standard config.

Test It Out!

Once installed and configured, you can ask questions like:

• "Search template-outlet docs for recursive rendering"
• "Show me the nested menu example from template-outlet"
• "What sections are available in the template-outlet documentation?"
• "How do I handle infinite recursion in template-outlet?"

AI will use the MCP server to search documentation and provide accurate, contextual answers.

🛠️ Available Tools

This MCP server exposes the following tools:

| Tool | Purpose | Required Arguments | Optional Arguments | |-----------------|--------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------| | search-docs | Search Alpine.js Template Outlet documentation for specific topics, patterns, or examples. | query (string) | section (enum: all, api, examples, troubleshooting, best-practices) | | get-example | Retrieve a specific code example with full implementation details from the documentation. | example (enum: simple-tree, nested-menu, interactive-tree, file-system, comment-thread, org-chart) | - | | list-sections | List all available documentation sections and topics with their hierarchy. | - | - |

⚙️ Configuration

The server automatically searches for Template Outlet documentation in multiple locations. You can customize this behavior using environment variables.

Documentation Path Resolution

The server checks locations in this order:

1. TEMPLATE_OUTLET_DOCS_PATH environment variable (highest priority)
2. Sibling directory: ../template-outlet/ (for development)
3. Node modules: node_modules/alpine-template-outlet/ (peer dependency)

Setting Custom Documentation Path

If your Template Outlet documentation is in a custom location:

Linux/macOS:

export TEMPLATE_OUTLET_DOCS_PATH=/path/to/template-outlet

Windows (Command Prompt):

set TEMPLATE_OUTLET_DOCS_PATH=C:\path\to\template-outlet

Windows (PowerShell):

$env:TEMPLATE_OUTLET_DOCS_PATH="C:\path\to\template-outlet"

In MCP Configuration:

{
  "mcpServers": {
    "template-outlet": {
      "command": "npx",
      "args": ["-y", "@masum-nishat/template-outlet-mcp"],
      "env": {
        "TEMPLATE_OUTLET_DOCS_PATH": "/custom/path/to/template-outlet"
      }
    }
  }
}

Advanced Configuration

The server uses sensible defaults but can be customized:

• Cache TTL: Search index is cached for 5 minutes by default
• Node Version: Managed via .nvmrc (defaults to Node 20)
• Development Mode: Set NODE_ENV=development for debug information

🚀 Performance

Intelligent Caching

The server implements a smart caching mechanism:

• Search Index Caching: Documentation is indexed once and cached for 5 minutes
• Automatic Cache Invalidation: Cache expires after TTL, ensuring fresh results
• Memory Efficient: Only active searches consume memory
• Instant Subsequent Searches: Cached searches return results in milliseconds

Performance Tips

• The first search after server start takes ~100-200ms to build the index
• Subsequent searches within 5 minutes are nearly instant (~1-5ms)
• Large documentation sets benefit most from caching
• Cache automatically clears and rebuilds when documentation changes are detected

🛠️ Development

Want to contribute or customize the server? Here's how to get started.

Local Development Setup

# Clone the repository
git clone https://github.com/MasumNishat/template-outlet-mcp.git
cd template-outlet-mcp

# Install dependencies
npm install

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

# Lint code
npm run lint

# Fix linting issues
npm run lint:fix

# Format code
npm run format

# Check formatting
npm run format:check

Project Structure

template-outlet-mcp/
├── src/
│   ├── server.js           # Main MCP server
│   ├── config.js           # Configuration & path resolution
│   ├── errors.js           # Custom error classes
│   └── tools/
│       ├── searchDocs.js   # Documentation search tool
│       ├── getExample.js   # Example retrieval tool
│       └── listSections.js # Section listing tool
├── test/                   # Unit tests
├── .github/workflows/      # CI/CD pipelines
├── index.js               # Entry point
└── package.json

Running Locally

# Start the server
npm start

# Or run directly
node index.js

Testing

The project uses Vitest for testing:

# Run all tests
npm test

# Run tests with coverage report
npm run test:coverage

# Watch mode for development
npm run test:watch

Code Quality

We maintain high code quality standards:

• ESLint: Enforces code style and catches errors
• Prettier: Ensures consistent formatting
• Vitest: Comprehensive unit test coverage
• JSDoc: Full documentation for all functions
• GitHub Actions: Automated CI/CD pipeline

🐛 Troubleshooting

Documentation Not Found

Error: Template Outlet documentation not found

Solutions:

1. Set TEMPLATE_OUTLET_DOCS_PATH environment variable
2. Clone the template-outlet repository as a sibling directory
3. Install alpine-template-outlet as a peer dependency

# Option 1: Set environment variable
export TEMPLATE_OUTLET_DOCS_PATH=/path/to/template-outlet

# Option 2: Clone as sibling directory
cd ..
git clone https://github.com/alpinejs/template-outlet.git
cd template-outlet-mcp

# Option 3: Install peer dependency
npm install alpine-template-outlet

Search Returns No Results

Possible causes:

• Query is too specific
• Documentation hasn't been indexed yet
• Cache is stale

Solutions:

1. Try broader search terms
2. Wait a moment and try again (first search builds index)
3. Restart the MCP server to rebuild cache

Example Not Found

Error: Example "xyz" not found

Solution: Use list-sections tool to see available examples, or check the Available Tools section for valid example names.

Server Not Starting

Possible causes:

• Node.js version too old
• Dependencies not installed
• Port conflicts

Solutions:

# Check Node.js version (should be 18+)
node --version

# Reinstall dependencies
rm -rf node_modules package-lock.json
npm install

# Check for errors in logs
npm start 2>&1 | tee server.log

Performance Issues

If searches are slow:

1. First search is always slower: The index builds on first search
2. Check documentation size: Very large docs may take longer
3. Monitor memory usage: Ensure adequate system resources
4. Review cache settings: Default 5-minute TTL should work for most cases

🤝 Contributing

We welcome contributions! Here's how you can help:

Ways to Contribute

• 🐛 Report bugs: Open an issue with detailed reproduction steps
• 💡 Suggest features: Share your ideas for improvements
• 📖 Improve documentation: Help make the docs clearer
• 🔧 Submit PRs: Fix bugs or add features
• ⭐ Star the repo: Show your support!

Contribution Workflow

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Add tests: Ensure your changes are tested
5. Run quality checks:

   npm run lint
   npm run format:check
   npm test

6. Commit your changes: git commit -m "Add amazing feature"
7. Push to your fork: git push origin feature/amazing-feature
8. Open a Pull Request

Development Guidelines

• Follow existing code style (enforced by ESLint and Prettier)
• Add JSDoc comments to all public functions
• Write tests for new features
• Update documentation as needed
• Keep PRs focused and atomic

Code of Conduct

Be respectful, inclusive, and considerate. We're all here to learn and improve together!

📝 Changelog

See CHANGELOG.md for a detailed history of changes.

🔗 Related Projects

• Alpine.js - The progressive JavaScript framework
• Alpine.js Template Outlet - Recursive component rendering
• Model Context Protocol - MCP specification

📄 License

MIT © Masum

⬆ Back to Top

Made with ❤️ for the Alpine.js community