kayaozkur/mcp-server-specnavigator

@lepion/mcp-server-specnavigator

An intelligent MCP (Model Context Protocol) server for navigating, exploring, and understanding the Model Context Protocol specification with dynamic markdown tree generation, intelligent section navigation, and upstream synchronization.

🎯 Purpose

The MCP SpecNavigator server transforms the way you interact with MCP specifications by providing:

• 🌳 Dynamic Markdown Trees - Navigate specifications with auto-generated tree structures
• 🔍 Intelligent Search - Find sections instantly with keyword search and anchor links
• 🔄 Upstream Sync - Stay updated with the latest specification changes
• 📚 Contextual Documentation - Access specific sections on-demand
• ⚡ Performance Optimized - Efficient caching for fast responses

📋 Attribution

This project is based on and provides navigation for the Model Context Protocol specification created by the Model Context Protocol team. This is a wrapper/navigation tool that enhances access to the original specification.

✨ Features

• Dynamic Markdown Tree Generation: Automatically generates navigable tree structures from MCP specifications
• Intelligent Section Search: Find sections by keywords and get direct anchor links
• Specification Caching: Efficiently caches specifications to reduce network requests
• Upstream Synchronization: Check for updates from the official MCP repository
• Section Content Retrieval: Get specific sections of the specification on demand

📦 Installation

Via npm (Recommended)

npm install -g @lepion/mcp-server-specnavigator

From Source

# Clone the repository
git clone https://github.com/kayaozkur/mcp-server-specnavigator.git
cd mcp-server-specnavigator

# Install dependencies
npm install

# Build the TypeScript code
npm run build

# Start the server
npm start

Development Mode

# Run with hot reload
npm run dev

🛠️ Available Tools

1. fetch_spec_updates

Check for upstream changes in the MCP specification repository.

Parameters:

• force_refresh (boolean, optional): Force refresh even if cache is valid

Returns:

• Update status and any new changes detected

2. generate_markdown_tree

Create a navigable tree structure of the MCP specification.

Parameters:

• max_depth (number, optional): Maximum depth of the tree (default: 3)
• include_anchors (boolean, optional): Include anchor links in the tree

Returns:

• Markdown-formatted tree structure with navigation links

3. find_section

Search for sections by keyword and return anchor links.

Parameters:

• query (string, required): Search query for section titles
• fuzzy (boolean, optional): Enable fuzzy matching (default: false)

Returns:

• Array of matching sections with titles, paths, and anchor links

4. get_spec_content

Retrieve content from a specific section of the specification.

Parameters:

• section_path (string, required): Path to the section (e.g., "protocol/messages")
• include_subsections (boolean, optional): Include subsection content

Returns:

• Markdown content of the requested section

⚙️ MCP Configuration

For Claude Desktop

Add to your Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "specnavigator": {
      "command": "npx",
      "args": ["@lepion/mcp-server-specnavigator"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

For Development

{
  "mcpServers": {
    "specnavigator": {
      "command": "node",
      "args": ["/path/to/mcp-server-specnavigator/dist/index.js"],
      "env": {
        "NODE_ENV": "development"
      }
    }
  }
}

🏗️ Architecture

src/
├── index.ts                    # Main MCP server entry point
├── spec-fetcher.ts            # Handles fetching and caching specs
├── markdown-tree-generator.ts  # Generates dynamic markdown trees
├── anchor-navigator.ts        # Finds sections and generates anchors
└── tools.ts                   # MCP tool definitions

🧪 Development

Running Tests

npm test

Linting

npm run lint

Formatting

npm run format

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

📄 License

MIT License - see file for details.

🙏 Acknowledgments

• Model Context Protocol Team - For creating the MCP specification that this server navigates
• Anthropic - For developing the Model Context Protocol standard
• Contributors - Everyone who has contributed to improving this navigation tool

🔗 Links

• NPM Package
• GitHub Repository
• Model Context Protocol Specification
• Report Issues

Built with ❤️ by the Lepion Team