npm package: @phoenix-erp/mcp-server
Description: MCP server for Phoenix ERP - AI-powered documentation with dev-guide and user-guide collections
Latest version: 0.3.0

# @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)

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

### Cursor (stdio)

Add to `.cursor/mcp.json`:

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

### Cursor (HTTP -- production)

```json
{
  "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)

```json
{
  "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

```bash
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](https://gitea.phx-erp.de/yurilima/phoenix-erp-mcp-server).

## 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