@happyvertical/sdk-mcp

中文文档
0.113.1发布于 2026/11/17MITTypeScriptES Module近 30 天下载 5828

MCP server for HAVE SDK - Routes queries to package experts using AGENT.md files

原始使用文档
文档目录18 节
  1. Installation
  2. Usage
  3. As an MCP Server
  4. Claude Code Context CLI
  5. Environment Variables
  6. MCP Tools
  7. ask
  8. list-packages
  9. get-docs
  10. How It Works
  11. Adding a New Package
  12. API
  13. Registry ( registry.ts )
  14. Router ( router.ts )
  15. Tools ( tools/ )
  16. Dependencies
  17. Development
  18. License

@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

Released to npm.happyvertical.com and mirrored to public npm, which can lag; see the root README's installation notes for the @happyvertical:registry line. Public npm needs no scoped registry configuration.

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)

ExportDescription
PackageMetadataInterface: name, path, description, claudeMd, keywords
PACKAGE_KEYWORDSStatic 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)

ExportDescription
PackageMatchInterface: 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/)

ExportDescription
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

版本与发布记录

@happyvertical/sdk-mcp 共发布 131 个版本,首次发布于 2026/06/23;过去 12 个月发布了 131 个版本。

版本发布日期距今
0.113.1latest2026/11/17今天
0.113.02026/11/152 天前
0.112.32026/11/134 天前
0.112.22026/11/125 天前
0.112.02026/11/125 天前
0.112.12026/11/125 天前

关于 @happyvertical/sdk-mcp 的常见问题

@happyvertical/sdk-mcp 是什么?

MCP server for HAVE SDK - Routes queries to package experts using AGENT.md files

如何安装 @happyvertical/sdk-mcp?

在项目目录运行 npm install @happyvertical/sdk-mcp,或使用 pnpm add / yarn add / bun add。它还提供命令行工具 sdk-mcp、have-sdk-mcp-context,可以用 npx sdk-mcp 直接运行。

@happyvertical/sdk-mcp 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@happyvertical/sdk-mcp 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@happyvertical/sdk-mcp 可以商用吗?

@happyvertical/sdk-mcp 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@happyvertical/sdk-mcp 的下载量有多少?

根据 npm 官方下载统计,@happyvertical/sdk-mcp 在 2026/10/17 – 2026/11/15 这 30 天内被下载 5,828 次,日均约 194 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@happyvertical/sdk-mcp 还在维护吗?

最新版本 0.113.1 发布于 2026/11/17(今天);至今共发布 131 个版本,其中过去 12 个月发布了 131 个;首次发布于 2026/06/23。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。