Stage AI MCP

Stage AI MCP

A Model Context Protocol (MCP) server that replicates how a creative strategist gathers and structures context before writing ad copy, scripts, or briefs. Built with FastMCP, it connects an agency's Google Drive knowledge base directly to LLMs and delivers structured, role-categorized context through an advanced RAG pipeline.

The Problem

Creative strategists spend significant time gathering context before producing work: reviewing brand guidelines, studying top-performing ads, referencing proven frameworks. This context gathering is what separates good creative output from generic content. Most RAG implementations treat retrieval as a flat keyword lookup, missing the structured thinking that makes strategists effective.

How It Works

Stage AI MCP models the context-gathering workflow of a creative strategist through a multi-stage retrieval pipeline:

┌─────────────┐  Query   ┌─────────────────┐  Expanded   ┌─────────────┐
│   FastMCP    │────────>│ Claude 3.5 Haiku │  Queries   >│  ChromaDB   │
│   Server     │         │ Query Expansion  │             │   Search    │
└─────────────┘          └─────────────────┘             └─────────────┘
                                                                │
                                                       Semantic Results
                                                                v
┌─────────────┐ Ranked   ┌─────────────────────────────────────────┐
│   Response   │<─────────│  Hybrid BM25 + Semantic Fusion          │
│ (Structured) │          │  with RRF (Reciprocal Rank Fusion)      │
└─────────────┘          └─────────────────────────────────────────┘

1. Query Expansion (Thinking Like a Strategist)

A single query like "write a testimonial script for a recovery product" gets expanded by Claude 3.5 Haiku into multiple semantically related queries that cover the angles a strategist would naturally consider: brand voice guidelines, high-performing testimonial examples, audience pain points, product benefit frameworks.

2. Hybrid Search (Comprehensive Retrieval)

Each expanded query runs against ChromaDB using OpenAI text-embedding-3-large embeddings. Results are then re-ranked using a hybrid approach:

• Semantic similarity via vector search for conceptual matches
• BM25 keyword matching via MiniSearch for exact terminology
• Reciprocal Rank Fusion (RRF) to combine both ranking signals into a single score

3. MECE Categorization (Structured Context Delivery)

Retrieved documents are classified into mutually exclusive, collectively exhaustive (MECE) categories that mirror how strategists organize their thinking:

| Category | Purpose | Example Documents | |---|---|---| | Context & Constraints | Brand voice, audience, restrictions | Brand guidelines, audience profiles | | Task Decomposition | Frameworks, processes, how-tos | Copywriting playbooks, ad format guides | | Examples & Patterns | Proven high-performers to reference | Top-performing ad analyses, case studies |

This structured delivery means the LLM receives context organized by its role in the creative process, not as a flat list of search results.

4. Contextual Embeddings (Document Understanding)

During ingestion, each document chunk is enriched with contextual metadata generated by Claude. This means the embedding captures not just the chunk's content, but its role within the broader document, improving retrieval accuracy for nuanced queries.

Technology Stack

| Component | Technology | Role | |---|---|---| | Server Framework | FastMCP | MCP protocol implementation | | Vector Database | ChromaDB Cloud | Semantic similarity search | | Embeddings | OpenAI text-embedding-3-large | High-dimensional vector representations | | Query Expansion | Claude 3.5 Haiku | Multi-angle query generation | | Keyword Search | MiniSearch | BM25 ranking for hybrid fusion | | Document Source | Google Drive API | Knowledge base sync | | Validation | Zod | Type-safe parameter schemas | | Transport | stdio / HTTP | Local MCP clients or cloud deployment |

MCP Tool

The server exposes a single tool, find_context:

{
  "name": "find_context",
  "arguments": {
    "query": "write a before/after testimonial script for a freeze roll-on with marathon runner showing immediate relief post-run",
    "limit": 5
  }
}

Returns structured context organized by MECE categories:

Found the 5 most relevant documents:

CONTEXT & CONSTRAINTS (2 documents)
├── Brand_Voice_Guidelines.pdf
└── Target_Audience_Profile.md

EXAMPLES & PATTERNS (3 documents)
├── High_Converting_Ads.md
├── Successful_Campaign_Case_Study.pdf
└── Best_Practice_Templates.md

---

### CONTEXT & CONSTRAINTS
#### Brand_Voice_Guidelines.pdf
*brand strategy*

[Document content...]

### EXAMPLES & PATTERNS
#### High_Converting_Ads.md
*winning examples*

[High-performing examples...]

Project Structure

stage-ai-mcp/
├── src/
│   ├── index.ts                     # FastMCP server entry point
│   └── types/
│       └── fastmcp.d.ts             # Type declarations
├── core/
│   ├── chroma-client.ts             # ChromaDB integration + hybrid search + RRF
│   └── lib/
│       ├── query-expander.ts        # Claude 3.5 Haiku query expansion
│       ├── google-drive.ts          # Google Drive document sync
│       ├── semantic-chunker.ts      # Document chunking for embeddings
│       ├── contextual-embeddings.ts # Contextual embedding generation
│       └── document-processor.ts    # Document processing utilities
├── data/
│   └── scripts/
│       └── sync-drive.ts            # Google Drive -> ChromaDB sync pipeline
├── manifest.json                    # MCP manifest
├── .env.example                     # Required environment variables
└── tsconfig.json                    # TypeScript ES2022 config

Setup

Prerequisites

• Node.js 18+
• ChromaDB Cloud account
• OpenAI API key (for embeddings)
• Anthropic API key (for query expansion)
• Google Service Account (for Drive sync)

Installation

npm install
cp .env.example .env.local
# Fill in your API keys in .env.local

Build & Run

# Build TypeScript
npm run build

# Run MCP server (stdio - for local MCP clients)
npm start

# Run in development mode
npm run mcp:dev

# Run with HTTP transport (for development/testing)
npm run mcp:http

# Sync Google Drive documents to ChromaDB
npm run sync-drive

MCP Client Configuration

Add to your MCP client config (e.g., Claude Desktop):

{
  "mcpServers": {
    "stage-ai": {
      "command": "node",
      "args": ["path/to/stage-ai-mcp/dist/src/index.js"],
      "env": {
        "CHROMA_API_KEY": "your_key",
        "CHROMA_TENANT": "your_tenant",
        "CHROMA_DATABASE": "your_database",
        "OPENAI_API_KEY": "your_key",
        "ANTHROPIC_API_KEY": "your_key",
        "AGENCY_ID": "your_agency_id"
      }
    }
  }
}

Search Pipeline Details

Query Expansion: Claude 3.5 Haiku generates 5 additional semantically related queries for each user query, covering complementary angles (brand context, examples, frameworks). Total of 6 queries run per search.

Multi-Query Retrieval: Each of the 6 queries retrieves up to 5 results from ChromaDB, yielding up to 30 candidate documents before deduplication.

Deduplication: Simple set-based deduplication using content as the unique key, preserving discovery order. Typical yield: 10-15 unique documents from 30 candidates.

Hybrid Ranking: RRF fusion with configurable weights (default 0.8 semantic / 0.2 BM25) combines both ranking signals. Final results are sorted by fused score and trimmed to the requested limit.

Related Projects

This is part of the Stage AI suite:

• Stage AI MCP (this repo) - Context engineering / advanced RAG for creative strategy
• Stage AI Editor - AI-powered image editing tool

License

ISC