feat: add Docker support for HTTP-based MCP server

[jonpspri]

Summary

• Add multi-stage Dockerfile optimized for production HTTP server deployment
• Add GitHub Actions workflow for automated container image builds and publishing to GHCR
• Update .dockerignore to exclude tests, examples, and documentation from images

Details

Dockerfile features:

• Multi-stage build for minimal image size
• Uses uv for fast dependency installation
• Runs as non-root databeak user for security
• Health check endpoint for container orchestration
• Default: --transport http --host 0.0.0.0 --port 8000

GitHub workflow triggers:

• Release published → semver tags + latest
• Push to main (relevant files) → main tag
• Manual dispatch → custom tag option

Platforms: linux/amd64, linux/arm64

Test plan

• Build image locally: docker build -t databeak .
• Run container: docker run -p 8000:8000 databeak
• Verify MCP server responds on port 8000
• Verify workflow runs on push to main

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 80.00000% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 84.74%. Comparing base (26d3a3c) to head (51fc085).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
src/databeak/server.py	80.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #136      +/-   ##
==========================================
- Coverage   84.74%   84.74%   -0.01%     
==========================================
  Files          27       27              
  Lines        3075     3080       +5     
  Branches      458      458              
==========================================
+ Hits         2606     2610       +4     
- Misses        355      356       +1     
  Partials      114      114              

Flag	Coverage Δ
unittests	84.74% <80.00%> (-0.01%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
src/databeak/server.py	95.65% <80.00%> (-1.23%)	⬇️

---

Continue to review full report in Codecov by Sentry.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 26d3a3c...51fc085. Read the comment docs.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[claude]

Code Review: Docker Support for HTTP-based MCP Server

Overview

This PR adds production-ready Docker support for deploying DataBeak as an HTTP-based MCP server. The implementation follows modern container best practices with multi-stage builds, security hardening, and automated CI/CD.

---

Critical Issues

🔴 Health Check Endpoint Mismatch

Priority: High - Blocks deployment

The Dockerfile HEALTHCHECK references http://localhost:8000/health, but FastMCP servers don't automatically expose this endpoint.

Problem:

• DataBeak has a health_check MCP tool (src/databeak/servers/system_server.py:83), but this is an MCP tool, not an HTTP endpoint
• FastMCP HTTP mode exposes MCP protocol at /mcp and /sse, not a /health REST endpoint
• The README mentions http://localhost:8000/health but this doesn't exist in the current codebase

Impact: Health checks will fail, causing container orchestration platforms to continuously restart the container.

Recommendations:

1. Option A (Minimal): Remove the HEALTHCHECK directive
2. Option B (Better): Add a simple HTTP health endpoint to FastMCP server
3. Option C (Best): Check the root endpoint instead of /health

---

🟡 GitHub Workflow: Attestation Step Issue

Priority: Medium

The attestation step references steps.build-push.outputs.digest but the build step has no explicit ID.

Fix: Add "id: build-push" to line 68 (Build and push Docker image step)

---

Security Review ✅

Strong Points:

1. ✅ Non-root user: Runs as databeak:databeak (UID/GID 1000)
2. ✅ Minimal attack surface: Multi-stage build excludes tests, docs, dev tools
3. ✅ Supply chain security: Uses official Python base image and pinned uv from GHCR
4. ✅ Provenance attestation: Generates SLSA-compliant build attestations
5. ✅ Platform diversity: Supports linux/amd64 and linux/arm64

Minor Recommendations:

• Consider adding LABEL directives for OCI metadata
• Add --read-only flag examples in docs

---

Performance ✅

Excellent Optimizations:

1. ✅ Layer caching: Dependencies installed before source code copy
2. ✅ Multi-stage build: ~50% size reduction
3. ✅ GitHub Actions cache: Uses cache-from/cache-to
4. ✅ Frozen lockfile: Reproducible builds
5. ✅ Production-only deps: --no-dev flag

Size Estimate: ~400-500 MB (reasonable for data processing server)

---

Code Quality ✅

Alignment with CLAUDE.md:

1. ✅ Defensive programming: Multi-stage build isolates concerns
2. ✅ Modern tooling: Uses uv as per project standards
3. ✅ Documentation: Clear comments explaining each stage
4. ✅ Best practices: Proper COPY order, WORKDIR, env vars

---

Test Coverage ⚠️

Missing: No automated tests for Docker functionality

Suggestions:

1. Add build validation test in CI
2. Add container smoke test
3. Add integration test for MCP endpoint

---

Documentation Gap 📝

No documentation files were modified. Consider:

1. Update README.md Docker section
2. Add docs/docker.md deployment guide
3. Update CHANGELOG.md

---

Summary

Must Fix Before Merge

1. 🔴 Fix health check endpoint issue
2. 🔴 Add id: build-push to workflow

Should Fix

3. 🟡 Add Docker build test to CI
4. 🟡 Update README with Docker examples

Nice to Have

5. Add OCI labels to Dockerfile
6. Add deployment documentation
7. Verify attestation permissions

---

Verdict: Approve with Changes Required 🟡

Excellent Docker implementation with strong security and performance practices. The health check endpoint issue is a blocker that needs addressing. Once fixed, this is production-ready.

Estimated fix time: 15-30 minutes

Great work overall! Just need to address the health endpoint mismatch before deployment.

[Copilot]

Pull request overview

This PR reintroduces Docker support for the DataBeak MCP server, specifically optimized for HTTP-based deployment. Previously, Docker support was removed (per CHANGELOG.md), but this PR adds it back with a focus on production HTTP server deployments to container registries.

Key changes:

• Multi-stage Dockerfile with security hardening (non-root user, minimal runtime image)
• Automated GitHub Actions workflow for building and publishing multi-platform images to GHCR
• Updated .dockerignore to exclude development artifacts while preserving necessary runtime files

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 5 comments.

File	Description
Dockerfile	Multi-stage build configuration with uv package manager, non-root user security, and HTTP server defaults
.github/workflows/docker-publish.yml	Automated CI/CD pipeline for building and publishing container images on releases, main branch pushes, and manual triggers
.dockerignore	Excludes tests, examples, and documentation from container images to reduce image size

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The actions/attest-build-provenance@v2 action requires additional permissions that are not currently granted. The attestation step will fail without id-token: write and attestations: write permissions.

Update the permissions section:

permissions:
  contents: read
  packages: write
  id-token: write
  attestations: write

Suggested change

	packages: write
	packages: write
	id-token: write
	attestations: write

[Copilot]

Using the latest tag for the uv image can lead to non-reproducible builds and potential breakages if the uv image is updated with breaking changes. This violates container best practices for reproducibility.

Pin to a specific version or SHA:

COPY --from=ghcr.io/astral-sh/uv:0.5.18 /uv /uvx /bin/

Or use a specific version tag to ensure reproducible builds across time.

Suggested change

	COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
	COPY --from=ghcr.io/astral-sh/uv:0.5.18 /uv /uvx /bin/

[Copilot]

The step "Build and push Docker image" is missing an id attribute. Line 83 references steps.build-push.outputs.digest, but this step doesn't have id: build-push, causing the attestation step to fail.

Add id: build-push to this step:

- name: Build and push Docker image
  id: build-push
  uses: docker/build-push-action@v6

Suggested change

	- name: Build and push Docker image
	- name: Build and push Docker image
	id: build-push

[Copilot]

The *.md exclusion pattern on line 68 will exclude src/databeak/instructions.md, which is required by the server at runtime (loaded in server.py:41-46). While the code has fallback handling, this will cause a warning log and the server will run with "Instructions file not available" instead of the proper instructions.

Add an exception for the instructions file:

# Documentation files
*.md
!README.md
!src/databeak/instructions.md

Suggested change

	!README.md
	!README.md
	!src/databeak/instructions.md

[Copilot]

The HEALTHCHECK command will succeed even if the /health endpoint returns an error status (4xx/5xx). In httpx 0.27.0+, httpx.get() doesn't raise exceptions for non-2xx responses by default - it only raises on network errors.

Fix by explicitly checking the status code:

HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
    CMD python -c "import sys, httpx; sys.exit(0 if httpx.get('http://localhost:8000/health', timeout=5).status_code == 200 else 1)"

Alternatively, use raise_for_status():

HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
    CMD python -c "import httpx; httpx.get('http://localhost:8000/health', timeout=5).raise_for_status()"

Suggested change

	CMD python -c "import httpx; httpx.get('http://localhost:8000/health', timeout=5)" || exit 1
	CMD python -c "import httpx; httpx.get('http://localhost:8000/health', timeout=5).raise_for_status()"

[claude]

PR Review: Docker Support for HTTP-based MCP Server

Summary

This PR adds Docker support for running DataBeak as an HTTP-based MCP server with multi-architecture container builds. The implementation is generally solid with good security practices, though there are several issues that need addressing.

---

Critical Issues

1. Health Check Dependency Missing

Location: Dockerfile:54

The health check uses httpx but it's not guaranteed to be in the container:

HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
    CMD python -c "import httpx; httpx.get('http://localhost:8000/health', timeout=5).raise_for_status()"

Issue: While httpx>=0.27.0 is in pyproject.toml dependencies, the Dockerfile uses --no-dev which should include it, but this creates a coupling between the health check and an HTTP client library that may not be needed for the core server functionality.

Recommendation: Use a simpler health check that doesn't require external dependencies:

HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
    CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health', timeout=5).read()"

Or alternatively, use curl (requires installing it in the image):

RUN apt-get update && apt-get install -y --no-install-recommends curl && rm -rf /var/lib/apt/lists/*
HEALTHCHECK CMD curl -f http://localhost:8000/health || exit 1

2. Health Check Endpoint Not Tested

Location: src/databeak/server.py:117-121

The new /health endpoint has zero test coverage. This creates a risk that the health check could silently fail.

Recommendation: Add integration tests:

# In tests/integration/test_server_integration.py or new file
async def test_health_endpoint():
    """Test health check endpoint responds correctly."""
    # Test that /health returns 200 OK with "OK" body
    pass

3. Workflow May Trigger on Draft PRs

Location: .github/workflows/docker-publish.yml:6-13

The workflow triggers on pushes to main but doesn't validate that the push came from a merged PR. This could lead to incomplete builds if someone accidentally commits to main directly (though pre-commit hooks should prevent this).

Recommendation: Consider adding a condition to only run on successful PR merges or releases:

on:
  pull_request:
    types: [closed]
    branches: [main]
  # ... rest of triggers

---

Code Quality Issues

4. Inconsistent ARG001 Handling

Location: src/databeak/server.py:119

async def health_check(request: Request) -> PlainTextResponse:  # noqa: ARG001

Issue: The request parameter is required by FastMCP's route signature but unused, leading to an ARG001 suppression. This is correct, but consider making the intent clearer.

Recommendation: Use underscore prefix per Python convention:

async def health_check(_request: Request) -> PlainTextResponse:
    """Health check endpoint for container orchestration."""
    return PlainTextResponse("OK")

This eliminates the need for noqa comments and makes the intent explicit.

5. Missing Type Annotations in Workflow

Not applicable (YAML file), but documentation could be improved.

---

Security Considerations

6. Non-Root User Implementation ✅

Location: Dockerfile:29-30

The use of a dedicated non-root user (databeak:1000) is excellent security practice. Well done.

7. Binding to 0.0.0.0 ⚠️

Location: Dockerfile:58

CMD ["--transport", "http", "--host", "0.0.0.0", "--port", "8000"]

Note: Binding to 0.0.0.0 is necessary in containers but exposes the service to all network interfaces. This is correct for containerized deployments but should be documented.

Recommendation: Add a comment in the Dockerfile and/or documentation noting that users should use reverse proxies (nginx, traefik) or network policies for production deployments.

8. No Secrets in Image ✅

The .dockerignore properly excludes sensitive files like .env. Good work.

---

Performance Considerations

9. Multi-Stage Build Optimization ✅

Location: Dockerfile:1-23

The multi-stage build is well-designed:

• Separates build from runtime dependencies
• Uses layer caching effectively with COPY pyproject.toml uv.lock before code
• Pins uv version for reproducibility

10. Build Cache Strategy

Location: .github/workflows/docker-publish.yml:79-80

cache-from: type=gha
cache-to: type=gha,mode=max

Good: Uses GitHub Actions cache for faster builds.

Consideration: mode=max caches all layers. This is appropriate for this use case but increases cache storage. Monitor cache usage over time.

11. Platform Support

Location: .github/workflows/docker-publish.yml:75

Building for both linux/amd64 and linux/arm64 is forward-thinking and supports diverse deployment environments (x86 servers, ARM-based cloud instances, Apple Silicon development).

---

Documentation & Maintenance

12. Missing Docker Documentation

The PR doesn't update the main README.md or add Docker-specific documentation.

Recommendation: Add a section to README.md:

## Docker Deployment

### Quick Start
```bash
docker pull ghcr.io/jonpspri/databeak:latest
docker run -p 8000:8000 ghcr.io/jonpspri/databeak:latest

Building Locally

docker build -t databeak .
docker run -p 8000:8000 databeak

Environment Variables

• DATABEAK_*: See configuration documentation

13. Test Plan Checklist Incomplete

The PR body includes unchecked test items. These should be verified before merge.

---

Best Practices Alignment

14. Follows Project Conventions ✅

• Uses uv package manager as required by CLAUDE.md
• Maintains security-first approach (non-root user)
• Follows structured logging patterns (Context-based)

15. Git Workflow ✅

• Correctly uses feature/docker-support branch
• PR targets main branch as required

---

Recommendations Summary

Must Fix (Blocking)

1. ❗ Fix health check to not depend on httpx or ensure it's available
2. ❗ Add integration tests for /health endpoint to meet 80% coverage requirement
3. ❗ Complete test plan checklist items before merging

Should Fix (High Priority)

4. Replace noqa: ARG001 with underscore-prefixed parameter
5. Add Docker usage documentation to README.md
6. Consider adding production deployment security notes (reverse proxy, network policies)

Nice to Have (Low Priority)

7. Add workflow condition to prevent builds on non-PR commits to main
8. Add example docker-compose.yml for local development
9. Consider adding Docker-specific environment variable documentation

---

Overall Assessment

This is a well-structured PR that follows security best practices with a clean multi-stage build. The main concerns are:

1. Test coverage - The health endpoint needs tests to maintain the 80% threshold
2. Health check reliability - Dependency on httpx could fail
3. Documentation gaps - Users need guidance on Docker deployment

The code quality is solid, the security approach is sound, and the multi-architecture support is a strong addition. Address the critical issues above and this will be ready to merge.

Suggested next steps:

1. Fix health check dependency issue
2. Add test_health_endpoint integration test
3. Run uv run pre-commit run --all-files to verify no ruff/mypy violations
4. Update README.md with Docker deployment section
5. Complete manual test plan verification

---

Generated by Claude Code - Following DataBeak quality standards from CLAUDE.md

[claude]

Code Review: Docker Support for HTTP-based MCP Server

This PR adds Docker support with multi-stage builds and GitHub Actions workflow. The implementation is solid but has critical test coverage issues.

Critical Issues

1. Weak Test Coverage (tests/unit/test_server.py:485-509)
The health endpoint tests don't actually test HTTP behavior. Current test only checks that create_server() returns non-None, which doesn't verify the /health route works.

Recommendation: Use httpx AsyncClient to test actual HTTP responses:

async def test_health_check_endpoint(self) -> None:
    from httpx import AsyncClient
    mcp = create_server()
    async with AsyncClient(app=mcp._app, base_url="http://test") as client:
        response = await client.get("/health")
        assert response.status_code == 200
        assert response.text == "OK"

2. Dockerfile Missing Metadata Files (Dockerfile:14)
Only copies README.md but pyproject.toml references LICENSE, NOTICE, CHANGELOG.md in sdist. Should verify build succeeds or copy all metadata files.

3. Overly Broad Workflow Triggers (.github/workflows/docker-publish.yml:8-12)
Triggers on all src/** changes, causing unnecessary multi-platform builds for internal refactorings. Consider triggering only on releases.

Security Considerations

4. Hardcoded UID/GID (Dockerfile:30-31)
UID/GID 1000 may conflict with mounted volumes. Consider making configurable via build args or document the assumption.

5. Silent Health Check Failures (Dockerfile:54)
Health check has no error output. Add proper exit code handling for debugging.

Best Practices

✅ Good:

• Multi-stage build
• Non-root user
• Pinned dependencies
• Supply chain attestations

⚠️ Needs Work:

• Test coverage inadequate
• Health check error handling

Required Before Merge

1. Fix health endpoint tests to actually test HTTP behavior
2. Verify Dockerfile builds successfully
3. Add error handling to HEALTHCHECK

Verdict

⚠️ Needs revision - Test coverage doesn't meet the 80% requirement. Architecture is sound but tests must actually verify HTTP functionality.

Review based on CLAUDE.md: Zero tolerance for quality issues