dcert (Python)

A Python MCP wrapper for the dcert Rust server.

The package uses FastMCP to run a transparent proxy around the dcert-mcp Rust binary and exposes all TLS certificate tools over the Model Context Protocol. Tools added to the Rust binary are discovered at runtime, so the Python layer never needs to change.

Requirements

• Python 3.12 or later
• The dcert-mcp Rust binary. Platform wheels bundle it; the universal wheel downloads it on first use after verifying its SHA256 checksum.

Installation

pip install dcert

Platform wheels exist for Linux x86_64 (glibc 2.35 or later), macOS Intel, macOS Apple Silicon and Windows x86_64. The universal wheel works everywhere else that a release archive exists for.

Quick start

As a server

from dcert import create_server

create_server().run()  # stdio transport

As a client

import asyncio
from dcert import create_client

async def main() -> None:
    async with create_client() as client:
        tools = await client.list_tools()
        result = await client.call_tool("analyze_certificate", {"target": "example.com"})
        print(len(tools), result)

asyncio.run(main())

Typed async tool functions

The functional API opens a session (a subprocess plus its resilience stack) and passes it to plain async functions:

import asyncio
from dcert import analyze_certificate, check_expiry, create_session, export_pem

async def main() -> None:
    async with create_session(timeout=60.0) as session:
        cert = await analyze_certificate(target="example.com", session=session)
        expiry = await check_expiry(target="example.com", days=90, session=session)
        pem = await export_pem(target="example.com", output_path="chain.pem", session=session)
        raw = await session.call("tls_connection_info", {"target": "example.com"})

asyncio.run(main())

Leaving out session uses a shared default session that is created on first use and reused afterwards; close_default_session() shuts it down.

The network facing functions accept the shared mTLS and connection options (client_cert, client_key, pkcs12, cert_password, ca_cert, connect_to, resolve, proxy, noproxy) as keyword arguments.

Error handling

from dcert import (
    DcertError,            # base class
    DcertTimeoutError,     # the call exceeded its timeout
    DcertConnectionError,  # the subprocess died or the circuit breaker is open
    DcertToolError,        # the tool returned an error result (has .tool)
)

Only transport failures are retried, with exponential backoff and full jitter. TypeError and ValueError surface immediately and cancellation is never swallowed.

Command line

dcert-python                                   # stdio (for MCP clients such as Claude Code)
dcert-python --transport http --port 8080      # HTTP; bind 0.0.0.0 only behind a gateway
dcert-python --setup                           # download the binary and exit
dcert-python --binary /usr/local/bin/dcert-mcp # explicit binary
dcert-python --rate-limit 20 --bulkhead-max 4  # resilience flags
dcert-python --help                            # every option

dcert and dcert-mcp are thin wrappers that exec the Rust binaries with all arguments.

Configuration

Defaults live in the packaged dcert/config.yaml: the release URL, download limits, the platform table, the environment variables forwarded to the subprocess, the server bind address and every resilience value. dcert.load_config() returns them as an immutable record.

Resilience values can be overridden with DCERT_MCP_* environment variables (listed in dcert/resilience.py) and the dcert-python flags override those.

The proxy reads each tool's MCP annotations before applying caching or retries:

• Caching (--cache) replays results only for tools marked read-only and idempotent. Tools that generate keys, issue or sign certificates, or change Vault state (create_csr, vault_issue, vault_sign, vault_renew, …) are always run.
• Retry after a transport failure applies only to read-only or idempotent tools. Any other call surfaces the error instead of running a second time, because the first attempt may already have issued a certificate.

Binary discovery

1. DCERT_MCP_BINARY (or DCERT_PATH for the dcert CLI)
2. The bundled binary in the package bin/ directory
3. A compiled dcert-mcp on PATH (pip console script wrappers are skipped)
4. Download from GitHub Releases: https only, redirects restricted to GitHub hosts, size capped, SHA256 verified before extraction, installed atomically under a lock

Environment variables forwarded to the binary

Development

cd python
pip install -e ".[dev]"
ruff check src tests ../scripts
ruff format --check src tests ../scripts
mypy
pytest

License

MIT