MCP 服务器

SMRT Documentation MCP Server

Enables querying the SMRT framework documentation by automatically routing questions to relevant package experts and synthesizing responses from their CLAUDE.md files using AI-powered retrieval-augmented generation.

README

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

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.md file documenting the package
Update src/registry.ts to 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