Augments MCP Server

🚀 Augments MCP Server

Augments MCP Server is a comprehensive framework documentation provider for Claude Code via Model Context Protocol (MCP). It offers real - time access to framework documentation, context - aware assistance, and intelligent caching to enhance development workflows.

🚀 Quick Start

Explore the powerful features of the Augments MCP Server right away. It integrates seamlessly with Claude Code, providing up - to - date and comprehensive framework information. You can choose between a hosted server for hassle - free use or a local installation for development and customization.

✨ Features

🎯 Comprehensive Framework Support

• Categorized Framework Registry: Covers Web, Backend, Mobile, AI/ML, Design, and Tools domains.
• Multi - Source Documentation: Aggregates from GitHub repositories, official websites, and examples.
• Hot - Reloading Configuration: Allows dynamic framework updates without restarting the server.
• Intelligent Prioritization: Ranks frameworks based on their importance.

⚡ Advanced Caching System

• TTL - Based Strategies: Different cache durations for stable, beta, and dev versions.
• Multi - Level Caching: Utilizes both memory and disk persistence for optimal performance.
• Smart Invalidation: Automatically refreshes the cache based on source updates.
• Cache Analytics: Provides detailed statistics and performance monitoring.

🧠 Context Enhancement

• Multi - Framework Context: Combines documentation from multiple frameworks.
• Code Compatibility Analysis: Detects framework compatibility issues.
• Pattern Recognition: Identifies common usage patterns and best practices.
• Task - Specific Guidance: Tailors context to development tasks.

🔧 Developer Experience

• 9 Comprehensive MCP Tools: Covers the full documentation lifecycle.
• Structured Responses: Outputs clean and validated JSON.
• Error Resilience: Gracefully degrades with detailed error messages.
• Async Performance: Enables non - blocking operations throughout.

🏗️ Architecture

Directory Structure

src/augments_mcp/
├── registry/                   # Framework registry management
│   ├── manager.py             # Hot - reloading registry manager
│   ├── models.py              # Pydantic data models
│   └── cache.py               # Advanced caching system
├── tools/                      # MCP tool implementations
│   ├── framework_discovery.py # Framework search and listing
│   ├── documentation.py       # Documentation retrieval
│   ├── context_enhancement.py # Multi - framework context
│   └── updates.py             # Cache management and updates
├── providers/                  # Documentation source providers
│   ├── github.py              # GitHub API integration
│   ├── website.py             # Web scraping provider
│   └── base.py                # Provider interface
├── utils/                      # Shared utilities
│   ├── github_client.py       # GitHub API client with rate limiting
│   └── validation.py          # Data validation utilities
└── server.py                  # FastMCP server implementation

frameworks/                     # Framework configurations by category
├── web/                       # Web frameworks
│   ├── tailwindcss.json
│   ├── react.json
│   └── nextjs.json
├── backend/                   # Backend frameworks
│   └── fastapi.json
├── design/                    # Design systems
│   └── shadcn - ui.json
└── ai - ml/                     # AI/ML frameworks
    ├── mcp - sdk - python.json
    └── anthropic - sdk.json

Framework Configuration Schema

{
  "name": "framework - name",
  "display_name": "Framework Display Name",
  "category": "web|backend|mobile|ai - ml|design|tools",
  "type": "framework|library|tool|service", 
  "version": "latest",
  "sources": {
    "documentation": {
      "github": {
        "repo": "owner/repository",
        "docs_path": "docs",
        "branch": "main"
      },
      "website": "https://docs.framework.com"
    },
    "examples": {
      "github": {
        "repo": "owner/examples",
        "docs_path": "examples", 
        "branch": "main"
      }
    }
  },
  "context_files": ["README.md", "CHANGELOG.md", "API.md"],
  "key_features": ["feature1", "feature2", "feature3"],
  "common_patterns": ["pattern1", "pattern2"],
  "priority": 50
}

📦 Installation

Prerequisites

• Python 3.11+
• uv (recommended) or pip

Installation Steps

# Clone the repository
git clone <repository - url>
cd augments - mcp - server

# Install with uv (recommended)
uv sync

# Or install with pip
pip install -e .

Environment Configuration

Create a .env file for optional configuration:

# Cache settings
AUGMENTS_CACHE_DIR=~/.cache/augments - mcp - server
AUGMENTS_CACHE_TTL=3600

# GitHub API (optional, for higher rate limits)
GITHUB_TOKEN=your_github_token_here

# Logging
LOG_LEVEL=INFO

💻 Usage Examples

Option 1: Hosted MCP Server (Recommended)

Connect directly to our hosted MCP server at https://mcp.augments.dev/mcp for the easiest setup.

Using Claude Code CLI

# Add the hosted MCP server
claude mcp add --transport http augments https://mcp.augments.dev/mcp

# Verify the server is configured
claude mcp list

# Get server details
claude mcp get augments

Using Cursor

Add to your Cursor MCP configuration:

{
  "mcpServers": {
    "augments": {
      "transport": "http",
      "url": "https://mcp.augments.dev/mcp"
    }
  }
}

Manual Configuration (Claude Desktop)

Add to your Claude Desktop MCP configuration file:

Location:

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

{
  "mcpServers": {
    "augments": {
      "transport": {
        "type": "streamable - http",
        "url": "https://mcp.augments.dev/mcp"
      }
    }
  }
}

Using the Hosted Server

Once configured, you can access all framework documentation directly:

1. Access Framework Documentation:

   @augments list frameworks in the web category
   @augments get documentation for tailwindcss responsive design
   

2. Get Multi - Framework Context:

   @augments get context for nextjs, tailwindcss, and shadcn - ui 
   for building a dashboard with dark mode
   

3. Analyze Code Compatibility:

   @augments analyze this React component for tailwindcss compatibility:
   [paste your code]
   

4. Search Documentation:

   @augments search nextjs documentation for "app router"
   

The hosted server provides:

• ✅ No installation required - Works immediately
• ✅ Always up - to - date - Latest framework documentation
• ✅ High availability - Reliable uptime with smart caching
• ✅ No authentication - Completely frictionless access
• ✅ Rate limiting protection - Intelligent abuse prevention
• ✅ MCP Protocol Compliant - Uses official MCP Python SDK with streamable - http transport
• ✅ Multi - Client Support - Compatible with Claude Code, Cursor, and other MCP clients

Option 2: Local Installation

For development, customization, or offline use, run the server locally.

Starting the Local Server

# Run with uv (recommended)
uv run augments - mcp - server

# Or run directly
python -m augments_mcp.server

# Development mode with auto - reload
uv run fastmcp dev src/augments_mcp/server.py

Claude Code Integration (Local)

Method 1: Using Claude Code CLI (Recommended)

# Add the local MCP server with environment variables
claude mcp add augments - local - e AUGMENTS_CACHE_DIR="~/.cache/augments - mcp - server" - e GITHUB_TOKEN="your_github_token" -- uv run augments - mcp - server

# Verify the server is configured
claude mcp list

# Get server details
claude mcp get augments - local

Method 2: Manual Configuration

{
  "mcpServers": {
    "augments - local": {
      "command": "uv",
      "args": ["run", "augments - mcp - server"],
      "cwd": "/path/to/augments - mcp - server",
      "env": {
        "AUGMENTS_CACHE_DIR": "~/.cache/augments - mcp - server",
        "GITHUB_TOKEN": "your_github_token"
      }
    }
  }
}

Method 3: Global Configuration

# Add with full path to project directory
claude mcp add augments - local - e GITHUB_TOKEN="your_github_token" -- uv run --directory /path/to/augments - mcp - server augments - mcp - server

Server Management

# List all configured MCP servers
claude mcp list

# Get details for a specific server
claude mcp get augments

# Remove the server if needed
claude mcp remove augments

# Update server configuration (remove and re - add)
claude mcp remove augments
claude mcp add --transport http augments https://mcp.augments.dev/mcp

Troubleshooting

• Server not appearing: Restart Claude Code after configuration.
• Connection errors: For hosted server, check internet connection. For local server, verify installation.
• Environment issues: Only applies to local installations.
• Permission errors: Ensure Claude Code has network access (hosted) or file access (local).

🔧 MCP Tools

Framework Discovery

list_available_frameworks

List all available frameworks with optional category filtering.

{
  "category": "web"
}

search_frameworks

Search frameworks by name, features, or keywords.

{
  "query": "react component library"
}

get_framework_info

Get detailed information about a specific framework.

{
  "framework": "tailwindcss"
}

Documentation Access

get_framework_docs

Retrieve comprehensive documentation for a framework.

{
  "framework": "nextjs",
  "section": "app - router",
  "use_cache": true
}

get_framework_examples

Get code examples for specific patterns within a framework.

{
  "framework": "react",
  "pattern": "hooks"
}

search_documentation

Search within a framework's cached documentation.

{
  "framework": "tailwindcss",
  "query": "responsive design",
  "limit": 10
}

Context Enhancement

get_framework_context

Get relevant context for multiple frameworks based on development task.

{
  "frameworks": ["nextjs", "tailwindcss", "shadcn - ui"],
  "task_description": "Building a responsive dashboard with dark mode"
}

analyze_code_compatibility

Analyze code for framework compatibility and suggest improvements.

{
  "code": "const App = () => { return <div className='p - 4'>Hello</div> }",
  "frameworks": ["react", "tailwindcss"]
}

Cache Management

check_framework_updates

Check if framework documentation has been updated since last cache.

{
  "framework": "nextjs"
}

refresh_framework_cache

Refresh cached documentation for frameworks.

{
  "framework": "react",
  "force": false
}

get_cache_stats

Get detailed cache statistics and performance metrics.

{}

📚 Documentation

Supported Frameworks

With 85+ frameworks across 8 categories, it provides comprehensive documentation coverage for modern development stacks:

Web Frameworks (25)

• React - JavaScript library for building user interfaces
• Next.js - React framework for production applications
• Vue.js - Progressive JavaScript framework
• Angular - Platform for building web applications
• Svelte - Compile - time optimized web framework
• SvelteKit - Full - stack Svelte framework
• Astro - Static site generator with islands architecture
• Remix - Full - stack web framework focused on web fundamentals
• Qwik - Resumable web framework
• SolidJS - Reactive JavaScript library
• Preact - Fast 3kB React alternative
• Alpine.js - Minimal framework for HTML enhancement
• Lit - Simple library for building web components
• Stimulus - JavaScript framework for HTML
• HTMX - Modern HTML with minimal JavaScript
• Tailwind CSS - Utility - first CSS framework
• Bootstrap - CSS framework for responsive design
• Bulma - Modern CSS framework based on Flexbox
• Foundation - Responsive front - end framework
• Material - UI - React components implementing Google's Material Design
• Chakra UI - Simple, modular, and accessible React components
• Mantine - Full - featured React components library
• Semantic UI - Development framework for creating beautiful, responsive layouts
• Three.js - JavaScript 3D library
• D3.js - Data - driven documents library

Backend Frameworks (18)

• FastAPI - Modern, fast Python web framework
• Django - High - level Python web framework
• Flask - Lightweight Python web framework
• Pyramid - Python web framework
• Sanic - Async Python web server/framework
• Express.js - Fast, unopinionated Node.js web framework
• Fastify - Fast and low overhead Node.js web framework
• Koa.js - Expressive middleware for Node.js
• NestJS - Progressive Node.js framework
• Laravel - PHP web application framework
• Ruby on Rails - Server - side web application framework
• Spring Boot - Java - based framework
• Actix - Rust web framework
• Axum - Ergonomic and modular Rust web framework
• Phoenix - Elixir web framework
• Echo - High performance Go web framework
• Gin - HTTP web framework for Go
• Fiber - Express - inspired Go web framework

AI/ML Frameworks (14)

• PyTorch - Machine learning framework
• TensorFlow - End - to - end ML platform
• Scikit - learn - Machine learning library for Python
• NumPy - Fundamental package for scientific computing
• Pandas - Data manipulation and analysis library
• Matplotlib - Plotting library for Python
• Seaborn - Statistical data visualization
• OpenCV - Computer vision library
• Hugging Face - Transformers and datasets library
• LangChain - Framework for developing LLM applications
• Streamlit - App framework for ML and data science
• Gradio - Build ML web apps
• MCP SDK Python - Model Context Protocol Python SDK
• Anthropic SDK - Python SDK for Anthropic APIs

Mobile Frameworks (6)

• React Native - Build mobile apps using React
• Flutter - Google's UI toolkit for mobile
• Expo - Platform for universal React applications
• Ionic - Cross - platform mobile app development
• Capacitor - Cross - platform native runtime
• Xamarin - Microsoft's mobile development platform

Database & ORM (5)

• Prisma - Next - generation Node.js and TypeScript ORM
• Mongoose - MongoDB object modeling for Node.js
• TypeORM - ORM for TypeScript and JavaScript
• SQLAlchemy - Python SQL toolkit and ORM
• Sequelize - Promise - based Node.js ORM

State Management (4)

• Redux - Predictable state container for JavaScript
• Zustand - Small, fast, and scalable state management
• MobX - Reactive state management
• Recoil - Experimental state management for React

Testing Frameworks (5)

• Jest - JavaScript testing framework
• Vitest - Fast Vite - native unit test framework
• Cypress - End - to - end testing framework
• Playwright - Web testing and automation
• pytest - Python testing framework

Development Tools (7)

• Webpack - Module bundler
• Vite - Fast build tool
• Parcel - Zero configuration build tool
• Rollup - Module bundler for JavaScript
• ESLint - JavaScript linter
• Prettier - Code formatter
• Turbo - High - performance build system
• Nx - Smart, fast and extensible build system

DevOps & Infrastructure (4)

• Docker - Containerization platform
• Kubernetes - Container orchestration
• Terraform - Infrastructure as code
• Ansible - Automation platform

Design Systems (1)

• shadcn/ui - Beautifully designed React components

Adding New Frameworks

1. Create Framework Configuration

Create a JSON file in the appropriate category directory:

# For a web framework
frameworks/web/my - framework.json

# For a backend framework  
frameworks/backend/my - framework.json

2. Framework Configuration Example

{
  "name": "my - framework",
  "display_name": "My Awesome Framework",
  "category": "web",
  "type": "framework",
  "version": "2.0.0",
  "sources": {
    "documentation": {
      "github": {
        "repo": "myorg/my - framework",
        "docs_path": "docs",
        "branch": "main"
      },
      "website": "https://myframework.dev/docs"
    },
    "examples": {
      "github": {
        "repo": "myorg/my - framework - examples",
        "docs_path": "examples",
        "branch": "main"
      }
    }
  },
  "context_files": ["README.md", "GUIDE.md"],
  "key_features": ["fast", "modern", "typescript"],
  "common_patterns": ["component - based", "declarative"],
  "priority": 60
}

3. Configuration Fields

The server automatically detects new framework configurations and hot - reloads them without restart.

🔧 Technical Details

Core Technologies

• FastMCP: Official MCP Python SDK with streamable - http transport
• Pydantic: Data validation and serialization
• httpx: Async HTTP client for API requests
• BeautifulSoup4: HTML parsing for web scraping
• diskcache: Persistent caching with TTL support
• structlog: Structured logging for observability
• watchdog: File system monitoring for hot - reload

MCP Protocol Implementation

• Transport: Streamable - HTTP (official MCP specification)
• Endpoint: /mcp (automatically mounted by FastMCP)
• Protocol Version: MCP 2024 - 11 - 05 specification
• Client Compatibility: Claude Code, Cursor, and all MCP - compliant clients
• Message Format: JSON - RPC over HTTP with streaming support
• Security: HTTPS/TLS encryption for hosted deployment

Design Principles

• Async - First: All I/O operations use async/await
• Type Safety: Comprehensive type hints throughout
• Error Resilience: Graceful degradation with detailed errors
• Performance: Multi - level caching and efficient data structures
• Extensibility: Plugin - based architecture for new providers
• Observability: Structured logging and comprehensive metrics

Caching Strategy

• Memory Cache: Fast access for recently used data
• Disk Cache: Persistent storage with TTL expiration
• TTL Strategies: Different durations based on content stability
  • Stable releases: 24 hours
  • Beta versions: 6 hours
  • Development branches: 1 hour
• Smart Invalidation: Automatic refresh based on source updates

🤝 Contributing

We welcome contributions! Please follow these steps:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing - feature
3. Add comprehensive tests for new functionality
4. Ensure code quality: Run formatters and linters
5. Update documentation for new features
6. Submit a pull request with detailed description

Development Setup

# Clone your fork
git clone https://github.com/yourusername/augments - mcp - server.git
cd augments - mcp - server

# Install development dependencies
uv sync

# Run tests to verify setup
uv run pytest

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

• 📖 Documentation: Model Context Protocol
• 🐛 Issues: [GitHub Issues](https://github.com/augmnt/augments - mcp - server/issues)
• 💬 Discussions: [GitHub Discussions](https://github.com/augmnt/augments - mcp - server/discussions)

Built with ❤️ for the Claude Code ecosystem