jacobjaffe972/braze-docs-mcp

Braze Documentation MCP Server

A Model Context Protocol (MCP) server that scrapes Braze's public documentation and makes it available to goose for interactive querying, searching, and code extraction.

Features

✨ Core Capabilities:

• Resource Access: Access documentation pages via doc://path URIs
• Full-Text Search: Search across all scraped documentation
• Code Extraction: Extract code examples from pages
• Documentation Listing: Browse available documentation pages
• Caching: Automatically caches scraped docs for fast startup

Installation

Prerequisites

• Python 3.13+ (MCP SDK requires Python 3.10+)
• pip or pip3

Setup

1. Create and activate virtual environment:

   cd braze-docs-server
   /usr/local/bin/python3.13 -m venv venv
   source venv/bin/activate
   

2. Install dependencies:

   pip install -r requirements.txt
   

Usage

Running with Goose

Start a goose session with this MCP server:

cd /Users/Jacob.Jaffe/braze-docs-server
goose session --with-extension "source venv/bin/activate && python server.py"

Or run a headless test:

goose run --with-extension "source venv/bin/activate && python server.py" --text "Search for 'email campaigns' in Braze documentation"

What You Can Do

Once connected, you can ask goose to:

1. Search documentation:

   • "Search the Braze docs for information about email campaigns"
   • "Find pages about segmentation in the Braze documentation"

2. Access specific pages:

   • "Show me the content from doc://user_guide/email"
   • "Get the Braze API documentation"

3. Extract code examples:

   • "Extract all code examples from the email campaigns page"
   • "Show me code examples for Braze REST API"

4. Browse available docs:

   • "List all available Braze documentation pages"

How It Works

Startup Process

1. Server starts and checks for cached documentation (braze_docs_cache.json)
2. If cache exists, loads it immediately (fast startup)
3. If no cache, scrapes Braze docs (first run takes ~30-60 seconds)
4. Saves scraped docs to cache for future runs

Scraping Strategy

• Starts from common Braze documentation entry points
• Follows links to discover related pages
• Extracts page titles, content, code examples, and sections
• Limits to ~50 pages per run (to avoid excessive bandwidth)
• Stores everything in structured JSON format

Resources and Tools Exposed

Resources:

• doc://path/to/page - Returns full documentation page with content, sections, and code examples

Tools:

• search_documentation(query) - Search across all docs
• list_documentation() - Show all available pages
• extract_code_from_page(page_path) - Get code examples from a specific page

Architecture Explanation

MCP Server Components

┌─────────────────────────────────────────────┐
│         Goose AI Agent                      │
│  (Uses tools & reads resources)             │
└──────────────┬──────────────────────────────┘
               │ MCP Protocol
               ▼
┌─────────────────────────────────────────────┐
│    Braze Docs MCP Server (server.py)        │
│                                              │
│  ┌────────────────────────────────────────┐ │
│  │ Resources:                             │ │
│  │ - doc://user_guide/email               │ │
│  │ - doc://api/endpoints                  │ │
│  │ - etc.                                 │ │
│  └────────────────────────────────────────┘ │
│                                              │
│  ┌────────────────────────────────────────┐ │
│  │ Tools:                                 │ │
│  │ - search_documentation(query)          │ │
│  │ - extract_code_from_page(path)         │ │
│  │ - list_documentation()                 │ │
│  └────────────────────────────────────────┘ │
│                                              │
│  ┌────────────────────────────────────────┐ │
│  │ Data Storage:                          │ │
│  │ - braze_docs_cache.json                │ │
│  │  (structured doc data)                 │ │
│  └────────────────────────────────────────┘ │
└─────────────────────────────────────────────┘
               ▲
               │ HTTP Requests
               ▼
┌─────────────────────────────────────────────┐
│    Braze Public Documentation               │
│    (braze.com/docs)                         │ 
└─────────────────────────────────────────────┘

Data Flow

1. Startup Phase:

   • Server reads/creates cache
   • Scrapes Braze docs if needed
   • Stores structured data in memory

2. Query Phase:

   • Goose sends request (resource read or tool call)
   • Server processes request against cached docs
   • Returns formatted results

3. Caching:

   • First run: Slow (scraping)
   • Subsequent runs: Fast (cache loaded)

Debugging

The server logs all activity to mcp_extension.log:

# Watch logs in real-time
tail -f mcp_extension.log

Common issues:

• "No pages found" - Cache hasn't been built yet; restart server
• Slow startup - First run scrapes docs; subsequent runs use cache
• Empty cache - Delete braze_docs_cache.json to force rescrape

Extending the Server

Add New Scraping Sources

Edit the base_urls in scrape_documentation():

base_urls = [
    "https://www.braze.com/docs/",
    "https://www.braze.com/docs/your-new-section/",
]

Add New Tools

Use the FastMCP decorator pattern:

@mcp.tool()
def your_new_tool(param: str) -> str:
    """Tool description"""
    # Your implementation
    return result

Add New Resources

Use the FastMCP resource decorator:

@mcp.resource("custom://{path}")
def get_custom_data(path: str) -> str:
    """Resource description"""
    return data

Troubleshooting

Server won't start

# Check Python version
python3 --version  # Should be 3.10+

# Verify dependencies
pip list | grep mcp

# Check logs
cat mcp_extension.log

Goose can't connect

# Ensure venv is activated properly
source venv/bin/activate
which python  # Should show venv path

# Test server directly
python server.py

Cache issues

# Delete cache to force rescrape
rm braze_docs_cache.json

# Restart server
python server.py

License

This MCP server is provided as-is for educational and research purposes.

References

• MCP Documentation
• Braze Documentation
• Python MCP SDK