mcp-trust 0.1.0__tar.gz

mcp_trust-0.1.0/.dockerignore

@@ -0,0 +1,19 @@
+# Dockerfile.scan copies nothing from the build context (only the uv binaries
+# from a build stage), so none of this would reach the image anyway — but keep
+# the context small and never hand the local registry DB / receipts to the
+# Docker daemon.
+.venv/
+.git/
+registry.db
+*.db
+receipts/
+site/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.serena/
+node_modules/
+dist/
+build/

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

@@ -0,0 +1,25 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        run: uv python install 3.11
+
+      - name: Install dependencies
+        run: uv sync --frozen --extra dev
+
+      - name: Run tests
+        run: uv run pytest -q

mcp_trust-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,34 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  build-and-publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read   # checkout needs read on this (private) repo
+      id-token: write  # OIDC trusted publishing
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.11"
+
+      # Gate the release on the test suite: a broken tag must not publish.
+      - name: Test gate
+        run: uv run --extra dev pytest -q
+
+      - name: Build wheel and sdist
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

mcp_trust-0.1.0/.gitignore

@@ -0,0 +1,30 @@
+__pycache__/
+*.pyc
+.venv/
+venv/
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+*.db
+*.sqlite3
+.env
+receipts/
+
+# generated static-site output (build artifact)
+/site/
+
+# serena language-server project cache
+.serena/
+
+# sandbox/worktree build-cache symlinks
+.build
+.cargo
+.next
+dist/
+node_modules/
+target/
+
+# agent worktree dir
+.claude/

mcp_trust-0.1.0/AGENTS.md

@@ -0,0 +1,89 @@
+# AGENTS.md — MCP Trust Registry
+
+## Project Summary
+MCP Trust Registry is a neutral public trust registry for MCP servers. Its product
+loop is "check before you connect": register public MCP servers, scan them with a
+pluggable engine, normalize the results into an A-F danger grade plus transparency
+signal, persist the record, and serve it through a public API, web catalog, and
+README badge endpoint.
+
+This repo is not trying to win by being another scanner. The scanner is a
+replaceable backend; the durable layer is the public catalog, stable lookup API,
+trust-grade normalization, and author badge distribution loop. The current real
+engine adapter wraps `mcp-audits`, while the default `StubEngine` keeps the full
+system testable without launching untrusted code.
+
+## Current State
+The MVP is built and tested end to end: seed catalog, scan, grade, persist,
+serve JSON and web views, and emit shields.io-compatible badge JSON. The repo is
+currently private/pre-launch. The seed catalog now contains official reference
+MCP servers for launch calibration. Public launch is gated by validating
+sandboxed real-engine scans, inspecting the grade distribution, deciding whether
+to broaden beyond reference servers, deploying the FastAPI app with persistent
+SQLite storage, and smoke-testing the badge loop against the public base URL.
+
+## Stack
+- Python 3.11+
+- FastAPI and Uvicorn for the API/web surface
+- Typer for the CLI
+- Pydantic domain models
+- SQLite persistence
+- Pytest and Ruff for local verification
+- Optional `mcp-audits` engine extra for real MCP-server scanning
+
+## How To Run
+Install and run the deterministic local path:
+
+```bash
+uv venv .venv
+. .venv/bin/activate
+uv pip install -e ".[dev]"
+python -m pytest -q
+ruff check src tests
+mcp-trust seed
+mcp-trust scan mcp-reference-time
+mcp-trust check mcp-reference-time
+mcp-trust serve
+```
+
+Run the real engine only when the target server is trusted or sandboxed:
+
+```bash
+uv pip install -e ".[dev,engine]"
+MCP_TRUST_ENGINE=mcpaudit mcp-trust scan mcp-reference-time
+MCP_TRUST_ENGINE=mcpaudit MCP_TRUST_SANDBOX=docker mcp-trust scan mcp-reference-time
+```
+
+Use `LAUNCH.md` as the public-launch runbook. Use `SPEC.md` as the product and
+module-boundary contract.
+
+## Known Risks
+- Real scans launch server processes. Never scan untrusted servers without an
+  isolation decision; prefer `MCP_TRUST_SANDBOX=docker` and a purpose-built
+  image for public catalog scans.
+- API scan triggering with the real `mcpaudit` engine is operator-gated by
+  `MCP_TRUST_SCAN_TOKEN`; public callers must not be able to launch scans.
+- The current seed catalog contains official reference servers. Public grades
+  are not meaningful until real sandbox scans run and grading bands are checked
+  against that distribution.
+- Low-transparency servers can look risky because annotations are missing; keep
+  danger grade and transparency as separate signals instead of collapsing them
+  into one overconfident verdict.
+- Public launch is a one-way trust event. Do not make the repository public or
+  send author-badge outreach until the live catalog, sandbox path, deployment,
+  and smoke tests are green.
+
+## Next Recommended Move
+Start Docker/Colima, build `Dockerfile.scan`, run one sandboxed `mcp-audits`
+smoke scan against `mcp-reference-time`, then run the full reference corpus,
+inspect the resulting grade distribution, recalibrate bands if needed, and
+deploy the API with persistent SQLite storage for a live badge-loop smoke test.
+
+## Agent Operating Notes
+- Keep `core/` and `engine/base.py` contracts stable unless the spec is updated
+  first.
+- Do not put secrets or environment values in server source specs; `env_keys`
+  are names only.
+- Prefer adding tests beside the module being changed.
+- Treat scanner behavior, grading changes, and public-launch steps as
+  high-trust-surface changes that require explicit verification.

mcp_trust-0.1.0/DEPLOY-VERCEL.md

@@ -0,0 +1,92 @@
+# Deploy: static catalog → Vercel
+
+Low-ops launch path: render the catalog to static HTML/JSON **locally**, then
+deploy the rendered output to Vercel. This is the alternative to the always-on
+VM service documented in `DEPLOY-VM.md`.
+
+## Why build locally (not on Vercel)
+
+The site is generated from `registry.db`, which holds scan data and is **never
+committed** (`.gitignore`). So Vercel cannot build from a fresh `git clone`.
+Instead, the build runs where the data lives (your machine or a scheduled job),
+and only the **public-safe rendered output** (`site/`) is uploaded. The raw scan
+database and receipts stay local. Freshness comes from re-running the build on a
+schedule (see `Scheduled freshness`), not from Vercel's Git integration.
+
+## Prerequisites
+
+- The Vercel CLI is installed and you are logged in (`vercel login`).
+- A Vercel project exists (or accept the prompts on first `vercel` run).
+- A domain you control, to set `--base-url` (badge embeds resolve against it).
+
+## 1. Build the static site from real data
+
+`DOMAIN` must be the final public URL so README badge-embed snippets point at the
+live host. The build is read-only against `registry.db`; it never scans.
+
+```bash
+DOMAIN="https://<your-domain>"
+uv run python scripts/build_site.py \
+  --db ./registry.db \
+  --out site \
+  --base-url "$DOMAIN"
+# Expect: "Built static site for 7 server(s) (7 scanned) ... VERIFY OK"
+```
+
+Ship the deploy config with the rendered output so headers/CSP/clean-URLs apply:
+
+```bash
+cp deploy/vercel.json site/vercel.json
+```
+
+## 2. Preview deploy (no production traffic)
+
+```bash
+vercel deploy site                 # prints a preview URL
+```
+
+Open the preview URL and confirm, on the real grades:
+
+- Catalog (`/`) lists all 7 servers with A–F grades and **no `DEMO DATA` banner**
+  (real scans → no demo label).
+- A detail page (`/ui/servers/mcp-reference-filesystem`) renders the grade,
+  transparency, findings, and the badge-embed snippet.
+- `/servers/mcp-reference-time/badge.json` returns a shields.io endpoint payload
+  (`"message": "A"`, no `(demo)` suffix).
+- An unknown path (e.g. `/nope`) serves the 404 page.
+
+## 3. Production deploy (operator action — public)
+
+```bash
+vercel deploy site --prod          # promotes to the production domain
+```
+
+Then point your domain at the Vercel project (Vercel dashboard → Domains) and
+re-run the badge check against the production URL.
+
+## 4. Scheduled freshness
+
+`scripts/refresh_and_publish.sh` runs the whole loop: re-scan the corpus in the
+network-off Docker sandbox, rebuild the site, and (only if `MCP_TRUST_AUTO_DEPLOY=1`)
+deploy. Install it as a weekly launchd job:
+
+```bash
+bash deploy/launchd/install.sh            # weekly, Monday 09:00; deploy OFF by default
+launchctl start com.d.mcp-trust-refresh   # force one run to test
+bash deploy/launchd/uninstall.sh          # remove the job
+```
+
+Deploy is opt-in: in the installed plist
+(`~/Library/LaunchAgents/com.d.mcp-trust-refresh.plist`) set
+`MCP_TRUST_SITE_BASE_URL` to your real domain and add `MCP_TRUST_AUTO_DEPLOY=1`,
+then re-run the install script. Re-scanning a version-pinned image is
+deterministic; to catch upstream drift, periodically rebuild `Dockerfile.scan`
+with current server versions.
+
+## Safety notes
+
+- `registry.db` and `receipts/` are **never** uploaded — only `site/`.
+- The static site is read-only; there is no scan-trigger endpoint to protect
+  (unlike the VM service). Re-scans happen locally, behind the sandbox.
+- Grades are honest by construction: stub/demo data carries a loud banner and
+  `(demo)`-suffixed badges; only real `mcpaudit` scans render bare grades.

mcp_trust-0.1.0/DEPLOY-VM.md

@@ -0,0 +1,223 @@
+# MCP Trust VM Deployment Package
+
+This is the v1 deployment lane: one controlled VM/VPS, a read-only public app,
+operator-run Docker scans, persistent SQLite, durable receipts, and nightly
+backups.
+
+Public traffic must never launch an MCP server. The public service runs with
+`MCP_TRUST_PUBLIC_READONLY=1`.
+
+## Target Layout
+
+```text
+/opt/mcp-trust/app
+/etc/mcp-trust/mcp-trust.env
+/data/mcp-trust/registry.db
+/data/mcp-trust/receipts/
+/data/mcp-trust/backups/
+/var/log/mcp-trust/
+```
+
+## VM Baseline
+
+Use a small Ubuntu VM with Docker, Caddy, Git, `uv`, and SQLite:
+
+```bash
+sudo apt-get update
+sudo apt-get install -y ca-certificates curl git sqlite3 caddy
+
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+sudo install -d -m 0755 /opt/mcp-trust /etc/mcp-trust /data/mcp-trust/receipts /data/mcp-trust/backups /var/log/mcp-trust
+sudo useradd --system --home /opt/mcp-trust --shell /usr/sbin/nologin mcp-trust || true
+sudo chown -R mcp-trust:mcp-trust /opt/mcp-trust /data/mcp-trust /var/log/mcp-trust
+```
+
+Install Docker Engine using Docker's official Ubuntu instructions, then confirm:
+
+```bash
+docker info
+```
+
+## App Install
+
+Clone or copy the repo into `/opt/mcp-trust/app`, then install into a venv:
+
+```bash
+cd /opt/mcp-trust/app
+uv venv .venv
+. .venv/bin/activate
+uv pip install -e ".[engine]"
+```
+
+Copy the env file and keep it secret-owned:
+
+```bash
+sudo cp deploy/mcp-trust.env.example /etc/mcp-trust/mcp-trust.env
+sudo chown root:mcp-trust /etc/mcp-trust/mcp-trust.env
+sudo chmod 0640 /etc/mcp-trust/mcp-trust.env
+```
+
+Required public env:
+
+```bash
+MCP_TRUST_DB=/data/mcp-trust/registry.db
+MCP_TRUST_ENGINE=mcpaudit
+MCP_TRUST_PUBLIC_READONLY=1
+```
+
+Do not set `MCP_TRUST_ALLOW_UNAUTHENTICATED_STUB_SCANS` on the VM.
+
+## Seed Data And Receipts
+
+Build a sanitized transfer bundle from the workstation after scans pass:
+
+```bash
+python scripts/build_deploy_bundle.py \
+  --db ./registry.db \
+  --receipts-dir ./receipts
+```
+
+Upload the resulting `dist/mcp-trust-deploy-bundle-*.tar.gz` to the VM, extract
+it, and copy its contents into `/data/mcp-trust/`:
+
+```bash
+tar -xzf mcp-trust-deploy-bundle-*.tar.gz
+sudo install -m 0644 mcp-trust-deploy-bundle-*/registry.db /data/mcp-trust/registry.db
+sudo rsync -a --delete mcp-trust-deploy-bundle-*/receipts/ /data/mcp-trust/receipts/
+sudo chown -R mcp-trust:mcp-trust /data/mcp-trust
+```
+
+The bundle DB contains only latest scan rows, so historical local rehearsal rows
+and absolute local receipt paths are not copied to the VM.
+
+For a fresh VM rehearsal that scans directly on the VM, use the operator shell:
+
+```bash
+cd /opt/mcp-trust/app
+export MCP_TRUST_DB=/data/mcp-trust/registry.db
+export MCP_TRUST_RECEIPTS_DIR=/data/mcp-trust/receipts
+export MCP_TRUST_ENGINE=mcpaudit
+export MCP_TRUST_SANDBOX=docker
+export MCP_TRUST_SANDBOX_NETWORK=none
+export MCP_TRUST_SANDBOX_IMAGE=mcp-trust-scan:reference-2026-06-19
+
+.venv/bin/mcp-trust seed
+docker build -f Dockerfile.scan -t mcp-trust-scan:reference-2026-06-19 .
+.venv/bin/mcp-trust scan mcp-reference-time
+python scripts/validate_launch_state.py \
+  --db /data/mcp-trust/registry.db \
+  --receipts-dir /data/mcp-trust/receipts
+```
+
+Run additional approved scans only after the candidate/source/sandbox decision
+is recorded in `LAUNCH-CATALOG.md`.
+
+## Systemd Service
+
+Install and start the read-only API service:
+
+```bash
+sudo cp deploy/mcp-trust.service /etc/systemd/system/mcp-trust.service
+sudo systemctl daemon-reload
+sudo systemctl enable --now mcp-trust.service
+sudo systemctl status mcp-trust.service
+```
+
+The service binds to `127.0.0.1:8000`. It should not be reachable directly from
+the public internet.
+
+## Caddy Reverse Proxy
+
+Edit `deploy/Caddyfile` and replace:
+
+- `admin@example.com`
+- `mcptrust.example.com`
+
+Then install it:
+
+```bash
+sudo cp deploy/Caddyfile /etc/caddy/Caddyfile
+sudo caddy validate --config /etc/caddy/Caddyfile
+sudo systemctl reload caddy
+```
+
+## Nightly Backups
+
+Install the backup units:
+
+```bash
+sudo cp deploy/mcp-trust-backup.service /etc/systemd/system/mcp-trust-backup.service
+sudo cp deploy/mcp-trust-backup.timer /etc/systemd/system/mcp-trust-backup.timer
+sudo systemctl daemon-reload
+sudo systemctl enable --now mcp-trust-backup.timer
+sudo systemctl start mcp-trust-backup.service
+sudo systemctl status mcp-trust-backup.service
+```
+
+The backup script writes:
+
+```text
+/data/mcp-trust/backups/registry-<timestamp>.db
+/data/mcp-trust/backups/receipts-<timestamp>.tar.gz
+```
+
+After the first backup, copy at least one DB backup and one receipt tarball
+off-box.
+
+## Read-Only Smoke
+
+Run this from the VM or your workstation after DNS/HTTPS is live:
+
+```bash
+BASE_URL=https://mcptrust.example.com SLUG=mcp-reference-time ./deploy/smoke-readonly.sh
+```
+
+Before the smoke, run the offline state verifier on the VM:
+
+```bash
+python scripts/validate_launch_state.py \
+  --db /data/mcp-trust/registry.db \
+  --receipts-dir /data/mcp-trust/receipts
+```
+
+Manual checks:
+
+```bash
+curl -s "$BASE_URL/healthz"
+curl -s "$BASE_URL/servers" | head
+open "$BASE_URL/"
+open "$BASE_URL/ui/servers/mcp-reference-time"
+curl -s "$BASE_URL/servers/mcp-reference-time/badge.json"
+curl -i -X POST "$BASE_URL/servers/mcp-reference-time/scan"
+```
+
+Expected `POST /scan` result: `403 Forbidden`.
+
+## Rollback
+
+Use the last known-good git checkout plus the last known-good DB backup:
+
+```bash
+sudo systemctl stop mcp-trust.service
+sudo cp /data/mcp-trust/backups/registry-<timestamp>.db /data/mcp-trust/registry.db
+sudo chown mcp-trust:mcp-trust /data/mcp-trust/registry.db
+cd /opt/mcp-trust/app
+git checkout <known-good-ref>
+. .venv/bin/activate
+uv pip install -e ".[engine]"
+sudo systemctl start mcp-trust.service
+```
+
+Then rerun the read-only smoke.
+
+## Launch Gate
+
+Do not make the repo/site public until:
+
+- `systemctl status mcp-trust.service` is healthy.
+- Caddy serves HTTPS for the final domain.
+- `deploy/smoke-readonly.sh` passes against the public base URL.
+- `POST /servers/<slug>/scan` returns 403 publicly.
+- At least one backup has been created and copied off-box.
+- `LAUNCH-GATE.md` is updated with deployed evidence.

mcp_trust-0.1.0/Dockerfile.scan

@@ -0,0 +1,74 @@
+# syntax=docker/dockerfile:1
+
+# Purpose-built image for approval-gated, network-off reference scans.
+# Build only after the sandbox decision is approved:
+#   docker build -f Dockerfile.scan -t mcp-trust-scan:corpus-2026-06-27 .
+#
+# Reference-server versions are pinned (metadata observed 2026-06-19); the
+# archived official servers added for corpus expansion are unpinned because
+# their releases are frozen (the repos are archived, no new versions ship).
+# Scan-time execution should use MCP_TRUST_SANDBOX_NETWORK=none.
+
+FROM ghcr.io/astral-sh/uv:0.8.15 AS uv
+FROM node:22-slim
+
+ARG SERVER_EVERYTHING_VERSION=2026.1.26
+ARG SERVER_FILESYSTEM_VERSION=2026.1.14
+ARG SERVER_MEMORY_VERSION=2026.1.26
+ARG SERVER_SEQUENTIAL_THINKING_VERSION=2025.12.18
+ARG SERVER_FETCH_VERSION=2026.6.4
+ARG SERVER_GIT_VERSION=2026.6.16
+ARG SERVER_TIME_VERSION=2026.6.4
+
+ENV UV_TOOL_DIR=/opt/uv-tools
+ENV UV_TOOL_BIN_DIR=/usr/local/bin
+
+COPY --from=uv /uv /uvx /usr/local/bin/
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends ca-certificates git python3 \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN npm install --global \
+    "@modelcontextprotocol/server-everything@${SERVER_EVERYTHING_VERSION}" \
+    "@modelcontextprotocol/server-filesystem@${SERVER_FILESYSTEM_VERSION}" \
+    "@modelcontextprotocol/server-memory@${SERVER_MEMORY_VERSION}" \
+    "@modelcontextprotocol/server-sequential-thinking@${SERVER_SEQUENTIAL_THINKING_VERSION}"
+
+RUN uv tool install --python python3 "mcp-server-fetch==${SERVER_FETCH_VERSION}" \
+    && uv tool install --python python3 "mcp-server-git==${SERVER_GIT_VERSION}" \
+    && uv tool install --python python3 "mcp-server-time==${SERVER_TIME_VERSION}"
+
+# --- Archived official reference servers (corpus expansion 2026-06-27) ---
+# Moved to modelcontextprotocol/servers-archived and no longer maintained.
+# Baked because the sandbox blocks registry fetches at scan time (`npx -y` /
+# `uvx` would fail without a pre-installed binary). npm archived releases are
+# frozen so they're unpinned; mcp-server-sqlite is pinned because PyPI is mutable.
+#
+# github, aws-kb-retrieval, sqlite enumerate network-off with NO credentials.
+RUN npm install --global \
+    "@modelcontextprotocol/server-github" \
+    "@modelcontextprotocol/server-aws-kb-retrieval"
+
+RUN uv tool install --python python3 "mcp-server-sqlite==2025.4.25"
+
+# --- Credentialed-sandboxed archived servers (corpus expansion 2026-06-28) ---
+# Token/API-key gated. Now baked so the credentialed-sandboxed scan mode
+# (MCP_TRUST_SCAN_CREDENTIALS=dummy) can launch them network-off with
+# non-functional dummy values and enumerate their real tool surface.
+RUN npm install --global \
+    "@modelcontextprotocol/server-gitlab" \
+    "@modelcontextprotocol/server-slack" \
+    "@modelcontextprotocol/server-brave-search" \
+    "@modelcontextprotocol/server-google-maps" \
+    "@modelcontextprotocol/server-everart"
+
+RUN mkdir -p /fixtures/repo \
+    && git init /fixtures/repo \
+    && git -C /fixtures/repo config user.email "scan-fixture@example.invalid" \
+    && git -C /fixtures/repo config user.name "MCP Trust Scan Fixture" \
+    && printf "fixture repo for mcp-trust reference scans\n" > /fixtures/repo/README.md \
+    && git -C /fixtures/repo add README.md \
+    && git -C /fixtures/repo commit -m "Add scan fixture"
+
+WORKDIR /scan