# churn-mcp-server

Exposes the existing `ml-production-template` churn-prediction API as an MCP
tool, so an MCP-aware client (Claude Desktop, Claude Code, or any MCP client)
can call `predict_churn` directly.

## Design

This is a thin adapter, not a rewrite of the model server. It does not load
the model itself -- it calls the already-deployed `churn-api` service's
`/predict` endpoint over HTTP. That means:

- The MCP layer can be redeployed or scaled independently of the model.
- If `churn-api` restarts, this doesn't need to.
- The "real" ML system (FastAPI + MLflow) is untouched; MCP is an additive
  interface on top of it, matching how you'd actually integrate MCP into an
  existing production service rather than baking it into the model server.

Two tools are exposed:
- `predict_churn` -- the 19-field customer schema from the real API, returns
  churn_probability / churn_prediction / threshold_used.
- `check_model_health` -- proxies the API's `/health` endpoint.

## A version note

The official `mcp` Python SDK shipped a v2.0 recently that renamed `FastMCP`
to `MCPServer` and moved import paths. This project pins `mcp<2.0.0` and uses
`from mcp.server.fastmcp import FastMCP`, since that's still the stable,
widely-documented line as of this writing. If you're reading this later and
`pip install mcp` pulls v2 by default, you'll need to port the import
(`mcp.server.fastmcp.FastMCP` → `mcp.server.MCPServer`) — check the SDK's
migration guide before assuming the code below still applies as-is.

## Local test (stdio, no Docker)

```powershell
pip install -r requirements.txt
$env:MCP_TRANSPORT="stdio"
$env:CHURN_API_URL="http://localhost:8000"   # your local churn-api
python server.py
```

Point Claude Desktop's `claude_desktop_config.json` at it:

```json
{
  "mcpServers": {
    "churn-predictor": {
      "command": "python",
      "args": ["C:\\path\\to\\churn-mcp-server\\server.py"],
      "env": { "CHURN_API_URL": "http://localhost:8000" }
    }
  }
}
```

## Deploying into the existing kind cluster

This assumes the `churn-api` Deployment + Service from the Kubernetes
project are already running in your `kind` cluster.

```powershell
docker build -t churn-mcp-server:local .
kind load docker-image churn-mcp-server:local --name <your-cluster-name>
kubectl apply -f k8s/deployment.yaml
kubectl get pods -l app=churn-mcp-server
```

Verify:

```powershell
kubectl port-forward svc/churn-mcp-server 8080:80
curl http://localhost:8080/healthz
```