# Ranger RAG MCP Server

MCP server that integrates Apache Ranger authorization with RAG (Retrieval Augmented Generation). When a user queries a knowledge base, the server first checks Ranger policies to verify the user has permission — if denied, the query is rejected before reaching the RAG system.

## Architecture

```
User (AI Agent) ──→ MCP Server ──→ Ranger Policy Check ──→ RAG Studio
                                        │
                                  DENY → "Access Denied"
                                  ALLOW → Forward query, return results
```

## Features

- **Per-knowledge-base authorization** — Ranger policies control which users can access which knowledge bases
- **Transparent enforcement** — denied queries never reach the RAG system
- **Policy-based access control** — uses existing Ranger infrastructure (policies, users, groups)
- **Automatic retries** — exponential backoff on transient errors
- **Fallback evaluation** — if Ranger's evaluateOnce API isn't available, evaluates policies locally

## MCP Tools

| Tool | Description |
|------|-------------|
| `query_knowledge_base(user, knowledge_base, query)` | Query a KB with Ranger auth check |
| `list_knowledge_bases(user)` | List KBs the user can access |
| `check_access(user, knowledge_base, access_type)` | Pre-flight permission check |
| `list_policies()` | Show all RAG Ranger policies (admin) |

## Setup

### 1. Create a Ranger Service for RAG

In Ranger Admin, create a new service (or use an existing custom service type) with:
- **Service Name:** `rag`
- **Resource:** `knowledge_base` (string, supports wildcards)
- **Access Types:** `read`, `write`

### 2. Create Ranger Policies

Example policies:

| Policy Name | Resource | Users | Access |
|---|---|---|---|
| Finance KB - Analysts | `Finance KB` | alice, bob | read |
| HR KB - HR Team | `HR Policies` | charlie | read |
| All KBs - Admin | `*` | admin | read, write |

### 3. Install and Configure

```bash
git clone <repo-url>
cd ranger-rag-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
```

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

```bash
cp .env.example .env
# Edit .env with your Ranger and RAG Studio credentials
```

### 4. Configure MCP Client

**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "ranger-rag-mcp-server": {
      "command": "/FULL/PATH/TO/ranger-rag-mcp/.venv/bin/python",
      "args": ["-m", "ranger_rag_mcp_server.server"],
      "env": {
        "RANGER_GATEWAY_URL": "https://<gateway>/<topology>/cdp-proxy-api/ranger/",
        "RANGER_USER": "<workload_username>",
        "RANGER_PASS": "<workload_password>",
        "RANGER_SERVICE_NAME": "rag",
        "RAG_STUDIO_URL": "https://<rag-studio-url>",
        "RAG_STUDIO_API_KEY": "<api_key>"
      }
    }
  }
}
```

**Agent Studio / Kiro:**

```json
{
  "mcpServers": {
    "ranger-rag-mcp-server": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/<your-org>/ranger-rag-mcp@main",
        "run-server"
      ],
      "env": {
        "RANGER_GATEWAY_URL": "https://<gateway>/<topology>/cdp-proxy-api/ranger/",
        "RANGER_USER": "<workload_username>",
        "RANGER_PASS": "<workload_password>",
        "RANGER_SERVICE_NAME": "rag",
        "RAG_STUDIO_URL": "https://<rag-studio-url>",
        "RAG_STUDIO_API_KEY": "<api_key>"
      }
    }
  }
}
```

## Configuration

### Ranger

| Variable | Required | Description |
|----------|----------|-------------|
| `RANGER_GATEWAY_URL` | Yes | Ranger Admin REST API URL via Knox |
| `RANGER_USER` | Yes | Workload username for Ranger API auth |
| `RANGER_PASS` | Yes | Workload password for Ranger API auth |
| `RANGER_SERVICE_NAME` | No | Ranger service name (default: `rag`) |

### RAG Studio

| Variable | Required | Description |
|----------|----------|-------------|
| `RAG_STUDIO_URL` | Yes | RAG Studio base URL |
| `RAG_STUDIO_API_KEY` | Yes | RAG Studio API key |
| `RAG_STUDIO_PROJECT_ID` | No | Project ID (default: 1) |
| `RAG_RESPONSE_CHUNKS` | No | Number of chunks to retrieve (default: 5) |
| `RAG_INFERENCE_MODEL` | No | LLM model for response generation |

### TLS/HTTP

| Variable | Default | Description |
|----------|---------|-------------|
| `VERIFY_SSL` | `true` | Set `false` to disable SSL verification |
| `CA_BUNDLE` | — | Path to CA certificate bundle |
| `HTTP_TIMEOUT_SECONDS` | `30` | Request timeout in seconds |

## Example Usage

Once configured, ask the AI:

```
# User with access → gets results
"As user 'alice', query the 'Finance KB' knowledge base: What was Q3 revenue?"

# User without access → gets denied
"As user 'bob', query the 'HR Policies' knowledge base: What is the PTO policy?"

# Check what a user can access
"List all knowledge bases that user 'alice' can access"

# Admin: see all policies
"Show me all the RAG access policies"
```

## How It Works

1. **User calls `query_knowledge_base(user="alice", knowledge_base="Finance KB", query="...")`**
2. **MCP server calls Ranger:** `POST /service/plugins/policies/evaluateOnce` — "Can alice read Finance KB?"
3. **Ranger evaluates policies:**
   - Checks all enabled policies for the `rag` service
   - Looks for policies where resource `knowledge_base` matches "Finance KB"
   - Checks if user "alice" or any of her groups appear in `policyItems` with `read` access
4. **If ALLOWED:** Forward query to RAG Studio, return answer
5. **If DENIED:** Return `ACCESS_DENIED` with reason — RAG Studio is never contacted

## Ranger Policy Structure

The server expects Ranger policies with this structure:

```json
{
  "service": "rag",
  "name": "Finance KB Access",
  "isEnabled": true,
  "resources": {
    "knowledge_base": {
      "values": ["Finance KB"],
      "isRecursive": false
    }
  },
  "policyItems": [
    {
      "users": ["alice", "bob"],
      "groups": ["finance-team"],
      "accesses": [
        {"type": "read", "isAllowed": true}
      ]
    }
  ]
}
```

## License

Apache License 2.0