Protheus Chat MCP Server

MCP (Model Context Protocol) server that exposes a knowledge base search tool for TOTVS Protheus ERP. Uses pgvector for vector similarity search, OpenAI (text-embedding-3-small) for question embeddings, and Cohere (rerank-v3.5) for result reranking.

Quick Start

git clone https://github.com/Straider2/protheus-mcp.git
cd protheus-mcp
cp .env.example .env
# edit .env with your credentials
uv pip install -e .
mcp-server-protheus

Or run remotely via SSE:

{
  "mcpServers": {
    "protheus": {
      "url": "https://mcp-protheus.yourdomain.com/sse"
    }
  }
}

Configuration

Variable	Default	Required
PGHOST	localhost	Database host
PGPORT	5433	Database port
PGUSER	—	Database user
PGDATABASE	—	Database name
PGPASSWORD	—	Database password
OPENAI_API_KEY	—	OpenAI API key (embeddings)
COHERE_API_KEY	—	Cohere API key (reranking)

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

Installation

Local (stdio)

uv pip install -e .
mcp-server-protheus

Available commands:

• mcp-server-protheus — stdio MCP server (Claude Desktop, Cursor)
• mcp-server-protheus-sse — SSE/HTTP server (remote access)
• protheus-mcp — alias for stdio

Docker (SSE)

docker compose -f docker-compose.yml up -d protheus-mcp-sse

The server listens on http://localhost:8092/sse.

Usage

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "protheus": {
      "command": "uv",
      "args": ["run", "mcp-server-protheus"]
    }
  }
}

Remote via SSE URL

{
  "mcpServers": {
    "protheus": {
      "url": "https://mcp-protheus.yourdomain.com/sse"
    }
  }
}

Available Tool

protheus_search(question: str) — Search the Protheus FAQ knowledge base.

Architecture

User Question → OpenAI Embedding → pgvector Cosine Search → Cohere Rerank → Results

The server connects read-only to PostgreSQL/pgvector.

Testing

uv run pytest tests/ -v

All tests use mocked connections — no real credentials needed.

Project Structure

protheus-mcp/
├── .env.example
├── pyproject.toml
├── README.md
├── src/protheus_mcp/
│   ├── __init__.py
│   ├── search.py      # pgvector search + Cohere rerank
│   └── server.py      # MCP server (stdio + SSE)
└── tests/
    ├── conftest.py
    └── test_server.py

License

MIT