@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

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 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:

{
  "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:

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

# 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:

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
• Model Context Protocol
• SDK MCP Server - Similar implementation for the SDK