augmnt/augments-mcp-server releases

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

What's New

Query-Focused Context Extraction

New v4 architecture that fetches TypeScript definitions directly from npm packages, providing:

• Accuracy: Types are compiled and must be correct
• Minimal context: ~500-2000 tokens vs 50KB of docs
• Zero LLM cost: Just data retrieval, the calling LLM uses the structured data
• Version-specific: Can query specific package versions
• Universal coverage: Any npm package with types can be queried

New MCP Tools

• get_api_context - Primary tool for query-focused context extraction
• search_apis - Discovery tool for searching APIs across frameworks
• get_version_info - Version information with breaking change detection

Extended Framework Support

Added Supabase, React Hook Form, Framer Motion, Firebase, styled-components, Emotion, and more. Now supporting 92 frameworks across 10 categories.

New Core Modules

• src/core/type-fetcher.ts - Fetches .d.ts files from npm packages
• src/core/type-parser.ts - Extracts API signatures using TypeScript compiler API
• src/core/query-parser.ts - Extracts framework and concept from natural language
• src/core/version-registry.ts - Tracks npm package versions
• src/core/example-extractor.ts - Extracts code examples from documentation

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

🚀 Complete TypeScript Rewrite

This release is a complete rewrite from Python to TypeScript, optimized for Vercel serverless deployment.

Changed

• Complete TypeScript Rewrite: Migrated from Python to TypeScript
• Serverless Architecture: Optimized for Vercel edge deployment
• Cache System: Switched to Upstash Redis

Added

• Next.js 14 App Router for API routes
• 12 MCP tools (expanded from 9)
• Zod schema validation
• Health check endpoint

Fixed

• SDK transport compatibility for Claude Code integration

Technical Stack

• TypeScript 5.4+ / Next.js 14
• @modelcontextprotocol/sdk
• Upstash Redis & Ratelimit
• Vercel deployment

💰 Massive cost reduction for Railway hobby deployments!

This release dramatically reduces resource usage and costs, targeting ~75% reduction in Railway bills.

🔧 Resource Optimizations

Railway Configuration

| Setting | Before | After | Savings |
|---------|--------|-------|---------|
| Memory Limit | 2Gi | 512Mi | 75% |
| CPU Limit | 2000m | 500m | 75% |
| Workers | 2 | 1 | 50% |
| Max Replicas | 4 | 1 | 75% |
| Redis Pool | 20 | 5 | 75% |

Expected Monthly Savings

• Before: ~$40+/month
• After: ~$5-15/month
• Total Savings: ~$25-35/month

🧠 Memory Leak Fixes

1. LRU Cache Eviction

• Memory cache was unbounded - grew forever
• Now limited to 100 entries max with LRU eviction
• Oldest entries automatically removed when limit reached
• Prevents OOM crashes during extended operation

2. Framework Key Indexing

• Cache operations like clear_framework() were O(n) - scanned all entries
• Added framework → keys index for O(1) lookups
• Eliminates CPU spikes during cache operations

⚡ Performance Improvements

1. Production Logging

• Switched from ConsoleRenderer to JSONRenderer in production
• JSON is more efficient to generate and parse
• Log level defaults to WARNING (reduced log volume)

2. Redis Made Optional

• Redis is now optional for hobby deployments
• Falls back to in-memory rate limiting when Redis unavailable
• Removes ~$5-10/month Redis add-on cost
• Server continues working without Redis features

📊 Technical Details

Files Modified

• railway.json - Reduced resource limits, removed auto-scaling
• Dockerfile - Updated defaults for hobby deployment
• src/augments_mcp/registry/cache.py - LRU eviction + framework indexing
• src/augments_mcp/server.py - Production logging config
• src/augments_mcp/web_server.py - Optional Redis support

Memory Cache Changes

# Before: Unbounded growth
self.memory_cache: Dict[str, CacheEntry] = {}

# After: LRU with max 100 entries
MAX_MEMORY_CACHE_ENTRIES = 100
self.memory_cache: OrderedDict[str, CacheEntry] = OrderedDict()
self._framework_keys: Dict[str, Set[str]] = {}  # O(1) index

🎯 Impact Summary

• ✅ ~75% reduction in Railway resource usage
• ✅ Memory cache bounded - no more OOM from cache growth
• ✅ O(1) cache operations - no more CPU spikes
• ✅ Redis optional - works without external dependencies
• ✅ Production-optimized logging - less overhead

Installation

PyPI

pip install augments-mcp-server==2.0.9

uv

uv add augments-mcp-server==2.0.9

Your Railway bill should drop significantly after this update. Monitor for 24 hours to confirm stability.