Metadata-Version: 2.4
Name: db2st-mcp
Version: 0.0.1
Summary: Database-to-Structured-Tools MCP server. Horizontally scalable, auth-gated, Knative-deployable.
Project-URL: Homepage, https://github.com/AlexisMarasigan/db2st-mcp
Project-URL: Documentation, https://github.com/AlexisMarasigan/db2st-mcp#readme
Project-URL: Source, https://github.com/AlexisMarasigan/db2st-mcp
Project-URL: Changelog, https://github.com/AlexisMarasigan/db2st-mcp/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/AlexisMarasigan/db2st-mcp/issues
Project-URL: Bug reports, https://github.com/AlexisMarasigan/db2st-mcp/issues/new?template=bug_report.md
Project-URL: Security, https://github.com/AlexisMarasigan/db2st-mcp/security/policy
Author-email: Alexis <alexismarasigan31@gmail.com>
License: MIT
License-File: LICENSE
Keywords: knative,mcp,model-context-protocol,schenker,shipment-tracking
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: fastapi>=0.115.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.2.0
Requires-Dist: pydantic-settings>=2.6.0
Requires-Dist: pydantic>=2.9.0
Requires-Dist: python-ulid>=3.0.0
Requires-Dist: structlog>=24.4.0
Requires-Dist: uvicorn[standard]>=0.32.0
Provides-Extra: fallback
Requires-Dist: playwright>=1.48.0; extra == 'fallback'
Provides-Extra: otel
Requires-Dist: opentelemetry-api>=1.27.0; extra == 'otel'
Requires-Dist: opentelemetry-exporter-otlp>=1.27.0; extra == 'otel'
Requires-Dist: opentelemetry-instrumentation-fastapi>=0.48b0; extra == 'otel'
Requires-Dist: opentelemetry-instrumentation-httpx>=0.48b0; extra == 'otel'
Requires-Dist: opentelemetry-sdk>=1.27.0; extra == 'otel'
Provides-Extra: redis
Requires-Dist: upstash-redis>=1.2.0; extra == 'redis'
Description-Content-Type: text/markdown

# DB2ST MCP

**Database-to-Structured-Tools MCP server.** A horizontally scalable Model Context Protocol server that exposes shipment tracking (and, by design, other data sources) as authenticated MCP tools. Built in Python, deployable as a Knative Function.

The first tool wraps DB Schenker's public shipment tracking endpoint. The shape of the codebase is built so additional carriers, databases, or third-party endpoints slot in behind the same transport, auth, and scaling primitives.

## Quickstart

```bash
uv sync --group dev              # install deps
cp .env.example .env             # configure
uv run db2st-mcp serve           # start HTTP server on :8080
uv run pytest                    # unit suite (integration tests deselected)
uv run pytest -m integration     # live upstream — needs unblocked egress IP
uv run pytest tests/e2e --report # E2E + Markdown report
```

## Use as a local Claude Code MCP

```bash
# from the repo root
uv sync --group dev --extra fallback   # extra installs Playwright
uv run playwright install chromium     # download the browser driver
claude mcp add db2st-mcp -s user \
  -e TOKEN_STORE=memory \
  -e DB2ST_HTML_FALLBACK=1 \
  -- uv --directory "$(pwd)" run db2st-mcp stdio

# verify
claude mcp list | grep db2st-mcp   # should show: ✓ Connected
```

`DB2ST_HTML_FALLBACK=1` enables the Playwright-based SPA scrape that
takes over when the upstream JSON path is rate-limited — which it
usually is from a fresh egress IP. Without the fallback, expect
`shipment not found` on most first-call attempts. The `[fallback]`
extra is what installs Playwright; see
[CONTRIBUTING.md](CONTRIBUTING.md#optional-extras-projectoptional-dependencies)
for the full list of optional extras.

Then ask Claude Code to track a shipment, e.g. `track DSV shipment 1806203236`.

Two MCP tools are registered:

| Tool | Returns |
|---|---|
| `track_shipment` | Full structured shipment (sender, receiver, package, history). |
| `track_shipment_events` | Just the chronological events timeline — lighter for poll-style clients. |

> Claude Code caches the MCP tool list per session. If you added this
> MCP before both tools were registered, restart Claude Code (or
> `claude mcp remove db2st-mcp -s user` and re-add) so the second
> tool is exposed. The same applies after pulling new code: the
> stdio subprocess holds whatever was on disk at `claude mcp add`
> time, so source changes (bug fixes, new tools) don't propagate
> until the next add.

Want to see the raw JSON-RPC handshake + a `tools/call` exchange without
involving Claude Code? Run the example client:

```bash
uv run python scripts/example_call.py 1806203236
```

## Use as a deployed MCP (HTTP + auth)

```bash
# 1. start the server
uv run db2st-mcp serve

# 2. mint a token (one-time, secret is shown once)
uv run db2st-mcp mint --plan pro --limit 10000

# 3. call the MCP transport at /mcp with the bearer token.
#    Streamable HTTP requires the Accept header to list both types.

# 3a. Full shipment record:
curl https://your-host/mcp/ \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"track_shipment","arguments":{"reference":"1806203236"}}}'

# 3b. Events timeline only (lighter — for poll-style clients):
curl https://your-host/mcp/ \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"track_shipment_events","arguments":{"reference":"1806203236"}}}'
```

## Architecture

See [ARCHITECTURE.md](ARCHITECTURE.md) for system architecture and domain documentation.

## Testing

See [docs/TESTING.md](docs/TESTING.md) for the unit/integration/e2e split,
coverage gates, and CI workflows.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) and [CLAUDE.md](CLAUDE.md).

## License

MIT
