Skip to content

feat: HTTP transport + Docker (ADR-0010 Stage 1)#41

Merged
shin13 merged 7 commits into
mainfrom
feat/http-transport-docker
Jun 26, 2026
Merged

feat: HTTP transport + Docker (ADR-0010 Stage 1)#41
shin13 merged 7 commits into
mainfrom
feat/http-transport-docker

Conversation

@shin13

@shin13 shin13 commented Jun 26, 2026

Copy link
Copy Markdown
Owner

Summary

Implements ADR-0010 Stage 1 — the shared institutional HTTP service (Model B). The server now runs over stdio by default (individual uvx use, unchanged) or as one shared HTTP service via MCP_TRANSPORT=http, packaged as a non-root Docker container behind a Caddy TLS edge.

Scope is Stage 1 (internal/院內) only — no auth, no cache, no Stage 2 external exposure. The in-memory insert cache (ADR-0011) and Redis/HA remain separate, deferred work.

What changed

  • config.pyMCP_TRANSPORT (Literal["stdio","http"] → fail-fast at settings load), MCP_HTTP_HOST / MCP_HTTP_PORT (8765) / MCP_HTTP_PATH (/mcp/).
  • mcp_server.pymain() branches stdio vs mcp.run(transport="http", …); stdio stays the default. Adds a /health route (PlainTextResponse("OK")) and an @asynccontextmanager lifespan that cancels the background refresh task on shutdown.
  • tools.pyshutdown() cancels the in-flight SWR _REFRESH_TASK (graceful SIGTERM).
  • Dockerfile (non-root appuser) + docker-compose.yml (app internal-only, no published port; Caddy publishes 443 only) + Caddyfile (TLS terminates at the edge — the app holds no certificate).
  • Docs.env.example activated, README "Deployment" section, CLAUDE.md quick-ref row, CHANGELOG, ADR-0010 → Accepted (Stage 1).

Key design (per ADR-0010)

  • TLS at the edge; the app speaks plain HTTP and holds no cert → portable across 院內 / AWS / laptop.
  • Single worker / single instance — per-process cache/refresh/lock state breaks under replicas (compose carries a loud "do not scale" comment; Redis is the gated prerequisite, not built here).

Verification

  • Unit: ruff clean · pyright 0 errors · 132 passed (+6). Tool schemas untouched (no snapshot change).
  • Live Docker: docker build OK; container runs as appuser, /health → OK; docker compose up → HTTPS via Caddy /health → OK, mcp (healthy) with no host port, proxy only on 443; a real fastmcp.Client over HTTP listed all 3 tools.
  • FastMCP 3.4.x API (run(transport="http", host/port/path), custom_route, lifespan) verified against the installed version before coding.

Assisted-By: Claude noreply@anthropic.com

shin13 added 7 commits June 26, 2026 18:43
Assisted-By: Claude <noreply@anthropic.com>
Assisted-By: Claude <noreply@anthropic.com>
Assisted-By: Claude <noreply@anthropic.com>
Assisted-By: Claude <noreply@anthropic.com>
@shin13 shin13 merged commit 2aee83a into main Jun 26, 2026
2 checks passed
@shin13 shin13 deleted the feat/http-transport-docker branch June 26, 2026 11:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant