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 生態系統精心打造 ❤️