NPM MCP Generator

Project Story

What Inspired Us

AI assistants consistently provide outdated code suggestions for NPM packages. When asking about @tanstack/react-query, they suggest v4 syntax useQuery('key', fetchFn) instead of the current v5 syntax useQuery({ queryKey: ['key'], queryFn: fetchFn }). This results in broken code, wasted debugging time, and lost confidence in AI-assisted development.

This problem affects every developer using AI assistants with JavaScript libraries. With 600,000+ packages on NPM and constant version updates, AI models trained on static datasets cannot keep current.

What We Learned

Package analysis requires multi-source data fusion from NPM registry, GitHub, TypeScript definitions, and documentation sites. We implemented vector embeddings for semantic search using cosine similarity:

$$\text{similarity}(q, d) = \frac{q \cdot d}{||q|| \cdot ||d||}$$

This enables natural language queries like "handle loading states" to find relevant functions without exact keyword matches. We built graceful degradation for 10+ error scenarios including network timeouts, missing documentation, and rate limiting.

How We Built It

We designed a pipeline architecture that fetches data from NPM Registry, GitHub API, unpkg.com, and documentation sites. The system processes this through PackageAnalyzer, FunctionAnalyzer, ExampleExtractor, and VectorEmbedder components to generate MCP servers with 5 specialized tools.

Key technical decisions include multi-source analysis for comprehensive coverage, intelligent TypeScript parsing for complex type scenarios, OpenAI embedding integration for semantic search, and graceful degradation using Promise.allSettled to handle partial failures.

Challenges We Faced

GitHub API rate limiting required intelligent caching, exponential backoff, and token support. Documentation format diversity across packages needed adaptive parsing for multiple Markdown variants and code block formats. TypeScript definition complexity including generic constraints and conditional types required robust parsing. Vector embedding performance was optimized through intelligent chunking and content prioritization. MCP server generation needed template systems and comprehensive error handling.

The Result

We created a system that generates MCP servers in under 60 seconds, works with 600,000+ NPM packages, provides 5 specialized tools per package, handles errors gracefully, and integrates seamlessly with AI assistants. Developers now get accurate, current package information instead of outdated suggestions.

Built With

TypeScript, Node.js, Model Context Protocol (MCP), NPM Registry API, GitHub API, OpenAI Embeddings API, unpkg.com, @modelcontextprotocol/sdk, cheerio, turndown, commander, node-fetch, Jest, ESLint, tsx