augments-mcp-server

🚀 Augments MCP Server

Augments MCP Server 是一个通过模型上下文协议（MCP）为 Claude Code 提供全面框架文档的系统。它能实时访问框架文档，提供上下文感知辅助和智能缓存，以优化开发流程。

🚀 快速开始

Augments MCP Server 是一个复杂的文档检索系统，它与 Claude Code 集成，提供全面、最新的框架信息。它具有先进的缓存策略、多源文档聚合和智能上下文增强功能，适用于现代开发工作流程。

✨ 主要特性

🎯 全面的框架支持

• 分类框架注册表：涵盖 Web、后端、移动、人工智能/机器学习、设计和工具等类别。
• 多源文档：包括 GitHub 仓库、官方网站和示例。
• 热重载配置：无需重启服务器即可动态更新框架。
• 智能优先级排序：根据框架重要性进行排名。

⚡ 高级缓存系统

• 基于 TTL 的策略：为稳定版、测试版和开发版设置不同的缓存时长。
• 多级缓存：内存和磁盘持久化，以实现最佳性能。
• 智能失效机制：根据源更新自动刷新缓存。
• 缓存分析：提供详细的统计信息和性能监控。

🧠 上下文增强

• 多框架上下文：整合多个框架的文档。
• 代码兼容性分析：检测框架兼容性问题。
• 模式识别：识别常见使用模式和最佳实践。
• 特定任务指导：根据开发任务提供定制化的上下文。

🔧 开发者体验

• 9 种全面的 MCP 工具：覆盖完整的文档生命周期。
• 结构化响应：提供清晰、经过验证的 JSON 输出。
• 错误恢复能力：优雅降级并提供详细的错误信息。
• 异步性能：全程支持非阻塞操作。

🏗️ 架构

目录结构

src/augments_mcp/
├── registry/                   # 框架注册表管理
│   ├── manager.py             # 热重载注册表管理器
│   ├── models.py              # Pydantic 数据模型
│   └── cache.py               # 高级缓存系统
├── tools/                      # MCP 工具实现
│   ├── framework_discovery.py # 框架搜索和列表
│   ├── documentation.py       # 文档检索
│   ├── context_enhancement.py # 多框架上下文
│   └── updates.py             # 缓存管理和更新
├── providers/                  # 文档源提供者
│   ├── github.py              # GitHub API 集成
│   ├── website.py             # 网页抓取提供者
│   └── base.py                # 提供者接口
├── utils/                      # 共享实用工具
│   ├── github_client.py       # 带速率限制的 GitHub API 客户端
│   └── validation.py          # 数据验证实用工具
└── server.py                  # FastMCP 服务器实现

frameworks/                     # 按类别划分的框架配置
├── web/                       # Web 框架
│   ├── tailwindcss.json
│   ├── react.json
│   └── nextjs.json
├── backend/                   # 后端框架
│   └── fastapi.json
├── design/                    # 设计系统
│   └── shadcn-ui.json
└── ai-ml/                     # 人工智能/机器学习框架
    ├── mcp-sdk-python.json
    └── anthropic-sdk.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
}

🛠️ 安装指南

前提条件

• Python 3.11 或更高版本。
• uv（推荐）或 pip。

安装步骤

# 克隆仓库
git clone <repository-url>
cd augments-mcp-server

# 使用 uv 安装（推荐）
uv sync

# 或者使用 pip 安装
pip install -e .

环境配置

创建一个 .env 文件进行可选配置：

# 缓存设置
AUGMENTS_CACHE_DIR=~/.cache/augments-mcp-server
AUGMENTS_CACHE_TTL=3600

# GitHub API（可选，用于更高的速率限制）
GITHUB_TOKEN=your_github_token_here

# 日志记录
LOG_LEVEL=INFO

💻 使用示例

选项 1：使用托管的 MCP 服务器（推荐）

为了最简便的设置，直接连接到我们托管的 MCP 服务器 https://mcp.augments.dev/mcp。无需安装！

使用 Claude Code CLI

# 添加托管的 MCP 服务器
claude mcp add --transport http augments https://mcp.augments.dev/mcp

# 验证服务器配置
claude mcp list

# 获取服务器详细信息
claude mcp get augments

使用 Cursor

添加到您的 Cursor MCP 配置中：

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

手动配置（Claude 桌面版）

添加到您的 Claude 桌面版 MCP 配置文件中：

位置：

• 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"
      }
    }
  }
}

使用托管服务器

配置完成后，您可以直接访问所有框架文档：

1. 访问框架文档：

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

2. 获取多框架上下文：

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

3. 分析代码兼容性：

   @augments analyze this React component for tailwindcss compatibility:
   [粘贴您的代码]
   

4. 搜索文档：

   @augments search nextjs documentation for "app router"
   

托管服务器提供以下优势：

• ✅ 无需安装 - 立即使用
• ✅ 始终保持最新 - 获取最新的框架文档
• ✅ 高可用性 - 通过智能缓存确保可靠的正常运行时间
• ✅ 无需身份验证 - 完全无摩擦访问
• ✅ 速率限制保护 - 智能防止滥用
• ✅ 符合 MCP 协议 - 使用官方 MCP Python SDK 和可流式传输的 HTTP 传输协议
• ✅ 多客户端支持 - 与 Claude Code、Cursor 和其他 MCP 客户端兼容

选项 2：本地安装

如果您需要进行开发、定制或离线使用，可以在本地运行服务器。

启动本地服务器

# 使用 uv 运行（推荐）
uv run augments-mcp-server

# 或者直接运行
python -m augments_mcp.server

# 开发模式，支持自动重载
uv run fastmcp dev src/augments_mcp/server.py

Claude Code 集成（本地）

方法 1：使用 Claude Code CLI（推荐）

# 使用环境变量添加本地 MCP 服务器
claude mcp add augments-local -e AUGMENTS_CACHE_DIR="~/.cache/augments-mcp-server" -e GITHUB_TOKEN="your_github_token" -- uv run augments-mcp-server

# 验证服务器配置
claude mcp list

# 获取服务器详细信息
claude mcp get augments-local

方法 2：手动配置

{
  "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"
      }
    }
  }
}

方法 3：全局配置

# 添加项目目录的完整路径
claude mcp add augments-local -e GITHUB_TOKEN="your_github_token" -- uv run --directory /path/to/augments-mcp-server augments-mcp-server

服务器管理

# 列出所有配置的 MCP 服务器
claude mcp list

# 获取特定服务器的详细信息
claude mcp get augments

# 如果需要，移除服务器
claude mcp remove augments

# 更新服务器配置（移除并重新添加）
claude mcp remove augments
claude mcp add --transport http augments https://mcp.augments.dev/mcp

故障排除

• 服务器未显示：配置完成后重启 Claude Code。
• 连接错误：对于托管服务器，检查网络连接；对于本地服务器，验证安装情况。
• 环境问题：仅适用于本地安装。
• 权限错误：确保 Claude Code 具有网络访问权限（托管）或文件访问权限（本地）。

🔧 MCP 工具

框架发现

list_available_frameworks

列出所有可用的框架，并可选择按类别进行过滤。

{
  "category": "web"
}

search_frameworks

按名称、特性或关键字搜索框架。

{
  "query": "react component library"
}

get_framework_info

获取特定框架的详细信息。

{
  "framework": "tailwindcss"
}

文档访问

get_framework_docs

检索框架的全面文档。

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

get_framework_examples

获取框架内特定模式的代码示例。

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

search_documentation

在框架的缓存文档中进行搜索。

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

上下文增强

get_framework_context

根据开发任务获取多个框架的相关上下文。

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

analyze_code_compatibility

分析代码与框架的兼容性，并提供改进建议。

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

缓存管理

check_framework_updates

检查框架文档自上次缓存以来是否有更新。

{
  "framework": "nextjs"
}

refresh_framework_cache

刷新框架的缓存文档。

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

get_cache_stats

获取详细的缓存统计信息和性能指标。

{}

📚 支持的框架

涵盖 8 个类别中的 85 多个框架，为现代开发栈提供全面的文档覆盖：

Web 框架（25 个）

• React - 用于构建用户界面的 JavaScript 库。
• Next.js - 用于生产应用的 React 框架。
• Vue.js - 渐进式 JavaScript 框架。
• Angular - 用于构建 Web 应用的平台。
• Svelte - 编译时优化的 Web 框架。
• SvelteKit - 全栈 Svelte 框架。
• Astro - 具有岛屿架构的静态网站生成器。
• Remix - 专注于 Web 基础的全栈 Web 框架。
• Qwik - 可恢复的 Web 框架。
• SolidJS - 响应式 JavaScript 库。
• Preact - 轻量级的 3kB React 替代方案。
• Alpine.js - 用于增强 HTML 的最小框架。
• Lit - 用于构建 Web 组件的简单库。
• Stimulus - 用于 HTML 的 JavaScript 框架。
• HTMX - 具有最少 JavaScript 的现代 HTML。
• Tailwind CSS - 实用优先的 CSS 框架。
• Bootstrap - 用于响应式设计的 CSS 框架。
• Bulma - 基于 Flexbox 的现代 CSS 框架。
• Foundation - 响应式前端框架。
• Material-UI - 实现 Google Material Design 的 React 组件。
• Chakra UI - 简单、模块化且可访问的 React 组件。
• Mantine - 功能齐全的 React 组件库。
• Semantic UI - 用于创建美观、响应式布局的开发框架。
• Three.js - JavaScript 3D 库。
• D3.js - 数据驱动文档库。

后端框架（18 个）

• FastAPI - 现代、快速的 Python Web 框架。
• Django - 高级 Python Web 框架。
• Flask - 轻量级 Python Web 框架。
• Pyramid - Python Web 框架。
• Sanic - 异步 Python Web 服务器/框架。
• Express.js - 快速、无偏见的 Node.js Web 框架。
• Fastify - 快速、低开销的 Node.js Web 框架。
• Koa.js - Node.js 的表达性中间件。
• NestJS - 渐进式 Node.js 框架。
• Laravel - PHP Web 应用框架。
• Ruby on Rails - 服务器端 Web 应用框架。
• Spring Boot - 基于 Java 的框架。
• Actix - Rust Web 框架。
• Axum - 符合人体工程学且模块化的 Rust Web 框架。
• Phoenix - Elixir Web 框架。
• Echo - 高性能 Go Web 框架。
• Gin - Go 的 HTTP Web 框架。
• Fiber - 受 Express 启发的 Go Web 框架。

人工智能/机器学习框架（14 个）

• PyTorch - 机器学习框架。
• TensorFlow - 端到端的机器学习平台。
• Scikit-learn - Python 机器学习库。
• NumPy - 科学计算的基础包。
• Pandas - 数据操作和分析库。
• Matplotlib - Python 绘图库。
• Seaborn - 统计数据可视化库。
• OpenCV - 计算机视觉库。
• Hugging Face - 转换器和数据集库。
• LangChain - 用于开发大语言模型应用的框架。
• Streamlit - 用于机器学习和数据科学的应用框架。
• Gradio - 构建机器学习 Web 应用。
• MCP SDK Python - 模型上下文协议 Python SDK。
• Anthropic SDK - 用于 Anthropic API 的 Python SDK。

移动框架（6 个）

• React Native - 使用 React 构建移动应用。
• Flutter - Google 的移动 UI 工具包。
• Expo - 通用 React 应用平台。
• Ionic - 跨平台移动应用开发框架。
• Capacitor - 跨平台原生运行时。
• Xamarin - Microsoft 的移动开发平台。

数据库与 ORM（5 个）

• Prisma - 下一代 Node.js 和 TypeScript ORM。
• Mongoose - 用于 Node.js 的 MongoDB 对象建模。
• TypeORM - 用于 TypeScript 和 JavaScript 的 ORM。
• SQLAlchemy - Python SQL 工具包和 ORM。
• Sequelize - 基于 Promise 的 Node.js ORM。

状态管理（4 个）

• Redux - 用于 JavaScript 的可预测状态容器。
• Zustand - 小型、快速且可扩展的状态管理库。
• MobX - 响应式状态管理库。
• Recoil - 用于 React 的实验性状态管理库。

测试框架（5 个）

• Jest - JavaScript 测试框架。
• Vitest - 快速的 Vite 原生单元测试框架。
• Cypress - 端到端测试框架。
• Playwright - Web 测试和自动化工具。
• pytest - Python 测试框架。

开发工具（7 个）

• Webpack - 模块打包工具。
• Vite - 快速构建工具。
• Parcel - 零配置构建工具。
• Rollup - JavaScript 模块打包工具。
• ESLint - JavaScript 代码检查工具。
• Prettier - 代码格式化工具。
• Turbo - 高性能构建系统。
• Nx - 智能、快速且可扩展的构建系统。

DevOps 与基础设施（4 个）

• Docker - 容器化平台。
• Kubernetes - 容器编排平台。
• Terraform - 基础设施即代码工具。
• Ansible - 自动化平台。

设计系统（1 个）

• shadcn/ui - 设计精美的 React 组件。

🔄 添加新框架

1. 创建框架配置

在相应的类别目录中创建一个 JSON 文件：

# 对于 Web 框架
frameworks/web/my-framework.json

# 对于后端框架  
frameworks/backend/my-framework.json

2. 框架配置示例

{
  "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. 配置字段说明

| 字段 | 类型 | 是否必需 | 描述 | |------|------|----------|------| | name | 字符串 | ✅ | 唯一的框架标识符 | | display_name | 字符串 | ✅ | 人类可读的名称 | | category | 字符串 | ✅ | 框架类别 | | type | 字符串 | ✅ | 框架类型 | | version | 字符串 | ❌ | 版本（默认："latest"） | | sources | 对象 | ✅ | 文档源 | | context_files | 数组 | ✅ | 重要文件列表 | | key_features | 数组 | ✅ | 主要特性/功能 | | common_patterns | 数组 | ✅ | 使用模式 | | priority | 数字 | ❌ | 重要性（1 - 100，默认：50） |

服务器会自动检测新的框架配置，并在不重启的情况下进行热重载。

🧪 开发

运行测试

# 运行所有测试
uv run pytest

# 运行特定测试类别
uv run pytest tests/test_models.py -v
uv run pytest tests/test_cache.py -v
uv run pytest tests/test_tools.py -v

# 运行测试并生成覆盖率报告
uv run pytest --cov=src/augments_mcp --cov-report=html

代码质量

# 格式化代码
uv run black src tests

# 代码检查
uv run ruff check src tests

# 类型检查
uv run mypy src

# 运行所有质量检查
uv run black src tests && uv run ruff check src tests && uv run mypy src

开发服务器

# 开发模式，支持自动重载
uv run fastmcp dev src/augments_mcp/server.py

# 以调试日志级别运行
LOG_LEVEL=DEBUG uv run augments-mcp-server

🏛️ 技术细节

核心技术

• FastMCP：官方 MCP Python SDK，支持可流式传输的 HTTP 传输协议。
• Pydantic：数据验证和序列化库。
• httpx：用于 API 请求的异步 HTTP 客户端。
• BeautifulSoup4：用于网页抓取的 HTML 解析库。
• diskcache：支持 TTL 的持久化缓存库。
• structlog：用于可观测性的结构化日志库。
• watchdog：用于热重载的文件系统监控库。

MCP 协议实现

• 传输协议：可流式传输的 HTTP（官方 MCP 规范）。
• 端点：/mcp（由 FastMCP 自动挂载）。
• 协议版本：MCP 2024 - 11 - 05 规范。
• 客户端兼容性：Claude Code、Cursor 和所有符合 MCP 标准的客户端。
• 消息格式：支持流式传输的 JSON - RPC over HTTP。
• 安全性：托管部署使用 HTTPS/TLS 加密。

设计原则

• 异步优先：所有 I/O 操作使用 async/await。
• 类型安全：全程使用全面的类型提示。
• 错误恢复能力：优雅降级并提供详细的错误信息。
• 性能优化：多级缓存和高效的数据结构。
• 可扩展性：基于插件的架构，支持新的提供者。
• 可观测性：结构化日志记录和全面的指标监控。

缓存策略

• 内存缓存：快速访问最近使用的数据。
• 磁盘缓存：支持 TTL 过期的持久化存储。
• TTL 策略：根据内容稳定性设置不同的时长。
  • 稳定版：24 小时
  • 测试版：6 小时
  • 开发版：1 小时
• 智能失效机制：根据源更新自动刷新缓存。

🤝 贡献

我们欢迎贡献！请遵循以下步骤：

1. fork 仓库
2. 创建功能分支：git checkout -b feature/amazing-feature
3. 为新功能添加全面的测试
4. 确保代码质量：运行格式化工具和代码检查工具。
5. 更新文档：为新功能更新文档。
6. 提交拉取请求：并提供详细的描述。

开发设置

# 克隆您的 fork
git clone https://github.com/yourusername/augments-mcp-server.git
cd augments-mcp-server

# 安装开发依赖
uv sync

# 运行测试以验证设置
uv run pytest

📄 许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。

🆘 支持

• 📖 文档：Model Context Protocol
• 🐛 问题反馈：GitHub Issues
• 💬 讨论：GitHub Discussions

为 Claude Code 生态系统精心打造 ❤️