Movie Recommendation MCP

FastMCP wrapper around the Rust movie recommendation API.

This repository was extracted from movie-reservation-platform-lab/movie-recommendation-service/axum-tools-mcp so the MCP component can have an independent CI and artifact pipeline.

Run

uv run movie-recommendation-mcp

The production container runs as UID 10001 and listens on port 8092:

docker build --tag movie-recommendation-mcp:local .
docker run --rm --network host movie-recommendation-mcp:local

The demo assumes the MCP and recommendation API containers share one ECS task network namespace, so the default downstream address remains 127.0.0.1:8082. Override the downstream URL when running the containers independently.

Defaults:

• MCP endpoint: http://127.0.0.1:8092/mcp

• Health endpoint: http://127.0.0.1:8092/health

• Downstream API: http://127.0.0.1:8082

Useful environment variables:

• MOVIE_RECOMMENDATION_API_URL

• AXUM_TOOLS_API_URL for compatibility with the original demo extraction

• PORT

• HOST

• OTEL_SERVICE_NAME

• OTEL_EXPORTER_OTLP_ENDPOINT

• OTEL_EXPORTER_OTLP_PROTOCOL

• OTEL_RESOURCE_ATTRIBUTES

Related MCP server: Weather Info MCP Server

Tools

• recommendation_get_movies

  • Inputs: limit, optional preference, optional fault, optional traceparent, optional tracestate, optional correlation_id, optional request_id, and optional demo_fault.

  • Calls Rust GET /recommendations.

  • Success payload: {"ok": true, "service_name": "movie-recommendation-mcp", "fault": "<fault-or-none>", "recommendations": [...]}

  • Downstream error payload: {"ok": false, "service_name": "movie-recommendation-mcp", "fault": "<fault-or-none>", "status_code": <int>, "error": "recommendation_dependency_failed"}

• recommendation_health

  • Inputs: optional traceparent, optional tracestate, optional correlation_id, optional request_id, and optional demo_fault.

  • Calls Rust GET /health.

  • Success payload: {"ok": true, "service_name": "movie-recommendation-mcp", "health": {...}}

Both tools forward:

• traceparent

• tracestate

• X-Correlation-Id

• X-Request-Id

• X-Demo-Fault

Extraction Decisions

• Keep the internal Python import path as axum_tools_mcp for this extraction slice. The public package, console script, service name, image, and repository are already named movie-recommendation-mcp; renaming the import path would add churn without changing the external MCP contract consumed by the agent.

• Keep the tool names recommendation_get_movies and recommendation_health. The proven reservation-agent demo allowlisted recommendation_get_movies and called it with limit, preference, fault, and propagation arguments.

• Keep AXUM_TOOLS_API_URL as a compatibility fallback, but prefer MOVIE_RECOMMENDATION_API_URL for new runtime configuration.

Artifact Contract

Platform infrastructure consumes this component as an immutable application artifact, not as source code:

• OCI image built from this repository's Dockerfile.

• Private ECR image reference pinned by digest: <account>.dkr.ecr.<region>.amazonaws.com/movie-recommendation-mcp@sha256:<64-hex-digest>.

• Separate release identifier, such as the Git commit SHA or release version, recorded alongside the digest by the consuming environment/infra repository.

• Runtime command: movie-recommendation-mcp.

• Container port and default PORT: 8092.

• MCP endpoint: /mcp.

• Health endpoint: /health.

• Required runtime configuration is environment-driven; the downstream API URL is supplied with MOVIE_RECOMMENDATION_API_URL or the compatibility fallback AXUM_TOOLS_API_URL.

• Deployment composition, environment manifests, promotion state, and AWS resources stay outside this repository.

Checks

uv sync --frozen
uv run --frozen --no-sync pytest tests
uv run --frozen --no-sync pytest automation/tests
uv run --frozen --no-sync ruff check .
uv run --frozen --no-sync ruff format --check .
uv run --frozen --no-sync python -m compileall src tests automation

Pushes to main publish a Linux AMD64 candidate to GHCR as sha-<commit>. CI disables BuildKit's automatic registry attestation to keep the candidate a single-image manifest, then records explicit GitHub build provenance against the published digest for the environment admission gate.