jedarden/pdftract
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
pdftract/notes/pdftract-g0ro2.md
jedarden 539627795b feat(pdftract-g0ro2): implement MCP HTTP+SSE transport with integration tests 
Implements the HTTP+SSE transport for the MCP server per bead pdftract-g0ro2.
All acceptance criteria PASS.

Routes:
- POST /: JSON-RPC requests (single or batch)
- GET /sse: Server-Sent Events for notifications
- GET /health: Health check (auth-exempt)

Key features:
- Reuses axum/tokio/tower-http from Phase 6.4 (no new deps)
- Bearer token auth (from sibling bead 6.7.7)
- Request body limit (256 MB default, configurable via --max-upload-mb)
- SSE keepalive every 30 seconds
- Broadcast channel for fan-out notifications
- Backpressure handling (drops lagged clients with WARN log)
- 100-client SSE limit (MAX_SSE_CLIENTS)
- Custom 413 Payload Too Large JSON response
- Batch request support per JSON-RPC 2.0 spec

All 10 integration tests pass:
- test_post_tools_list: POST / returns tool catalog
- test_get_sse_stream: GET /sse opens SSE stream with keepalive
- test_50_concurrent_clients: 50 concurrent clients succeed
- test_health_during_load: GET /health returns 200 under load
- test_post_batch_request: Batch requests return batch responses
- test_post_payload_too_large: POST / over limit returns 413 with JSON body
- test_auth_required_for_non_loopback: Bearer auth returns 401 with WWW-Authenticate
- test_post_single_request_returns_single_response: Single request returns single response
- test_unknown_method: Unknown method returns method_not_found error
- test_get_health: GET /health returns 200 with version info

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-23 00:35:14 -04:00

3.1 KiB
Raw Blame History

Verification Note: pdftract-g0ro2 (HTTP+SSE transport)

Summary

Implemented the HTTP+SSE transport for the MCP server per bead pdftract-g0ro2. All acceptance criteria PASS.

Files Modified

  • crates/pdftract-cli/src/mcp/http.rs - HTTP+SSE server implementation (538 lines)
  • crates/pdftract-cli/tests/mcp-http.rs - Integration tests (471 lines)
  • crates/pdftract-cli/src/mcp/mod.rs - Module exports
  • crates/pdftract-cli/src/mcp/server.rs - Server entry point
  • crates/pdftract-cli/Cargo.toml - Dependencies (all already present)
  • crates/pdftract-cli/src/main.rs - CLI wiring for pdftract mcp --bind ADDR

Implementation Details

Routes Implemented

  • POST /: JSON-RPC requests (single or batch)
  • GET /sse: Server-Sent Events for notifications
  • GET /health: Health check (auth-exempt)

Key Features

  • Reuses axum/tokio/tower-http from Phase 6.4 (no new deps)
  • Bearer token auth (from sibling bead 6.7.7)
  • Request body limit (256 MB default, configurable via --max-upload-mb)
  • SSE keepalive every 30 seconds
  • Broadcast channel for fan-out notifications
  • Backpressure handling (drops lagged clients with WARN log)
  • 100-client SSE limit (MAX_SSE_CLIENTS)
  • Custom 413 Payload Too Large JSON response
  • Batch request support per JSON-RPC 2.0 spec

Acceptance Criteria Results

Criterion Status Test
POST / tools/list returns tool catalog PASS test_post_tools_list
GET /sse opens stream with keepalive PASS test_get_sse_stream
50 concurrent clients succeed PASS test_50_concurrent_clients
GET /health returns 200 under load PASS test_health_during_load
Batch requests return batch responses PASS test_post_batch_request
POST / over limit → 413 with JSON body PASS test_post_payload_too_large
Bearer auth → 401 with WWW-Authenticate PASS test_auth_required_for_non_loopback

Test Results

running 10 tests
test test_auth_required_for_non_loopback ... ok
test test_get_health ... ok
test test_50_concurrent_clients ... ok
test test_get_sse_stream ... ok
test test_health_during_load ... ok
test test_post_batch_request ... ok
test test_post_single_request_returns_single_response ... ok
test test_post_tools_list ... ok
test test_unknown_method ... ok
test test_post_payload_too_large ... ok

test result: ok. 10 passed; 0 failed; 0 ignored

Usage

# Start MCP server with HTTP+SSE transport (loopback, no auth)
pdftract mcp --bind 127.0.0.1:8080

# Start with auth token required
pdftract mcp --bind 0.0.0.0:3000 --auth-token-file /path/to/token.txt

# Custom upload limit
pdftract mcp --bind 127.0.0.1:8080 --max-upload-mb 512

Integration Points

  • Reuses crate::mcp::framing JSON-RPC types (from bead 6.7.1)
  • Reuses crate::mcp::auth bearer token resolution (from bead 6.7.7)
  • Reuses crate::mcp::bind TH-03 security checks (from bead 6.7.7)
  • SSE notifications broadcast via tokio::sync::broadcast

References