churn-mcp-server

Предоставляет API прогнозирования оттока ml-production-template как инструмент MCP, чтобы MCP-совместимый клиент (Claude Desktop, Claude Code или любой MCP-клиент) мог напрямую вызывать predict_churn.

Дизайн

Это тонкий адаптер, а не переписывание сервера моделей. Сам он модель не загружает — он обращается по HTTP к эндпоинту /predict уже развернутого сервиса churn-api. Это означает:

• Слой MCP можно переразвернуть или масштабировать независимо от модели.

• Если churn-api перезапускается, этот слой перезапускать не нужно.

• «Настоящая» ML-система (FastAPI + MLflow) остаётся нетронутой; MCP — это дополнительный интерфейс поверх неё, что соответствует тому, как MCP реально интегрируют в существующий production-сервис, а не встраивают в сам сервер моделей.

Доступно два инструмента:

• predict_churn — схема клиента из 19 полей из реального API; возвращает churn_probability / churn_prediction / threshold_used.

• check_model_health — проксирует эндпоинт /health API.

Related MCP server: MCP from API

Примечание о версии

В официальном Python SDK mcp недавно вышла версия 2.0, в которой FastMCP переименован в MCPServer, а пути импортов перенесены. Этот проект закрепляет зависимость mcp<2.0.0 и использует from mcp.server.fastmcp import FastMCP, поскольку по состоянию на момент написания это всё ещё стабильная и хорошо документированная ветка. Если вы читаете это позже и pip install mcp по умолчанию ставит v2, вам нужно будет перенести импорт (mcp.server.fastmcp.FastMCP → mcp.server.MCPServer) — сначала посмотрите руководство по миграции от SDK, прежде чем считать, что код ниже по-прежнему применим без изменений.

Локальный тест (stdio, без Docker)

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

В claude_desktop_config.json Claude Desktop укажите этот сервер:

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

Развёртывание в существующем кластере kind

Предполагается, что в вашем кластере kind уже работают Deployment и Service для churn-api из Kubernetes-проекта.

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

Проверьте:

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

Реальный подводный камень, о котором стоит знать на собеседовании

Простой GET /mcp возвращает 406 Not Acceptable — транспорту MCP streamable-http требуется заголовок Accept: text/event-stream, а обычный Kubernetes-пробник httpGet его не отправляет. Это ломает наивную readiness-проверку, направленную прямо на /mcp. Исправление здесь: FastMCP.streamable_http_app() возвращает лежащее в основе приложение Starlette, которое можно смонтировать вместе с собственноручно написанным маршрутом /healthz, возвращающим обычный статус 200 — см. конец server.py. Это настоящая история «я наткнулся на реальную проблему интеграции и понял, почему», и на собеседовании она звучит сильнее, чем проект, где ничего не пошло не так.

Что это демонстрирует (точная формулировка для резюме)

«Разработал MCP-сервер, который открывает production-эндпоинт FastAPI для обслуживания моделей как вызываемый инструмент, развёрнутый в Kubernetes рядом с существующим сервисом».

Неточно: заявлять «MCP» как просто тег навыка, не умея объяснить, что такое MCP на самом деле (это протокол предоставления инструментов LLM-клиентам, а не механизм развёртывания или хостинга).