augments-mcp-server

通过 Model Context Protocol（MCP）为 Claude Code 提供的新一代框架文档服务。针对任何 npm 包返回类型 + 说明文字 + 示例，并根据上下文调整格式，而不仅限于精选包。

mcp-name: dev.augments/mcp

v7 新特性

Version 7.0 是迄今为止最大的一次升级——文档优先搜索、4 个新工具、BM25 索引，以及生产级可靠性。

v6	v7
3 个工具	8 个工具（+ 诊断）
仅搜索类型	文档优先的 BM25 搜索
8 个概念同义词	25 组概念同义词
通用版本差异	基于真实更新日志的破坏性变更
无迁移指南	跨版本迁移指南
无错误诊断	精选错误模式 + GitHub Issues
无包比较	并排比较包
无依赖扫描	依赖扫描器（过时／已弃用／安全问题）
FIFO 缓存	带命中／未命中统计的 LRU 缓存
固定重试间隔	指数退避 + 熔断器

快速开始

Claude Code

# Add the MCP server (runs locally via npx)
claude mcp add -s user augments -- npx -y @augmnt-sh/augments-mcp-server

# Verify configuration
claude mcp list

Cursor

添加到 MCP 配置中：

{
  "mcpServers": {
    "augments": {
      "command": "npx",
      "args": ["-y", "@augmnt-sh/augments-mcp-server"]
    }
  }
}

环境变量

设置 GITHUB_TOKEN，以便在获取示例和文档时提高 GitHub API 速率限制：

{
  "mcpServers": {
    "augments": {
      "command": "npx",
      "args": ["-y", "@augmnt-sh/augments-mcp-server"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

用法

# Get API context with prose + examples (recommended first tool)
@augments get_api_context query="useEffect cleanup" framework="react"

# Natural language queries work great
@augments get_api_context query="how to use zustand middleware"

# Search for APIs by concept (synonym-aware)
@augments search_apis query="state management"

# Get version info with real breaking changes
@augments get_version_info framework="react" fromVersion="18" toVersion="19"

# Migration guide between versions
@augments get_migration_guide package="next" fromVersion="14" toVersion="15"

# Diagnose an error
@augments diagnose_error error="Objects are not valid as a React child" package="react"

# Compare packages side-by-side
@augments compare_packages packages=["zod", "yup", "joi"]

# Scan project dependencies
@augments scan_project_deps

工具

工具	描述
get_api_context	主要工具。 为任何 npm 包返回 API 签名、文档说明和代码示例。支持通过意图检测处理自然语言查询。现已支持文档优先的 BM25 搜索。
search_apis	按关键词或概念搜索各框架中的 API。包含 25 组同义词（“state”可匹配 useState、createStore、atom 等）。
get_version_info	获取 npm 版本信息、比较版本，并检测基于真实更新日志的破坏性变更。
get_migration_guide	新增。 跨版本迁移指南，包含破坏性变更、新功能、弃用内容、类型差异和官方迁移文档。
diagnose_error	新增。 使用精选错误模式、GitHub Issues 搜索和故障排除文档诊断错误。
compare_packages	新增。 比较 2-5 个 npm 包：下载量、包体积、GitHub 星标数、依赖项、导出的 API。
scan_project_deps	新增。 扫描 package.json，查找过时、已弃用和不安全的依赖项。
diagnostics	服务健康状况：版本、运行时间、内存、缓存统计、Node.js 版本。

架构

flowchart TD
    A["Query: 'how to use useEffect cleanup'"] --> B

    B["Intent Detection → howto<br/>Query Parser → react / useEffect"]

    B --> C["Type Fetcher<br/>CDN racing · npm metadata · @types"]
    B --> D["Doc Fetcher<br/>GitHub API · BM25 search · 25 synonym clusters"]
    B --> E["Example Extractor<br/>GitHub docs · README fallback · Auto-discovery"]

    C --> F["Type Parser<br/>Signatures · Parameters · Related types"]
    D --> G["Doc Search Engine<br/>BM25 indexing · Heading-based chunks · API boost"]

    F --> H["Intent-Driven Formatter (howto)<br/>→ Examples first, prose, brief signature<br/>→ ~500-2000 tokens, 10KB max"]
    G --> H
    E --> H

源代码结构

src/
├── cli.ts                   # stdio entry point
├── server.ts                # MCP server (8 tools + diagnostics)
├── core/                    # Core modules
│   ├── query-parser.ts      # Parse natural language → framework + concept
│   ├── type-fetcher.ts      # Fetch .d.ts + README from npm/unpkg/jsdelivr
│   ├── type-parser.ts       # Parse TypeScript, extract signatures, synonym search
│   ├── example-extractor.ts # Fetch examples from GitHub docs + auto-discovery
│   ├── version-registry.ts  # npm registry integration + changelog-backed diffs
│   ├── doc-fetcher.ts       # GitHub documentation fetcher
│   ├── doc-search.ts        # BM25 inverted index search engine
│   ├── changelog-fetcher.ts # CHANGELOG.md + GitHub Releases parser
│   ├── type-differ.ts       # .d.ts diff between versions
│   └── error-patterns.ts    # Curated error pattern database
├── tools/v4/                # MCP tools
│   ├── get-api-context.ts   # Primary tool (types + docs + examples)
│   ├── search-apis.ts       # Cross-framework API search
│   ├── get-version-info.ts  # Version comparison
│   ├── get-migration-guide.ts # Cross-version migration guides
│   ├── diagnose-error.ts    # Error diagnosis
│   ├── compare-packages.ts  # Package comparison
│   └── scan-project-deps.ts # Dependency scanner
└── utils/
    ├── logger.ts            # stderr logger
    └── lru-cache.ts         # Generic LRU cache with stats

主要功能

文档优先搜索（v7 新增）

现在，诸如“prisma findMany with pagination”和“zustand create store with middleware”这样的查询会返回真实文档内容。BM25 搜索引擎会将从 GitHub 获取的文档按标题分块建立索引，并结合 API 名称加权和同义词扩展。

概念同义词

25 组同义词涵盖状态、表单、获取数据、动画、路由、身份验证、缓存、副作用、中间件、分页、验证、测试、流式处理、错误处理、数据库、布局、模态框、表格、上传、实时功能、部署、i18n、SSR、组件和上下文模式。双向查找意味着“usestate”会扩展到“state”同义词组。

意图感知格式

意图	触发词	格式
howto	“how to”、“example of”、“guide”	示例 → 文档说明 → 简要签名
reference	“signature”、“types”、“parameters”	完整签名 → 相关类型 → 1 个示例
migration	“migrate”、“upgrade”、“breaking”	文档说明 → 签名 → 示例
balanced	默认	签名 → 文档说明 → 示例

生产可靠性（v7 新增）

• 带抖动的指数退避，用于 npm registry 重试，并支持 429 Retry-After
• CDN 熔断器——跳过反复失败的 CDN 端点（3 次失败 / 5 分钟）
• GitHub 速率限制——跟踪剩余配额，配额耗尽时跳过获取
• LRU 缓存，所有使用缓存的模块均提供命中 / 未命中统计信息

覆盖范围

任意 npm 包

开箱即支持每个 npm 包——无需整理或配置。Augments 通过四个层级自动解析文档：

1. 文档搜索——从 GitHub 仓库获取真实文档，并使用 BM25 建立索引
2. TypeScript 类型——打包在包中（package.json 中的 "types"），或来自 DefinitelyTyped（@types/*）
3. 自动发现文档——解析 npm repository 字段，查找 GitHub 仓库，并探测 docs/ 目录
4. README 回退——从 README.md 中提取与概念相关的代码块和正文

这意味着 augments 可用于整个 npm 生态系统（约 250 万个包），而不仅是经过整理的子集。

为热门框架提供增强结果

22 个框架提供了整理好的文档来源，可提供更丰富的示例：React、Next.js、Vue、Prisma、Zod、Supabase、TanStack Query、tRPC、React Hook Form、Framer Motion、Express、Zustand、Jotai、Drizzle、SWR、Vitest、Playwright、Fastify、Hono、Solid、Svelte、Angular、Redux

Barrel 导出处理

为以下工具提供特殊的子模块解析：React Hook Form、TanStack Query、Zustand、Jotai、tRPC、Drizzle ORM、Next.js

本地开发

# Clone and install
git clone https://github.com/augmentscode/augments-mcp-server.git
cd augments-mcp-server
npm install

# Build with tsup
npm run build

# Run locally
npm start

# Watch mode
npm run dev

# Run tests
npm test

# Run e2e tests (real network calls)
npm run test:e2e

# Type check
npm run type-check

Augments 与 Context7 的比较

方面	Context7	Augments v7
来源	解析后的正文文档	类型 + BM25 索引文档 + README
准确性	文档可能有误	类型必须正确，文档作为补充
上下文大小	约 5-10KB 的片段	约 500-2000 个 token（感知意图）
覆盖范围	手动提交	任意 npm 包（自动发现）
格式	一刀切	感知意图（操作指南与参考资料）
搜索	关键词匹配	BM25 + 25 个概念同义词簇
新鲜度	爬取计划	按需从 npm + GitHub 获取
迁移	不支持	跨版本迁移指南
错误帮助	不支持	整理好的模式 + GitHub Issues
依赖扫描	不支持	过时 / 已弃用 / 安全检查

参与贡献

1. Fork 此仓库
2. 创建功能分支：git checkout -b feature/amazing-feature
3. 进行更改
4. 运行测试：npm test
5. 提交 pull request

许可证

MIT License——详情请参阅 LICENSE。

支持

• GitHub Issues
• GitHub Discussions

---

为 Claude Code 生态系统打造 | 版本 7.0.0