# Enterprise Support MCP Service

An MCP server for enterprise SaaS support operations. It exposes retrieval-augmented answers from support documentation and natural-language queries against the support PostgreSQL database.

## Features

- `semantic_search`: searches indexed support documentation and returns an answer, retrieved context, and source references.
- `get_sql_tool`: converts a natural-language question into a SQL query over the support database and returns the query and result.
- PostgreSQL-backed vector retrieval through LlamaIndex PGVector, with an in-memory fallback when the vector store is unavailable.
- Optional Langfuse tracing and evaluation support.

## Requirements

- Python 3.12 or newer
- PostgreSQL with the support tables and, for RAG retrieval, a configured PGVector store
- Azure OpenAI access for the chat and embedding deployments

## Installation

From the repository root:

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -e .
```

## Configuration

Create a `.env` file in the repository root. Do not commit this file because it contains credentials.

```dotenv
# Azure OpenAI
AZURE_OPENAI_API_KEY=your-api-key
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
AZURE_OPENAI_API_VERSION=2024-02-15-preview
AZURE_OPENAI_LLM_MODEL=gpt-4o-mini
AZURE_OPENAI_LLM_DEPLOYMENT=your-chat-deployment
AZURE_OPENAI_EMBEDDING_MODEL=text-embedding-3-small
AZURE_OPENAI_EMBEDDING_DEPLOYMENT=your-embedding-deployment
AZURE_OPENAI_TEMPERATURE=1

# PostgreSQL
DB_USER=postgres
DB_PASSWORD=your-password
DB_HOST=localhost
DB_PORT=5432
DB_NAME=enterprise_support_db
DB_TABLE_NAME=your-vector-table

# Optional Langfuse tracing
LANGFUSE_SECRET_KEY=your-secret-key
LANGFUSE_PUBLIC_KEY=your-public-key
LANGFUSE_BASE_URL=https://cloud.langfuse.com
```

The SQL tool reads these tables:

- `customers`
- `support_tickets`
- `incident_logs`
- `knowledge_article_usage`

The SQL connection uses the database name `enterprise_support_db`. The RAG vector store uses `DB_NAME` and `DB_TABLE_NAME`.

## Run the MCP server

Start the HTTP server from the repository root:

```powershell
python -m main.app
```

The MCP endpoint is available at:

```text
http://localhost:8000/v1/mcp
```

To use another host or port, call the server entry point from Python:

```python
from main.app import run_server

run_server(host="0.0.0.0", port=8000)
```

The application name defaults to `Employee Directory Service` and can be changed with `APP_NAME`.

## Test with the included client

With the server running in one terminal, run this from a second terminal:

```powershell
python test.py
```

The client discovers the MCP tools and calls `semantic_search` with a sample support question. To change the question, edit the default `query` argument in `test.py` or call `create_mcp_tool_spec` from your own Python client.

## Project layout

```text
main.py                         # Direct RAG smoke test
main/app.py                     # FastMCP HTTP application and tool definitions
main/service/rag_service.py     # Azure OpenAI and vector index setup
main/service/retrieval.py       # RAG query and response formatting
main/service/sql_database.py    # PostgreSQL SQLAlchemy connection
main/tools/SQLQuerytools.py     # Natural-language SQL query engine
main/tools/queryRetrivalTool.py # RAG tool adapter
main/evaluation/SLOs.py         # Optional Langfuse evaluations
test.py                         # MCP client smoke test
```

## Direct RAG smoke test

`main.py` runs a direct retrieval query without using MCP:

```powershell
python main.py
```

It asks the RAG service when error `429` occurs and prints the response. Azure OpenAI and database configuration are still required for this path.