# Discovery Agent — MCP Server (Render deploy)

Self-contained copy of the Discovery Agent **MCP server**, ready to host on
[Render](https://render.com) (or any host that runs a Python web service) and
drive from any MCP-compliant agent over HTTP.

It exposes the full session lifecycle — connect → upload/pick source schema →
choose target model → match → review → export/push — as MCP tools over the
**streamable-http** transport.

## What's in here

```
discovery-agent-mcp-server/
├── backend/app/          # the MCP server + all business logic (Python)
│   ├── mcp/              # FastMCP server, tools, HTTP entrypoint
│   ├── api.py            # route functions the tools call into
│   ├── matcher.py        # lexical fuzzy/Jaccard matcher
│   ├── parsers.py        # CSV / Excel / PDF / XML parsing
│   ├── idmc_client.py    # IDMC REST + mock catalogue
│   ├── ootb_schema.json  # mock Business Entities
│   └── ...
├── industry-library/     # curated source/target schemas
├── sample-data/          # sample dictionaries for demos
├── requirements.txt      # pinned dependencies (Python 3.13)
├── render.yaml           # Render blueprint (one-click infra)
├── Procfile              # start command
├── runtime.txt           # Python version pin
└── README.md
```

## How it runs

The server starts with:

```bash
MCP_TRANSPORT=http MCP_HOST=0.0.0.0 MCP_PORT=$PORT PYTHONPATH=backend python -m app.mcp
```

It then serves MCP at **`https://<your-service>.onrender.com/mcp`**.

| Env var | Purpose | Value on Render |
|---|---|---|
| `MCP_TRANSPORT` | selects the transport | `http` |
| `MCP_HOST` | bind address | `0.0.0.0` |
| `MCP_PORT` | bind port | `$PORT` (Render injects it) |
| `MCP_ALLOWED_ORIGINS` | **required** — DNS-rebinding / CORS allowlist | your Render URL (see step 5) |
| `IDMC_MODE` | `mock` for the demo catalogue, or unset for live | `mock` |

> **Important:** the MCP SDK blocks any request whose `Host` header isn't in
> `MCP_ALLOWED_ORIGINS`. If you skip step 5 the service will boot but every
> client request returns a rebinding-protection error.

---

## Deploy to Render (Blueprint — easiest)

### 1. Put this folder in its own Git repo
```bash
cd discovery-agent-mcp-server
git init
git add .
git commit -m "Discovery Agent MCP server"
git branch -M main
git remote add origin https://github.com/<you>/discovery-agent-mcp.git
git push -u origin main
```

### 2. Create the service on Render
- Go to the [Render dashboard](https://dashboard.render.com) → **New +** → **Blueprint**.
- Connect the GitHub repo you just pushed. Render reads `render.yaml` and
  proposes a web service named `discovery-agent-mcp`.
- Click **Apply**. The first build installs `requirements.txt` (takes a few
  minutes — `pandas`/`pdfplumber` compile).

### 3. Wait for "Live"
When the build finishes, Render shows a URL like
`https://discovery-agent-mcp.onrender.com`.

### 4. Set the allowlist and redeploy
- Open the service → **Environment** → the `MCP_ALLOWED_ORIGINS` var.
- Set it to your service URL, e.g. `https://discovery-agent-mcp.onrender.com`
  (comma-separate more origins if a browser UI will connect too).
- **Save changes** → Render redeploys automatically.

### 5. Verify
```bash
curl https://discovery-agent-mcp.onrender.com/mcp
```
A running MCP endpoint replies with a JSON-RPC / SSE error about a missing
session (that's expected — it means the endpoint is alive). A 404 or connection
error means the service isn't up yet.

---

## Deploy to Render (manual, without the blueprint)

**New +** → **Web Service** → connect the repo, then set:
- **Runtime:** Python 3
- **Build command:** `pip install -r requirements.txt`
- **Start command:** `MCP_TRANSPORT=http MCP_HOST=0.0.0.0 MCP_PORT=$PORT PYTHONPATH=backend python -m app.mcp`
- **Environment variables:** `MCP_ALLOWED_ORIGINS=https://<your-service>.onrender.com`, `IDMC_MODE=mock`

---

## Point an agent at it

Any MCP client that supports **streamable-http** can connect to
`https://<your-service>.onrender.com/mcp`.

Example `mcp.json` (Claude Desktop / Cursor / AI Expert Suite style):
```json
{
  "mcpServers": {
    "discovery-agent": {
      "url": "https://<your-service>.onrender.com/mcp",
      "transport": "streamable-http"
    }
  }
}
```

For a client that only speaks stdio, use a bridge such as `mcp-remote`:
```json
{
  "mcpServers": {
    "discovery-agent": {
      "command": "npx",
      "args": ["mcp-remote", "https://<your-service>.onrender.com/mcp"]
    }
  }
}
```

Once connected, the agent sees all the discovery tools (`idmc_use_mock`,
`list_business_entities`, `create_session`, `run_match`, `get_candidates`,
`apply_decisions`, `export_mapping`, `er_diagram`, …) and the `start_discovery`
prompt.

---

## Notes & limits

- **Mock mode works fully out of the box** — no IDMC credentials required.
- **Live IDMC** over REST works if you set real credentials via the
  `idmc_login` tool, but the bundled `b360-mdm-server.exe` bridge is
  Windows-only and won't run on Render's Linux — live MDM-bridge features are
  unavailable there. Mock mode and REST-based flows are unaffected.
- **Sessions are in-memory** and do not survive a restart. Render's free plan
  also spins the service down after inactivity; the first request after a spin
  cools starts it back up (cold start ~30–60 s).
- **Uploaded files** must be reachable by the server. Over HTTP, prefer the
  industry-library source (`source_mode="industry"`) or paste-JSON targets,
  since local `file_paths` refer to the *server's* filesystem, not the client's.

## Run locally first (optional sanity check)
```bash
pip install -r requirements.txt
$env:MCP_TRANSPORT="http"; $env:MCP_HOST="127.0.0.1"; $env:MCP_PORT="8800"; $env:PYTHONPATH="backend"
python -m app.mcp
# → serving on http://127.0.0.1:8800/mcp
```