certindex-mcp 0.1.0__tar.gz

certindex_mcp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,47 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Test (py${{ matrix.python }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Lint
+        run: ruff check .
+      - name: Test
+        run: pytest -v
+
+  audit:
+    name: Dependency audit
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - name: Install pip-audit
+        run: pip install pip-audit
+      - name: Audit
+        run: pip-audit --strict -r <(python -c "import tomllib,sys;d=tomllib.load(open('pyproject.toml','rb'));print('\n'.join(d['project']['dependencies']))")

certindex_mcp-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.coverage
+dist/
+build/
+.venv/
+*.log

certindex_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CertIndex contributors
+
+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.

certindex_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: certindex-mcp
+Version: 0.1.0
+Summary: MCP server exposing CertIndex's Certificate Transparency search tools to any MCP-compatible client.
+Project-URL: Homepage, https://ctindex.io
+Project-URL: Documentation, https://github.com/certindex/certindex-mcp#readme
+Project-URL: Source, https://github.com/certindex/certindex-mcp
+Project-URL: Issues, https://github.com/certindex/certindex-mcp/issues
+Project-URL: Changelog, https://github.com/certindex/certindex-mcp/releases
+Author-email: CertIndex contributors <support@ctindex.io>
+License: MIT License
+        
+        Copyright (c) 2026 CertIndex contributors
+        
+        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.
+License-File: LICENSE
+Keywords: agent,certificate-transparency,certificates,claude,ct-logs,llm,mcp,model-context-protocol,security,tls
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Security
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp>=1.2.0
+Requires-Dist: pydantic>=2.6
+Provides-Extra: dev
+Requires-Dist: pip-audit>=2.7; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# certindex-mcp
+
+[![CI](https://github.com/certindex/certindex-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/certindex/certindex-mcp/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/certindex-mcp.svg)](https://pypi.org/project/certindex-mcp/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+An [MCP](https://modelcontextprotocol.io) (Model Context Protocol) server
+that exposes [CertIndex](https://ctindex.io)'s Certificate
+Transparency search tools to any MCP-compatible client (Claude
+Desktop, the MCP Inspector, Continue, etc.).
+
+CertIndex indexes the full public CT corpus (~5 M certificates, growing
+~100 k/day). This server wraps the public CertIndex REST API so an LLM
+can ask questions like:
+
+- "List every TLS certificate ever issued for `example.com`."
+- "What subdomains has Let's Encrypt seen for `mycompany.io`?"
+- "Show me certs expiring in the next 30 days for `api.mycompany.io`."
+- "Pull the full PEM and CT log metadata for SHA-256 `<fingerprint>`."
+
+## Why this repo exists
+
+The CertIndex monorepo bundles an MCP server (mounted at
+`https://api.ctindex.io/mcp`) that talks directly to the production
+Postgres index. This standalone package is a thin **client-side**
+shim: it speaks MCP to your editor / agent and forwards every tool
+call to the hosted CertIndex REST API over HTTPS. Two consequences:
+
+1. You don't need a copy of the index — sign up for a free API key
+   at https://ctindex.io and you're done.
+2. The package has a tiny dependency footprint (`mcp`, `httpx`,
+   `pydantic`) — easy to audit, easy to vendor, no DB drivers.
+
+## Install
+
+```bash
+pip install git+https://github.com/certindex/certindex-mcp
+```
+
+Or with [`uvx`](https://docs.astral.sh/uv/) for one-shot use:
+
+```bash
+uvx --from git+https://github.com/certindex/certindex-mcp certindex-mcp
+```
+
+(PyPI release coming soon — after that, plain `pip install certindex-mcp` /
+`uvx certindex-mcp` will work too.)
+
+## Quickstart — Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`
+(macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "certindex": {
+      "command": "uvx",
+      "args": ["--from", "git+https://github.com/certindex/certindex-mcp", "certindex-mcp"],
+      "env": {
+        "CERTINDEX_API_KEY": "ctx_live_..."
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. The six CertIndex tools (`search_certificates`,
+`get_certificate`, `get_domain_certificates`, `get_subdomains`,
+`get_latest_cert`, `get_expiring_certs`) appear in the tool tray.
+
+## Quickstart — MCP Inspector
+
+```bash
+export CERTINDEX_API_KEY=ctx_live_...
+npx @modelcontextprotocol/inspector uvx --from git+https://github.com/certindex/certindex-mcp certindex-mcp
+```
+
+## Configuration
+
+| Env var | Default | Description |
+| --- | --- | --- |
+| `CERTINDEX_API_KEY` | *(required)* | Your CertIndex API key. Mint one at https://ctindex.io/app/keys |
+| `CERTINDEX_BASE_URL` | `https://api.ctindex.io` | Override for self-hosted deployments / staging |
+| `CERTINDEX_TIMEOUT` | `30` | Per-request HTTP timeout (seconds) |
+
+## Security
+
+Input validation, rate-limit handling, and our supply-chain posture are
+documented in [SECURITY.md](SECURITY.md). Please report vulnerabilities
+to security@ctindex.io rather than filing public issues.
+
+## Development
+
+```bash
+git clone https://github.com/certindex/certindex-mcp
+cd certindex-mcp
+pip install -e ".[dev]"
+pytest
+```
+
+CI runs on Python 3.11 / 3.12 / 3.13.
+
+## License
+
+[MIT](LICENSE) © CertIndex contributors.

certindex_mcp-0.1.0/README.md

@@ -0,0 +1,106 @@
+# certindex-mcp
+
+[![CI](https://github.com/certindex/certindex-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/certindex/certindex-mcp/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/certindex-mcp.svg)](https://pypi.org/project/certindex-mcp/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+An [MCP](https://modelcontextprotocol.io) (Model Context Protocol) server
+that exposes [CertIndex](https://ctindex.io)'s Certificate
+Transparency search tools to any MCP-compatible client (Claude
+Desktop, the MCP Inspector, Continue, etc.).
+
+CertIndex indexes the full public CT corpus (~5 M certificates, growing
+~100 k/day). This server wraps the public CertIndex REST API so an LLM
+can ask questions like:
+
+- "List every TLS certificate ever issued for `example.com`."
+- "What subdomains has Let's Encrypt seen for `mycompany.io`?"
+- "Show me certs expiring in the next 30 days for `api.mycompany.io`."
+- "Pull the full PEM and CT log metadata for SHA-256 `<fingerprint>`."
+
+## Why this repo exists
+
+The CertIndex monorepo bundles an MCP server (mounted at
+`https://api.ctindex.io/mcp`) that talks directly to the production
+Postgres index. This standalone package is a thin **client-side**
+shim: it speaks MCP to your editor / agent and forwards every tool
+call to the hosted CertIndex REST API over HTTPS. Two consequences:
+
+1. You don't need a copy of the index — sign up for a free API key
+   at https://ctindex.io and you're done.
+2. The package has a tiny dependency footprint (`mcp`, `httpx`,
+   `pydantic`) — easy to audit, easy to vendor, no DB drivers.
+
+## Install
+
+```bash
+pip install git+https://github.com/certindex/certindex-mcp
+```
+
+Or with [`uvx`](https://docs.astral.sh/uv/) for one-shot use:
+
+```bash
+uvx --from git+https://github.com/certindex/certindex-mcp certindex-mcp
+```
+
+(PyPI release coming soon — after that, plain `pip install certindex-mcp` /
+`uvx certindex-mcp` will work too.)
+
+## Quickstart — Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`
+(macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "certindex": {
+      "command": "uvx",
+      "args": ["--from", "git+https://github.com/certindex/certindex-mcp", "certindex-mcp"],
+      "env": {
+        "CERTINDEX_API_KEY": "ctx_live_..."
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. The six CertIndex tools (`search_certificates`,
+`get_certificate`, `get_domain_certificates`, `get_subdomains`,
+`get_latest_cert`, `get_expiring_certs`) appear in the tool tray.
+
+## Quickstart — MCP Inspector
+
+```bash
+export CERTINDEX_API_KEY=ctx_live_...
+npx @modelcontextprotocol/inspector uvx --from git+https://github.com/certindex/certindex-mcp certindex-mcp
+```
+
+## Configuration
+
+| Env var | Default | Description |
+| --- | --- | --- |
+| `CERTINDEX_API_KEY` | *(required)* | Your CertIndex API key. Mint one at https://ctindex.io/app/keys |
+| `CERTINDEX_BASE_URL` | `https://api.ctindex.io` | Override for self-hosted deployments / staging |
+| `CERTINDEX_TIMEOUT` | `30` | Per-request HTTP timeout (seconds) |
+
+## Security
+
+Input validation, rate-limit handling, and our supply-chain posture are
+documented in [SECURITY.md](SECURITY.md). Please report vulnerabilities
+to security@ctindex.io rather than filing public issues.
+
+## Development
+
+```bash
+git clone https://github.com/certindex/certindex-mcp
+cd certindex-mcp
+pip install -e ".[dev]"
+pytest
+```
+
+CI runs on Python 3.11 / 3.12 / 3.13.
+
+## License
+
+[MIT](LICENSE) © CertIndex contributors.

certindex_mcp-0.1.0/SECURITY.md

@@ -0,0 +1,41 @@
+# Security Policy
+
+## Reporting a vulnerability
+
+Please email **security@ctindex.io** with details. Do **not** open a
+public GitHub issue for security-sensitive reports. We aim to acknowledge
+within 48 hours and to ship a fix or coordinated disclosure timeline
+within 14 days for high-severity reports.
+
+## Threat model
+
+`certindex-mcp` is a client-side MCP shim. The threat surface is
+deliberately small:
+
+| Surface | Posture |
+| --- | --- |
+| **Auth** | Single bearer-token (API key) read from `CERTINDEX_API_KEY`. Never logged. |
+| **Transport** | HTTPS only; certificate verification cannot be disabled. |
+| **Outbound HTTP** | Every request goes to `CERTINDEX_BASE_URL` (default `https://api.ctindex.io`). No user input is interpolated into the URL host or scheme. |
+| **Input validation** | All tool parameters go through `certindex_mcp.validation` (strict hostname regex, SHA-256 hex regex, substring length caps) before reaching the wire. The same validators are used server-side. |
+| **SSRF** | Not directly exposed — the package only talks to a single configured base URL. |
+| **SQL injection** | N/A — package never builds SQL; the hosted API uses parameterised queries. |
+| **Supply chain** | Three runtime deps (`mcp`, `httpx`, `pydantic`). CI runs `pip-audit` on every push. Releases are built and published from a GitHub Actions workflow with provenance attestations. |
+
+## What this package will NOT do
+
+* Read your filesystem.
+* Make outbound requests to any host other than `CERTINDEX_BASE_URL`.
+* Log your API key, even at DEBUG.
+* Cache certificate bodies to disk.
+
+## Supported versions
+
+The latest minor release on PyPI receives security fixes. Older minors
+are best-effort. Pin to the latest patch in `^x.y.z`.
+
+## Coordinated disclosure
+
+If you would like credit in the release notes, include your preferred
+handle and (optionally) a homepage URL in your report. Anonymous
+reports are equally welcome.

certindex_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,70 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "certindex-mcp"
+version = "0.1.0"
+description = "MCP server exposing CertIndex's Certificate Transparency search tools to any MCP-compatible client."
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.11"
+authors = [
+  { name = "CertIndex contributors", email = "support@ctindex.io" },
+]
+keywords = [
+  "mcp", "model-context-protocol",
+  "certificate-transparency", "ct-logs",
+  "tls", "certificates", "security",
+  "llm", "claude", "agent",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Intended Audience :: System Administrators",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Security",
+  "Topic :: Internet :: WWW/HTTP",
+]
+dependencies = [
+  "mcp>=1.2.0",
+  "httpx>=0.27",
+  "pydantic>=2.6",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8",
+  "pytest-asyncio>=0.23",
+  "respx>=0.21",
+  "ruff>=0.6",
+  "pip-audit>=2.7",
+]
+
+[project.urls]
+Homepage = "https://ctindex.io"
+Documentation = "https://github.com/certindex/certindex-mcp#readme"
+Source = "https://github.com/certindex/certindex-mcp"
+Issues = "https://github.com/certindex/certindex-mcp/issues"
+Changelog = "https://github.com/certindex/certindex-mcp/releases"
+
+[project.scripts]
+certindex-mcp = "certindex_mcp.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/certindex_mcp"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "SIM"]

certindex_mcp-0.1.0/src/certindex_mcp/__init__.py

@@ -0,0 +1,9 @@
+"""certindex-mcp — MCP server for CertIndex's CT search tools.
+
+See ``server.main`` for the stdio entry point.
+"""
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

certindex_mcp-0.1.0/src/certindex_mcp/client.py

@@ -0,0 +1,118 @@
+"""HTTP client wrapper for the CertIndex public REST API.
+
+The MCP tool layer in :mod:`certindex_mcp.server` is intentionally a
+thin shim — every tool call resolves to a single HTTPS request against
+``{base_url}/mcp-api/{tool_name}`` with the caller's API key in the
+``X-API-Key`` header.
+
+Keeping all networking in this module makes the package easy to audit:
+there is exactly one place that opens sockets, exactly one place that
+reads the API key from the environment, and exactly one place that
+decides what an error response looks like to the LLM.
+"""
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import httpx
+
+DEFAULT_BASE_URL = "https://api.ctindex.io"
+DEFAULT_TIMEOUT_SECONDS = 30.0
+USER_AGENT = "certindex-mcp/0.1.0 (+https://github.com/certindex/certindex-mcp)"
+
+
+class CertIndexConfigError(RuntimeError):
+    """Raised on missing / malformed configuration (no API key, bad URL)."""
+
+
+class CertIndexClient:
+    """Minimal async HTTP client over the CertIndex ``/mcp-api`` surface."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float | None = None,
+    ) -> None:
+        self.api_key = (api_key or os.environ.get("CERTINDEX_API_KEY", "")).strip()
+        if not self.api_key:
+            raise CertIndexConfigError(
+                "CERTINDEX_API_KEY is required. Mint a key at https://ctindex.io/app/keys "
+                "and set it in your MCP client config (Claude Desktop: the `env` block; "
+                "MCP Inspector: shell env)."
+            )
+        raw_base = (base_url or os.environ.get("CERTINDEX_BASE_URL") or DEFAULT_BASE_URL).strip()
+        parsed = httpx.URL(raw_base) if raw_base else None
+        if (
+            parsed is None
+            or parsed.scheme not in ("http", "https")
+            or not parsed.host
+        ):
+            raise CertIndexConfigError(
+                f"CERTINDEX_BASE_URL must be a fully-qualified http(s) URL (got: {raw_base!r})"
+            )
+        # Refuse plaintext HTTP except for an explicit localhost
+        # carve-out — the SECURITY.md posture promises HTTPS-only and
+        # silently accepting ``http://`` against an arbitrary host
+        # would downgrade traffic carrying the API key. Operators
+        # running a self-hosted dev instance on the loopback interface
+        # are the only legitimate plain-HTTP case.
+        if parsed.scheme == "http" and parsed.host not in ("localhost", "127.0.0.1", "::1"):
+            raise CertIndexConfigError(
+                "CERTINDEX_BASE_URL must use https:// (plaintext http:// "
+                "is only allowed against localhost for self-hosted dev)"
+            )
+        self.base_url = raw_base.rstrip("/")
+        self.timeout = (
+            timeout
+            if timeout is not None
+            else float(os.environ.get("CERTINDEX_TIMEOUT", DEFAULT_TIMEOUT_SECONDS))
+        )
+
+    def _client(self) -> httpx.AsyncClient:
+        return httpx.AsyncClient(
+            base_url=self.base_url,
+            timeout=self.timeout,
+            headers={
+                "X-API-Key": self.api_key,
+                "User-Agent": USER_AGENT,
+                "Accept": "application/json",
+            },
+            # No follow_redirects: ``/mcp-api`` never redirects, and an
+            # unexpected 30x is more interesting as a hard error than
+            # as a silent host change.
+            follow_redirects=False,
+        )
+
+    async def get(self, path: str, params: dict | None = None) -> dict[str, Any]:
+        """GET ``{base}/mcp-api{path}`` and return the parsed JSON body.
+
+        Non-2xx responses are surfaced as a structured dict the LLM can
+        reason about, *not* raised — raising would turn a 422 into an
+        opaque transport-level failure in the MCP client.
+        """
+        # Drop None-valued params so query strings stay tidy and the
+        # server doesn't see empty filters as "filter to empty".
+        clean = {k: v for k, v in (params or {}).items() if v is not None}
+        async with self._client() as client:
+            resp = await client.get(f"/mcp-api{path}", params=clean)
+        if resp.status_code >= 400:
+            return _error_body(resp)
+        return resp.json()
+
+
+def _error_body(resp: httpx.Response) -> dict[str, Any]:
+    """Convert a non-2xx response into a tool-friendly error dict."""
+    try:
+        body = resp.json()
+    except Exception:
+        body = {"message": resp.text[:500]}
+    detail = body.get("detail") if isinstance(body, dict) else None
+    if isinstance(detail, dict):
+        return {"error": detail.get("error", "http_error"), "status": resp.status_code, **detail}
+    return {
+        "error": "http_error",
+        "status": resp.status_code,
+        "message": (detail if isinstance(detail, str) else None) or str(body),
+    }

certindex_mcp-0.1.0/src/certindex_mcp/server.py

@@ -0,0 +1,178 @@
+"""FastMCP stdio entry point for certindex-mcp.
+
+Six tools that mirror the hosted CertIndex MCP surface
+(``https://api.ctindex.io/mcp``). Each tool:
+
+  1. Validates input client-side (rejects malformed hostnames /
+     SHA-256s / overlong substrings before going to the wire).
+  2. Forwards to ``GET /mcp-api/<tool>`` on the configured base URL.
+  3. Returns the upstream JSON body verbatim, or a structured error
+     dict on validation failure / HTTP error.
+
+The entry point :func:`main` runs the server over stdio so any MCP
+client (Claude Desktop, Continue, MCP Inspector, …) can spawn it.
+
+NB: this module deliberately does NOT use ``from __future__ import
+annotations``. FastMCP introspects each tool's parameter annotations
+at registration time (``issubclass(param.annotation, Context)``); with
+PEP 563 deferred evaluation those annotations are strings and the
+introspection raises ``TypeError``. Keeping runtime annotations here
+is the smallest fix that lets every tool register cleanly.
+"""
+
+import asyncio
+import logging
+from typing import Any
+
+from .client import CertIndexClient
+from .validation import (
+    McpValidationError,
+    clamp_expiring_days,
+    clamp_limit,
+    clamp_page,
+    validate_domain,
+    validate_san,
+    validate_sha256_hex,
+    validate_substring,
+)
+
+logger = logging.getLogger("certindex_mcp")
+
+
+def _build_server(client: CertIndexClient):
+    """Construct and return a configured FastMCP server.
+
+    Factored out of :func:`main` so unit tests can inject a stubbed
+    :class:`CertIndexClient` (e.g. one backed by :mod:`respx`).
+    """
+    from mcp.server.fastmcp import FastMCP  # local import keeps `--help` cheap
+
+    mcp = FastMCP("certindex")
+
+    @mcp.tool()
+    async def search_certificates(
+        domain: str | None = None,
+        cn: str | None = None,
+        issuer: str | None = None,
+        san: str | None = None,
+        expired: bool | None = None,
+        is_wildcard: bool | None = None,
+        page: int = 1,
+        limit: int = 10,
+    ) -> dict[str, Any]:
+        """Search the CT certificate index by domain, CN, issuer, SAN,
+        validity, or wildcard status. Returns a ``has_more`` boolean
+        for paging (no unbounded COUNT)."""
+        try:
+            params = {
+                "domain": validate_domain(domain) if domain else None,
+                "cn": validate_substring(cn, parameter="cn"),
+                "issuer": validate_substring(issuer, parameter="issuer"),
+                "san": validate_san(san),
+                "expired": expired,
+                "is_wildcard": is_wildcard,
+                "page": clamp_page(page),
+                "limit": clamp_limit(limit),
+            }
+        except McpValidationError as exc:
+            return exc.to_tool_error()
+        return await client.get("/search_certificates", params=params)
+
+    @mcp.tool()
+    async def get_certificate(
+        sha256: str, include_enrichment: bool = False
+    ) -> dict[str, Any]:
+        """Fetch a single cert by its 64-char hex SHA-256 fingerprint.
+
+        Set ``include_enrichment=true`` to attach RDAP + DNS + ASN/hosting
+        context for the cert's primary hostname under ``enrichment``."""
+        try:
+            sha = validate_sha256_hex(sha256)
+        except McpValidationError as exc:
+            return exc.to_tool_error()
+        return await client.get(
+            f"/get_certificate/{sha}",
+            params={"include_enrichment": include_enrichment},
+        )
+
+    @mcp.tool()
+    async def get_domain_certificates(
+        domain: str,
+        valid_only: bool = False,
+        include_enrichment: bool = False,
+        page: int = 1,
+        limit: int = 10,
+    ) -> dict[str, Any]:
+        """List certificates for an exact domain name. Cold domains
+        return a ``backfill_status`` sentinel; retry per the hint.
+
+        Set ``include_enrichment=true`` to attach RDAP + DNS + ASN/hosting
+        context for the domain under ``enrichment``."""
+        try:
+            d = validate_domain(domain)
+            params = {
+                "valid_only": valid_only,
+                "include_enrichment": include_enrichment,
+                "page": clamp_page(page),
+                "limit": clamp_limit(limit),
+            }
+        except McpValidationError as exc:
+            return exc.to_tool_error()
+        return await client.get(f"/get_domain_certificates/{d}", params=params)
+
+    @mcp.tool()
+    async def get_subdomains(
+        domain: str, page: int = 1, limit: int = 25
+    ) -> dict[str, Any]:
+        """Enumerate unique subdomains seen in CT logs."""
+        try:
+            d = validate_domain(domain)
+            params = {"page": clamp_page(page), "limit": clamp_limit(limit)}
+        except McpValidationError as exc:
+            return exc.to_tool_error()
+        return await client.get(f"/get_subdomains/{d}", params=params)
+
+    @mcp.tool()
+    async def get_latest_cert(
+        domain: str, include_enrichment: bool = False
+    ) -> dict[str, Any]:
+        """Most recently issued cert for a domain (or ``{cert: null}``
+        with a backfill sentinel on cold domains).
+
+        Set ``include_enrichment=true`` to attach RDAP + DNS + ASN/hosting
+        context for the domain under ``cert.enrichment``."""
+        try:
+            d = validate_domain(domain)
+        except McpValidationError as exc:
+            return exc.to_tool_error()
+        return await client.get(
+            f"/get_latest_cert/{d}",
+            params={"include_enrichment": include_enrichment},
+        )
+
+    @mcp.tool()
+    async def get_expiring_certs(domain: str, days: int = 30) -> dict[str, Any]:
+        """Certificates for ``domain`` expiring within ``days`` days."""
+        try:
+            d = validate_domain(domain)
+            params = {"days": clamp_expiring_days(days)}
+        except McpValidationError as exc:
+            return exc.to_tool_error()
+        return await client.get(f"/get_expiring_certs/{d}", params=params)
+
+    return mcp
+
+
+def main() -> None:
+    """CLI entry point — runs the MCP server over stdio."""
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s %(levelname)s %(name)s %(message)s",
+    )
+    client = CertIndexClient()
+    server = _build_server(client)
+    asyncio.run(server.run_stdio_async())
+
+
+if __name__ == "__main__":
+    main()

certindex_mcp-0.1.0/src/certindex_mcp/validation.py

@@ -0,0 +1,149 @@
+"""Client-side input validation for certindex-mcp.
+
+These validators are an exact mirror of the server-side validators in
+the CertIndex monorepo (``api/mcp_validation.py``). We duplicate them
+here so that:
+
+  1. Invalid input is rejected **before** a network round-trip — the
+     LLM gets immediate feedback and the upstream service never sees
+     malformed traffic.
+  2. The package can be audited independently without cloning the
+     server monorepo.
+
+When the two implementations diverge, the server-side validators are
+authoritative — the worst that can happen with a stale client copy is
+a redundant 422 from the server.
+"""
+from __future__ import annotations
+
+import re
+
+
+class McpValidationError(ValueError):
+    """Raised when a tool parameter fails validation."""
+
+    def __init__(self, parameter: str, reason: str) -> None:
+        super().__init__(f"{parameter}: {reason}")
+        self.parameter = parameter
+        self.reason = reason
+
+    def to_tool_error(self) -> dict:
+        return {
+            "error": "invalid_parameter",
+            "parameter": self.parameter,
+            "message": self.reason,
+        }
+
+
+DOMAIN_MAX_LEN = 253
+LABEL_MAX_LEN = 63
+SHA256_HEX_LEN = 64
+SUBSTR_MAX_LEN = 255
+PAGE_MAX = 10_000
+LIMIT_MAX = 50
+EXPIRING_DAYS_MAX = 365
+
+_LABEL = r"[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?"
+_DOMAIN_RE = re.compile(rf"^(?:{_LABEL}\.)+{_LABEL}$")
+_SHA256_RE = re.compile(r"^[0-9a-f]{64}$")
+_SUBSTR_RE = re.compile(r"^[A-Za-z0-9 .,/&'()\-]+$")
+
+
+def validate_domain(value: str, *, parameter: str = "domain") -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise McpValidationError(parameter, "value is required")
+    v = value.strip().lower()
+    if v.startswith("*."):
+        v = v[2:]
+    if not v:
+        raise McpValidationError(parameter, "value is required")
+    if len(v) > DOMAIN_MAX_LEN:
+        raise McpValidationError(parameter, f"length exceeds {DOMAIN_MAX_LEN} octets")
+    if any(len(label) > LABEL_MAX_LEN for label in v.split(".")):
+        raise McpValidationError(parameter, f"label exceeds {LABEL_MAX_LEN} octets")
+    if not _DOMAIN_RE.match(v):
+        raise McpValidationError(
+            parameter,
+            "must be a well-formed registrable hostname "
+            "(LDH labels separated by dots; no IP literals, ports, or paths)",
+        )
+    if v.split(".")[-1].isdigit():
+        raise McpValidationError(
+            parameter,
+            "must be a well-formed registrable hostname "
+            "(IP literals are not accepted)",
+        )
+    return v
+
+
+def validate_sha256_hex(value: str, *, parameter: str = "sha256") -> str:
+    if not isinstance(value, str):
+        raise McpValidationError(parameter, "value is required")
+    v = value.strip().lower()
+    if len(v) != SHA256_HEX_LEN or not _SHA256_RE.match(v):
+        raise McpValidationError(
+            parameter,
+            f"must be a {SHA256_HEX_LEN}-character lowercase hex SHA-256 fingerprint",
+        )
+    return v
+
+
+def validate_substring(value: str | None, *, parameter: str) -> str | None:
+    if value is None:
+        return None
+    if not isinstance(value, str):
+        raise McpValidationError(parameter, "value must be a string")
+    v = value.strip()
+    if not v:
+        return None
+    if len(v) > SUBSTR_MAX_LEN:
+        raise McpValidationError(parameter, f"length exceeds {SUBSTR_MAX_LEN} characters")
+    if not _SUBSTR_RE.match(v):
+        raise McpValidationError(
+            parameter,
+            "contains disallowed characters "
+            "(allowed: letters, digits, spaces, and . , / & ' ( ) -)",
+        )
+    return v
+
+
+def validate_san(value: str | None) -> str | None:
+    """Exact-match SAN filter. Preserves a leading ``*.`` wildcard
+    so wildcard SAN entries round-trip verbatim — without this, the
+    apex would be queried instead and wildcard SANs would silently
+    become unmatchable. Mirror of the server-side ``validate_san``.
+    """
+    if value is None:
+        return None
+    if not isinstance(value, str):
+        raise McpValidationError("san", "value must be a string")
+    raw = value.strip().lower()
+    if not raw:
+        return None
+    if raw.startswith("*."):
+        apex = raw[2:]
+        validate_domain(apex, parameter="san")
+        return "*." + apex
+    return validate_domain(raw, parameter="san")
+
+
+def clamp_limit(value: int, *, parameter: str = "limit") -> int:
+    if not isinstance(value, int) or isinstance(value, bool):
+        raise McpValidationError(parameter, "must be an integer")
+    return max(1, min(LIMIT_MAX, value))
+
+
+def clamp_page(value: int, *, parameter: str = "page") -> int:
+    if not isinstance(value, int) or isinstance(value, bool):
+        raise McpValidationError(parameter, "must be an integer")
+    if value < 1:
+        raise McpValidationError(parameter, "must be >= 1")
+    if value > PAGE_MAX:
+        raise McpValidationError(parameter, f"must be <= {PAGE_MAX}")
+    return value
+
+
+def clamp_expiring_days(value: int, *, parameter: str = "days") -> int:
+    if not isinstance(value, int) or isinstance(value, bool):
+        raise McpValidationError(parameter, "must be an integer")
+    return max(1, min(EXPIRING_DAYS_MAX, value))

certindex_mcp-0.1.0/tests/test_client.py

@@ -0,0 +1,140 @@
+"""Client-side wiring tests for :mod:`certindex_mcp.client`."""
+from __future__ import annotations
+
+import pytest
+
+from certindex_mcp.client import CertIndexClient, CertIndexConfigError
+
+
+def test_missing_api_key_raises(monkeypatch):
+    monkeypatch.delenv("CERTINDEX_API_KEY", raising=False)
+    with pytest.raises(CertIndexConfigError):
+        CertIndexClient()
+
+
+def test_explicit_api_key_overrides_env(monkeypatch):
+    monkeypatch.setenv("CERTINDEX_API_KEY", "env-key")
+    c = CertIndexClient(api_key="explicit-key")
+    assert c.api_key == "explicit-key"
+
+
+def test_base_url_requires_scheme(monkeypatch):
+    monkeypatch.setenv("CERTINDEX_API_KEY", "k")
+    with pytest.raises(CertIndexConfigError):
+        CertIndexClient(base_url="api.ctindex.io")
+
+
+def test_base_url_rejects_plain_http_to_remote_host(monkeypatch):
+    """SECURITY.md promises HTTPS-only transport. Plain ``http://``
+    against an arbitrary host would downgrade traffic carrying the
+    API key — only an explicit localhost carve-out is allowed."""
+    monkeypatch.setenv("CERTINDEX_API_KEY", "k")
+    with pytest.raises(CertIndexConfigError):
+        CertIndexClient(base_url="http://evil.example.com")
+
+
+def test_base_url_allows_http_to_localhost(monkeypatch):
+    """Self-hosted dev on the loopback interface is the only
+    legitimate plain-HTTP case."""
+    monkeypatch.setenv("CERTINDEX_API_KEY", "k")
+    c = CertIndexClient(base_url="http://localhost:8080")
+    assert c.base_url == "http://localhost:8080"
+    c2 = CertIndexClient(base_url="http://127.0.0.1:8080")
+    assert c2.base_url == "http://127.0.0.1:8080"
+
+
+def test_explicit_empty_api_key_raises(monkeypatch):
+    monkeypatch.delenv("CERTINDEX_API_KEY", raising=False)
+    with pytest.raises(CertIndexConfigError):
+        CertIndexClient(api_key="   ")
+
+
+def test_default_base_url(monkeypatch):
+    monkeypatch.setenv("CERTINDEX_API_KEY", "k")
+    c = CertIndexClient()
+    assert c.base_url == "https://api.ctindex.io"
+
+
+def test_trailing_slash_stripped(monkeypatch):
+    monkeypatch.setenv("CERTINDEX_API_KEY", "k")
+    c = CertIndexClient(base_url="https://staging.ctindex.io/")
+    assert c.base_url == "https://staging.ctindex.io"
+
+
+@pytest.mark.asyncio
+async def test_get_returns_structured_error_on_4xx(monkeypatch):
+    import respx
+    from httpx import Response
+
+    monkeypatch.setenv("CERTINDEX_API_KEY", "k")
+    c = CertIndexClient(base_url="https://example.test")
+    with respx.mock(base_url="https://example.test") as router:
+        router.get("/mcp-api/search_certificates").mock(
+            return_value=Response(
+                422,
+                json={
+                    "detail": {
+                        "error": "invalid_parameter",
+                        "parameter": "cn",
+                        "message": "contains disallowed characters",
+                    }
+                },
+            )
+        )
+        body = await c.get("/search_certificates", params={"cn": "x%y"})
+    assert body["error"] == "invalid_parameter"
+    assert body["parameter"] == "cn"
+    assert body["status"] == 422
+
+
+@pytest.mark.asyncio
+async def test_search_forwards_wildcard_san_verbatim(monkeypatch):
+    """End-to-end parity guard: a wildcard SAN must be forwarded to
+    ``/mcp-api/search_certificates`` as ``*.example.com``, not the
+    apex. Exercises the full server tool path including validation +
+    request building."""
+    import respx
+    from httpx import Response
+
+    from certindex_mcp.client import CertIndexClient
+    from certindex_mcp.server import _build_server
+
+    monkeypatch.setenv("CERTINDEX_API_KEY", "k")
+    client = CertIndexClient(base_url="https://example.test")
+    server = _build_server(client)
+    # FastMCP stores registered tools on the underlying tool manager;
+    # call ours directly to bypass MCP transport.
+    tool = server._tool_manager._tools["search_certificates"]
+    with respx.mock(base_url="https://example.test") as router:
+        route = router.get("/mcp-api/search_certificates").mock(
+            return_value=Response(
+                200, json={"results": [], "has_more": False, "page": 1, "limit": 10}
+            )
+        )
+        await tool.fn(san="*.example.com")
+    qs = str(route.calls.last.request.url)
+    # URL-encoded; ``*`` may or may not be encoded depending on httpx,
+    # so accept either form.
+    assert "san=%2A.example.com" in qs or "san=*.example.com" in qs
+
+
+@pytest.mark.asyncio
+async def test_get_drops_none_params(monkeypatch):
+    import respx
+    from httpx import Response
+
+    monkeypatch.setenv("CERTINDEX_API_KEY", "k")
+    c = CertIndexClient(base_url="https://example.test")
+    with respx.mock(base_url="https://example.test") as router:
+        route = router.get("/mcp-api/search_certificates").mock(
+            return_value=Response(200, json={"results": []})
+        )
+        await c.get(
+            "/search_certificates",
+            params={"domain": "example.com", "cn": None, "issuer": None},
+        )
+    # URL should contain ``domain`` but not the dropped Nones.
+    qs = str(route.calls.last.request.url)
+    assert "domain=example.com" in qs
+    assert "cn=" not in qs
+    assert "issuer=" not in qs

certindex_mcp-0.1.0/tests/test_validation.py

@@ -0,0 +1,100 @@
+"""Mirror of the server-side validator tests, kept in-package so the
+distribution can be audited without cloning the server monorepo."""
+from __future__ import annotations
+
+import pytest
+
+from certindex_mcp.validation import (
+    LIMIT_MAX,
+    SHA256_HEX_LEN,
+    McpValidationError,
+    clamp_expiring_days,
+    clamp_limit,
+    clamp_page,
+    validate_domain,
+    validate_san,
+    validate_sha256_hex,
+    validate_substring,
+)
+
+
+@pytest.mark.parametrize(
+    "raw,expected",
+    [
+        ("example.com", "example.com"),
+        ("  EXAMPLE.COM  ", "example.com"),
+        ("*.example.com", "example.com"),
+        ("api.v2.example.co.uk", "api.v2.example.co.uk"),
+    ],
+)
+def test_validate_domain_accepts(raw, expected):
+    assert validate_domain(raw) == expected
+
+
+@pytest.mark.parametrize(
+    "bad",
+    [
+        "", "   ", "localhost", "example.com:8080", "http://example.com",
+        "user@example.com", "example..com", "-x.com", "x-.com",
+        "exa mple.com", "exa%mple.com", "exa_mple.com", "a" * 64 + ".com",
+    ],
+)
+def test_validate_domain_rejects(bad):
+    with pytest.raises(McpValidationError):
+        validate_domain(bad)
+
+
+def test_validate_sha256_accepts():
+    h = "a" * SHA256_HEX_LEN
+    assert validate_sha256_hex(h.upper()) == h
+
+
+@pytest.mark.parametrize("bad", ["", "abc", "g" * SHA256_HEX_LEN, "a" * 63])
+def test_validate_sha256_rejects(bad):
+    with pytest.raises(McpValidationError):
+        validate_sha256_hex(bad)
+
+
+def test_validate_substring_empty_is_none():
+    assert validate_substring("", parameter="cn") is None
+    assert validate_substring(None, parameter="cn") is None
+
+
+@pytest.mark.parametrize("bad", ["a%b", "a_b", "x\x00y", "drop;table"])
+def test_validate_substring_rejects(bad):
+    with pytest.raises(McpValidationError):
+        validate_substring(bad, parameter="cn")
+
+
+def test_validate_san_preserves_wildcard_prefix():
+    """Parity guard with the in-tree validator: wildcard SANs are
+    first-class CT entries and must round-trip verbatim through the
+    OSS shim, otherwise ``search_certificates(san='*.example.com')``
+    would silently rewrite to the apex and miss wildcard SAN rows."""
+    assert validate_san("*.example.com") == "*.example.com"
+    assert validate_san("  *.EXAMPLE.com  ") == "*.example.com"
+    assert validate_san("api.example.com") == "api.example.com"
+    assert validate_san(None) is None
+    assert validate_san("") is None
+    with pytest.raises(McpValidationError):
+        validate_san("not a domain")
+
+
+def test_validate_domain_rejects_leading_dots_or_stars():
+    """Regression: a previous ``lstrip('*.')`` implementation silently
+    normalised ``.example.com`` and ``**.example.com`` to the apex."""
+    with pytest.raises(McpValidationError):
+        validate_domain(".example.com")
+    with pytest.raises(McpValidationError):
+        validate_domain("*..example.com")
+    with pytest.raises(McpValidationError):
+        validate_domain("**.example.com")
+
+
+def test_numeric_clamps():
+    assert clamp_limit(0) == 1
+    assert clamp_limit(LIMIT_MAX + 99) == LIMIT_MAX
+    assert clamp_page(1) == 1
+    with pytest.raises(McpValidationError):
+        clamp_page(0)
+    assert clamp_expiring_days(99999) == 365