Feature: Dockerize the http server with detailed hosting instructions

[coderberry]

We need to support self-hosted streamable http server hosting.

Server-side configuration overrides

The following cli args must be configurable as ENV vars:

• --verbose: Enable verbose logging
• --file-path: Default file path for JSON operations
• --jq-path: Path to local jq binary (auto-detected if not provided)
• --s3-uri: S3 URI to sync from (e.g., s3://bucket/key)
• --aws-region: AWS region for S3 operations
• --transport: Transport type (stdio or http)
• --port: Port for HTTP transport (default: 3000)
• --host: Host for HTTP transport (default: localhost)
• --cors-origin: CORS allowed origins for HTTP transport

Example .env file

AUTH_TOKEN=<auth-token-for-client-config>
MCP_VERSION=1.1.0
TRANSPORT=http
VERBOSE=true
LOG_FILE=/path/to/logs/server.log
FILE_PATH=/path/to/file/on/server.json
JQ_PATH=/path/to/jq
HOST=my-domain.com
PORT=8080
CORS_ORIGIN=*
AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
AWS_REGION=us-east-1

Prepare for Docker deployment with documentation.

The docker image will exist on Github (ghcr.io) with the same version number that mimics that of NPM registry.

Example running Streamable HTTP

docker run -d --name json-mcp-server \
  -p 8080:8080 \
  -v json-mcp-server:/data \
  -v TRANSPORT=http \
  -v VERBOSE=true \
  -v LOG_FILE=/path/to/logs/server.log \
  -v FILE_PATH=/path/to/file/on/server.json \
  -v JQ_PATH=/path/to/jq \
  -v HOST=0.0.0.0 \
  -v PORT=3000 \
  -v CORS_ORIGIN=* \
  -v AWS_ACCESS_KEY_ID \
  -v AWS_SECRET_ACCESS_KEY \
  -v AWS_REGION=us-east-1
  ghcr.io/berrydev-ai/json-mcp-server:latest

Example MCP client configuration for http streaming:

This example does not include the AUTH_TOKEN configuration.

{
  "mcpServers": {
    "json-mcp-server": {
      "serverUrl": "http://localhost:8080/mcp"
    }
  }
}

Refer to jbrinkman/valkey-ai-tasks for example implementation.

Success Criteria

• Server can run locally using docker command
• Dockerfile exists and is configured to run the MCP server with ENV-based overrides
• The server run applies the correct version when pulling from NPM registry (MCP_VERSION -> @berrydev-ai/json-mcp-server@${MCP_VERSION}
• The MCP client configuration uses the serverUrl and includes the AUTH_TOKEN in the requests via a header (if possible), else a query param.
• Detailed instructions on server deployment with locally runnable example
• Update tests.js to test new/existing functionality that is missing.
• Github workflow exists to automatically build and release versions of the docker image

CLAUDE CODE instructions:

1. Read and understand the @modelcontextprotocol/sdk documentation at https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/refs/heads/main/README.md
2. Read the issue description (this document) in detail and base your plan on the success criteria.
3. Review the relevant code in the reference MCP server project at https://github.com/jbrinkman/valkey-ai-tasks to use as a reference implementation.
4. Do not make assumptions on the intent of the issue. Ask the USER if you have any questions or need clarification.
5. Generate a plan and save it to this issue in a comment.
6. Review the plan you created as a comment and ask yourself if the plan be simplified while still fulfilling the success criteria? If so, add an additional comment to this issue with the revised/simplified plan.
7. Make the necessary code changes until the success criteria is satisfied.
8. Commit your changes with a detailed and helpful commit message.
9. Update the @CHANGELOG.md to reflect the new changes. The new version will be a minor update from the existing npm version.

[coderberry]

Implementation Plan for Docker Deployment

Based on my analysis of the codebase and requirements, here's the comprehensive plan to implement Docker deployment with HTTP streaming support:

Phase 1: Environment Variable Support

• Add ENV variable mapping for all CLI arguments:
  • VERBOSE maps to --verbose
  • FILE_PATH maps to --file-path
  • JQ_PATH maps to --jq-path
  • S3_URI maps to --s3-uri
  • AWS_REGION maps to --aws-region
  • TRANSPORT maps to --transport
  • PORT maps to --port
  • HOST maps to --host
  • CORS_ORIGIN maps to --cors-origin
  • New: LOG_FILE for output redirection
  • New: MCP_VERSION for version management
  • New: AUTH_TOKEN for client authentication

Phase 2: Authentication Implementation

• Implement AUTH_TOKEN support for HTTP transport:
  • Add token validation middleware to Express server
  • Support both header-based (Authorization: Bearer token) and query parameter authentication
  • Integrate with existing session management system
  • Add proper error responses for invalid/missing tokens

Phase 3: Docker Infrastructure

• Create optimized Dockerfile:
  • Use official Node.js LTS Alpine image for smaller footprint
  • Install jq system dependency via package manager
  • Set up proper user permissions and working directory
  • Configure environment variables and exposed ports
  • Use multi-stage build if needed for optimization

Phase 4: CI/CD Pipeline

• GitHub Actions workflow:
  • Trigger on version tags and releases
  • Build Docker images for multiple architectures (amd64, arm64)
  • Push to GitHub Container Registry
  • Tag images with version numbers matching npm registry
  • Include security scanning and testing steps

Phase 5: Testing & Documentation

• Enhanced testing (test.js updates):

  • Test environment variable precedence over CLI arguments
  • Test Docker container startup with various configurations
  • Validate authentication token functionality
  • Test S3 sync functionality in containerized environment

• Comprehensive documentation:

  • Docker deployment guide with working examples
  • Environment variable reference table
  • Client configuration examples with authentication
  • Troubleshooting guide for common deployment issues

This plan addresses all success criteria while maintaining backward compatibility and following Docker/container best practices.

[coderberry]

Simplified Implementation Plan

After reviewing the initial plan, here's a streamlined approach that focuses on the core requirements:

Core Implementation (Minimum Viable Product)

1. Environment Variables: Add ENV support for all existing CLI args + AUTH_TOKEN and LOG_FILE
2. Authentication: Simple Bearer token validation for HTTP transport
3. Dockerfile: Basic Node.js Alpine image with jq dependency
4. GitHub Actions: Automated Docker builds to GHCR on version tags

Implementation Order:

1. Modify index.js to read ENV vars with CLI fallback
2. Add AUTH_TOKEN middleware to HTTP transport
3. Create Dockerfile with proper jq installation
4. Create GitHub Actions workflow for Docker builds
5. Update tests and documentation

Key Simplifications:

• Focus on Bearer token auth (most common pattern)
• Use single-stage Dockerfile (optimize later if needed)
• Basic GitHub Actions workflow (can enhance incrementally)
• Essential documentation only (detailed guides can come later)

This simplified approach delivers all success criteria while reducing complexity and implementation time. Each component can be enhanced iteratively after the core functionality is working.