@happyvertical/smrt-docs-mcp
Documentation MCP server for the SMRT framework that acts as an orchestrator, routing developer queries to appropriate package experts using CLAUDE.md files.
Overview
The SMRT Documentation MCP Server implements a RAG (Retrieval-Augmented Generation) pattern where each SMRT package's CLAUDE.md file serves as domain expertise. When you ask a question, the server:
- Routes your query to relevant packages based on keyword matching
- Loads the CLAUDE.md documentation for those packages
- Uses AI to synthesize a response based on the expert documentation
- Returns an answer with package references
Installation
pnpm install @happyvertical/smrt-mcp
Usage
As an MCP Server
Add to your .mcp.json (see Configuration section below):
{
"mcpServers": {
"smrt-advisor": {
"type": "stdio",
"command": "pnpm",
"args": [
"exec",
"tsx",
"/path/to/smrt/packages/smrt-mcp/src/index.ts"
],
"env": {
"DEBUG": "false"
},
"cwd": "/path/to/smrt"
}
}
}
Environment Variables
The ask tool requires an AI provider to be configured. Set one of:
HAVE_AI_API_KEY- Fallback API key for any providerHAVE_AI_TYPE- Provider type ('openai', 'anthropic', 'gemini')OPENAI_API_KEY- OpenAI API keyANTHROPIC_API_KEY- Anthropic API keyGEMINI_API_KEY- Google Gemini API key
Other tools (list-packages, get-docs) work without AI configuration.
Available Tools
ask
Ask a question about the SMRT framework. Automatically routes to relevant packages and synthesizes a response.
Input:
{
"query": "How do I create a collection with custom actions?",
"packages": ["core", "products"] // Optional: specify packages explicitly
}
Example:
Query: "How do I create a collection with custom actions?"
Response:
To create a collection with custom actions in the SMRT framework, you extend SmrtCollection and use the @smrt() decorator to configure which actions are exposed...
---
*Consulted packages: @happyvertical/smrt-core, @happyvertical/smrt-products*
list-packages
List all available SMRT framework packages with descriptions and keywords.
Input:
{
// No parameters required
}
Example Output:
# SMRT Framework Packages (13 total)
### @happyvertical/smrt-core
Core framework with ORM, code generation, and AI integration
**Keywords**: smrt, framework, orm, database, collection, object...
---
### @happyvertical/smrt-agents
Agent framework for autonomous actors
**Keywords**: agent, autonomous, actor, workflow...
get-docs
Get the full CLAUDE.md documentation for a specific package.
Input:
{
"packageName": "core"
}
Example:
# @happyvertical/smrt-core
## Purpose and Responsibilities
The `@happyvertical/smrt-core` package is the core framework...
How It Works
Package Registry
The registry scans packages/*/CLAUDE.md files at startup and builds a catalog of available packages with:
- Package name
- Description (extracted from CLAUDE.md)
- Keywords for routing
- Full documentation content
Query Routing
When you ask a question, the router:
- Extracts keywords from your query
- Matches against package keyword lists
- Scores packages by relevance
- Returns top matches
AI Synthesis
The ask tool:
- Loads CLAUDE.md for relevant packages (top 3 matches)
- Builds context from documentation
- Uses AI (via
@happyvertical/ai) to generate response - Includes package references in response
Package Keywords
Each package has associated keywords for routing. Examples:
- core: smrt, framework, orm, database, collection, object, decorator, schema, api, rest, cli, mcp
- agents: agent, autonomous, actor, workflow, orchestration, task
- content: content, article, markdown, cms, document, blog, publishing
- events: event, calendar, meeting, schedule, attendance, rsvp
- gnode: federation, network, knowledge base, distributed, peer
See src/registry.ts for the complete mapping.
Development
# Build the package
pnpm run build
# Run tests
pnpm test
# Watch mode
pnpm run dev
Configuration
Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"smrt-advisor": {
"command": "pnpm",
"args": [
"exec",
"tsx",
"/Users/you/path/to/smrt/packages/smrt-mcp/src/index.ts"
],
"env": {
"ANTHROPIC_API_KEY": "your-key-here"
}
}
}
}
Claude Code
Add to project root .mcp.json:
{
"mcpServers": {
"smrt-advisor": {
"type": "stdio",
"command": "pnpm",
"args": [
"exec",
"tsx",
"/Users/you/path/to/smrt/packages/smrt-mcp/src/index.ts"
],
"env": {
"DEBUG": "false",
"ANTHROPIC_API_KEY": "your-key-here"
},
"cwd": "/Users/you/path/to/smrt"
}
}
}
Adding New Packages
When you add a new package to the SMRT framework:
- Create a
CLAUDE.mdfile documenting the package - Update
src/registry.tsto add keywords for the new package - Rebuild:
pnpm run build
The package will be automatically discovered and included in the registry.
Architecture
Developer Query → MCP Server (Orchestrator)
↓
┌─────────────────┼─────────────────┐
↓ ↓ ↓
Package Expert Package Expert Package Expert
(@happyvertical/smrt-core) (@happyvertical/smrt-agents) (@happyvertical/smrt-content)
CLAUDE.md CLAUDE.md CLAUDE.md
↓ ↓ ↓
└─────────────────┴─────────────────┘
↓
Synthesized Response
Troubleshooting
"AI client initialization failed"
The ask tool requires an AI provider. Set one of the environment variables listed above.
"No relevant packages found"
Try using list-packages to see available packages, or specify packages explicitly with the packages parameter.
"Package not found"
Use list-packages to see the exact package names. Package names should not include the @happyvertical/smrt- prefix (use "core" not "smrt-core").
License
MIT
Related
- SMRT Framework
- Model Context Protocol
- SDK MCP Server - Similar implementation for the SDK