MDX Documents  -->  Indexer  -->  Search Index  -->  MCP Server  -->  AI Assistant
                                  (BM25)             (tools)

# 1. Clone and install
git clone <repo-url> my-docs-mcp
cd my-docs-mcp
npm install

# 2. Configure
cp .env.example .env
# Edit .env: set OPENAI_API_KEY, DOCS_ROOT

# 3. Build the search index
npm run reindex

# 4. Start the MCP server
npm run start

docs-mcp/
|
+-- content/
|   +-- docs/              # Your MDX documentation
|   |   +-- domain-a/      # Organized by domain
|   |   +-- domain-b/
|   +-- conventions/        # How-to-write-docs guides
|
+-- src/
|   +-- indexer/            # MDX parser + BM25 index builder
|   +-- retriever/          # Search engine (BM25 + metadata filters)
|   +-- tools/              # MCP tool definitions
|   +-- chat/               # RAG chatbot (OpenAI)
|
+-- analysis/
|   +-- scripts/            # Analysis pipeline scripts
|   +-- templates/          # MDX templates for generated docs
|
+-- data/
|   +-- search-index.json   # Built index (gitignored)
|
+-- dist/                   # Compiled output (gitignored)

  MDX files (content/docs/)
       |
       v
  [Indexer] -- parses frontmatter + content
       |
       v
  search-index.json (BM25 terms + metadata)
       |
       v
  [Retriever] -- query -> ranked results
       |
       v
  [MCP Tools] -- exposed to AI assistants
       |
       v
  [Chat] -- RAG: retriever results + OpenAI completion

search_docs("user registration flow")
search_docs("traps", { category: "traps", domain: "user-management" })
get_document("example/sample-api")
list_categories()
find_related("example/index")

{
  "mcpServers": {
    "project-docs": {
      "command": "node",
      "args": ["/path/to/docs-mcp/dist/server.js"],
      "env": {
        "DOCS_ROOT": "/path/to/docs-mcp/content/docs"
      }
    }
  }
}

---
title: "Document Title"
description: "One-line summary for search results"
category: endpoint
---

# First time
fly launch --name my-docs-mcp

# Deploy
fly deploy

# Set secrets
fly secrets set OPENAI_API_KEY=sk-...

# Build
npm run build

# Run in development mode (auto-rebuild)
npm run dev

# Rebuild search index
npm run reindex

# Type check
npm run typecheck