# @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:
1. Routes your query to relevant packages based on keyword matching
2. Loads the CLAUDE.md documentation for those packages
3. Uses AI to synthesize a response based on the expert documentation
4. Returns an answer with package references
## Installation
```bash
pnpm install @happyvertical/smrt-mcp
```
## Usage
### As an MCP Server
Add to your `.mcp.json` (see Configuration section below):
```json
{
"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 provider
- `HAVE_AI_TYPE` - Provider type ('openai', 'anthropic', 'gemini')
- `OPENAI_API_KEY` - OpenAI API key
- `ANTHROPIC_API_KEY` - Anthropic API key
- `GEMINI_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:**
```typescript
{
"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:**
```typescript
{
// 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:**
```typescript
{
"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:
1. Extracts keywords from your query
2. Matches against package keyword lists
3. Scores packages by relevance
4. Returns top matches
### AI Synthesis
The `ask` tool:
1. Loads CLAUDE.md for relevant packages (top 3 matches)
2. Builds context from documentation
3. Uses AI (via `@happyvertical/ai`) to generate response
4. 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
```bash
# 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`:
```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`:
```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:
1. Create a `CLAUDE.md` file documenting the package
2. Update `src/registry.ts` to add keywords for the new package
3. 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](https://github.com/happyvertical/smrt)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [SDK MCP Server](https://github.com/happyvertical/sdk/tree/main/packages/sdk-mcp) - Similar implementation for the SDK
