@phoenix-erp/mcp-server

MCP server for Phoenix ERP -- exposes dev-guide and user-guide documentation to AI assistants (Cursor, Claude, Windsurf) via the Model Context Protocol.

Quick Start

npx (stdio)

PHX_MCP_TOKEN=your-token npx -y @phoenix-erp/mcp

Cursor (stdio)

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "phoenix-erp": {
      "command": "npx",
      "args": ["-y", "@phoenix-erp/mcp"],
      "env": {
        "PHX_MCP_TOKEN": "your-token"
      }
    }
  }
}

Cursor (HTTP -- production)

{
  "mcpServers": {
    "phoenix-erp": {
      "type": "streamableHttp",
      "url": "https://mcp.phx-erp.cloud/mcp-server/mcp",
      "headers": {
        "Authorization": "Bearer your-phx-mcp-token"
      }
    }
  }
}

Cursor (HTTP -- with per-session OpenAI embeddings)

{
  "mcpServers": {
    "phoenix-erp": {
      "type": "streamableHttp",
      "url": "https://mcp.phx-erp.cloud/mcp-server/mcp",
      "headers": {
        "Authorization": "Bearer your-phx-mcp-token",
        "OPENAI-API-KEY": "sk-..."
      }
    }
  }
}

Tools

| Tool | Description | Parameters | |------|-------------|------------| | search_docs | Hybrid search (lexical + semantic) across ERP docs | query, category?, limit?, fuzzy?, mode? | | get_section | Get a section by document slug and path | document, section_path | | list_documents | List all docs, optionally by category | category? | | list_sections | Table of contents for a document | document, max_depth? | | get_code_examples | Find code examples by topic | query, language?, category? | | get_architecture | Architecture info, mermaid diagrams | topic | | get_file_map | File structure for a module | document, section? | | get_usage_stats | Get API usage statistics, cost breakdown, and optimization recommendations | period? |

Prompts

| Prompt | Description | Args | |--------|-------------|------| | onboard_developer | Step-by-step setup (clone, env, Docker) plus module brief | module | | implement_feature | Implementation guide | feature_description | | review_code | Code review checklist | code_context | | explain_feature | User-facing feature explanation | feature_name | | support_answer | Draft support response | user_question | | analyze_costs | AI-powered cost analysis with spending breakdown and recommendations to reduce waste | period? |

Resources

| URI | Description | |-----|-------------| | erp://docs | List of all documents (JSON) | | erp://dev-guide/{slug} | Full dev-guide document (markdown) | | erp://user-guide/{slug} | Full user-guide document (markdown) |

Embedding Providers

Search combines lexical (MiniSearch) and semantic (embeddings) with Reciprocal Rank Fusion.

| Provider | Quality | Requirements | |----------|---------|--------------| | OpenAI (recommended) | High | OPENAI_API_KEY | | Cohere (recommended) | High | COHERE_API_KEY | | Xenova (fallback) | Moderate | None (local) |

Per-session provider switching

Clients can send their own API key via headers at session initialization. The server selects the matching provider for that session.

| Header | Purpose | |--------|---------| | OPENAI-API-KEY | Client's OpenAI API key | | COHERE-API-KEY | Client's Cohere API key | | EMBEDDING-PROVIDER | Explicit override: xenova / openai / cohere |

Clients without these headers use the server's default provider. The server validates that the requested provider has pre-built embeddings and falls back to xenova if not.

Health Check & Usage Stats

GET /health returns version, active sessions, uptime, available/loaded embedding providers, memory stats, and usage totals.

GET /usage returns a full cost breakdown by provider, tool, search mode, top queries, duplicate queries, and optimization recommendations. Accepts an optional ?period=session|today|all query parameter.

Docker

docker build -f packages/server/Dockerfile -t phoenix-erp-mcp .
docker run -p 3100:3100 -e PHX_MCP_TOKEN=your-token phoenix-erp-mcp

For production with Traefik and multi-provider embeddings, see the monorepo documentation.

Environment Variables

| Variable | Required | Default | Purpose | |----------|----------|---------|---------| | PHX_MCP_TOKEN | Yes | -- | Authentication token | | PHX_MCP_PORT | No | 3100 | HTTP server port | | EMBEDDING_PROVIDER | No | auto-detect | xenova, openai, or cohere | | OPENAI_API_KEY | No | -- | OpenAI API key for embeddings | | COHERE_API_KEY | No | -- | Cohere API key for embeddings | | YOUTRACK_TOKEN | No | -- | Runtime refresh from YouTrack | | LOG_LEVEL | No | info | debug, info, warn, error | | USAGE_RETENTION_DAYS | No | 30 | Number of days to retain usage records before auto-cleanup | | USAGE_SAVE_INTERVAL_MS | No | 60000 | Interval (ms) between usage data flushes to disk |

License

MIT