Skip to content
Back to search

augments-mcp-server

Comprehensive MCP server providing real-time framework documentation access for Claude Code with intelligent caching, multi-source integration, and context-aware assistance.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/augmnt--augments-mcp-server/badge.svg)](/listings/augmnt--augments-mcp-server)

HTML

<a href="/listings/augmnt--augments-mcp-server"><img src="/api/listings/augmnt--augments-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

Add to your MCP config:

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

Environment Variables

Set `GITHUB_TOKEN` for higher GitHub API rate limits when fetching examples and documentation:

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

Usage

# 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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 261 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ![Augments MCP Server](https://raw.githubusercontent.com/augmnt/augments-mcp-server/main/banner.png)
  2. A next-generation framework documentation provider for Claude Code via Model Context Protocol (MCP). Returns **types + prose + examples** with context-aware formatting for **any** npm package — not just curated ones.
  3. mcp-name: dev.augments/mcp
  4. ## What's New in v7
  5. **Version 7.0** is the biggest upgrade yet — documentation-first search, 4 new tools, BM25 indexing, and production-grade reliability.
  6. | v6 | v7 |
  7. |----|-----|
  8. | 3 tools | 8 tools (+ diagnostics) |
  9. | Types-only search | Documentation-first BM25 search |
  10. | 8 concept synonyms | 25 concept synonym clusters |
  11. | Generic version diffs | Real changelog-backed breaking changes |
  12. | No migration guides | Cross-version migration guides |
  13. | No error diagnosis | Curated error patterns + GitHub Issues |
  14. | No package comparison | Side-by-side package comparison |
  15. | No dep scanning | Dependency scanner (outdated/deprecated/security) |
  16. | FIFO caches | LRU caches with hit/miss stats |
  17. | Fixed retry delays | Exponential backoff + circuit breaker |
  18. ## Quick Start
  19. ### Claude Code
  20. ```bash
  21. # Add the MCP server (runs locally via npx)
  22. claude mcp add -s user augments -- npx -y @augmnt-sh/augments-mcp-server
  23. # Verify configuration
  24. claude mcp list
  25. ```
  26. ### Cursor
  27. Add to your MCP config:
  28. ```json
  29. {
  30. "mcpServers": {
  31. "augments": {
  32. "command": "npx",
  33. "args": ["-y", "@augmnt-sh/augments-mcp-server"]
  34. }
  35. }
  36. }
  37. ```
  38. ### Environment Variables
  39. Set `GITHUB_TOKEN` for higher GitHub API rate limits when fetching examples and documentation:
  40. ```json
  41. {
  42. "mcpServers": {
  43. "augments": {
  44. "command": "npx",
  45. "args": ["-y", "@augmnt-sh/augments-mcp-server"],
  46. "env": {
  47. "GITHUB_TOKEN": "ghp_your_token_here"
  48. }
  49. }
  50. }
  51. }
  52. ```
  53. ### Usage
  54. ```
  55. # Get API context with prose + examples (recommended first tool)
  56. @augments get_api_context query="useEffect cleanup" framework="react"
  57. # Natural language queries work great
  58. @augments get_api_context query="how to use zustand middleware"
  59. # Search for APIs by concept (synonym-aware)
  60. @augments search_apis query="state management"
  61. # Get version info with real breaking changes
  62. @augments get_version_info framework="react" fromVersion="18" toVersion="19"
  63. # Migration guide between versions
  64. @augments get_migration_guide package="next" fromVersion="14" toVersion="15"
  65. # Diagnose an error
  66. @augments diagnose_error error="Objects are not valid as a React child" package="react"
  67. # Compare packages side-by-side
  68. @augments compare_packages packages=["zod", "yup", "joi"]
  69. # Scan project dependencies
  70. @augments scan_project_deps
  71. ```
  72. ## Tools
  73. | Tool | Description |
  74. |------|-------------|
  75. | `get_api_context` | **Primary tool.** Returns API signatures, prose documentation, and code examples for any npm package. Handles natural language queries with intent detection. Now with documentation-first BM25 search. |
  76. | `search_apis` | Search for APIs across frameworks by keyword or concept. 25 synonym clusters ("state" matches useState, createStore, atom, etc). |
  77. | `get_version_info` | Get npm version info, compare versions, and detect breaking changes backed by real changelogs. |
  78. | `get_migration_guide` | **New.** Cross-version migration guide with breaking changes, new features, deprecations, type diffs, and official migration docs. |
  79. | `diagnose_error` | **New.** Diagnose errors using curated patterns, GitHub Issues search, and troubleshooting docs. |
  80. | `compare_packages` | **New.** Compare 2-5 npm packages: downloads, bundle size, GitHub stars, dependencies, exported APIs. |
  81. | `scan_project_deps` | **New.** Scan package.json for outdated, deprecated, and insecure dependencies. |
  82. | `diagnostics` | Server health: version, uptime, memory, cache stats, Node.js version. |
  83. ## Architecture
  84. ```mermaid
  85. flowchart TD
  86. A["Query: 'how to use useEffect cleanup'"] --> B
  87. B["Intent Detection → howto<br/>Query Parser → react / useEffect"]
  88. B --> C["Type Fetcher<br/>CDN racing · npm metadata · @types"]
  89. B --> D["Doc Fetcher<br/>GitHub API · BM25 search · 25 synonym clusters"]
  90. B --> E["Example Extractor<br/>GitHub docs · README fallback · Auto-discovery"]
  91. C --> F["Type Parser<br/>Signatures · Parameters · Related types"]
  92. D --> G["Doc Search Engine<br/>BM25 indexing · Heading-based chunks · API boost"]
  93. F --> H["Intent-Driven Formatter (howto)<br/>→ Examples first, prose, brief signature<br/>→ ~500-2000 tokens, 10KB max"]
  94. G --> H
  95. E --> H
  96. ```
  97. ### Source Structure
  98. ```
  99. src/
  100. ├── cli.ts # stdio entry point
  101. ├── server.ts # MCP server (8 tools + diagnostics)
  102. ├── core/ # Core modules
  103. │ ├── query-parser.ts # Parse natural language → framework + concept
  104. │ ├── type-fetcher.ts # Fetch .d.ts + README from npm/unpkg/jsdelivr
  105. │ ├── type-parser.ts # Parse TypeScript, extract signatures, synonym search
  106. │ ├── example-extractor.ts # Fetch examples from GitHub docs + auto-discovery
  107. │ ├── version-registry.ts # npm registry integration + changelog-backed diffs
  108. │ ├── doc-fetcher.ts # GitHub documentation fetcher
  109. │ ├── doc-search.ts # BM25 inverted index search engine
  110. │ ├── changelog-fetcher.ts # CHANGELOG.md + GitHub Releases parser
  111. │ ├── type-differ.ts # .d.ts diff between versions
  112. │ └── error-patterns.ts # Curated error pattern database
  113. ├── tools/v4/ # MCP tools
  114. │ ├── get-api-context.ts # Primary tool (types + docs + examples)
  115. │ ├── search-apis.ts # Cross-framework API search
  116. │ ├── get-version-info.ts # Version comparison
  117. │ ├── get-migration-guide.ts # Cross-version migration guides
  118. │ ├── diagnose-error.ts # Error diagnosis
  119. │ ├── compare-packages.ts # Package comparison
  120. │ └── scan-project-deps.ts # Dependency scanner
  121. └── utils/
  122. ├── logger.ts # stderr logger
  123. └── lru-cache.ts # Generic LRU cache with stats
  124. ```
  125. ## Key Features
  126. ### Documentation-First Search (New in v7)
  127. Queries like "prisma findMany with pagination" and "zustand create store with middleware" now return real documentation content. The BM25 search engine indexes docs fetched from GitHub by heading-based chunks, with API name boosting and synonym expansion.
  128. ### Concept Synonyms
  129. 25 synonym clusters cover state, form, fetch, animation, routing, auth, cache, effect, middleware, pagination, validation, testing, streaming, error handling, database, layout, modal, table, upload, realtime, deployment, i18n, SSR, component, and context patterns. Bidirectional lookup means "usestate" expands to the "state" cluster.
  130. ### Intent-Aware Formatting
  131. | Intent | Trigger | Format |
  132. |--------|---------|--------|
  133. | `howto` | "how to", "example of", "guide" | Examples → prose → brief signature |
  134. | `reference` | "signature", "types", "parameters" | Full signature → related types → 1 example |
  135. | `migration` | "migrate", "upgrade", "breaking" | Prose → signature → examples |
  136. | `balanced` | Default | Signature → prose → examples |
  137. ### Production Reliability (New in v7)
  138. - **Exponential backoff with jitter** for npm registry retries, with 429 Retry-After support
  139. - **CDN circuit breaker** — skips repeatedly failing CDN endpoints (3 failures / 5 min)
  140. - **GitHub rate limiting** — tracks remaining quota, skips fetches when exhausted
  141. - **LRU caches** with hit/miss statistics across all cache-using modules
  142. ## Coverage
  143. ### Any npm Package
  144. Every npm package is supported out of the box — no curation or configuration needed. Augments resolves documentation automatically through four layers:
  145. 1. **Documentation search** — fetches real docs from GitHub repos, indexes with BM25
  146. 2. **TypeScript types** — bundled (`"types"` in package.json) or DefinitelyTyped (`@types/*`)
  147. 3. **Auto-discovered docs** — parses the npm `repository` field, finds the GitHub repo, probes `docs/` directories
  148. 4. **README fallback** — extracts concept-relevant code blocks and prose from `README.md`
  149. This means augments works with the entire npm ecosystem (~2.5M packages), not just a curated subset.
  150. ### Enhanced Results for Popular Frameworks
  151. 22 frameworks have curated doc sources for richer examples: 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
  152. ### Barrel Export Handling
  153. Special sub-module resolution for: React Hook Form, TanStack Query, Zustand, Jotai, tRPC, Drizzle ORM, Next.js
  154. ## Local Development
  155. ```bash
  156. # Clone and install
  157. git clone https://github.com/augmentscode/augments-mcp-server.git
  158. cd augments-mcp-server
  159. npm install
  160. # Build with tsup
  161. npm run build
  162. # Run locally
  163. npm start
  164. # Watch mode
  165. npm run dev
  166. # Run tests
  167. npm test
  168. # Run e2e tests (real network calls)
  169. npm run test:e2e
  170. # Type check
  171. npm run type-check
  172. ```
  173. ## How Augments Compares to Context7
  174. | Aspect | Context7 | Augments v7 |
  175. |--------|----------|-------------|
  176. | **Source** | Parsed prose docs | Types + BM25-indexed docs + README |
  177. | **Accuracy** | Docs can be wrong | Types must be correct, docs supplement |
  178. | **Context size** | ~5-10KB chunks | ~500-2000 tokens (intent-aware) |
  179. | **Coverage** | Manual submission | Any npm package (auto-discovery) |
  180. | **Format** | One-size-fits-all | Intent-aware (how-to vs reference) |
  181. | **Search** | Keyword match | BM25 + 25 concept synonym clusters |
  182. | **Freshness** | Crawl schedule | On-demand from npm + GitHub |
  183. | **Migration** | No | Cross-version migration guides |
  184. | **Error help** | No | Curated patterns + GitHub Issues |
  185. | **Dep scanning** | No | Outdated/deprecated/security checks |
  186. ## Contributing
  187. 1. Fork the repository
  188. 2. Create a feature branch: `git checkout -b feature/amazing-feature`
  189. 3. Make your changes
  190. 4. Run tests: `npm test`
  191. 5. Submit a pull request
  192. ## License
  193. MIT License - see [LICENSE](LICENSE) for details.
  194. ## Support
  195. - [GitHub Issues](https://github.com/augmentscode/augments-mcp-server/issues)
  196. - [GitHub Discussions](https://github.com/augmentscode/augments-mcp-server/discussions)
  197. ---
  198. **Built for the Claude Code ecosystem** | **Version 7.0.0**

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.