@ygen-phoenix-kb/phoenix-rag-mcp

MCP server na nag-eexpose ng Phoenix RAG (Postgres + Qdrant + Ollama) bilang tools sa anumang MCP-compatible client (Claude Desktop, Cursor, Phoenix agents, atbp). Tumatakbo over stdio.

Yung embedding model ay auto-resolved per collection — yung server nagbabasa ng embedding_model mula sa Phoenix collections table sa Postgres, kaya kahit iba-ibang model ang bawat collection (e.g. mxbai-embed-large for one, nomic-embed-text for another), gagana lahat.

Tools

| Tool | Purpose | |---|---| | list_collections | Lists all Phoenix collections from Postgres with description, embedding model, and vector size. | | search_collection | Semantic search inside a specific collection. Auto-resolves the correct embedding model from DB. | | answer_question | Full RAG: searches the collection then synthesizes an answer with citations using the configured chat model. |

Install

npm install -g @ygen-phoenix-kb/phoenix-rag-mcp

Or run it ad-hoc with npx:

npx @ygen-phoenix-kb/phoenix-rag-mcp

Configuration

The server reads from environment variables. Copy .env.example to .env next to where you run the binary, or set them in your shell / MCP client config.

| Var | Required | Purpose | Example | |---|---|---|---| | DATABASE_URL | yes | Postgres connection (reads the collections table for per-collection embedding_model) | postgresql://phoenix:[email protected]:5432/phoenix | | QDRANT_BASE_URL | yes | Qdrant endpoint | http://localhost:6333 | | QDRANT_API_KEY | no | API key (Qdrant Cloud only) | eyJhbGciOi... | | OLLAMA_BASE_URL | yes | Ollama endpoint | http://localhost:11434 | | CHAT_MODEL | yes (for answer_question) | LLM for synthesized answers | gpt-oss:20b |

Note: No global EMBEDDING_MODEL env var. Embedding models are resolved per collection from the collections.embedding_model column.

Usage with Claude Desktop

Edit claude_desktop_config.json:

{
  "mcpServers": {
    "phoenix-rag": {
      "command": "npx",
      "args": ["-y", "@ygen-phoenix-kb/phoenix-rag-mcp"],
      "env": {
        "DATABASE_URL": "postgresql://phoenix:[email protected]:5432/phoenix",
        "QDRANT_BASE_URL": "http://localhost:6333",
        "OLLAMA_BASE_URL": "http://localhost:11434",
        "CHAT_MODEL": "gpt-oss:20b"
      }
    }
  }
}

Usage with Phoenix agents

Sa agent's MCP config (Settings & Tools tab):

• Name: rag
• Transport: stdio
• Command: npx
• Args (one per line):

  -y
  @ygen-phoenix-kb/phoenix-rag-mcp

Itakda ang environment variables sa agent config.

Payload contract

Para gumana ang search_collection at answer_question tools:

• Yung Qdrant collection name ay dapat eksaktong tugma sa name field sa Postgres collections table
• Yung embedding model used for indexing ay dapat tugma sa collections.embedding_model (auto-resolved on each call)
• Ang Qdrant payload structure ay:

{
  text: string                  // chunk content (required)
  fileName?: string             // optional — used as citation source
  sourceId?: string             // optional
  metadata?: Record<string, unknown>  // optional
}

Local development

git clone <this-repo>
cd phoenix-rag-mcp
npm install
cp .env.example .env
# edit .env

# dev mode (tsx — direct TS execution)
npm run dev

# typecheck
npm run typecheck

# build for publish
npm run build

# run the built artifact
npm start

Publishing (maintainer notes)

npm run build            # outputs dist/
npm pack                 # inspect the tarball before publishing
npm publish --access public

The prepublishOnly hook builds dist/ automatically, and "files" in package.json whitelists what gets shipped (dist/, README.md, .env.example).

License

MIT