Enable easy installation of MCP server via Docker image

[nikomatsakis]

Goal

Enable easy installation and deployment of Hippo MCP server via Docker image, making it simple for users to run Hippo without local Python/uv setup.

Context & Strategic Considerations

Uncertainty: It's unclear whether standalone Docker distribution is the right long-term approach, as Hippo may eventually be distributed as part of a larger MCP server ecosystem. This work serves as both immediate utility and exploration of packaging patterns.

Progress Summary

✅ Completed (WIP Commit f1cb9a9)

Docker Infrastructure:

• ✅ Created Dockerfile with Python 3.11-slim base and uv dependency management
• ✅ Added docker-compose.yml for easy orchestration with persistent storage
• ✅ Added .dockerignore to optimize build context (excludes dev files, caches, test data)

Documentation:

• ✅ Created comprehensive Docker usage guide (md/docker.md)
  • Podman/Docker build and run commands
  • Persistent storage configuration via /data volume mount
  • Development and production deployment scenarios
  • Logging and debugging instructions
• ✅ Added MCP server setup guide (md/mcp-setup.md) for Q CLI and Claude Desktop integration
• ✅ Updated README.md with Docker quick start section
• ✅ Restructured documentation organization in md/SUMMARY.md

Technical Details:

• Container exposes port 8080 for MCP server
• Default hippo file location: /data/hippo.json
• SELinux compatibility with :Z volume flags
• Support for custom hippo file locations and environment variables

🔄 Next Steps

Immediate (to complete basic Docker installation):

• Test Docker build and run process end-to-end
• Verify MCP server connectivity from containerized deployment
• Add container health checks and proper signal handling
• Consider multi-stage build for smaller production image

Distribution & Publishing:

• Decide on container registry strategy (Docker Hub, GitHub Container Registry, etc.)
• Set up automated builds/CI for container images
• Version tagging strategy for container releases
• Consider providing pre-built images vs build-from-source

Integration Considerations:

• Evaluate how this fits with potential larger MCP server distribution
• Document migration path if Hippo becomes part of larger system
• Consider whether to maintain standalone Docker option long-term

🤔 Open Questions

1. Distribution Strategy: Should we publish pre-built Docker images or just provide Dockerfile?
2. Integration Path: How will this work if Hippo becomes part of a larger MCP server?
3. Networking: Does the current port 8080 approach work well for MCP protocol needs?
4. Security: Do we need additional security considerations for containerized deployment?

📋 Acceptance Criteria

For this issue to be considered complete:

• Users can install and run Hippo via simple Docker commands
• Container properly persists data across restarts
• MCP clients can successfully connect to containerized Hippo
• Documentation provides clear installation and troubleshooting guidance
• Decision made on long-term distribution strategy

Notes

• Current implementation uses uv for dependency management within container
• Documentation emphasizes both Docker and Podman compatibility
• Volume mount approach allows for easy data backup and migration
• Container design supports both development and production use cases