A comprehensive framework documentation provider for Claude Code via Model Context Protocol (MCP). Provides real-time access to framework documentation, context-aware assistance, and intelligent caching to enhance development workflows.
mcp-name: io.github.augmnt/augments-mcp-server
## 🚀 Overview
Augments MCP Server is a sophisticated documentation retrieval system that integrates with Claude Code to provide comprehensive, up-to-date framework information. It features advanced caching strategies, multi-source documentation aggregation, and intelligent context enhancement for modern development workflows.
## ✨ Key Features
### 🎯 **Comprehensive Framework Support**
- **Categorized Framework Registry**: Web, Backend, Mobile, AI/ML, Design, and Tools
- **Multi-Source Documentation**: GitHub repositories, official websites, and examples
- **Hot-Reloading Configuration**: Dynamic framework updates without server restart
- **Intelligent Prioritization**: Framework importance-based ranking
### ⚡ **Advanced Caching System**
- **TTL-Based Strategies**: Different cache durations for stable/beta/dev versions
- **Multi-Level Caching**: Memory and disk persistence for optimal performance
- **Smart Invalidation**: Automatic cache refresh based on source updates
- **Cache Analytics**: Detailed statistics and performance monitoring
### 🧠 **Context Enhancement**
- **Multi-Framework Context**: Combine documentation from multiple frameworks
- **Code Compatibility Analysis**: Detect framework compatibility issues
- **Pattern Recognition**: Common usage patterns and best practices
- **Task-Specific Guidance**: Context tailored to development tasks
### 🔧 **Developer Experience**
- **9 Comprehensive MCP Tools**: Full documentation lifecycle coverage
- **Structured Responses**: Clean, validated JSON outputs
- **Error Resilience**: Graceful degradation with detailed error messages
- **Async Performance**: 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**
```json
{
"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](https://docs.astral.sh/uv/) (recommended) or pip
### **Installation Steps**
```bash
# 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:
```env
# 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
### **Option 1: Hosted MCP Server (Recommended)**
For the easiest setup, connect directly to our hosted MCP server at `https://mcp.augments.dev/mcp`. No installation required!
#### **Using Claude Code CLI**
```bash
# 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:
```json
{
"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`
```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, you can run the server locally.
#### **Starting the Local Server**
```bash
# 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)**
```bash
# 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**
```json
{
"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**
```bash
# 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**
```bash
# 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.
```json
{
"category": "web"
}
```
#### `search_frameworks`
Search frameworks by name, features, or keywords.
```json
{
"query": "react component library"
}
```
#### `get_framework_info`
Get detailed information about a specific framework.
```json
{
"framework": "tailwindcss"
}
```
### **Documentation Access**
#### `get_framework_docs`
Retrieve comprehensive documentation for a framework.
```json
{
"framework": "nextjs",
"section": "app-router",
"use_cache": true
}
```
#### `get_framework_examples`
Get code examples for specific patterns within a framework.
```json
{
"framework": "react",
"pattern": "hooks"
}
```
#### `search_documentation`
Search within a framework's cached documentation.
```json
{
"framework": "tailwindcss",
"query": "responsive design",
"limit": 10
}
```
### **Context Enhancement**
#### `get_framework_context`
Get relevant context for multiple frameworks based on development task.
```json
{
"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.
```json
{
"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.
```json
{
"framework": "nextjs"
}
```
#### `refresh_framework_cache`
Refresh cached documentation for frameworks.
```json
{
"framework": "react",
"force": false
}
```
#### `get_cache_stats`
Get detailed cache statistics and performance metrics.
```json
{}
```
## 📚 Supported Frameworks
With **85+ frameworks** across 8 categories, providing 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:
```bash
# For a web framework
frameworks/web/my-framework.json
# For a backend framework
frameworks/backend/my-framework.json
```
### **2. Framework Configuration Example**
```json
{
"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**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | ✅ | Unique framework identifier |
| `display_name` | string | ✅ | Human-readable name |
| `category` | string | ✅ | Framework category |
| `type` | string | ✅ | Framework type |
| `version` | string | ❌ | Version (default: "latest") |
| `sources` | object | ✅ | Documentation sources |
| `context_files` | array | ✅ | Important files to include |
| `key_features` | array | ✅ | Main features/capabilities |
| `common_patterns` | array | ✅ | Usage patterns |
| `priority` | number | ❌ | Importance (1-100, default: 50) |
The server automatically detects new framework configurations and hot-reloads them without restart.
## 🧪 Development
### **Running Tests**
```bash
# Run all tests
uv run pytest
# Run specific test categories
uv run pytest tests/test_models.py -v
uv run pytest tests/test_cache.py -v
uv run pytest tests/test_tools.py -v
# Run with coverage
uv run pytest --cov=src/augments_mcp --cov-report=html
```
### **Code Quality**
```bash
# Format code
uv run black src tests
# Lint code
uv run ruff check src tests
# Type checking
uv run mypy src
# Run all quality checks
uv run black src tests && uv run ruff check src tests && uv run mypy src
```
### **Development Server**
```bash
# Run with auto-reload for development
uv run fastmcp dev src/augments_mcp/server.py
# Run with debug logging
LOG_LEVEL=DEBUG uv run augments-mcp-server
```
## 🏛️ 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**
```bash
# 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](LICENSE) file for details.
## 🆘 Support
- 📖 **Documentation**: [Model Context Protocol](https://modelcontextprotocol.io)
- 🐛 **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**
Raw data
{
"_id": null,
"home_page": null,
"name": "augments-mcp-server",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "mcp, claude, documentation, framework, ai, development-tools",
"author": "augmnt",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/1a/39/71b991d53b5670b416cfb17695779b8a5244b680aca2e574a463eb91aeac/augments_mcp_server-2.0.1.tar.gz",
"platform": null,
"description": "\n\nA comprehensive framework documentation provider for Claude Code via Model Context Protocol (MCP). Provides real-time access to framework documentation, context-aware assistance, and intelligent caching to enhance development workflows.\n\nmcp-name: io.github.augmnt/augments-mcp-server\n\n## \ud83d\ude80 Overview\n\nAugments MCP Server is a sophisticated documentation retrieval system that integrates with Claude Code to provide comprehensive, up-to-date framework information. It features advanced caching strategies, multi-source documentation aggregation, and intelligent context enhancement for modern development workflows.\n\n## \u2728 Key Features\n\n### \ud83c\udfaf **Comprehensive Framework Support**\n- **Categorized Framework Registry**: Web, Backend, Mobile, AI/ML, Design, and Tools\n- **Multi-Source Documentation**: GitHub repositories, official websites, and examples\n- **Hot-Reloading Configuration**: Dynamic framework updates without server restart\n- **Intelligent Prioritization**: Framework importance-based ranking\n\n### \u26a1 **Advanced Caching System**\n- **TTL-Based Strategies**: Different cache durations for stable/beta/dev versions\n- **Multi-Level Caching**: Memory and disk persistence for optimal performance\n- **Smart Invalidation**: Automatic cache refresh based on source updates\n- **Cache Analytics**: Detailed statistics and performance monitoring\n\n### \ud83e\udde0 **Context Enhancement**\n- **Multi-Framework Context**: Combine documentation from multiple frameworks\n- **Code Compatibility Analysis**: Detect framework compatibility issues\n- **Pattern Recognition**: Common usage patterns and best practices\n- **Task-Specific Guidance**: Context tailored to development tasks\n\n### \ud83d\udd27 **Developer Experience**\n- **9 Comprehensive MCP Tools**: Full documentation lifecycle coverage\n- **Structured Responses**: Clean, validated JSON outputs\n- **Error Resilience**: Graceful degradation with detailed error messages\n- **Async Performance**: Non-blocking operations throughout\n\n## \ud83c\udfd7\ufe0f Architecture\n\n### **Directory Structure**\n```\nsrc/augments_mcp/\n\u251c\u2500\u2500 registry/ # Framework registry management\n\u2502 \u251c\u2500\u2500 manager.py # Hot-reloading registry manager\n\u2502 \u251c\u2500\u2500 models.py # Pydantic data models\n\u2502 \u2514\u2500\u2500 cache.py # Advanced caching system\n\u251c\u2500\u2500 tools/ # MCP tool implementations\n\u2502 \u251c\u2500\u2500 framework_discovery.py # Framework search and listing\n\u2502 \u251c\u2500\u2500 documentation.py # Documentation retrieval\n\u2502 \u251c\u2500\u2500 context_enhancement.py # Multi-framework context\n\u2502 \u2514\u2500\u2500 updates.py # Cache management and updates\n\u251c\u2500\u2500 providers/ # Documentation source providers\n\u2502 \u251c\u2500\u2500 github.py # GitHub API integration\n\u2502 \u251c\u2500\u2500 website.py # Web scraping provider\n\u2502 \u2514\u2500\u2500 base.py # Provider interface\n\u251c\u2500\u2500 utils/ # Shared utilities\n\u2502 \u251c\u2500\u2500 github_client.py # GitHub API client with rate limiting\n\u2502 \u2514\u2500\u2500 validation.py # Data validation utilities\n\u2514\u2500\u2500 server.py # FastMCP server implementation\n\nframeworks/ # Framework configurations by category\n\u251c\u2500\u2500 web/ # Web frameworks\n\u2502 \u251c\u2500\u2500 tailwindcss.json\n\u2502 \u251c\u2500\u2500 react.json\n\u2502 \u2514\u2500\u2500 nextjs.json\n\u251c\u2500\u2500 backend/ # Backend frameworks\n\u2502 \u2514\u2500\u2500 fastapi.json\n\u251c\u2500\u2500 design/ # Design systems\n\u2502 \u2514\u2500\u2500 shadcn-ui.json\n\u2514\u2500\u2500 ai-ml/ # AI/ML frameworks\n \u251c\u2500\u2500 mcp-sdk-python.json\n \u2514\u2500\u2500 anthropic-sdk.json\n```\n\n### **Framework Configuration Schema**\n```json\n{\n \"name\": \"framework-name\",\n \"display_name\": \"Framework Display Name\",\n \"category\": \"web|backend|mobile|ai-ml|design|tools\",\n \"type\": \"framework|library|tool|service\", \n \"version\": \"latest\",\n \"sources\": {\n \"documentation\": {\n \"github\": {\n \"repo\": \"owner/repository\",\n \"docs_path\": \"docs\",\n \"branch\": \"main\"\n },\n \"website\": \"https://docs.framework.com\"\n },\n \"examples\": {\n \"github\": {\n \"repo\": \"owner/examples\",\n \"docs_path\": \"examples\", \n \"branch\": \"main\"\n }\n }\n },\n \"context_files\": [\"README.md\", \"CHANGELOG.md\", \"API.md\"],\n \"key_features\": [\"feature1\", \"feature2\", \"feature3\"],\n \"common_patterns\": [\"pattern1\", \"pattern2\"],\n \"priority\": 50\n}\n```\n\n## \ud83d\udee0\ufe0f Installation\n\n### **Prerequisites**\n- Python 3.11+\n- [uv](https://docs.astral.sh/uv/) (recommended) or pip\n\n### **Installation Steps**\n\n```bash\n# Clone the repository\ngit clone <repository-url>\ncd augments-mcp-server\n\n# Install with uv (recommended)\nuv sync\n\n# Or install with pip\npip install -e .\n```\n\n### **Environment Configuration**\n\nCreate a `.env` file for optional configuration:\n```env\n# Cache settings\nAUGMENTS_CACHE_DIR=~/.cache/augments-mcp-server\nAUGMENTS_CACHE_TTL=3600\n\n# GitHub API (optional, for higher rate limits)\nGITHUB_TOKEN=your_github_token_here\n\n# Logging\nLOG_LEVEL=INFO\n```\n\n## \ud83d\ude80 Usage\n\n### **Option 1: Hosted MCP Server (Recommended)**\n\nFor the easiest setup, connect directly to our hosted MCP server at `https://mcp.augments.dev/mcp`. No installation required!\n\n#### **Using Claude Code CLI**\n\n```bash\n# Add the hosted MCP server\nclaude mcp add --transport http augments https://mcp.augments.dev/mcp\n\n# Verify the server is configured\nclaude mcp list\n\n# Get server details\nclaude mcp get augments\n```\n\n#### **Using Cursor**\n\nAdd to your Cursor MCP configuration:\n\n```json\n{\n \"mcpServers\": {\n \"augments\": {\n \"transport\": \"http\",\n \"url\": \"https://mcp.augments.dev/mcp\"\n }\n }\n}\n```\n\n#### **Manual Configuration (Claude Desktop)**\n\nAdd to your Claude Desktop MCP configuration file:\n\n**Location**: \n- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n- **Linux**: `~/.config/Claude/claude_desktop_config.json`\n\n```json\n{\n \"mcpServers\": {\n \"augments\": {\n \"transport\": {\n \"type\": \"streamable-http\",\n \"url\": \"https://mcp.augments.dev/mcp\"\n }\n }\n }\n}\n```\n\n#### **Using the Hosted Server**\n\nOnce configured, you can access all framework documentation directly:\n\n1. **Access Framework Documentation**:\n ```\n @augments list frameworks in the web category\n @augments get documentation for tailwindcss responsive design\n ```\n\n2. **Get Multi-Framework Context**:\n ```\n @augments get context for nextjs, tailwindcss, and shadcn-ui \n for building a dashboard with dark mode\n ```\n\n3. **Analyze Code Compatibility**:\n ```\n @augments analyze this React component for tailwindcss compatibility:\n [paste your code]\n ```\n\n4. **Search Documentation**:\n ```\n @augments search nextjs documentation for \"app router\"\n ```\n\nThe hosted server provides:\n- \u2705 **No installation required** - Works immediately\n- \u2705 **Always up-to-date** - Latest framework documentation\n- \u2705 **High availability** - Reliable uptime with smart caching\n- \u2705 **No authentication** - Completely frictionless access\n- \u2705 **Rate limiting protection** - Intelligent abuse prevention\n- \u2705 **MCP Protocol Compliant** - Uses official MCP Python SDK with streamable-http transport\n- \u2705 **Multi-Client Support** - Compatible with Claude Code, Cursor, and other MCP clients\n\n### **Option 2: Local Installation**\n\nFor development, customization, or offline use, you can run the server locally.\n\n#### **Starting the Local Server**\n\n```bash\n# Run with uv (recommended)\nuv run augments-mcp-server\n\n# Or run directly\npython -m augments_mcp.server\n\n# Development mode with auto-reload\nuv run fastmcp dev src/augments_mcp/server.py\n```\n\n#### **Claude Code Integration (Local)**\n\n##### **Method 1: Using Claude Code CLI (Recommended)**\n\n```bash\n# Add the local MCP server with environment variables\nclaude mcp add augments-local -e AUGMENTS_CACHE_DIR=\"~/.cache/augments-mcp-server\" -e GITHUB_TOKEN=\"your_github_token\" -- uv run augments-mcp-server\n\n# Verify the server is configured\nclaude mcp list\n\n# Get server details\nclaude mcp get augments-local\n```\n\n##### **Method 2: Manual Configuration**\n\n```json\n{\n \"mcpServers\": {\n \"augments-local\": {\n \"command\": \"uv\",\n \"args\": [\"run\", \"augments-mcp-server\"],\n \"cwd\": \"/path/to/augments-mcp-server\",\n \"env\": {\n \"AUGMENTS_CACHE_DIR\": \"~/.cache/augments-mcp-server\",\n \"GITHUB_TOKEN\": \"your_github_token\"\n }\n }\n }\n}\n```\n\n##### **Method 3: Global Configuration**\n\n```bash\n# Add with full path to project directory\nclaude mcp add augments-local -e GITHUB_TOKEN=\"your_github_token\" -- uv run --directory /path/to/augments-mcp-server augments-mcp-server\n```\n\n#### **Server Management**\n\n```bash\n# List all configured MCP servers\nclaude mcp list\n\n# Get details for a specific server\nclaude mcp get augments\n\n# Remove the server if needed\nclaude mcp remove augments\n\n# Update server configuration (remove and re-add)\nclaude mcp remove augments\nclaude mcp add --transport http augments https://mcp.augments.dev/mcp\n```\n\n#### **Troubleshooting**\n\n- **Server not appearing**: Restart Claude Code after configuration\n- **Connection errors**: For hosted server, check internet connection. For local server, verify installation\n- **Environment issues**: Only applies to local installations\n- **Permission errors**: Ensure Claude Code has network access (hosted) or file access (local)\n\n## \ud83d\udd27 MCP Tools\n\n### **Framework Discovery**\n\n#### `list_available_frameworks`\nList all available frameworks with optional category filtering.\n\n```json\n{\n \"category\": \"web\"\n}\n```\n\n#### `search_frameworks` \nSearch frameworks by name, features, or keywords.\n\n```json\n{\n \"query\": \"react component library\"\n}\n```\n\n#### `get_framework_info`\nGet detailed information about a specific framework.\n\n```json\n{\n \"framework\": \"tailwindcss\"\n}\n```\n\n### **Documentation Access**\n\n#### `get_framework_docs`\nRetrieve comprehensive documentation for a framework.\n\n```json\n{\n \"framework\": \"nextjs\",\n \"section\": \"app-router\",\n \"use_cache\": true\n}\n```\n\n#### `get_framework_examples`\nGet code examples for specific patterns within a framework.\n\n```json\n{\n \"framework\": \"react\",\n \"pattern\": \"hooks\"\n}\n```\n\n#### `search_documentation`\nSearch within a framework's cached documentation.\n\n```json\n{\n \"framework\": \"tailwindcss\",\n \"query\": \"responsive design\",\n \"limit\": 10\n}\n```\n\n### **Context Enhancement**\n\n#### `get_framework_context`\nGet relevant context for multiple frameworks based on development task.\n\n```json\n{\n \"frameworks\": [\"nextjs\", \"tailwindcss\", \"shadcn-ui\"],\n \"task_description\": \"Building a responsive dashboard with dark mode\"\n}\n```\n\n#### `analyze_code_compatibility`\nAnalyze code for framework compatibility and suggest improvements.\n\n```json\n{\n \"code\": \"const App = () => { return <div className='p-4'>Hello</div> }\",\n \"frameworks\": [\"react\", \"tailwindcss\"]\n}\n```\n\n### **Cache Management**\n\n#### `check_framework_updates`\nCheck if framework documentation has been updated since last cache.\n\n```json\n{\n \"framework\": \"nextjs\"\n}\n```\n\n#### `refresh_framework_cache`\nRefresh cached documentation for frameworks.\n\n```json\n{\n \"framework\": \"react\",\n \"force\": false\n}\n```\n\n#### `get_cache_stats`\nGet detailed cache statistics and performance metrics.\n\n```json\n{}\n```\n\n## \ud83d\udcda Supported Frameworks\n\nWith **85+ frameworks** across 8 categories, providing comprehensive documentation coverage for modern development stacks:\n\n### **Web Frameworks (25)**\n- **React** - JavaScript library for building user interfaces\n- **Next.js** - React framework for production applications\n- **Vue.js** - Progressive JavaScript framework\n- **Angular** - Platform for building web applications\n- **Svelte** - Compile-time optimized web framework\n- **SvelteKit** - Full-stack Svelte framework\n- **Astro** - Static site generator with islands architecture\n- **Remix** - Full-stack web framework focused on web fundamentals\n- **Qwik** - Resumable web framework\n- **SolidJS** - Reactive JavaScript library\n- **Preact** - Fast 3kB React alternative\n- **Alpine.js** - Minimal framework for HTML enhancement\n- **Lit** - Simple library for building web components\n- **Stimulus** - JavaScript framework for HTML\n- **HTMX** - Modern HTML with minimal JavaScript\n- **Tailwind CSS** - Utility-first CSS framework\n- **Bootstrap** - CSS framework for responsive design\n- **Bulma** - Modern CSS framework based on Flexbox\n- **Foundation** - Responsive front-end framework\n- **Material-UI** - React components implementing Google's Material Design\n- **Chakra UI** - Simple, modular, and accessible React components\n- **Mantine** - Full-featured React components library\n- **Semantic UI** - Development framework for creating beautiful, responsive layouts\n- **Three.js** - JavaScript 3D library\n- **D3.js** - Data-driven documents library\n\n### **Backend Frameworks (18)**\n- **FastAPI** - Modern, fast Python web framework\n- **Django** - High-level Python web framework\n- **Flask** - Lightweight Python web framework\n- **Pyramid** - Python web framework\n- **Sanic** - Async Python web server/framework\n- **Express.js** - Fast, unopinionated Node.js web framework\n- **Fastify** - Fast and low overhead Node.js web framework\n- **Koa.js** - Expressive middleware for Node.js\n- **NestJS** - Progressive Node.js framework\n- **Laravel** - PHP web application framework\n- **Ruby on Rails** - Server-side web application framework\n- **Spring Boot** - Java-based framework\n- **Actix** - Rust web framework\n- **Axum** - Ergonomic and modular Rust web framework\n- **Phoenix** - Elixir web framework\n- **Echo** - High performance Go web framework\n- **Gin** - HTTP web framework for Go\n- **Fiber** - Express-inspired Go web framework\n\n### **AI/ML Frameworks (14)**\n- **PyTorch** - Machine learning framework\n- **TensorFlow** - End-to-end ML platform\n- **Scikit-learn** - Machine learning library for Python\n- **NumPy** - Fundamental package for scientific computing\n- **Pandas** - Data manipulation and analysis library\n- **Matplotlib** - Plotting library for Python\n- **Seaborn** - Statistical data visualization\n- **OpenCV** - Computer vision library\n- **Hugging Face** - Transformers and datasets library\n- **LangChain** - Framework for developing LLM applications\n- **Streamlit** - App framework for ML and data science\n- **Gradio** - Build ML web apps\n- **MCP SDK Python** - Model Context Protocol Python SDK\n- **Anthropic SDK** - Python SDK for Anthropic APIs\n\n### **Mobile Frameworks (6)**\n- **React Native** - Build mobile apps using React\n- **Flutter** - Google's UI toolkit for mobile\n- **Expo** - Platform for universal React applications\n- **Ionic** - Cross-platform mobile app development\n- **Capacitor** - Cross-platform native runtime\n- **Xamarin** - Microsoft's mobile development platform\n\n### **Database & ORM (5)**\n- **Prisma** - Next-generation Node.js and TypeScript ORM\n- **Mongoose** - MongoDB object modeling for Node.js\n- **TypeORM** - ORM for TypeScript and JavaScript\n- **SQLAlchemy** - Python SQL toolkit and ORM\n- **Sequelize** - Promise-based Node.js ORM\n\n### **State Management (4)**\n- **Redux** - Predictable state container for JavaScript\n- **Zustand** - Small, fast, and scalable state management\n- **MobX** - Reactive state management\n- **Recoil** - Experimental state management for React\n\n### **Testing Frameworks (5)**\n- **Jest** - JavaScript testing framework\n- **Vitest** - Fast Vite-native unit test framework\n- **Cypress** - End-to-end testing framework\n- **Playwright** - Web testing and automation\n- **pytest** - Python testing framework\n\n### **Development Tools (7)**\n- **Webpack** - Module bundler\n- **Vite** - Fast build tool\n- **Parcel** - Zero configuration build tool\n- **Rollup** - Module bundler for JavaScript\n- **ESLint** - JavaScript linter\n- **Prettier** - Code formatter\n- **Turbo** - High-performance build system\n- **Nx** - Smart, fast and extensible build system\n\n### **DevOps & Infrastructure (4)**\n- **Docker** - Containerization platform\n- **Kubernetes** - Container orchestration\n- **Terraform** - Infrastructure as code\n- **Ansible** - Automation platform\n\n### **Design Systems (1)**\n- **shadcn/ui** - Beautifully designed React components\n\n## \ud83d\udd04 Adding New Frameworks\n\n### **1. Create Framework Configuration**\n\nCreate a JSON file in the appropriate category directory:\n\n```bash\n# For a web framework\nframeworks/web/my-framework.json\n\n# For a backend framework \nframeworks/backend/my-framework.json\n```\n\n### **2. Framework Configuration Example**\n\n```json\n{\n \"name\": \"my-framework\",\n \"display_name\": \"My Awesome Framework\",\n \"category\": \"web\",\n \"type\": \"framework\",\n \"version\": \"2.0.0\",\n \"sources\": {\n \"documentation\": {\n \"github\": {\n \"repo\": \"myorg/my-framework\",\n \"docs_path\": \"docs\",\n \"branch\": \"main\"\n },\n \"website\": \"https://myframework.dev/docs\"\n },\n \"examples\": {\n \"github\": {\n \"repo\": \"myorg/my-framework-examples\",\n \"docs_path\": \"examples\",\n \"branch\": \"main\"\n }\n }\n },\n \"context_files\": [\"README.md\", \"GUIDE.md\"],\n \"key_features\": [\"fast\", \"modern\", \"typescript\"],\n \"common_patterns\": [\"component-based\", \"declarative\"],\n \"priority\": 60\n}\n```\n\n### **3. Configuration Fields**\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `name` | string | \u2705 | Unique framework identifier |\n| `display_name` | string | \u2705 | Human-readable name |\n| `category` | string | \u2705 | Framework category |\n| `type` | string | \u2705 | Framework type |\n| `version` | string | \u274c | Version (default: \"latest\") |\n| `sources` | object | \u2705 | Documentation sources |\n| `context_files` | array | \u2705 | Important files to include |\n| `key_features` | array | \u2705 | Main features/capabilities |\n| `common_patterns` | array | \u2705 | Usage patterns |\n| `priority` | number | \u274c | Importance (1-100, default: 50) |\n\nThe server automatically detects new framework configurations and hot-reloads them without restart.\n\n## \ud83e\uddea Development\n\n### **Running Tests**\n\n```bash\n# Run all tests\nuv run pytest\n\n# Run specific test categories\nuv run pytest tests/test_models.py -v\nuv run pytest tests/test_cache.py -v\nuv run pytest tests/test_tools.py -v\n\n# Run with coverage\nuv run pytest --cov=src/augments_mcp --cov-report=html\n```\n\n### **Code Quality**\n\n```bash\n# Format code\nuv run black src tests\n\n# Lint code \nuv run ruff check src tests\n\n# Type checking\nuv run mypy src\n\n# Run all quality checks\nuv run black src tests && uv run ruff check src tests && uv run mypy src\n```\n\n### **Development Server**\n\n```bash\n# Run with auto-reload for development\nuv run fastmcp dev src/augments_mcp/server.py\n\n# Run with debug logging\nLOG_LEVEL=DEBUG uv run augments-mcp-server\n```\n\n## \ud83c\udfdb\ufe0f Technical Details\n\n### **Core Technologies**\n- **FastMCP**: Official MCP Python SDK with streamable-http transport\n- **Pydantic**: Data validation and serialization \n- **httpx**: Async HTTP client for API requests\n- **BeautifulSoup4**: HTML parsing for web scraping\n- **diskcache**: Persistent caching with TTL support\n- **structlog**: Structured logging for observability\n- **watchdog**: File system monitoring for hot-reload\n\n### **MCP Protocol Implementation**\n- **Transport**: Streamable-HTTP (official MCP specification)\n- **Endpoint**: `/mcp` (automatically mounted by FastMCP)\n- **Protocol Version**: MCP 2024-11-05 specification\n- **Client Compatibility**: Claude Code, Cursor, and all MCP-compliant clients\n- **Message Format**: JSON-RPC over HTTP with streaming support\n- **Security**: HTTPS/TLS encryption for hosted deployment\n\n### **Design Principles**\n- **Async-First**: All I/O operations use async/await\n- **Type Safety**: Comprehensive type hints throughout\n- **Error Resilience**: Graceful degradation with detailed errors\n- **Performance**: Multi-level caching and efficient data structures\n- **Extensibility**: Plugin-based architecture for new providers\n- **Observability**: Structured logging and comprehensive metrics\n\n### **Caching Strategy**\n- **Memory Cache**: Fast access for recently used data\n- **Disk Cache**: Persistent storage with TTL expiration\n- **TTL Strategies**: Different durations based on content stability\n - Stable releases: 24 hours\n - Beta versions: 6 hours \n - Development branches: 1 hour\n- **Smart Invalidation**: Automatic refresh based on source updates\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! Please follow these steps:\n\n1. **Fork the repository**\n2. **Create a feature branch**: `git checkout -b feature/amazing-feature`\n3. **Add comprehensive tests** for new functionality\n4. **Ensure code quality**: Run formatters and linters\n5. **Update documentation** for new features\n6. **Submit a pull request** with detailed description\n\n### **Development Setup**\n\n```bash\n# Clone your fork\ngit clone https://github.com/yourusername/augments-mcp-server.git\ncd augments-mcp-server\n\n# Install development dependencies\nuv sync\n\n# Run tests to verify setup\nuv run pytest\n```\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## \ud83c\udd98 Support\n\n- \ud83d\udcd6 **Documentation**: [Model Context Protocol](https://modelcontextprotocol.io)\n- \ud83d\udc1b **Issues**: [GitHub Issues](https://github.com/augmnt/augments-mcp-server/issues)\n- \ud83d\udcac **Discussions**: [GitHub Discussions](https://github.com/augmnt/augments-mcp-server/discussions)\n\n---\n\n**Built with \u2764\ufe0f for the Claude Code ecosystem**\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Augments MCP Server - A comprehensive framework documentation provider for Claude Code",
"version": "2.0.1",
"project_urls": {
"Homepage": "https://augments.dev",
"Issues": "https://github.com/augmnt/augments-mcp-server/issues",
"Repository": "https://github.com/augmnt/augments-mcp-server"
},
"split_keywords": [
"mcp",
" claude",
" documentation",
" framework",
" ai",
" development-tools"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c7f90f473f360d64371cf144092194be9680c27de8331e8940802e8b77b80ae1",
"md5": "f22b3549dc702c08b1d87158ce209e46",
"sha256": "884f9ca699bf10ad221925fce7dc05d376626d45e2127c26f59308e66cf1728b"
},
"downloads": -1,
"filename": "augments_mcp_server-2.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f22b3549dc702c08b1d87158ce209e46",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 106994,
"upload_time": "2025-09-13T18:30:14",
"upload_time_iso_8601": "2025-09-13T18:30:14.106405Z",
"url": "https://files.pythonhosted.org/packages/c7/f9/0f473f360d64371cf144092194be9680c27de8331e8940802e8b77b80ae1/augments_mcp_server-2.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "1a3971b991d53b5670b416cfb17695779b8a5244b680aca2e574a463eb91aeac",
"md5": "90ee15a90772ed285e34e0917aae3ee3",
"sha256": "da62e107bc8f5ef5db209e0b557182d3884ad22d070b29c7053c3bb8fc3a8dd5"
},
"downloads": -1,
"filename": "augments_mcp_server-2.0.1.tar.gz",
"has_sig": false,
"md5_digest": "90ee15a90772ed285e34e0917aae3ee3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 99880,
"upload_time": "2025-09-13T18:30:15",
"upload_time_iso_8601": "2025-09-13T18:30:15.550503Z",
"url": "https://files.pythonhosted.org/packages/1a/39/71b991d53b5670b416cfb17695779b8a5244b680aca2e574a463eb91aeac/augments_mcp_server-2.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-13 18:30:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "augmnt",
"github_project": "augments-mcp-server",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "augments-mcp-server"
}
JSON
