Fairarena MCP Server

FairArena Documentation MCP Server

A production-grade Model Context Protocol (MCP) server for searching and retrieving FairArena documentation using semantic search powered by Pinecone and Google Gemini embeddings.

🚀 Features

• Semantic Search: Uses Google Gemini embeddings and Pinecone vector database for accurate, context-aware documentation retrieval.
• Enterprise-Grade Security:

- API Key authentication (supports client-side keys). - Rate limiting (per IP and per API key). - Secure headers and CORS configuration. - Zod-based request validation.

• Robustness & Reliability:

- Circuit breakers for external services (Pinecone, Gemini). - Smart retries with exponential backoff. - LRU Caching for high-performance responses. - Graceful shutdown and lifecycle management.

• Observability:

- Structured JSON logging (Winston) with sensitive data redaction. - Prometheus metrics endpoint (/health/metrics). - Comprehensive health checks (/health, /health/live, /health/ready).

• Modern Architecture:

- Built on Express with SSE (Server-Sent Events) transport. - Fully typed with TypeScript strict mode. - Modular, maintainable codebase.

🛠️ Architecture

flowchart TB
    Client["MCP Client
(Claude/Cursor)"] --> |SSE| Server[MCP Server]
    Server --> |Auth & Rate Limit| Middleware
    Middleware --> |Query| Core
    Core --> |Text| Embedding[Google Gemini]
    Core --> |Vector| VectorDB[Pinecone]
    Core --> |Cache| Redis[(Memory Cache)]

📦 Installation

1. Clone the repository:

   git clone https://github.com/FairArena/FairArena-MCP-Server.git
   cd FairArena-MCP-Server

1. Install dependencies:

   pnpm install

1. Configure environment:

Copy .env.example to .env and fill in your credentials.

   cp .env.example .env

Required Variables: - PINECONE_API_KEY: Your Pinecone API key. - PINECONE_DEVELOPER_INDEX: Index name for dev docs. - PINECONE_DEVELOPER_HOST: Host URL for dev index. - PINECONE_DOCS_INDEX: Index name for user docs. - PINECONE_DOCS_HOST: Host URL for user index. - EMBEDDING_DIMENSION: Dimension of your vectors (e.g., 768).

Optional Variables: - GOOGLE_GEMINI_API_KEY: Fallback server-side API key (clients should provide their own). - PORT: Server port (default: 3001). - LOG_LEVEL: Logging level (info, debug, error).

🏃‍♂️ Running the Server

Development

pnpm dev

Starts the server in watch mode with pretty logs.

Production

pnpm build
pnpm start

Starts the optimized build with JSON logging key component integration.

🔌 Client Configuration

Claude Desktop / Cursor

Add the following to your MCP settings file (e.g., ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%/Claude/claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "fairarena-docs": {
      "command": "node",
      "args": ["path/to/FairArena-MCP-Server/dist/http-server.js"],
      "env": {
        "PINECONE_API_KEY": "your-key-here",
        // ... other env vars
      }
    }
  }
}

OR (Recommended) - Connect via HTTP:

If you are running the server separately (e.g., on a cloud provider or localhost:3001), use the SSE transport configuration. See mcp-config.example.json for a complete template.

📚 API Endpoints

🚢 Deployment

Docker

1. Build image:

   docker build -t fairarena-mcp-server .

1. Run container:

   docker run -p 3001:3001 --env-file .env fairarena-mcp-server

Railway / Vercel / Cloud

This server is stateless and ready for serverless or containerized deployment.

• Port: Make sure to expose the port defined in PORT (default 3001).
• Health Check: Configure your load balancer to check /health/live.
• Persistence: No persistent storage required (uses Pinecone external DB).

🛡️ Security Best Practices

1. API Keys: Clients should provide their own Google Gemini API Key via the X-Gemini-Api-Key header.
2. TLS: Always run behind a reverse proxy (Nginx, Cloudflare) with HTTPS in production.
3. Rate Limiting: Adjust src/middleware/rate-limiter.ts values based on your traffic needs.

🧪 Testing

# Check types
pnpm typecheck

📄 License

This project is licensed under the Proprietary License — see the LICENSE file for details.

🌐 Website • 💻 GitHub • 📧 Support

Built with ❤️ by the FairArena Team