dev.augments/mcp

Install

Config snippet generator goes here (5 client tabs)

README

![Augments MCP Server](https://raw.githubusercontent.com/augmnt/augments-mcp-server/main/banner.png)

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.

mcp-name: dev.augments/mcp

## What's New in v7

**Version 7.0** is the biggest upgrade yet — documentation-first search, 4 new tools, BM25 indexing, and production-grade reliability.

| v6 | v7 |
|----|-----|
| 3 tools | 8 tools (+ diagnostics) |
| Types-only search | Documentation-first BM25 search |
| 8 concept synonyms | 25 concept synonym clusters |
| Generic version diffs | Real changelog-backed breaking changes |
| No migration guides | Cross-version migration guides |
| No error diagnosis | Curated error patterns + GitHub Issues |
| No package comparison | Side-by-side package comparison |
| No dep scanning | Dependency scanner (outdated/deprecated/security) |
| FIFO caches | LRU caches with hit/miss stats |
| Fixed retry delays | Exponential backoff + circuit breaker |

## Quick Start

### Claude Code

```bash
# 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:

```json
{
  "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:

```json
{
  "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
```

## Tools

| Tool | Description |
|------|-------------|
| `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. |
| `search_apis` | Search for APIs across frameworks by keyword or concept. 25 synonym clusters ("state" matches useState, createStore, atom, etc). |
| `get_version_info` | Get npm version info, compare versions, and detect breaking changes backed by real changelogs. |
| `get_migration_guide` | **New.** Cross-version migration guide with breaking changes, new features, deprecations, type diffs, and official migration docs. |
| `diagnose_error` | **New.** Diagnose errors using curated patterns, GitHub Issues search, and troubleshooting docs. |
| `compare_packages` | **New.** Compare 2-5 npm packages: downloads, bundle size, GitHub stars, dependencies, exported APIs. |
| `scan_project_deps` | **New.** Scan package.json for outdated, deprecated, and insecure dependencies. |
| `diagnostics` | Server health: version, uptime, memory, cache stats, Node.js version. |

## Architecture

```mermaid
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
```

### Source Structure

```
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 exam