ciphra-mcp 0.1.0__tar.gz

ciphra_mcp-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+.venv/
+__pycache__/
+.pytest_cache/
+*.egg-info/
+.coverage

ciphra_mcp-0.1.0/LICENSE

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

ciphra_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: ciphra-mcp
+Version: 0.1.0
+Summary: Python MCP server for Ciphra. Lets AI coding agents call Ciphra's secret scanner via the Model Context Protocol.
+Project-URL: Homepage, https://github.com/sanjayselvam31/ciphra
+Project-URL: Repository, https://github.com/sanjayselvam31/ciphra
+Project-URL: Issues, https://github.com/sanjayselvam31/ciphra/issues
+Author: Sanjay Selvam
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,ciphra,mcp,scanner,secrets,security
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+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 :: Security
+Requires-Python: >=3.11
+Requires-Dist: mcp>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ciphra-mcp
+
+Python MCP server exposing Ciphra's secret scanner to AI agents.
+
+## What this is
+
+The agent-facing layer for [Ciphra](../README.md). The actual scanning is done by the TypeScript CLI at the repo root; this Python project spawns the CLI as a subprocess and translates between MCP's JSON-RPC protocol and Ciphra's JSON output. With this server registered, agents like Claude Code and Cursor can scan a codebase, validate a key, or audit git history without the user typing CLI commands.
+
+## Prerequisites
+
+- **Node 20+** — needed for the underlying `ciphra` CLI, which this MCP server shells out to
+- **Python 3.11+** — for the MCP server itself
+- **[uv](https://github.com/astral-sh/uv)** (recommended) or `pip + venv`
+- **`ciphra` on `$PATH`.** The MCP server resolves the CLI via `shutil.which("ciphra")`, so it must be installed globally:
+
+  ```bash
+  npm install -g ciphra
+  ```
+
+  If you get an `EACCES` error on `npm install -g`, your npm prefix is root-owned. The cleanest fix:
+
+  ```bash
+  mkdir -p ~/.npm-global
+  npm config set prefix ~/.npm-global
+  echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
+  source ~/.zshrc
+  npm install -g ciphra
+  ```
+
+## Installation
+
+```bash
+uvx ciphra-mcp                    # ephemeral; runs the published wheel on demand
+```
+
+That's it — `uvx` downloads the wheel from PyPI on first invocation, then runs the entry point. No clone required.
+
+If you'd rather have it permanently installed in a project-local venv:
+
+```bash
+uv pip install ciphra-mcp
+```
+
+### Building from source (contributors)
+
+```bash
+cd /path/to/ciphra
+npm install && npm run build      # build the TS CLI
+
+cd mcp-server
+uv sync --extra dev               # creates .venv, installs deps
+```
+
+(pip alternative: `python3.11 -m venv .venv && source .venv/bin/activate && pip install -e ".[dev]"`)
+
+## Running the server
+
+**Standalone (sanity check that it launches):**
+
+```bash
+uv run ciphra-mcp
+```
+
+The server speaks MCP over stdio and isn't useful interactively. Send EOF (`Ctrl-D`) to exit. Most of the time you won't run this directly — the MCP client launches it for you.
+
+**As an MCP server in Claude Code:**
+
+Add to `~/.claude.json` (create the file if it doesn't exist):
+
+```json
+{
+  "mcpServers": {
+    "ciphra": {
+      "command": "uvx",
+      "args": ["ciphra-mcp"]
+    }
+  }
+}
+```
+
+Restart Claude Code. The four Ciphra tools become available to the agent automatically.
+
+**As an MCP server in Cursor:**
+
+Add the same block to `~/.cursor/mcp.json`. Restart Cursor.
+
+**Contributor / local-development alternative.** If you're running from a source checkout (the "Building from source" path above) instead of the published wheel, point the MCP client at your local venv:
+
+```json
+{
+  "mcpServers": {
+    "ciphra": {
+      "command": "uv",
+      "args": ["--directory", "/absolute/path/to/ciphra/mcp-server", "run", "ciphra-mcp"]
+    }
+  }
+}
+```
+
+## The four MCP tools
+
+- **`scan_directory`** — the primary tool for "is this codebase secure?" / "are there leaked keys?" prompts. Scans a directory and (by default) its git history across all 10 supported services. Validation is opt-in. Example: *"Scan this directory for leaked keys."*
+
+- **`check_specific_service`** — use when the user has named a single service of concern. Faster than `scan_directory` because only that service's detectors run, and defaults to live validation since scope is narrow. Example: *"I'm worried about Stripe keys in this codebase."*
+
+- **`scan_git_history`** — scans only the commit history (current files are not touched). For auditing keys that were committed and later removed but remain recoverable from history. Example: *"Did I ever commit an AWS key I later deleted?"*
+
+- **`validate_key`** — checks whether a specific key value is currently active against its service's live API. For "has this key value been used in my repo?" questions, agents should grep first; this tool is for one-shot live-status checks. Example: *"Is `sk_test_abc123` a real Stripe key?"*
+
+The exact descriptions live in [src/ciphra_mcp/server.py](src/ciphra_mcp/server.py). Agents read those directly — when in doubt about how a prompt routes, that file is the source of truth.
+
+## Running tests
+
+```bash
+uv run pytest
+```
+
+The suite is full integration: tests spawn the real CLI subprocess. A `pytest_sessionstart` hook checks that `dist/cli/index.js` is current relative to `src/**/*.ts`; if any TS file is newer, the session aborts before collection with the offending paths and an instruction to run `npm run build` from the repo root.
+
+Set `CIPHRA_SKIP_STALENESS_CHECK=1` to bypass — useful in CI where the build is guaranteed to have already run.
+
+## Layout
+
+```
+src/ciphra_mcp/
+  server.py         FastMCP setup, four @mcp.tool registrations
+  ciphra_client.py  Async subprocess wrapper around the TS CLI
+  types.py          TypedDicts mirroring the CLI JSON schema (v1.0)
+tests/
+  conftest.py       Staleness check + EXPECTED_TOOL_NAMES constant
+  test_*.py         Integration tests (33 in total)
+scripts/
+  verify_handshake.py            Manual MCP protocol handshake check
+  verify_*.py                    Per-tool one-shot verification scripts
+```
+
+## Security notes
+
+- **Validated keys hit live third-party APIs.** Defaults: `scan_directory` and `scan_git_history` are validate=OFF; `check_specific_service` is validate=ON (the user has narrowed scope to one service, so the cost is bounded); `validate_key` always sends. Don't validate keys you don't own or haven't been explicitly asked about — the call is logged at the third-party service.
+- **Key values are never logged or returned in tool output.** Findings include a redacted preview (first/last 4 chars); validation results contain only status and reason.
+- **`validation: invalid` is not a safety signal.** It means the key isn't currently authenticating — but it was exposed in the codebase, so the leak still happened. Rotate regardless.
+
+## Troubleshooting
+
+- **`ciphra-mcp: command not found`** — run `uv sync --extra dev` from `mcp-server/`, or activate the venv if using pip.
+- **"TypeScript source is newer than dist/cli/index.js"** — run `npm run build` from the repo root.
+- **Agent says no Ciphra tools are available** — the MCP client likely cached an older state of the server (e.g. from before tools were wired up). Restart the client. New tool descriptions also require a restart — the running Python process captures the description strings at import time.
+- **Tools appear but calls fail with `CiphraNotFoundError`** — the MCP config points at the wrong directory, or `npm run build` hasn't been run. Verify by running `uv run ciphra-mcp` from a terminal in `mcp-server/`; it should launch silently and wait on stdin.
+- **"Server has 0 tools"** in `verify_handshake.py` — almost always a stale running process. Check that `mcp-server/src/ciphra_mcp/server.py` has the four `@mcp.tool(...)` decorators and reload your client.

ciphra_mcp-0.1.0/README.md

@@ -0,0 +1,149 @@
+# ciphra-mcp
+
+Python MCP server exposing Ciphra's secret scanner to AI agents.
+
+## What this is
+
+The agent-facing layer for [Ciphra](../README.md). The actual scanning is done by the TypeScript CLI at the repo root; this Python project spawns the CLI as a subprocess and translates between MCP's JSON-RPC protocol and Ciphra's JSON output. With this server registered, agents like Claude Code and Cursor can scan a codebase, validate a key, or audit git history without the user typing CLI commands.
+
+## Prerequisites
+
+- **Node 20+** — needed for the underlying `ciphra` CLI, which this MCP server shells out to
+- **Python 3.11+** — for the MCP server itself
+- **[uv](https://github.com/astral-sh/uv)** (recommended) or `pip + venv`
+- **`ciphra` on `$PATH`.** The MCP server resolves the CLI via `shutil.which("ciphra")`, so it must be installed globally:
+
+  ```bash
+  npm install -g ciphra
+  ```
+
+  If you get an `EACCES` error on `npm install -g`, your npm prefix is root-owned. The cleanest fix:
+
+  ```bash
+  mkdir -p ~/.npm-global
+  npm config set prefix ~/.npm-global
+  echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
+  source ~/.zshrc
+  npm install -g ciphra
+  ```
+
+## Installation
+
+```bash
+uvx ciphra-mcp                    # ephemeral; runs the published wheel on demand
+```
+
+That's it — `uvx` downloads the wheel from PyPI on first invocation, then runs the entry point. No clone required.
+
+If you'd rather have it permanently installed in a project-local venv:
+
+```bash
+uv pip install ciphra-mcp
+```
+
+### Building from source (contributors)
+
+```bash
+cd /path/to/ciphra
+npm install && npm run build      # build the TS CLI
+
+cd mcp-server
+uv sync --extra dev               # creates .venv, installs deps
+```
+
+(pip alternative: `python3.11 -m venv .venv && source .venv/bin/activate && pip install -e ".[dev]"`)
+
+## Running the server
+
+**Standalone (sanity check that it launches):**
+
+```bash
+uv run ciphra-mcp
+```
+
+The server speaks MCP over stdio and isn't useful interactively. Send EOF (`Ctrl-D`) to exit. Most of the time you won't run this directly — the MCP client launches it for you.
+
+**As an MCP server in Claude Code:**
+
+Add to `~/.claude.json` (create the file if it doesn't exist):
+
+```json
+{
+  "mcpServers": {
+    "ciphra": {
+      "command": "uvx",
+      "args": ["ciphra-mcp"]
+    }
+  }
+}
+```
+
+Restart Claude Code. The four Ciphra tools become available to the agent automatically.
+
+**As an MCP server in Cursor:**
+
+Add the same block to `~/.cursor/mcp.json`. Restart Cursor.
+
+**Contributor / local-development alternative.** If you're running from a source checkout (the "Building from source" path above) instead of the published wheel, point the MCP client at your local venv:
+
+```json
+{
+  "mcpServers": {
+    "ciphra": {
+      "command": "uv",
+      "args": ["--directory", "/absolute/path/to/ciphra/mcp-server", "run", "ciphra-mcp"]
+    }
+  }
+}
+```
+
+## The four MCP tools
+
+- **`scan_directory`** — the primary tool for "is this codebase secure?" / "are there leaked keys?" prompts. Scans a directory and (by default) its git history across all 10 supported services. Validation is opt-in. Example: *"Scan this directory for leaked keys."*
+
+- **`check_specific_service`** — use when the user has named a single service of concern. Faster than `scan_directory` because only that service's detectors run, and defaults to live validation since scope is narrow. Example: *"I'm worried about Stripe keys in this codebase."*
+
+- **`scan_git_history`** — scans only the commit history (current files are not touched). For auditing keys that were committed and later removed but remain recoverable from history. Example: *"Did I ever commit an AWS key I later deleted?"*
+
+- **`validate_key`** — checks whether a specific key value is currently active against its service's live API. For "has this key value been used in my repo?" questions, agents should grep first; this tool is for one-shot live-status checks. Example: *"Is `sk_test_abc123` a real Stripe key?"*
+
+The exact descriptions live in [src/ciphra_mcp/server.py](src/ciphra_mcp/server.py). Agents read those directly — when in doubt about how a prompt routes, that file is the source of truth.
+
+## Running tests
+
+```bash
+uv run pytest
+```
+
+The suite is full integration: tests spawn the real CLI subprocess. A `pytest_sessionstart` hook checks that `dist/cli/index.js` is current relative to `src/**/*.ts`; if any TS file is newer, the session aborts before collection with the offending paths and an instruction to run `npm run build` from the repo root.
+
+Set `CIPHRA_SKIP_STALENESS_CHECK=1` to bypass — useful in CI where the build is guaranteed to have already run.
+
+## Layout
+
+```
+src/ciphra_mcp/
+  server.py         FastMCP setup, four @mcp.tool registrations
+  ciphra_client.py  Async subprocess wrapper around the TS CLI
+  types.py          TypedDicts mirroring the CLI JSON schema (v1.0)
+tests/
+  conftest.py       Staleness check + EXPECTED_TOOL_NAMES constant
+  test_*.py         Integration tests (33 in total)
+scripts/
+  verify_handshake.py            Manual MCP protocol handshake check
+  verify_*.py                    Per-tool one-shot verification scripts
+```
+
+## Security notes
+
+- **Validated keys hit live third-party APIs.** Defaults: `scan_directory` and `scan_git_history` are validate=OFF; `check_specific_service` is validate=ON (the user has narrowed scope to one service, so the cost is bounded); `validate_key` always sends. Don't validate keys you don't own or haven't been explicitly asked about — the call is logged at the third-party service.
+- **Key values are never logged or returned in tool output.** Findings include a redacted preview (first/last 4 chars); validation results contain only status and reason.
+- **`validation: invalid` is not a safety signal.** It means the key isn't currently authenticating — but it was exposed in the codebase, so the leak still happened. Rotate regardless.
+
+## Troubleshooting
+
+- **`ciphra-mcp: command not found`** — run `uv sync --extra dev` from `mcp-server/`, or activate the venv if using pip.
+- **"TypeScript source is newer than dist/cli/index.js"** — run `npm run build` from the repo root.
+- **Agent says no Ciphra tools are available** — the MCP client likely cached an older state of the server (e.g. from before tools were wired up). Restart the client. New tool descriptions also require a restart — the running Python process captures the description strings at import time.
+- **Tools appear but calls fail with `CiphraNotFoundError`** — the MCP config points at the wrong directory, or `npm run build` hasn't been run. Verify by running `uv run ciphra-mcp` from a terminal in `mcp-server/`; it should launch silently and wait on stdin.
+- **"Server has 0 tools"** in `verify_handshake.py` — almost always a stale running process. Check that `mcp-server/src/ciphra_mcp/server.py` has the four `@mcp.tool(...)` decorators and reload your client.

ciphra_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,67 @@
+[project]
+name = "ciphra-mcp"
+version = "0.1.0"
+description = "Python MCP server for Ciphra. Lets AI coding agents call Ciphra's secret scanner via the Model Context Protocol."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+authors = [
+  { name = "Sanjay Selvam" },
+]
+keywords = [
+  "mcp",
+  "security",
+  "scanner",
+  "secrets",
+  "ai-agents",
+  "ciphra",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "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",
+]
+dependencies = [
+  "mcp>=1.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+  "pytest-asyncio>=0.23",
+]
+
+[project.urls]
+Homepage = "https://github.com/sanjayselvam31/ciphra"
+Repository = "https://github.com/sanjayselvam31/ciphra"
+Issues = "https://github.com/sanjayselvam31/ciphra/issues"
+
+[project.scripts]
+ciphra-mcp = "ciphra_mcp.server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ciphra_mcp"]
+
+# Sdist allowlist: explicitly include only what should ship. tests/,
+# scripts/, .venv/, uv.lock, and __pycache__/ stay out.
+[tool.hatch.build.targets.sdist]
+include = [
+  "src/",
+  "pyproject.toml",
+  "README.md",
+  "LICENSE",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

ciphra_mcp-0.1.0/src/ciphra_mcp/__init__.py

@@ -0,0 +1 @@
+"""Python MCP server that wraps the Ciphra TypeScript CLI."""

ciphra_mcp-0.1.0/src/ciphra_mcp/__main__.py

@@ -0,0 +1,4 @@
+from ciphra_mcp.server import main
+
+if __name__ == "__main__":
+    main()

ciphra_mcp-0.1.0/src/ciphra_mcp/ciphra_client.py

@@ -0,0 +1,457 @@
+"""Subprocess wrapper around the Ciphra TypeScript CLI.
+
+The MCP server never talks to detector/scanner code directly. It shells out
+to `ciphra scan --json <path>` and parses stdout. This keeps the TS scanner
+authoritative and avoids a Python re-implementation.
+
+CLI exit codes (documented contract):
+    0  scan completed; no critical/high findings above threshold
+    1  scan completed; critical findings present
+    2  scan completed; high findings present (no critical)
+    3  scan errored (path missing, invalid arg, etc.)
+
+Exit 1 and 2 are NOT failures — they are "findings present" signals. Only
+exit 3 raises CiphraScanError. Default subprocess handling would conflate
+the three; that conflation would silently break the MCP tool's behavior.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+import shutil
+import sys
+from pathlib import Path
+from typing import cast
+
+from ciphra_mcp.types import (
+    EXPECTED_SCHEMA_VERSION,
+    KNOWN_SERVICE_IDS,
+    ScanResult,
+    ServiceId,
+    ValidateResult,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class CiphraError(Exception):
+    """Base class for all errors raised by the Ciphra subprocess wrapper."""
+
+
+class CiphraNotFoundError(CiphraError):
+    """The Ciphra TS CLI could not be located on disk or on PATH."""
+
+
+class CiphraScanError(CiphraError):
+    """The Ciphra CLI returned a real error (exit code 3)."""
+
+
+class CiphraTimeoutError(CiphraError):
+    """The Ciphra subprocess did not finish before the timeout elapsed."""
+
+
+class CiphraSchemaVersionError(CiphraError):
+    """The CLI returned JSON with an unexpected schemaVersion."""
+
+
+class CiphraNotAGitRepoError(CiphraError):
+    """The given path is not the root of a git repository."""
+
+
+def _resolve_cli() -> list[str]:
+    """Resolve the command (argv prefix) used to invoke the Ciphra CLI.
+
+    Lookup order:
+        1. $CIPHRA_CLI_PATH if set (path to a node script or executable)
+        2. `ciphra` on $PATH
+        3. ../../../dist/cli/index.js relative to this file (via `node`)
+    """
+    env_path = os.environ.get("CIPHRA_CLI_PATH")
+    if env_path:
+        p = Path(env_path)
+        if not p.exists():
+            raise CiphraNotFoundError(
+                f"CIPHRA_CLI_PATH points to a path that does not exist: {env_path}"
+            )
+        if p.suffix == ".js":
+            return ["node", str(p)]
+        return [str(p)]
+
+    on_path = shutil.which("ciphra")
+    if on_path:
+        return [on_path]
+
+    built = Path(__file__).resolve().parents[3] / "dist" / "cli" / "index.js"
+    if built.exists():
+        return ["node", str(built)]
+
+    raise CiphraNotFoundError(
+        "Could not locate the Ciphra CLI. Set CIPHRA_CLI_PATH, install ciphra "
+        f"globally so it is on $PATH, or run `npm run build` at the repo root "
+        f"to produce {built}."
+    )
+
+
+async def _run_scan_subprocess(
+    cli_args: list[str],
+    *,
+    timeout_seconds: float,
+) -> ScanResult:
+    """Spawn `ciphra scan --json <cli_args...>` and return the parsed result.
+
+    `cli_args` is everything that follows `scan --json` on the command
+    line — typically a path plus flags like `["--severity", "medium",
+    "<path>", "--no-validate"]`. The helper prepends `scan` and `--json`
+    automatically; do not include those in cli_args.
+
+    Exit code handling:
+        0, 1, 2 -> success (CLI completed; 1/2 mean "findings present")
+        3       -> CiphraScanError (real CLI error)
+        other   -> CiphraScanError (defensive)
+
+    Used by scan_directory, scan_git_history, and check_specific_service.
+    A single helper keeps timeout-kill discipline, schema-version checking,
+    and exit-code interpretation in one place.
+    """
+    argv = _resolve_cli() + ["scan", "--json"] + cli_args
+
+    logger.debug("invoking ciphra: %s", " ".join(argv))
+
+    proc = await asyncio.create_subprocess_exec(
+        *argv,
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.PIPE,
+        env={**os.environ, "NO_COLOR": "1"},
+    )
+
+    try:
+        stdout_bytes, stderr_bytes = await asyncio.wait_for(
+            proc.communicate(), timeout=timeout_seconds
+        )
+    except asyncio.TimeoutError as exc:
+        proc.kill()
+        try:
+            await asyncio.wait_for(proc.wait(), timeout=2.0)
+        except asyncio.TimeoutError:
+            pass
+        raise CiphraTimeoutError(
+            f"ciphra scan did not finish within {timeout_seconds}s "
+            f"(args={cli_args})"
+        ) from exc
+
+    stderr = stderr_bytes.decode("utf-8", errors="replace")
+    exit_code = proc.returncode
+
+    if exit_code == 3:
+        raise CiphraScanError(
+            f"ciphra scan failed (exit 3) for args={cli_args}\n"
+            f"stderr:\n{stderr.strip()}"
+        )
+    if exit_code not in (0, 1, 2):
+        raise CiphraScanError(
+            f"ciphra scan exited with unexpected code {exit_code} for "
+            f"args={cli_args}\nstderr:\n{stderr.strip()}"
+        )
+
+    stdout = stdout_bytes.decode("utf-8", errors="replace")
+    try:
+        parsed = json.loads(stdout)
+    except json.JSONDecodeError as exc:
+        raise CiphraScanError(
+            f"ciphra scan stdout was not valid JSON (exit {exit_code}):\n"
+            f"{stdout[:500]}"
+        ) from exc
+
+    if stderr.strip():
+        logger.debug("ciphra stderr: %s", stderr.strip())
+
+    actual_schema = parsed.get("schemaVersion")
+    if actual_schema != EXPECTED_SCHEMA_VERSION:
+        raise CiphraSchemaVersionError(
+            f"Ciphra CLI returned schemaVersion={actual_schema!r}, "
+            f"this client expects {EXPECTED_SCHEMA_VERSION!r}. Either upgrade "
+            f"ciphra-mcp or downgrade the Ciphra CLI."
+        )
+
+    return cast(ScanResult, parsed)
+
+
+async def scan_directory(
+    path: str,
+    *,
+    validate: bool = True,
+    history: bool = True,
+    severity: str = "medium",
+    timeout_seconds: float = 60.0,
+) -> ScanResult:
+    """Run `ciphra scan --json <path>` and return the parsed result.
+
+    Exit codes 0, 1, 2 are all treated as success (scan completed); only
+    exit 3 raises CiphraScanError. Non-zero stderr is logged at debug level.
+    """
+    cli_args: list[str] = ["--severity", severity, path]
+    if not validate:
+        cli_args.append("--no-validate")
+    if not history:
+        cli_args.append("--no-history")
+    return await _run_scan_subprocess(cli_args, timeout_seconds=timeout_seconds)
+
+
+async def validate_key(
+    service_id: ServiceId,
+    key: str,
+    *,
+    timeout_seconds: float = 15.0,
+) -> ValidateResult:
+    """Run `ciphra validate --json <service_id> --key-stdin` and return the result.
+
+    The key is written to the subprocess's stdin and never appears on argv,
+    in environment variables, or in any log/error output produced by this
+    function. The TS side enforces the same discipline (see
+    src/cli/validate.ts at the repo root and tests/cli-validate-contract).
+
+    SECURITY: do not add logging that references the `key` parameter. Do
+    not include `key` in any exception message. The Python-side
+    marker-key test in test_tools.test_validate_key_does_not_leak_key is
+    the regression guard for this rule.
+    """
+    argv = _resolve_cli() + ["validate", service_id, "--json", "--key-stdin"]
+
+    logger.debug("invoking ciphra validate for service=%s", service_id)
+
+    proc = await asyncio.create_subprocess_exec(
+        *argv,
+        stdin=asyncio.subprocess.PIPE,
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.PIPE,
+        env={**os.environ, "NO_COLOR": "1"},
+    )
+
+    # communicate(input=...) writes input to stdin, closes stdin, then
+    # concurrently reads stdout+stderr to EOF and waits for the process.
+    # We use it (rather than manual write+drain+close) because it handles
+    # cross-version asyncio quirks and avoids deadlocking on large stderr.
+    payload = (key + "\n").encode("utf-8")
+    try:
+        stdout_bytes, stderr_bytes = await asyncio.wait_for(
+            proc.communicate(input=payload),
+            timeout=timeout_seconds,
+        )
+    except asyncio.TimeoutError as exc:
+        proc.kill()
+        try:
+            await asyncio.wait_for(proc.wait(), timeout=2.0)
+        except asyncio.TimeoutError:
+            pass
+        # Do NOT include the key in this message.
+        raise CiphraTimeoutError(
+            f"ciphra validate did not finish within {timeout_seconds}s "
+            f"(service_id={service_id!r})"
+        ) from exc
+
+    stderr = stderr_bytes.decode("utf-8", errors="replace")
+    exit_code = proc.returncode
+
+    if exit_code == 3:
+        # The TS side guarantees its stderr never contains the key, so
+        # passing stderr through is safe. The `key` parameter itself is
+        # NEVER included in this message.
+        raise CiphraScanError(
+            f"ciphra validate failed (exit 3) for service_id={service_id!r}\n"
+            f"stderr:\n{stderr.strip()}"
+        )
+    if exit_code != 0:
+        raise CiphraScanError(
+            f"ciphra validate exited with unexpected code {exit_code} for "
+            f"service_id={service_id!r}\nstderr:\n{stderr.strip()}"
+        )
+
+    stdout = stdout_bytes.decode("utf-8", errors="replace")
+    try:
+        parsed = json.loads(stdout)
+    except json.JSONDecodeError as exc:
+        raise CiphraScanError(
+            f"ciphra validate stdout was not valid JSON (exit {exit_code})"
+        ) from exc
+
+    if stderr.strip():
+        logger.debug("ciphra stderr: %s", stderr.strip())
+
+    actual_schema = parsed.get("schemaVersion")
+    if actual_schema != EXPECTED_SCHEMA_VERSION:
+        raise CiphraSchemaVersionError(
+            f"Ciphra CLI returned schemaVersion={actual_schema!r}, "
+            f"this client expects {EXPECTED_SCHEMA_VERSION!r}."
+        )
+
+    logger.debug(
+        "validated service=%s status=%s",
+        service_id,
+        parsed.get("validation", {}).get("status"),
+    )
+
+    return cast(ValidateResult, parsed)
+
+
+async def scan_git_history(
+    path: str,
+    *,
+    validate: bool = False,
+    severity: str = "medium",
+    timeout_seconds: float = 120.0,
+) -> ScanResult:
+    """Scan only the git commit history of a repository for exposed secrets.
+
+    The TS CLI has no `--history-only` flag — instead, this function runs
+    a normal `ciphra scan --json` (history enabled by default) and then
+    filters the findings array to only those with source == "git-history".
+    Summary counts are recomputed to match the filtered set. This is the
+    ONLY place in the codebase where Python mutates a ScanResult after
+    receiving it from the CLI; if you add new mutation points elsewhere,
+    add a comment so future readers can grep for them.
+
+    Why filter on the Python side: keeps the TS CLI surface area minimal
+    (no extra flag, no new code path to test) and the filter is O(n) on
+    findings. The full git walk happens on the TS side regardless.
+
+    Git-repo detection: we check `<path>/.git` exists (matches the TS
+    side's check at src/scanner/git-history.ts). This is strict — passing
+    a subdirectory of a repo raises CiphraNotAGitRepoError even though
+    the subdir is technically inside the repo. Symmetric with the CLI
+    behavior, simpler than walking parents, no subprocess needed.
+    """
+    git_marker = Path(path) / ".git"
+    if not git_marker.exists():
+        raise CiphraNotAGitRepoError(
+            f"Path is not inside a git repository: {path} "
+            f"(no .git marker at {git_marker})"
+        )
+
+    argv = _resolve_cli() + ["scan", path, "--json", "--severity", severity]
+    if not validate:
+        argv.append("--no-validate")
+
+    logger.debug("invoking ciphra scan (history-only filter) for %s", path)
+
+    proc = await asyncio.create_subprocess_exec(
+        *argv,
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.PIPE,
+        env={**os.environ, "NO_COLOR": "1"},
+    )
+
+    try:
+        stdout_bytes, stderr_bytes = await asyncio.wait_for(
+            proc.communicate(), timeout=timeout_seconds
+        )
+    except asyncio.TimeoutError as exc:
+        proc.kill()
+        try:
+            await asyncio.wait_for(proc.wait(), timeout=2.0)
+        except asyncio.TimeoutError:
+            pass
+        raise CiphraTimeoutError(
+            f"ciphra scan_git_history did not finish within {timeout_seconds}s "
+            f"(path={path!r})"
+        ) from exc
+
+    stderr = stderr_bytes.decode("utf-8", errors="replace")
+    exit_code = proc.returncode
+
+    if exit_code == 3:
+        raise CiphraScanError(
+            f"ciphra scan failed (exit 3) for path={path!r}\nstderr:\n{stderr.strip()}"
+        )
+    if exit_code not in (0, 1, 2):
+        raise CiphraScanError(
+            f"ciphra scan exited with unexpected code {exit_code} for path={path!r}\n"
+            f"stderr:\n{stderr.strip()}"
+        )
+
+    stdout = stdout_bytes.decode("utf-8", errors="replace")
+    try:
+        parsed = json.loads(stdout)
+    except json.JSONDecodeError as exc:
+        raise CiphraScanError(
+            f"ciphra scan stdout was not valid JSON (exit {exit_code}):\n"
+            f"{stdout[:500]}"
+        ) from exc
+
+    if stderr.strip():
+        logger.debug("ciphra stderr: %s", stderr.strip())
+
+    actual_schema = parsed.get("schemaVersion")
+    if actual_schema != EXPECTED_SCHEMA_VERSION:
+        raise CiphraSchemaVersionError(
+            f"Ciphra CLI returned schemaVersion={actual_schema!r}, "
+            f"this client expects {EXPECTED_SCHEMA_VERSION!r}."
+        )
+
+    # MUTATION POINT (1 of 1 in this codebase): filter to history-only +
+    # recompute summary counts. Everything else in the ScanResult is
+    # passed through as-is.
+    history_findings = [
+        f for f in parsed["findings"] if f.get("source") == "git-history"
+    ]
+    severities = {"critical": 0, "high": 0, "medium": 0, "info": 0}
+    by_service: dict[str, int] = {}
+    for f in history_findings:
+        sev = f.get("severity")
+        if sev in severities:
+            severities[sev] += 1
+        name = f.get("serviceName")
+        if name:
+            by_service[name] = by_service.get(name, 0) + 1
+
+    parsed["findings"] = history_findings
+    parsed["summary"] = {
+        "total": len(history_findings),
+        **severities,
+        "byService": by_service,
+    }
+
+    return cast(ScanResult, parsed)
+
+
+async def check_specific_service(
+    service_id: ServiceId,
+    path: str,
+    *,
+    validate: bool = True,
+    history: bool = True,
+    severity: str = "medium",
+    timeout_seconds: float = 60.0,
+) -> ScanResult:
+    """Scan a directory for keys belonging to ONE specific named service.
+
+    Thin wrapper around `ciphra scan --json --service <service_id>`. The
+    TS CLI's --service flag pre-filters the detector list so only the
+    named service's detectors and validator run — no post-hoc filtering
+    happens here.
+
+    Defaults to validate=True (opposite of scan_directory's MCP default)
+    because the user has explicitly narrowed to a single service and the
+    validation cost is bounded by the count of findings for that one
+    service.
+
+    service_id is validated against KNOWN_SERVICE_IDS as defense-in-depth:
+    FastMCP's Literal catches bad values at the MCP protocol layer, but
+    direct Python callers (or future internal use) bypass that check.
+    """
+    if service_id not in KNOWN_SERVICE_IDS:
+        raise ValueError(
+            f"unknown service_id {service_id!r}. Must be one of: "
+            f"{', '.join(KNOWN_SERVICE_IDS)}"
+        )
+
+    cli_args: list[str] = [
+        "--service", service_id, "--severity", severity, path,
+    ]
+    if not validate:
+        cli_args.append("--no-validate")
+    if not history:
+        cli_args.append("--no-history")
+    return await _run_scan_subprocess(cli_args, timeout_seconds=timeout_seconds)

ciphra_mcp-0.1.0/src/ciphra_mcp/server.py

@@ -0,0 +1,306 @@
+"""Ciphra MCP server (stdio transport).
+
+Phase 2.2 complete — `scan_directory`, `validate_key`, `scan_git_history`,
+and `check_specific_service` are all registered.
+
+Critical gotcha: stdout is the MCP protocol channel (JSON-RPC). Anything
+written to stdout that isn't a valid protocol message will corrupt the
+session. Logging therefore goes to stderr.
+"""
+
+from __future__ import annotations
+
+import logging
+import sys
+from importlib.metadata import PackageNotFoundError, version
+from typing import Annotated, Literal
+
+from mcp.server.fastmcp import FastMCP
+from pydantic import Field
+
+from ciphra_mcp import ciphra_client
+
+SERVER_NAME = "ciphra"
+
+try:
+    SERVER_VERSION = version("ciphra-mcp")
+except PackageNotFoundError:
+    SERVER_VERSION = "0.0.0+unknown"
+
+logging.basicConfig(
+    level=logging.INFO,
+    stream=sys.stderr,
+    format="%(asctime)s %(name)s %(levelname)s %(message)s",
+)
+logger = logging.getLogger(__name__)
+
+mcp = FastMCP(SERVER_NAME)
+# FastMCP's constructor does not accept a server version, so the protocol's
+# initialize response would otherwise advertise the MCP SDK's version
+# (e.g. "1.27.1") under serverInfo. Set the underlying low-level server's
+# version field directly so clients see our package version.
+mcp._mcp_server.version = SERVER_VERSION
+
+
+@mcp.tool(
+    description=(
+        "Use this to answer 'is this codebase secure?' or 'are there "
+        "leaked keys?' — scans a directory and its subdirectories (and by "
+        "default its git history) for exposed API keys, tokens, and "
+        "credentials across 10 services: Stripe, OpenAI, Anthropic, AWS, "
+        "GitHub, Google, Twilio, SendGrid, Slack, Supabase. Validation "
+        "against live APIs is off by default (set validate=true to "
+        "enable). Returns structured findings with severity, file path, "
+        "line number, redacted preview, and validation status. For "
+        "audits focused on one named service, use check_specific_service. "
+        "For validating a single known key value, use validate_key."
+    )
+)
+async def scan_directory(
+    path: Annotated[
+        str,
+        Field(
+            description=(
+                "Absolute or relative path to the directory to scan. Must "
+                "be an existing directory. Use '.' for the current working "
+                "directory."
+            )
+        ),
+    ],
+    validate: Annotated[
+        bool,
+        Field(
+            description=(
+                "If true, discovered keys are validated against their "
+                "respective live APIs to confirm they are active. This "
+                "makes network requests to services like Stripe and OpenAI "
+                "using the discovered keys. Defaults to false in this MCP "
+                "tool (different from the CLI) because the agent should "
+                "opt in explicitly when active-key confirmation is needed, "
+                "rather than implicitly sending keys to third-party APIs "
+                "on every scan. When validation runs, findings include a "
+                "validation status. Note that an 'invalid' status does not "
+                "mean the leak is safe — the key was still exposed, and "
+                "should be rotated regardless. Validation status is "
+                "metadata, not a safety signal."
+            )
+        ),
+    ] = False,
+    history: Annotated[
+        bool,
+        Field(
+            description=(
+                "If true (default), git commit history is also scanned for "
+                "keys that may have been deleted from current files. "
+                "Requires the path to be inside a git repository; otherwise "
+                "this is skipped silently. Set to false to scan only current "
+                "file contents."
+            )
+        ),
+    ] = True,
+    severity: Annotated[
+        Literal["critical", "high", "medium", "info"],
+        Field(
+            description=(
+                "Minimum severity threshold for returned findings. One of: "
+                "'critical', 'high', 'medium' (default), 'info'. Findings "
+                "below the threshold are omitted from the response."
+            )
+        ),
+    ] = "medium",
+) -> dict:
+    return await ciphra_client.scan_directory(
+        path,
+        validate=validate,
+        history=history,
+        severity=severity,
+    )
+
+
+VALIDATE_KEY_DESCRIPTION = (
+    "Use this to answer 'is this specific key currently active?' — sends "
+    "a single key to its service's live API and returns the result. Only "
+    "call when the user owns the key or has explicitly asked; never "
+    "validate keys from third-party code, public repos, or pastes "
+    "without permission (the call is logged at the service). Returns "
+    "status (valid, invalid, unknown, unsupported) and reason; the key "
+    "is never echoed back. Validation status is metadata about the "
+    "key's current state, not a safety signal — if a key was found in "
+    "a codebase, treat the leak as compromised regardless of whether "
+    "validation returns 'valid' or 'invalid'. For finding keys-by-"
+    "pattern in a codebase (e.g., 'are there any Stripe keys here?'), "
+    "use scan_directory or check_specific_service. For finding a "
+    "specific literal key value, basic search tools (grep, git log -S) "
+    "are usually faster than pattern-based scans."
+)
+
+SERVICE_ID_PARAM_DESCRIPTION = (
+    "Machine-readable service identifier. Must be one of the 10 supported "
+    "values. Use the serviceId field from a scan_directory finding, or "
+    "pick the appropriate value based on the key's format if the user "
+    "supplied a raw key."
+)
+
+KEY_PARAM_DESCRIPTION = (
+    "The API key to validate. Sent to the service's live API to check if "
+    "it is active. This value is never logged and never echoed back. "
+    "Note that calling this tool with a key creates a record at the "
+    "third-party service (their API will log the authentication attempt)."
+)
+
+
+@mcp.tool(description=VALIDATE_KEY_DESCRIPTION)
+async def validate_key(
+    service_id: Annotated[
+        Literal[
+            "stripe", "openai", "anthropic", "aws", "github",
+            "google", "twilio", "sendgrid", "slack", "supabase",
+        ],
+        Field(description=SERVICE_ID_PARAM_DESCRIPTION),
+    ],
+    key: Annotated[str, Field(description=KEY_PARAM_DESCRIPTION)],
+) -> dict:
+    return await ciphra_client.validate_key(service_id, key)
+
+
+SCAN_GIT_HISTORY_DESCRIPTION = (
+    "Use this to answer 'did I ever commit a key I later deleted?' — "
+    "walks the git commit history of a repository and returns keys that "
+    "were committed at some point but may be absent from current files. "
+    "Useful for auditing past commits and branches; keys removed from "
+    "HEAD remain recoverable from history and are considered "
+    "compromised. Returns findings only from git history — current file "
+    "contents are NOT scanned. Path must be inside a git repository. "
+    "For a full scan including current files, use scan_directory. For "
+    "a current+history scan filtered to one service, use "
+    "check_specific_service with history=true (note: that combines "
+    "current files and history; this tool is history-only)."
+)
+
+SCAN_GIT_HISTORY_PATH_PARAM_DESCRIPTION = (
+    "Absolute or relative path inside a git repository to audit. The "
+    "scan walks the full git history reachable from all branches. Must "
+    "be a path inside a git repo — passing a non-git directory raises "
+    "an error."
+)
+
+SCAN_GIT_HISTORY_VALIDATE_PARAM_DESCRIPTION = (
+    "If true, discovered historical keys are validated against their "
+    "live APIs to check if they're still active. Defaults to false. "
+    "When validation runs, findings include a validation status. Note "
+    "that an 'invalid' status does not mean the leak is safe — the key "
+    "was still exposed (and a key in git history remains recoverable "
+    "forever), and should be rotated regardless. Validation status is "
+    "metadata, not a safety signal."
+)
+
+SCAN_GIT_HISTORY_SEVERITY_PARAM_DESCRIPTION = (
+    "Minimum severity threshold for returned findings. One of: "
+    "'critical', 'high', 'medium' (default), 'info'."
+)
+
+
+@mcp.tool(description=SCAN_GIT_HISTORY_DESCRIPTION)
+async def scan_git_history(
+    path: Annotated[str, Field(description=SCAN_GIT_HISTORY_PATH_PARAM_DESCRIPTION)],
+    validate: Annotated[
+        bool,
+        Field(description=SCAN_GIT_HISTORY_VALIDATE_PARAM_DESCRIPTION),
+    ] = False,
+    severity: Annotated[
+        Literal["critical", "high", "medium", "info"],
+        Field(description=SCAN_GIT_HISTORY_SEVERITY_PARAM_DESCRIPTION),
+    ] = "medium",
+) -> dict:
+    return await ciphra_client.scan_git_history(
+        path, validate=validate, severity=severity
+    )
+
+
+CHECK_SPECIFIC_SERVICE_DESCRIPTION = (
+    "Use this when the user has named a specific service of concern "
+    "('worried about Stripe keys', 'any OpenAI keys leaked?') — scans "
+    "a directory for keys belonging to ONE service and validates them "
+    "in a single call. Faster and more focused than scan_directory "
+    "because only the named service's detectors run. Unlike "
+    "scan_directory (which defaults validate=false to avoid network "
+    "calls on every scan), this tool defaults validate=true: scope is "
+    "narrow, and the user typically wants to know whether keys are "
+    "both present and still active. Also scans git history by default. "
+    "For a general scan across services, use scan_directory. For "
+    "checking a single key value, use validate_key."
+)
+
+CHECK_SPECIFIC_SERVICE_SERVICE_ID_PARAM_DESCRIPTION = (
+    "Machine-readable identifier of the single service to scan for. "
+    "Must be one of the 10 supported values. Pick based on the user's "
+    "phrasing: 'Stripe' → 'stripe', 'OpenAI' / 'GPT' → 'openai', "
+    "'Anthropic' / 'Claude' → 'anthropic', 'AWS' / 'Amazon' → 'aws', etc."
+)
+
+CHECK_SPECIFIC_SERVICE_PATH_PARAM_DESCRIPTION = (
+    "Absolute or relative path to the directory to scan. Same semantics "
+    "as scan_directory's path parameter."
+)
+
+CHECK_SPECIFIC_SERVICE_VALIDATE_PARAM_DESCRIPTION = (
+    "If true (default), discovered keys are validated against the "
+    "service's live API to confirm they are currently active. Defaults "
+    "to true for this tool (unlike scan_directory) because the user has "
+    "specifically narrowed to one service and the validation cost is "
+    "bounded. Set to false to skip the network calls. When validation "
+    "runs, findings include a validation status. Note that an 'invalid' "
+    "status does not mean the leak is safe — the key was still exposed, "
+    "and should be rotated regardless. Validation status is metadata, "
+    "not a safety signal."
+)
+
+CHECK_SPECIFIC_SERVICE_HISTORY_PARAM_DESCRIPTION = (
+    "If true (default), git commit history is also scanned. Set to false "
+    "to scan only current files. Requires the path to be inside a git "
+    "repository for history scanning; otherwise that part is skipped "
+    "silently."
+)
+
+CHECK_SPECIFIC_SERVICE_SEVERITY_PARAM_DESCRIPTION = (
+    "Minimum severity threshold for returned findings. One of: "
+    "'critical', 'high', 'medium' (default), 'info'."
+)
+
+
+@mcp.tool(description=CHECK_SPECIFIC_SERVICE_DESCRIPTION)
+async def check_specific_service(
+    service_id: Annotated[
+        Literal[
+            "stripe", "openai", "anthropic", "aws", "github",
+            "google", "twilio", "sendgrid", "slack", "supabase",
+        ],
+        Field(description=CHECK_SPECIFIC_SERVICE_SERVICE_ID_PARAM_DESCRIPTION),
+    ],
+    path: Annotated[str, Field(description=CHECK_SPECIFIC_SERVICE_PATH_PARAM_DESCRIPTION)],
+    validate: Annotated[
+        bool,
+        Field(description=CHECK_SPECIFIC_SERVICE_VALIDATE_PARAM_DESCRIPTION),
+    ] = True,
+    history: Annotated[
+        bool,
+        Field(description=CHECK_SPECIFIC_SERVICE_HISTORY_PARAM_DESCRIPTION),
+    ] = True,
+    severity: Annotated[
+        Literal["critical", "high", "medium", "info"],
+        Field(description=CHECK_SPECIFIC_SERVICE_SEVERITY_PARAM_DESCRIPTION),
+    ] = "medium",
+) -> dict:
+    return await ciphra_client.check_specific_service(
+        service_id, path,
+        validate=validate, history=history, severity=severity,
+    )
+
+
+def main() -> None:
+    """Entry point for the `ciphra-mcp` console script.
+
+    Starts the MCP server over stdio. Blocks until the client disconnects.
+    """
+    logger.info("starting %s v%s (stdio)", SERVER_NAME, SERVER_VERSION)
+    mcp.run()

ciphra_mcp-0.1.0/src/ciphra_mcp/types.py

@@ -0,0 +1,93 @@
+"""TypedDicts mirroring the Ciphra CLI JSON output schema (schemaVersion 1.0).
+
+The TS CLI is the source of truth for this shape; see src/cli/format-json.ts
+in the repo root. If the schemaVersion is ever bumped, both the constant
+below and these TypedDicts must be updated in lockstep.
+"""
+
+from __future__ import annotations
+
+from typing import Literal, Optional, TypedDict, get_args
+
+EXPECTED_SCHEMA_VERSION = "1.0"
+
+Severity = Literal["critical", "high", "medium", "info"]
+Source = Literal["file", "git-history"]
+Confidence = Literal["high", "medium", "low"]
+ValidationStatus = Literal["valid", "invalid", "unknown", "unsupported"]
+ServiceId = Literal[
+    "stripe",
+    "openai",
+    "anthropic",
+    "aws",
+    "github",
+    "google",
+    "twilio",
+    "sendgrid",
+    "slack",
+    "supabase",
+]
+
+# Runtime-iterable tuple derived from the Literal above. Use this for
+# membership checks (e.g. `if x in KNOWN_SERVICE_IDS`); `Literal` itself
+# is a type-time-only construct and doesn't enforce membership at runtime.
+KNOWN_SERVICE_IDS: tuple[str, ...] = get_args(ServiceId)
+
+
+class Validation(TypedDict):
+    status: ValidationStatus
+    reason: Optional[str]
+    checkedAt: str
+
+
+class Finding(TypedDict):
+    id: str
+    severity: Severity
+    serviceId: ServiceId
+    serviceName: str
+    detectorName: str
+    filePath: str
+    relativePath: str
+    line: int
+    column: int
+    redactedSecret: str
+    source: Source
+    confidence: Confidence
+    commitSha: Optional[str]
+    validation: Optional[Validation]
+
+
+class Summary(TypedDict):
+    total: int
+    critical: int
+    high: int
+    medium: int
+    info: int
+    byService: dict[str, int]
+
+
+class CiphraVersion(TypedDict):
+    version: str
+
+
+class ScanResult(TypedDict):
+    schemaVersion: str
+    ciphra: CiphraVersion
+    scanPath: str
+    scannedAt: str
+    scanDurationMs: int
+    filesScanned: int
+    summary: Summary
+    findings: list[Finding]
+
+
+class ServiceInfo(TypedDict):
+    id: ServiceId
+    name: str
+
+
+class ValidateResult(TypedDict):
+    schemaVersion: str
+    ciphra: CiphraVersion
+    service: ServiceInfo
+    validation: Validation