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 optional development target keeps uv, curl, source, and test tooling in a separate image without adding them to production:

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

The production target starts again from the clean Python runtime stage and copies only the built virtual environment. Adding development tools therefore does not change the published runtime contents.

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>-run-<run-id>-attempt-<attempt>. 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.

Container security evidence

The pinned organization-owned actions publish the signed recommendation-mcp-security-evidence-<run-id>-attempt-<attempt> artifact: component-candidate-evidence-v1alpha3.json, verified image provenance, CycloneDX SBOM, and subject-bound vulnerability report. Evidence is retained for 14 days. Missing provenance or any CRITICAL finding without a current, exact central exemption fails publication of the canonical evidence package. Raw findings stay visible; covered findings produce passed-with-exemptions. HIGH findings remain visible for admission review.

Run/attempt tags are discovery hints, not deployment selectors. Environment verification independently checks the successful canonical run and signed package before admitting its exact digest to ECR. This producer has no AWS credentials or deployment authority. Older runs without this package are not eligible for the new admission path; use a fresh successful main run. The environment reader must support v1alpha3 before admission. It independently reevaluates original findings against the latest approved central policy. See the shared action contract.

This canary adopts actions PR #18 at 036531133bcefd454b5afc0eb55f8ba0328901ea for both publisher actions and the PR/local scanner. Prepare receives github-token: ${{ github.token }} for its authenticated canonical-main lookup, using the publishing job's existing contents: read permission. The job's other permissions remain required; passing its token does not reduce that token's authority. This release also hardens evidence failure paths (including bounded legacy report reads and safe errors) and scanner cleanup. Evidence remains v1alpha3.

Offline caller tests verify wiring and guards. Hosted PR scanning does not exercise prepare or prove private-repository access or canonical publication; those require separate live rollout acceptance. Publication remains restricted to push events on this repository's canonical main. Rollback reverts both action pins, the PR tooling checkout, and the documented local tooling pin to bb40579c285df0b581c48b10f9b34574d5c78639, and removes the new prepare token input together. See the canary plan.

PR and local vulnerability checks

container-security-check builds the production linux/amd64 image on PRs and other non-canonical runs. It uses the same reviewed shared tooling and v1alpha3 policy as publication, with only contents: read. The GitHub token is supplied only to the scan/evaluation step to read approved policy from the actions repo. An uncovered CRITICAL or a scanner/policy retrieval error fails the job.

The complete report, policy decisions and summary are retained for 14 days as recommendation-mcp-pr-vulnerability-report-<run>-attempt-<attempt>, including after a failed gate. These local-image diagnostics are not signed candidate evidence. Canonical main publication independently scans its exact GHCR digest.

To reproduce using a sibling actions checkout at the reviewed commit:

git -C ../movie-platform-actions rev-parse HEAD
# Expected: 036531133bcefd454b5afc0eb55f8ba0328901ea
docker build --pull --platform linux/amd64 --target prod \
  --tag movie-recommendation-mcp:local .
# Supply GH_TOKEN securely through your normal environment setup.
node ../movie-platform-actions/local-tools/container-security/lib/scan.mjs \
  movie-recommendation-mcp:local \
  --evidence-version v1alpha3 --component recommendation-mcp

The helper writes an ignored .local-container-security/run-*/ directory. Exit 0 means policy pass, 1 means blocking findings, and 2 means an operational or validation failure. Request exemptions separately in the central governance repository using the exact CVE/package/version/PURL from the complete report and supporting applicability evidence. An unmerged request does not unblock the gate. After maintainer approval reaches central main, re-run the PR check; no new producer pin is needed for policy changes.