Metadata-Version: 2.5
Name: uefnmcp-connector
Version: 0.1.1
Summary: Local MCP server that grounds your AI in the hosted Verse Cortex knowledge base (Epic UEFN docs + Verse API) via the uefnmcp.com metered gateway.
Project-URL: Homepage, https://verseisland.com
Project-URL: API keys, https://verseisland.com/me/api-keys
Author: BrainDead / Verse Cortex
License: Apache-2.0
Keywords: epic-games,fortnite,mcp,model-context-protocol,uefn,verse
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: mcp<2,>=1.2.0
Description-Content-Type: text/markdown

# uefnmcp-connector

A local [MCP](https://modelcontextprotocol.io) server that grounds your AI
assistant in the **hosted Verse Cortex knowledge base** — Epic's full UEFN
documentation plus the Verse API index — through the metered
[verseisland.com](https://verseisland.com) gateway.

Plug it into Claude Desktop, Cursor, or Claude Code with your API key and your
AI can now answer UEFN / Verse questions from real, current Epic docs and the
indexed Verse API instead of guessing from stale training data. **The KB
grounding is the whole point**: local models are routinely wrong about Verse
syntax and API names — these tools fix that.

## Tools it exposes

| MCP tool | What it does | Gateway tool |
|----------|--------------|--------------|
| `verse_kb_search` | Semantic search over Epic UEFN docs + the Verse API | `search_verse_kb` |
| `verse_api_search` | Look up a Verse/Fortnite API symbol by name | `search_verse_api` |
| `verse_symbol` | Full signature + doc-comment for one symbol | `get_verse_symbol` |
| `verse_health` | Gateway / backend health probe | `health_check` |

Each call goes through the metered gateway: it authenticates your key, enforces
your tier's daily limits, meters usage, and returns ranked KB results. The
connector never touches the vector DB or the embedding server directly.

## Install

```bash
pip install uefnmcp-connector
```

or run it without installing, straight from PyPI, via [`uvx`](https://docs.astral.sh/uv/):

```bash
uvx uefnmcp-connector            # one-off run, no install
```

## Get an API key

1. Sign in at **https://verseisland.com** (Discord or email — free during beta).
2. Go to **https://verseisland.com/me/api-keys**.
3. Click **Create key**, copy the `uefn_sk_...` value — it's shown **once**.

## Configure your MCP client

The connector reads two environment variables:

| Variable | Default | Required |
|----------|---------|----------|
| `VERSEISLAND_API_KEY` | – | **yes** (for KB tools) |
| `VERSEISLAND_GATEWAY_URL` | `https://verseisland.com/mcp-api` | no |
| `VERSEISLAND_TIMEOUT` | `30` (seconds) | no |

### Claude Code (CLI)

One paste:

```bash
claude mcp add uefnmcp \
  --env VERSEISLAND_API_KEY=uefn_sk_your_key_here \
  -- uefnmcp-connector
```

### Claude Desktop

Edit `claude_desktop_config.json` (macOS:
`~/Library/Application Support/Claude/`, Windows: `%APPDATA%\Claude\`):

```json
{
  "mcpServers": {
    "uefnmcp": {
      "command": "uefnmcp-connector",
      "env": {
        "VERSEISLAND_API_KEY": "uefn_sk_your_key_here"
      }
    }
  }
}
```

If `uefnmcp-connector` isn't on your `PATH`, use the module form:
`"command": "python", "args": ["-m", "uefnmcp_connector"]` (or
`"command": "uvx", "args": ["uefnmcp-connector"]`).

### Cursor

Add to `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project):

```json
{
  "mcpServers": {
    "uefnmcp": {
      "command": "uefnmcp-connector",
      "env": {
        "VERSEISLAND_API_KEY": "uefn_sk_your_key_here"
      }
    }
  }
}
```

Restart the client. Ask it something like *"search the Verse KB for how to spawn
a prop"* and it will call `verse_kb_search`.

## Tiers

Free during the beta-launch window (all tiers unlocked, no card). Beta signups
lock the founder rate for 12 months.

| Tier | Price | `verse_kb_search` / `verse_api_search` | `verse_symbol` |
|------|-------|----------------------------------------|----------------|
| **Free** | $0 | 200 / day | 100 / day |
| **Pro** | $19/mo (founder $12) | 2,000 / day | 1,000 / day |
| **Studio** | $59/mo (founder $39) | unlimited | unlimited |

`verse_health` is always unlimited. Premium compile/build credit tools
(`compile_verse`, `compile_and_fix`, …) land in a later release behind the same
gateway. Manage keys and see usage at https://verseisland.com/me/api-keys.

## Composing with uefn-mcp (local UEFN drive)

This connector is the **KB-grounding half**. To also *drive* UEFN — compile
Verse, build, place actors on your own machine — pair it with a local
UEFN driver server (`uefn-mcp`, distributed separately), which talks to your
local UEFN build setup over Node. Add **both** servers to your client:

```json
{
  "mcpServers": {
    "uefnmcp": {
      "command": "uefnmcp-connector",
      "env": { "VERSEISLAND_API_KEY": "uefn_sk_..." }
    },
    "uefn-mcp": {
      "command": "node",
      "args": ["/path/to/uefn-mcp/dist/index.js"]
    }
  }
}
```

Your AI then grounds its Verse in the hosted KB (`verse_*` tools here) and
compiles/runs it locally (`uefn-mcp` tools) — the full write → ground → compile
loop, with the cloud KB doing the heavy lifting and your machine doing the
build. (Hosted compile credits via the gateway are on the roadmap; until then,
compile stays local via `uefn-mcp`.)

## Development / local testing

```bash
pip install -e .
# Point at a local gateway instead of prod:
VERSEISLAND_GATEWAY_URL=http://localhost:3101/mcp-api \
VERSEISLAND_API_KEY=uefn_sk_... \
  uefnmcp-connector            # serves MCP over stdio
```

A standalone smoke test (no MCP client needed) lives in `smoke_test.py`.

## License

Apache-2.0.
