@happyvertical/sdk-mcp

MCP server for the HAVE SDK that routes developer queries to package documentation. It scans each package's AGENT.md file at startup, builds a keyword-indexed registry, and exposes three MCP tools: ask (AI-powered Q&A), list-packages, and get-docs.

Installation

pnpm install @happyvertical/sdk-mcp

Published to public npm. No scoped registry configuration is required.

Usage

As an MCP Server

The package provides a stdio-based MCP server. Run it directly:

npx sdk-mcp

Or configure it in your MCP client (e.g., Claude Desktop) to launch as a subprocess.

Claude Code Context CLI

Copy AGENT.md and metadata into your project's .claude/ directory for AI-assisted development:

npx have-sdk-mcp-context

Environment Variables

The ask tool requires an AI provider. Set one of:

• HAVE_AI_API_KEY — Fallback API key for any provider
• HAVE_AI_TYPE — Provider type (openai, anthropic, gemini)
• OPENAI_API_KEY, ANTHROPIC_API_KEY, or GEMINI_API_KEY

The list-packages and get-docs tools work without AI configuration.

MCP Tools

ask

Ask a question about the SDK. Routes to relevant packages via keyword matching and synthesizes a response using AI (top 3 matches).

{
  "query": "How do I send an email with an attachment?",
  "packages": ["email", "messages"]
}

• query (required) — The question to ask
• packages (optional) — Explicit package names to consult instead of auto-routing

list-packages

List all discovered SDK packages with descriptions and keywords. No parameters.

get-docs

Get the full AGENT.md content for a specific package.

{
  "packageName": "ai"
}

How It Works

1. Registry — On first call, scans packages/*/AGENT.md and builds a Map<string, PackageMetadata> keyed by package name. Each entry includes the description (extracted from AGENT.md), keywords (from a static mapping in registry.ts), and the full documentation content.

2. Routing — Splits the user query into tokens and scores each package by keyword overlap (exact match = 10 pts, partial = 5 pts, name bonus = 15 pts). Packages below a minimum score threshold are excluded.

3. Synthesis — The ask tool loads AGENT.md for the top 3 matched packages, builds a system prompt with that context, and calls @happyvertical/ai to generate a response.

Adding a New Package

1. Create an AGENT.md in the new package directory
2. Add a keyword entry in src/registry.ts (PACKAGE_KEYWORDS)
3. Rebuild: pnpm run build

The package will be discovered automatically on the next server startup.

API

Registry (registry.ts)

| Export | Description | |--------|-------------| | PackageMetadata | Interface: name, path, description, claudeMd, keywords | | PACKAGE_KEYWORDS | Static keyword-to-package mapping used for routing | | buildPackageRegistry() | Scans packages directory and returns cached Map<string, PackageMetadata> | | getPackage(name) | Get metadata for a single package | | getAllPackages() | Get all package metadata as an array | | getPackageDocs(name) | Get raw AGENT.md content for a package | | clearCache() | Clear the in-memory registry cache |

Router (router.ts)

| Export | Description | |--------|-------------| | PackageMatch | Interface: package, score, matchedKeywords | | routeQuery(query, minScore?) | Score and rank packages against a query string | | getPackagesByNames(names) | Look up packages by explicit name list | | getTopPackages(query, limit?) | Shorthand for routeQuery + slice |

Tools (tools/)

| Export | Description | |--------|-------------| | ask(input) | AI-powered Q&A tool | | listPackages() | List all packages | | getDocs(packageName) | Get package documentation |

Dependencies

• @happyvertical/ai — AI provider for the ask tool
• @modelcontextprotocol/sdk — MCP protocol implementation

Development

pnpm run build       # Build
pnpm test            # Run tests
pnpm run dev         # Watch mode (build + test)

License

MIT