fipsign-mcp 0.1.0__py3-none-any.whl

fipsign_mcp/__init__.py

@@ -0,0 +1,11 @@
+"""
+fipsign-mcp — MCP server for FIPSign post-quantum signing API.
+
+Run with:
+    python -m fipsign_mcp.server
+
+Or via the installed entry point:
+    fipsign-mcp
+"""
+
+__version__ = "0.1.0"

fipsign_mcp/server.py

@@ -0,0 +1,712 @@
+"""
+fipsign_mcp.server — MCP server for FIPSign post-quantum signing API.
+
+Exposes 15 tools covering the full FIPSign runtime API:
+signing, verification, revocation, usage, CA certificate lifecycle,
+key pair generation, and webhook management.
+
+Configuration (environment variables):
+    FIPSIGN_API_KEY   — required for most tools (pqa_ + 64 hex chars)
+    FIPSIGN_BASE_URL  — optional, defaults to https://api.fipsign.dev
+
+Transport: stdio (compatible with Claude Desktop and Claude Code)
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import os
+import sys
+from typing import Any
+
+import httpx
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+from mcp.types import (
+    CallToolResult,
+    TextContent,
+    Tool,
+)
+
+# ─── Configuration ────────────────────────────────────────────────────────────
+
+API_KEY  = os.environ.get("FIPSIGN_API_KEY", "")
+BASE_URL = os.environ.get("FIPSIGN_BASE_URL", "https://api.fipsign.dev").rstrip("/")
+
+# ─── HTTP helper ──────────────────────────────────────────────────────────────
+
+async def api_request(
+    method: str,
+    path: str,
+    body: Any = None,
+) -> tuple[bool, Any]:
+    """
+    Make an authenticated request to the FIPSign API.
+    Returns (ok: bool, data: Any).
+    """
+    headers: dict[str, str] = {"Content-Type": "application/json"}
+    if API_KEY:
+        headers["X-API-Key"] = API_KEY
+
+    async with httpx.AsyncClient(timeout=30.0) as client:
+        try:
+            response = await client.request(
+                method,
+                f"{BASE_URL}{path}",
+                headers=headers,
+                content=json.dumps(body).encode() if body is not None else None,
+            )
+            try:
+                data = response.json()
+            except Exception:
+                data = {"success": False, "error": f"HTTP {response.status_code} — non-JSON response"}
+            return response.is_success, data
+        except httpx.TimeoutException:
+            return False, {"success": False, "error": "Request timed out after 30 seconds"}
+        except httpx.NetworkError as exc:
+            return False, {"success": False, "error": f"Network error: {exc}"}
+
+# ─── Key pair generation ──────────────────────────────────────────────────────
+
+def _generate_key_pair() -> dict[str, Any]:
+    """
+    Generate an ML-DSA-65 key pair using pyca/cryptography >= 48.0.0.
+    Returns publicKey (base64, 1952 bytes) and secretKey (base64, 32-byte seed).
+    """
+    try:
+        from cryptography.hazmat.primitives.asymmetric.mldsa import MLDSA65PrivateKey
+    except ImportError:
+        raise RuntimeError(
+            "generate_key_pair requires cryptography >= 48.0.0. "
+            "Install with: pip install 'cryptography>=48.0.0'"
+        )
+
+    private_key = MLDSA65PrivateKey.generate()
+    public_key  = private_key.public_key()
+
+    pub_b64  = base64.b64encode(public_key.public_bytes_raw()).decode()
+    seed_b64 = base64.b64encode(private_key.private_bytes_raw()).decode()
+
+    return {
+        "publicKey": pub_b64,
+        "secretKey": seed_b64,
+        "algorithm": "ML-DSA-65",
+        "standard":  "NIST FIPS 204",
+        "sizes": {
+            "publicKeyBytes": len(public_key.public_bytes_raw()),
+            "secretKeyBytes": len(private_key.private_bytes_raw()),
+            "note": "secretKey is the 32-byte seed form (Python SDK convention). The publicKey is 1952 bytes — compatible with fipsign_ca_issue and the JS SDK.",
+        },
+        "note": "Store secretKey securely on the device. Never send it to any server. Pass publicKey to fipsign_ca_issue.",
+    }
+
+# ─── Response helpers ─────────────────────────────────────────────────────────
+
+def _ok(data: Any) -> CallToolResult:
+    return CallToolResult(
+        content=[TextContent(type="text", text=json.dumps(data, indent=2))]
+    )
+
+def _err(message: str, detail: Any = None) -> CallToolResult:
+    payload: dict[str, Any] = {"error": message}
+    if detail is not None:
+        payload["detail"] = detail
+    return CallToolResult(
+        content=[TextContent(type="text", text=json.dumps(payload, indent=2))],
+        isError=True,
+    )
+
+def _missing_api_key() -> CallToolResult:
+    return _err(
+        "FIPSIGN_API_KEY is not set. "
+        "Export it before starting the server: export FIPSIGN_API_KEY=pqa_..."
+    )
+
+# ─── Tool definitions ─────────────────────────────────────────────────────────
+
+TOOLS: list[Tool] = [
+    # ── Infrastructure ─────────────────────────────────────────────────────────
+
+    Tool(
+        name="fipsign_health",
+        description=(
+            "Check the health of the FIPSign service. Returns the service status, "
+            "algorithm (ML-DSA-65), NIST standard, and version. No API key required. "
+            "Use this to verify the service is reachable before running other operations."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {},
+            "required": [],
+        },
+    ),
+
+    Tool(
+        name="fipsign_public_key",
+        description=(
+            "Get the current ML-DSA-65 public key of the FIPSign server. Returns a "
+            "base64-encoded 1952-byte public key. Use this when you need to verify token "
+            "signatures independently without calling the /verify endpoint (e.g. for "
+            "offline verification or third-party auditing). No API key required."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {},
+            "required": [],
+        },
+    ),
+
+    # ── Core signing ────────────────────────────────────────────────────────────
+
+    Tool(
+        name="fipsign_sign",
+        description=(
+            "Sign any payload with ML-DSA-65 (NIST FIPS 204). The only required field is "
+            "'sub' — any string identifying the entity being signed: a user ID, order ID, "
+            "document hash, device serial, AI agent action, or anything else. All other "
+            "fields are stored in the payload and returned on verify. Costs 1 token. "
+            "Returns the signed token object (payload, signature, algorithm, issuedAt) "
+            "plus usage info."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "sub": {
+                    "type": "string",
+                    "description": (
+                        "Required. Entity identifier. Max 128 characters. "
+                        "Examples: 'user_123', 'order_456', 'doc_hash_abc', "
+                        "'device_serial_001', 'agent_action_summarize'."
+                    ),
+                },
+                "expiresInSeconds": {
+                    "type": "number",
+                    "description": (
+                        "Token lifetime in seconds. Default: 3600 (1 hour). "
+                        "Pass a larger value for long-lived tokens (e.g. document signatures: "
+                        "365 * 24 * 3600)."
+                    ),
+                },
+            },
+            "required": ["sub"],
+            "additionalProperties": {
+                "description": (
+                    "Any additional custom fields to embed in the payload. "
+                    "Max 10 extra fields, string values max 256 chars."
+                ),
+            },
+        },
+    ),
+
+    Tool(
+        name="fipsign_verify",
+        description=(
+            "Verify a FIPSign token signed with ML-DSA-65. Checks the cryptographic "
+            "signature, expiry, and revocation list. Returns valid:true with the decoded "
+            "payload on success, or valid:false with an error message on failure. "
+            "Never throws — always returns a result. Costs 1 token."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "token": {
+                    "type": "object",
+                    "description": (
+                        "The token object returned by fipsign_sign. "
+                        "Must have: payload (string), signature (string), "
+                        "algorithm (string), issuedAt (number)."
+                    ),
+                    "properties": {
+                        "payload":   {"type": "string"},
+                        "signature": {"type": "string"},
+                        "algorithm": {"type": "string"},
+                        "issuedAt":  {"type": "number"},
+                    },
+                    "required": ["payload", "signature", "algorithm", "issuedAt"],
+                },
+            },
+            "required": ["token"],
+        },
+    ),
+
+    Tool(
+        name="fipsign_revoke",
+        description=(
+            "Permanently revoke a token. Once revoked, all future verify() calls will "
+            "reject the token even if its signature is valid and it has not expired. "
+            "Idempotent: revoking an already-revoked token returns success without "
+            "consuming an extra token. Costs 1 token. "
+            "Note: calling this on an already-expired token returns an error (400)."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "token": {
+                    "type": "object",
+                    "description": "The token object to revoke. Must have: payload, signature, algorithm, issuedAt.",
+                    "properties": {
+                        "payload":   {"type": "string"},
+                        "signature": {"type": "string"},
+                        "algorithm": {"type": "string"},
+                        "issuedAt":  {"type": "number"},
+                    },
+                    "required": ["payload", "signature", "algorithm", "issuedAt"],
+                },
+                "reason": {
+                    "type": "string",
+                    "description": (
+                        "Optional human-readable reason stored server-side. "
+                        "Examples: 'user logged out', 'order cancelled', "
+                        "'suspicious activity detected'."
+                    ),
+                },
+            },
+            "required": ["token"],
+        },
+    ),
+
+    # ── Account ─────────────────────────────────────────────────────────────────
+
+    Tool(
+        name="fipsign_usage",
+        description=(
+            "Get the current token balance and 6-month usage history for this API key's "
+            "account. Returns free tokens remaining (resets monthly), pack tokens remaining "
+            "(never expire), total remaining, and a monthly breakdown. "
+            "Free — no token cost. Use before batch operations to confirm sufficient balance."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {},
+            "required": [],
+        },
+    ),
+
+    # ── Key generation ──────────────────────────────────────────────────────────
+
+    Tool(
+        name="fipsign_generate_key_pair",
+        description=(
+            "Generate an ML-DSA-65 key pair locally (no API call, no token cost). "
+            "Returns a base64-encoded public key (1952 bytes) and secret key (32-byte seed). "
+            "Use the publicKey when calling fipsign_ca_issue to certify a device or entity. "
+            "SECURITY WARNING: the secretKey is sensitive — store it securely on the device "
+            "and never send it to any server. The secretKey will appear in this tool's "
+            "response; treat it like a private key.\n\n"
+            "Note: The Python SDK returns the secretKey as a 32-byte seed (base64). "
+            "This differs from the JS SDK which returns a 4032-byte expanded key. "
+            "Both publicKeys (1952 bytes) are fully interoperable with the FIPSign backend."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {},
+            "required": [],
+        },
+    ),
+
+    # ── Certificate Authority ───────────────────────────────────────────────────
+
+    Tool(
+        name="fipsign_ca_issue",
+        description=(
+            "Issue a post-quantum certificate signed by the project's CA. The certificate "
+            "certifies that the entity identified by 'subject' controls the given ML-DSA-65 "
+            "public key. Supports both PQCert (native JSON) and X.509 (standard PEM) CA "
+            "formats — the format is determined by which CA type was created in the "
+            "dashboard. For PQCert CAs, the response includes a certificate JSON object. "
+            "For X.509 CAs, it includes a PEM string. Costs 1 token.\n\n"
+            "Required: subject (entity name/ID), publicKey (base64 ML-DSA-65 public key — "
+            "generate with fipsign_generate_key_pair), expiresInSeconds "
+            "(min 60, max 157680000 = 5 years).\n\n"
+            "Optional: meta (up to 10 key-value pairs — PQCert CAs only; passing meta "
+            "to an X.509 CA returns a 400 error).\n\n"
+            "The returned certId (in meta.certId) is what you need for "
+            "fipsign_ca_revoke_cert and fipsign_ca_get_cert."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "subject": {
+                    "type": "string",
+                    "description": (
+                        "Entity identifier to certify. Examples: 'device-serial-00123', "
+                        "'service-payment-processor', 'lock-v3-batch-2026'. Max 256 characters."
+                    ),
+                },
+                "publicKey": {
+                    "type": "string",
+                    "description": (
+                        "Base64-encoded ML-DSA-65 public key of the entity to certify "
+                        "(1952 bytes decoded). Generate with fipsign_generate_key_pair."
+                    ),
+                },
+                "expiresInSeconds": {
+                    "type": "number",
+                    "description": (
+                        "Certificate lifetime in seconds. Min: 60 (1 minute). "
+                        "Max: 157680000 (5 years). Example: 31536000 = 1 year."
+                    ),
+                },
+                "meta": {
+                    "type": "object",
+                    "description": (
+                        "Optional custom key-value pairs to embed in the certificate "
+                        "(PQCert CAs only — returns 400 for X.509 CAs). Max 10 keys. "
+                        'Example: {"model": "lock-v3", "batch": "2026-05"}.'
+                    ),
+                    "additionalProperties": True,
+                },
+            },
+            "required": ["subject", "publicKey", "expiresInSeconds"],
+        },
+    ),
+
+    Tool(
+        name="fipsign_ca_revoke_cert",
+        description=(
+            "Revoke a certificate immediately. From this point on, the certificate will "
+            "appear in the CRL returned by fipsign_ca_get_crl. Use fipsign_ca_get_cert to "
+            "check real-time revocation status of a single certificate. Costs 1 token. "
+            "Returns 409 if the certificate is already revoked."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "certId": {
+                    "type": "string",
+                    "description": (
+                        "The certificate ID to revoke (cert_...). "
+                        "For PQCert: the 'id' field of the certificate object. "
+                        "For X.509: the 'certId' field from meta returned by fipsign_ca_issue."
+                    ),
+                },
+                "reason": {
+                    "type": "string",
+                    "description": (
+                        "Optional reason for revocation. Max 256 characters. "
+                        "Examples: 'device decommissioned', 'device reported stolen', "
+                        "'key compromise'."
+                    ),
+                },
+            },
+            "required": ["certId"],
+        },
+    ),
+
+    Tool(
+        name="fipsign_ca_get_cert",
+        description=(
+            "Get a certificate by ID and its current real-time status "
+            "(revoked, expired, revokedAt, expiresAt). Use this for single certificate "
+            "checks before authorizing high-value operations. For bulk offline revocation "
+            "checks across many certificates, use fipsign_ca_get_crl instead. "
+            "Free — no token cost."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "certId": {
+                    "type": "string",
+                    "description": (
+                        "The certificate ID (cert_...). "
+                        "For PQCert: certificate.id. "
+                        "For X.509: meta.certId from fipsign_ca_issue."
+                    ),
+                },
+            },
+            "required": ["certId"],
+        },
+    ),
+
+    Tool(
+        name="fipsign_ca_get_crl",
+        description=(
+            "Get the Certificate Revocation List (CRL) for this project's CA. Returns all "
+            "revoked certificate IDs with their revocation timestamps and reasons. Use this "
+            "to check revocation status of multiple certificates offline — download once, "
+            "check locally. For a single certificate's real-time status use "
+            "fipsign_ca_get_cert instead. Free — no token cost. For X.509 CAs the CRL is "
+            "signed with ML-DSA-65 and includes the full signed object in the 'raw' field."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {},
+            "required": [],
+        },
+    ),
+
+    # ── Webhooks ─────────────────────────────────────────────────────────────────
+
+    Tool(
+        name="fipsign_webhooks_register",
+        description=(
+            "Register or update a webhook endpoint that will receive real-time event "
+            "notifications. Available events: 'token.signed', 'token.rejected', "
+            "'token.revoked', 'limit.warning' (fired at 20% free tokens remaining), "
+            "'limit.reached' (fired when free tokens are exhausted). If omitted, all events "
+            "are subscribed. Re-registering an existing webhook updates the URL and events "
+            "but preserves the original secret — to rotate the secret, delete and "
+            "re-register. The 'secret' field in the response is shown only once — store it "
+            "securely to verify incoming request signatures via HMAC-SHA256 on the "
+            "X-PQAuth-Signature header."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "url": {
+                    "type": "string",
+                    "description": (
+                        "HTTPS endpoint that will receive POST requests. Must be a valid "
+                        "HTTPS URL accessible from the internet. "
+                        "Example: 'https://yourapp.com/webhooks/fipsign'."
+                    ),
+                },
+                "events": {
+                    "type": "array",
+                    "items": {
+                        "type": "string",
+                        "enum": [
+                            "token.signed",
+                            "token.rejected",
+                            "token.revoked",
+                            "limit.warning",
+                            "limit.reached",
+                        ],
+                    },
+                    "description": (
+                        "Optional list of events to subscribe to. "
+                        "Defaults to all events if omitted."
+                    ),
+                },
+            },
+            "required": ["url"],
+        },
+    ),
+
+    Tool(
+        name="fipsign_webhooks_get",
+        description=(
+            "Get the current webhook configuration (URL, subscribed events, active status, "
+            "creation timestamp). The webhook secret is never returned after initial "
+            "registration — only the URL and event list. Returns null webhook if no webhook "
+            "has been registered."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {},
+            "required": [],
+        },
+    ),
+
+    Tool(
+        name="fipsign_webhooks_delete",
+        description=(
+            "Delete the current webhook configuration. After deletion, no events will be "
+            "delivered until a new webhook is registered via fipsign_webhooks_register."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {},
+            "required": [],
+        },
+    ),
+
+    Tool(
+        name="fipsign_webhooks_test",
+        description=(
+            "Send a test 'token.signed' event to the registered webhook endpoint. Use this "
+            "immediately after registering a webhook to confirm delivery is working before "
+            "relying on it in production. Requires a webhook to be registered first."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {},
+            "required": [],
+        },
+    ),
+]
+
+# ─── Tool handlers ────────────────────────────────────────────────────────────
+
+async def handle_tool(name: str, args: dict[str, Any]) -> CallToolResult:
+    # Tools that don't require API key
+    if name == "fipsign_health":
+        ok, data = await api_request("GET", "/health")
+        return _ok(data)
+
+    if name == "fipsign_public_key":
+        ok, data = await api_request("GET", "/public-key")
+        return _ok(data)
+
+    if name == "fipsign_generate_key_pair":
+        try:
+            result = _generate_key_pair()
+            return _ok(result)
+        except RuntimeError as exc:
+            return _err(str(exc))
+
+    # All remaining tools require API key
+    if not API_KEY:
+        return _missing_api_key()
+
+    if name == "fipsign_sign":
+        sub = args.get("sub")
+        if not sub or not isinstance(sub, str):
+            return _err('"sub" is required and must be a string')
+        body: dict[str, Any] = {k: v for k, v in args.items() if k != "expiresInSeconds"}
+        if "expiresInSeconds" in args:
+            body["expiresInSeconds"] = args["expiresInSeconds"]
+        ok_flag, data = await api_request("POST", "/sign", body)
+        if not ok_flag:
+            return _err("Sign failed", data)
+        return _ok(data)
+
+    if name == "fipsign_verify":
+        token = args.get("token")
+        if not token or not isinstance(token, dict):
+            return _err('"token" is required and must be the token object returned by fipsign_sign')
+        ok_flag, data = await api_request("POST", "/verify", {"token": token})
+        # verify returns valid:false on failure — not necessarily an HTTP error
+        return _ok(data)
+
+    if name == "fipsign_revoke":
+        token = args.get("token")
+        if not token or not isinstance(token, dict):
+            return _err('"token" is required and must be the token object returned by fipsign_sign')
+        body = {"token": token}
+        if "reason" in args:
+            body["reason"] = args["reason"]
+        ok_flag, data = await api_request("POST", "/revoke", body)
+        if not ok_flag:
+            return _err("Revoke failed", data)
+        return _ok(data)
+
+    if name == "fipsign_usage":
+        ok_flag, data = await api_request("GET", "/usage")
+        if not ok_flag:
+            return _err("Usage request failed", data)
+        return _ok(data)
+
+    if name == "fipsign_ca_issue":
+        subject = args.get("subject")
+        public_key = args.get("publicKey")
+        expires_in_seconds = args.get("expiresInSeconds")
+
+        if not subject or not isinstance(subject, str):
+            return _err('"subject" is required')
+        if not public_key or not isinstance(public_key, str):
+            return _err('"publicKey" is required — generate one with fipsign_generate_key_pair')
+        if not isinstance(expires_in_seconds, (int, float)):
+            return _err('"expiresInSeconds" is required and must be a number (min 60, max 157680000)')
+
+        body = {
+            "subject":          subject,
+            "publicKey":        public_key,
+            "expiresInSeconds": expires_in_seconds,
+        }
+        if "meta" in args:
+            body["meta"] = args["meta"]
+
+        ok_flag, data = await api_request("POST", "/ca/issue", body)
+        if not ok_flag:
+            return _err("CA issue failed", data)
+        return _ok(data)
+
+    if name == "fipsign_ca_revoke_cert":
+        cert_id = args.get("certId")
+        if not cert_id or not isinstance(cert_id, str):
+            return _err('"certId" is required')
+        body = {"certId": cert_id}
+        if "reason" in args:
+            body["reason"] = args["reason"]
+        ok_flag, data = await api_request("POST", "/ca/revoke", body)
+        if not ok_flag:
+            return _err("CA revoke failed", data)
+        return _ok(data)
+
+    if name == "fipsign_ca_get_cert":
+        cert_id = args.get("certId")
+        if not cert_id or not isinstance(cert_id, str):
+            return _err('"certId" is required')
+        ok_flag, data = await api_request("GET", f"/ca/certificate/{cert_id}")
+        if not ok_flag:
+            return _err("CA get cert failed", data)
+        return _ok(data)
+
+    if name == "fipsign_ca_get_crl":
+        ok_flag, data = await api_request("GET", "/ca/crl")
+        if not ok_flag:
+            return _err("CA get CRL failed", data)
+        return _ok(data)
+
+    if name == "fipsign_webhooks_register":
+        url = args.get("url")
+        if not url or not isinstance(url, str):
+            return _err('"url" is required')
+        body = {"url": url}
+        if "events" in args:
+            body["events"] = args["events"]
+        ok_flag, data = await api_request("POST", "/webhooks", body)
+        if not ok_flag:
+            return _err("Webhook register failed", data)
+        return _ok(data)
+
+    if name == "fipsign_webhooks_get":
+        ok_flag, data = await api_request("GET", "/webhooks")
+        if not ok_flag:
+            return _err("Webhook get failed", data)
+        return _ok(data)
+
+    if name == "fipsign_webhooks_delete":
+        ok_flag, data = await api_request("DELETE", "/webhooks")
+        if not ok_flag:
+            return _err("Webhook delete failed", data)
+        return _ok(data)
+
+    if name == "fipsign_webhooks_test":
+        ok_flag, data = await api_request("POST", "/webhooks/test")
+        if not ok_flag:
+            return _err("Webhook test failed", data)
+        return _ok(data)
+
+    return _err(f"Unknown tool: {name}")
+
+# ─── Server setup ─────────────────────────────────────────────────────────────
+
+app = Server("fipsign-mcp")
+
+
+@app.list_tools()
+async def list_tools() -> list[Tool]:
+    return TOOLS
+
+
+@app.call_tool()
+async def call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent]:
+    try:
+        result = await handle_tool(name, arguments or {})
+        return result.content  # type: ignore[return-value]
+    except Exception as exc:
+        error_result = _err(f"Unexpected error in tool '{name}': {exc}")
+        return error_result.content  # type: ignore[return-value]
+
+
+# ─── Entry point ─────────────────────────────────────────────────────────────
+
+def main() -> None:
+    import asyncio
+
+    async def _run() -> None:
+        async with stdio_server() as (read_stream, write_stream):
+            await app.run(
+                read_stream,
+                write_stream,
+                app.create_initialization_options(),
+            )
+
+    asyncio.run(_run())
+
+
+if __name__ == "__main__":
+    main()

fipsign_mcp-0.1.0.dist-info/METADATA

@@ -0,0 +1,262 @@
+Metadata-Version: 2.4
+Name: fipsign-mcp
+Version: 0.1.0
+Summary: MCP server for FIPSign — post-quantum signing via ML-DSA-65 (NIST FIPS 204)
+Author-email: FIPSign <sdk@fipsign.dev>
+License-Expression: MIT
+Project-URL: Homepage, https://fipsign.dev
+Project-URL: Dashboard, https://app.fipsign.dev
+Project-URL: Repository, https://github.com/fipsign/fipsign-mcp-python
+Keywords: mcp,model-context-protocol,fipsign,post-quantum,ml-dsa,signing,cryptography,nist,fips-204
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security :: Cryptography
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: cryptography>=48.0.0
+Requires-Dist: httpx>=0.24
+Dynamic: license-file
+
+# fipsign-mcp
+
+[![PyPI](https://img.shields.io/pypi/v/fipsign-mcp)](https://pypi.org/project/fipsign-mcp/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![NIST FIPS 204](https://img.shields.io/badge/NIST-FIPS%20204-blue)](https://csrc.nist.gov/pubs/fips/204/final)
+
+MCP server for [FIPSign](https://fipsign.dev) — post-quantum digital signing via **ML-DSA-65** (NIST FIPS 204).
+
+Gives Claude Desktop, Claude Code, and any MCP-compatible AI agent full access to the FIPSign API without writing code: sign payloads, verify tokens, issue and revoke post-quantum certificates, manage webhooks, and monitor usage.
+
+---
+
+## Tools
+
+| Tool | Description | Token cost |
+|---|---|---|
+| `fipsign_health` | Check service status | free |
+| `fipsign_public_key` | Get the server's ML-DSA-65 public key | free |
+| `fipsign_sign` | Sign any payload | 1 token |
+| `fipsign_verify` | Verify a signed token | 1 token |
+| `fipsign_revoke` | Permanently revoke a token | 1 token |
+| `fipsign_usage` | Get token balance and usage history | free |
+| `fipsign_generate_key_pair` | Generate an ML-DSA-65 key pair locally | free |
+| `fipsign_ca_issue` | Issue a post-quantum certificate | 1 token |
+| `fipsign_ca_revoke_cert` | Revoke a certificate | 1 token |
+| `fipsign_ca_get_cert` | Get certificate status by ID | free |
+| `fipsign_ca_get_crl` | Get the Certificate Revocation List | free |
+| `fipsign_webhooks_register` | Register a webhook endpoint | free |
+| `fipsign_webhooks_get` | Get current webhook config | free |
+| `fipsign_webhooks_delete` | Delete webhook configuration | free |
+| `fipsign_webhooks_test` | Send a test event to your webhook | free |
+
+---
+
+## Prerequisites
+
+1. Python 3.10 or later
+2. A FIPSign account and API key — [create one free at app.fipsign.dev](https://app.fipsign.dev)
+3. For CA tools: a CA created inside your project from the dashboard
+
+---
+
+## Local testing before publishing
+
+### Level 1 — MCP Inspector (no Claude Desktop required)
+
+The Inspector opens a browser UI where you can call each tool manually and inspect responses without Claude Desktop.
+
+```bash
+git clone https://github.com/fipsign/fipsign-mcp-python
+cd fipsign-mcp-python
+pip install -e .
+export FIPSIGN_API_KEY=pqa_your_real_key
+npx @modelcontextprotocol/inspector python -m fipsign_mcp.server
+```
+
+Open the URL shown in the terminal (typically `http://localhost:5173`). Select a tool, fill in the parameters, and run it.
+
+### Level 2 — Claude Desktop with local code (without publishing to PyPI)
+
+Install in editable mode, then point Claude Desktop at the module:
+
+```bash
+pip install -e .
+```
+
+Add to your `claude_desktop_config.json` (see path below):
+
+```json
+{
+  "mcpServers": {
+    "fipsign": {
+      "command": "python",
+      "args": ["-m", "fipsign_mcp.server"],
+      "env": {
+        "FIPSIGN_API_KEY": "pqa_your_real_key"
+      }
+    }
+  }
+}
+```
+
+### Level 3 — Claude Desktop with published package (production)
+
+```json
+{
+  "mcpServers": {
+    "fipsign": {
+      "command": "uvx",
+      "args": ["fipsign-mcp"],
+      "env": {
+        "FIPSIGN_API_KEY": "pqa_your_real_key"
+      }
+    }
+  }
+}
+```
+
+Or with pip-installed package:
+
+```json
+{
+  "mcpServers": {
+    "fipsign": {
+      "command": "fipsign-mcp",
+      "env": {
+        "FIPSIGN_API_KEY": "pqa_your_real_key"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Installation for Claude Desktop
+
+`claude_desktop_config.json` is located at:
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+- **Linux:** `~/.config/Claude/claude_desktop_config.json`
+
+Add the `fipsign` entry inside `mcpServers` (create the file if it doesn't exist):
+
+```json
+{
+  "mcpServers": {
+    "fipsign": {
+      "command": "uvx",
+      "args": ["fipsign-mcp"],
+      "env": {
+        "FIPSIGN_API_KEY": "pqa_your_real_key"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop after editing the config.
+
+---
+
+## Installation for Claude Code
+
+```bash
+claude mcp add fipsign -- env FIPSIGN_API_KEY=pqa_your_real_key uvx fipsign-mcp
+```
+
+Or manually in your project's `.claude/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "fipsign": {
+      "command": "uvx",
+      "args": ["fipsign-mcp"],
+      "env": {
+        "FIPSIGN_API_KEY": "pqa_your_real_key"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Environment variables
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `FIPSIGN_API_KEY` | Yes (for most tools) | — | Your FIPSign API key. Format: `pqa_` + 64 lowercase hex chars. Get one at app.fipsign.dev. |
+| `FIPSIGN_BASE_URL` | No | `https://api.fipsign.dev` | Override API base URL (useful for self-hosted instances or local dev). |
+
+`fipsign_health`, `fipsign_public_key`, and `fipsign_generate_key_pair` work without an API key.
+
+---
+
+## Key pair generation — Python vs JS SDK note
+
+`fipsign_generate_key_pair` returns the `secretKey` as the **32-byte ML-DSA-65 seed** (base64), not the 4032-byte expanded key returned by the JS SDK's `generateKeyPair()`. The `publicKey` (1952 bytes) is identical in both SDKs and fully compatible with `fipsign_ca_issue`.
+
+This difference only matters if you need to sign data locally on a Python device using the returned `secretKey`:
+
+```python
+from cryptography.hazmat.primitives.asymmetric.mldsa import MLDSA65PrivateKey
+import base64
+
+private_key = MLDSA65PrivateKey.from_seed_bytes(base64.b64decode(secret_key))
+signature   = private_key.sign(message)
+```
+
+---
+
+## Usage examples
+
+Once configured, you can ask Claude:
+
+**Signing:**
+- *"Sign a token for user_123 with role admin that expires in 1 hour"*
+- *"Verify this token: { payload: '...', signature: '...', algorithm: 'ML-DSA-65', issuedAt: 123 }"*
+- *"Revoke this token because the user logged out"*
+
+**Certificates:**
+- *"Generate a key pair for a new IoT device"*
+- *"Issue a certificate for device-serial-00123 using the public key I just generated, valid for 1 year"*
+- *"Check the revocation status of cert_abc123"*
+- *"Get the full CRL for our CA"*
+- *"Revoke certificate cert_abc123 — device was reported stolen"*
+
+**Monitoring:**
+- *"How many tokens do I have left this month?"*
+- *"Register a webhook at https://myapp.com/hooks/fipsign for limit.warning and limit.reached events"*
+- *"Send a test event to my webhook"*
+
+---
+
+## Publishing to PyPI
+
+```bash
+pip install build twine
+python -m build
+twine upload dist/*
+```
+
+---
+
+## Links
+
+- Dashboard: [app.fipsign.dev](https://app.fipsign.dev)
+- API status: [status.fipsign.dev](https://status.fipsign.dev)
+- JS SDK: [npmjs.com/package/fipsign-sdk](https://www.npmjs.com/package/fipsign-sdk)
+- Python SDK: [pypi.org/project/fipsign-sdk](https://pypi.org/project/fipsign-sdk/)
+- TypeScript MCP: [npmjs.com/package/@fipsign/mcp](https://www.npmjs.com/package/@fipsign/mcp)
+- NIST FIPS 204: [csrc.nist.gov/pubs/fips/204/final](https://csrc.nist.gov/pubs/fips/204/final)

fipsign_mcp-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+fipsign_mcp/__init__.py,sha256=59OAldt0Vis4pgb3zp87Yab8wfwCWrtos14WLDDx_Yc,191
+fipsign_mcp/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fipsign_mcp/server.py,sha256=Gx3J4g_H7L9Uoh2YIhJpHZkXYhu79cmS6AazQo3n4GE,29377
+fipsign_mcp-0.1.0.dist-info/licenses/LICENSE,sha256=aNlBaMDkGDQQtmh1FVbJgnvhVGq-UMGhtfDzzi-6XCM,1064
+fipsign_mcp-0.1.0.dist-info/METADATA,sha256=qJBe4aOJPrsemaDMWyjzh8aqT48hDDWHrvmu-GqljwE,8031
+fipsign_mcp-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+fipsign_mcp-0.1.0.dist-info/entry_points.txt,sha256=YjTK90VHYOh4MFuXdQDtgn4bkPgfz0MRnilQSWDT2Yk,56
+fipsign_mcp-0.1.0.dist-info/top_level.txt,sha256=sNpdyHpiTYVkFcHsdseBNo0BPXsX6Sk0_ACOEJl3c_0,12
+fipsign_mcp-0.1.0.dist-info/RECORD,,

fipsign_mcp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

fipsign_mcp-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+fipsign-mcp = fipsign_mcp.server:main

fipsign_mcp-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FIPSign
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fipsign_mcp-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+fipsign_mcp