augmnt/augments-mcp-server

What's New

Closes the doc search relevance gap — multi-word queries like "zustand middleware persist" now correctly match the right documentation sections.

Improved

• Multi-word concept decomposition — file matching scores each word independently (e.g., "persist" matches even when "persistmiddleware" doesn't)
• BM25 heading boost — heading tokens weighted 2x in term frequency, plus 1–1.5x post-scoring multiplier for heading matches
• Synonym expansion in doc search — bidirectional synonym maps (e.g., "store" ↔ "state", "middleware" ↔ "plugin") improve recall
• Per-part scoring in matchConceptToFiles — 60/40/20 point tiers with all-parts bonus and path-depth preference

Fixed

• zustand middleware persist now returns persist middleware docs (was incorrectly returning immer)
• Section ranking improved for queries where relevant content appears in headings

Upgrade

claude mcp add -s user augments -- npx -y @augmnt-sh/augments-mcp-server@latest

What's New

Complete architecture overhaul — augments now searches official documentation alongside TypeScript types, delivering prose explanations, code examples, and API signatures in a single call.

Added

• Documentation search engine — BM25 inverted index over official docs (README, guides, API references)
• 4 new tools: get-api-context (unified entry point), search-apis, get-migration-guide, diagnose-error
• Multi-CDN type fetching — races esm.sh, unpkg, and jsdelivr with circuit breakers
• Exponential backoff + jitter for npm registry retries
• GitHub rate-limit awareness — reads X-RateLimit-Remaining/Reset headers
• Comprehensive test suite — 295 tests across 10 files

Changed

• compare-packages now includes doc search results alongside type diffs
• scan-project-deps returns richer per-dependency context
• Build output optimized: 79KB chunked + 36KB CLI

Upgrade

claude mcp add -s user augments -- npx -y @augmnt-sh/augments-mcp-server@latest

Local stdio MCP server — published on npm

Augments is now a local stdio MCP server distributed via npm. No more Vercel hosting dependency — everything runs on your machine.

Install

claude mcp add augments -- npx -y @augmnt-sh/augments-mcp-server

What changed

• Local stdio transport — replaced Vercel HTTP with StdioServerTransport, eliminating network round-trips
• Published on npm as @augmnt-sh/augments-mcp-server
• tsup bundler — replaced Next.js build with a lightweight ESM bundle
• Logger writes to stderr — all log output uses process.stderr.write() to keep the JSON-RPC stream on stdout clean
• typescript moved to prod dependencies — required at runtime by type-parser.ts

Removed

• Next.js runtime (next, react, react-dom)
• Vercel deployment files (vercel.json, next.config.mjs)
• HTTP transport layer and web UI

Fixes

• Natural language query parsing — queries like "how does useEffect work?" now correctly extract the API name instead of returning noise words. Expanded stop words, scan all tokens for API patterns, and broadened intent detection regex.
• MCP transport binding — create fresh McpServer per request to fix transport binding issues.
• Mermaid diagrams — use <br/> for line breaks.

Other

• Minimal install page for mcp.augments.dev
• README updates and dead code cleanup

What's New

v5 closes 5 structural gaps vs context7, delivering types + prose + examples with context-aware formatting for any npm package.

Prose Documentation

Extracts relevant prose from README/docs alongside type signatures. Section scoring finds the most concept-relevant content (2000 char budget).

README Fallback

For the 99%+ of npm packages without curated documentation sources, augments now fetches README.md from CDN and extracts concept-relevant code blocks and prose.

Concept Synonym Search

"state management" now matches useState, createStore, atom, signal, ref, and more via 8 concept clusters (state, form, fetch, animation, routing, auth, cache, effect).

Auto-Discovery of Doc Sources

Parses npm repository field → probes GitHub for docs/, documentation/, doc/, README.md. No manual curation needed.

Intent-Aware Formatting

Detects query intent and assembles response sections in optimal order:

| Intent | Trigger | Format |
|--------|---------|--------|
| howto | "how to", "example of", "guide" | Examples → prose → brief signature |
| reference | "signature", "types", "parameters" | Full signature → related types → 1 example |
| migration | "migrate", "upgrade", "breaking" | Prose → signature → examples |
| balanced | Default | Signature → prose → examples |

Cleanup

• Removed ~5,200 lines of legacy v3 code (16 files deleted)
• Consolidated from 7 tools to 3 focused tools
• Removed unused dependencies: @octokit/rest, jsdom, turndown, @upstash/ratelimit, @upstash/redis

Breaking Changes

• Legacy v3 tools removed (previously gated behind LEGACY_TOOLS_ENABLED=true)
• Tool count reduced from 7 → 3 (get_api_context, search_apis, get_version_info)
• GetApiContextOutput now includes prose: string | null and intent: QueryIntent fields
• Removed dependencies: @octokit/rest, jsdom, turndown, @upstash/ratelimit, @upstash/redis

Stats

• Net change: -4,738 lines (773 added, 5,511 deleted)
• Tests: 198 passing across 7 test files
• Source files: 17 (down from 33)

Full Changelog: https://github.com/augmnt/augments-mcp-server/compare/v4.1.0...v5.0.0