# Compass MCP Server

A small, self-contained [MCP](https://modelcontextprotocol.io) server that lets
Claude run SQL queries against **Infor Compass** (Data Fabric) directly from
chat. You ask a question, Claude writes the SQL, fires it through this server,
and reads back the results — including automatically exporting large result
sets to Excel when they're too big to show in chat.

It wraps the Compass async query API (submit → poll → fetch) and handles Infor
ION API OAuth2 authentication automatically using your own `.ionapi`
credentials file — nothing Compass-related is hardcoded, so anyone with access
to their own Infor tenant can use this as-is.

## Prerequisites

- **Python 3.10+** — [python.org/downloads](https://www.python.org/downloads/)
  (Windows: tick **"Add Python to PATH"** during install)
- **Claude Desktop**
- A **service-account `.ionapi` credentials file** for your Infor tenant. Get
  one from your Infor ION API administrator, or generate it yourself:
  Infor OS Portal → **API Gateway** → **Authorized Apps** → create/select an
  app → **Download credentials**. It downloads as a `.ionapi` file.

## Quick start

1. **Download this repo** — click the green **Code** button above → **Download ZIP**
   — and unzip it anywhere (e.g. Desktop or Downloads).
2. Drop your `.ionapi` file into the unzipped folder and rename it to
   `credentials.ionapi`.
3. Run the installer:
   - **macOS:** double-click `install.command`
   - **Windows:** double-click `install.bat`

   This copies the folder to your home directory, builds an isolated Python
   environment, verifies it can connect to Compass, and registers the server
   with Claude Desktop — all in one pass.
4. **Fully quit and reopen Claude Desktop** (not just close the window —
   quit it completely so it reloads its MCP server list).
5. Try it in a chat:
   > *"Ping Compass to make sure it's connected."*
   >
   > *"Query Compass: select the first 10 rows from \<your table\>."*

> **Windows SmartScreen note:** the first time you run `install.bat`, Windows
> may show a blue **"Windows protected your PC"** warning, because it's a
> script downloaded from the internet. Click **More info → Run anyway**.
> This is standard for any unsigned script and not a sign anything is wrong.

## Tools exposed to Claude

- **`query_compass(sql, max_rows=1000)`** — run a SQL query, return `columns`
  and `rows` (plus `row_count`, `truncated`, `query_id`). Failed queries return
  a clear `error` + `message`.
- **`export_compass_to_excel(sql, filename="compass_export", rows_per_file=500000)`**
  — run a SQL query in full and stream every row straight into one or more
  `.xlsx` files in your Downloads folder, instead of returning rows in chat.
  Claude calls this automatically instead of `query_compass` when a result is
  (or looks like it'll be) too big for chat. Streams to disk page-by-page
  (never holding the full result in memory) and auto-splits into
  `_part1.xlsx`, `_part2.xlsx`, etc. once a result exceeds the rows-per-file
  setting — this is what makes multi-hundred-thousand-row exports practical.
- **`ping_compass()`** — check Compass connectivity/auth. Returns
  `{"ok": true, "response": "pong"}` when healthy.

## Using this in a Claude Project

Two files are included to make Claude noticeably better at writing CSD/SX.e
SQL out of the box, meant to be attached to a **Claude Project** alongside
this MCP server:

- **`SX_Dictionary_AI_v3.md`** — a business-term-to-table/field reference
  covering 64 core CSD tables (customers, orders, inventory, pricing, AP/AR,
  warehouse management, etc.), generated from Infor's CSD data-conversion
  field maps. Add it as a **Project Knowledge** file.
- **`compass-query-agent-instructions.md`** — a starting-point **Project
  Instructions** template: tells Claude to default to writing/running SQL
  rather than asking clarifying questions, lists always-on filters
  (`cono`, `statustype`), and maps plain-language requests ("customers",
  "orders", "inventory") to the right tables. **Fill in the bracketed
  placeholders** (your company name, your warehouse code list) before using
  it — the rest is generic to any CSD/SX.e install.

Neither file is required for the MCP server itself to work — they're optional
but recommended context for a Claude Project built around it.

## What's in this folder

| File | Purpose |
|------|---------|
| `server.py` | The MCP server (Python, uses the official MCP SDK + httpx) |
| `compass_client.py` | Shared Compass API client — auth, submit/poll/paginate |
| `exporter.py` | Orchestrates a full query run (submit → poll → paginate → write) for `export_compass_to_excel` |
| `excel_writer.py` | Streaming, auto-splitting `.xlsx` writer used by `exporter.py` |
| `install.command` / `install.bat` | One-click installer (recommended — see Quick start) |
| `setup.sh` / `setup.bat` | Builds the venv in place, without touching Claude Desktop's config (see Manual setup) |
| `find_python.ps1` | Windows-only: locates a usable Python 3.10+ interpreter for `install.bat`/`setup.bat` |
| `_register_claude.py` | Registers/updates the `compass` entry in Claude Desktop's config; used by the installers |
| `requirements.txt` | Python dependencies |
| `.env.example` | Optional configuration overrides (none required) |
| `SX_Dictionary_AI_v3.md` | CSD/SX.e table & field reference — optional Claude Project Knowledge file (see above) |
| `compass-query-agent-instructions.md` | Starting-point Claude Project Instructions template (see above) |
| `credentials.ionapi` | **You provide this** — your own Infor ION API service-account credentials. Never commit it; see Security below. |

## Manual setup

If you'd rather not run the one-click installer, you can do it by hand:

1. Clone or download this repo, and place your `.ionapi` file inside it as
   `credentials.ionapi`.
2. Build the environment:

   **macOS / Linux:**
   ```bash
   cd compass-mcp
   bash setup.sh
   ```

   **Windows:**
   ```bat
   cd compass-mcp
   setup.bat
   ```

   This creates a `.venv`, installs dependencies, and runs a live self-test
   that authenticates and pings Compass. You should see:

   ```
   { "ok": true, "status_code": 200, "response": "pong" }
   ```

3. Note the Python interpreter path it prints at the end, e.g.
   `/path/to/compass-mcp/.venv/bin/python`.
4. Open the Claude Desktop config file:
   - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
   - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
   - **Windows, Microsoft Store build of Claude Desktop:** the Store version
     is sandboxed and never sees `%APPDATA%\Claude` — its config instead lives
     at `%LOCALAPPDATA%\Packages\Claude_<hash>\LocalCache\Roaming\Claude\claude_desktop_config.json`
     (the `<hash>` suffix is publisher-specific; there's normally only one
     `Claude_*` folder under `Packages`). `_register_claude.py` (used by the
     installers) already detects this automatically.

   (In Claude Desktop you can also reach it via **Settings → Developer → Edit Config**.)
5. Add a `compass` entry (merge into existing `mcpServers` if present),
   substituting your actual folder path:

   **macOS / Linux:**
   ```json
   {
     "mcpServers": {
       "compass": {
         "command": "/path/to/compass-mcp/.venv/bin/python",
         "args": ["/path/to/compass-mcp/server.py"]
       }
     }
   }
   ```

   **Windows** (note `Scripts\python.exe` and **double** backslashes):
   ```json
   {
     "mcpServers": {
       "compass": {
         "command": "C:\\Users\\you\\compass-mcp\\.venv\\Scripts\\python.exe",
         "args": ["C:\\Users\\you\\compass-mcp\\server.py"]
       }
     }
   }
   ```
6. Fully quit and reopen Claude Desktop.

## Updating an existing install

To pick up a newer version of this tool (e.g. a new release from this repo),
just replace `server.py`, `compass_client.py`, `exporter.py`, and
`excel_writer.py` in your installed folder with the latest versions, then
fully quit and reopen Claude Desktop. Since the server is already registered,
you don't need to touch `claude_desktop_config.json` or re-run the installer
— that step only happens once, the first time.

## Moving to another computer

The whole folder is self-contained. To move it:

1. Copy the folder (the `.venv` does **not** transfer — it has
   machine-specific paths; leave it behind or delete it). This works across
   operating systems.
2. On the new machine, rebuild the venv: `bash setup.sh` (macOS/Linux) or
   `setup.bat` (Windows).
3. Update the paths in the Claude Desktop config to match the new location
   and OS (see the Windows path format above).

`credentials.ionapi` travels with the folder, so there's no re-entering secrets
— just make sure you're not copying it somewhere less secure than where it
started.

## How it works

1. **Auth** — reads `credentials.ionapi`, performs an OAuth2 *password* grant
   against the ION token endpoint (`pu` + `ot`), caches the bearer token and
   refreshes it ~60s before expiry.
2. **Submit** — `POST {base}/jobs/` with the SQL as a plain-text body → returns
   a `queryId`.
3. **Poll** — `GET {base}/jobs/{queryId}/status/` every 2s. Compass returns
   HTTP 202 while `RUNNING` and 201 when `FINISHED`.
4. **Fetch** — `GET {base}/jobs/{queryId}/result/` → rows. The server
   normalizes them into `columns` + `rows`.

The Compass base URL is derived from your `.ionapi` tenant automatically —
there's nothing tenant-specific to configure.

## Configuration overrides (optional)

All optional — see `.env.example`. Set them as environment variables in the
Claude config's `env` block if needed, e.g. a longer timeout for big queries:

```json
"compass": {
  "command": "/path/to/compass-mcp/.venv/bin/python",
  "args": ["/path/to/compass-mcp/server.py"],
  "env": { "COMPASS_POLL_TIMEOUT": "300", "COMPASS_MAX_ROWS": "5000" }
}
```

## Security

- `credentials.ionapi` contains live secrets for your Infor tenant. **Never
  commit it to git or share it outside your organization.** The included
  `.gitignore` keeps it (and any other `*.ionapi` file) out of version control.
- Each person should use their own `.ionapi` file, scoped to whatever
  permissions their Infor admin has granted them — don't pass credentials
  files around between teammates.
- The installers back up your existing `claude_desktop_config.json` (as
  `claude_desktop_config.json.bak`) before modifying it, so a merge issue is
  always recoverable.

## Troubleshooting

| Symptom | Fix |
|---------|-----|
| Tools don't appear in Claude | Fully quit & reopen Claude Desktop; check the config JSON is valid and paths are absolute. |
| Windows: "python is not recognized" | Install Python from python.org and tick "Add Python to PATH", then try again. |
| Windows: installer says the `python` shortcut just opens the Microsoft Store | A real Python isn't installed — only the Store's app-execution alias is on PATH. Install Python from python.org (ticking "Add Python to PATH"), or disable the alias under Settings → Apps → Advanced app settings → App execution aliases. |
| `OAuth token request failed` | Credentials expired/revoked. Re-download the `.ionapi` from the Infor ION API portal and replace `credentials.ionapi`. |
| `No .ionapi file found` | Ensure `credentials.ionapi` sits next to `server.py`, or set `IONAPI_FILE`. |
| Query `timeout` | Increase `COMPASS_POLL_TIMEOUT`. |
| Verify from terminal | `./.venv/bin/python server.py --selftest` |
| `export_compass_to_excel` fails partway through a huge query | Compass jobs can expire if left idle too long between pages; re-run the export. If it keeps happening on the same query, try a smaller `rows_per_file` so pages write to disk faster. |

## License

[MIT](LICENSE)