mcpwatchman 0.0.2__tar.gz

mcpwatchman-0.0.2/.github/dependabot.yml

@@ -0,0 +1,8 @@
+version: 2
+updates:
+  # Release actions are SHA-pinned, which is only safe with something moving
+  # the pins — an unmaintained pin is a stale dependency that looks deliberate.
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly

mcpwatchman-0.0.2/.github/workflows/ci.yml

@@ -0,0 +1,35 @@
+name: ci
+
+on:
+  push:
+    branches: [dev, main]
+  pull_request:
+
+# A lint job reads the checkout and writes nothing; the default grant is wider.
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
+        with:
+          python-version: "3.12"
+      # Via the dev extra so CI and a local `ruff check` share one pinned
+      # version — a floating ruff reds CI the day a release adds a rule.
+      - run: pip install -e ".[dev]"
+      - run: ruff check .
+
+# Publishing lives in release.yml, fired by a vX.Y.Z tag.
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[dev]"
+      - run: pytest

mcpwatchman-0.0.2/.github/workflows/release.yml

@@ -0,0 +1,68 @@
+name: release
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+# Split deliberately: `pip install` executes arbitrary code from transitive
+# dependencies, so it must not run in a job that can mint a publish credential.
+# The build job holds no id-token; the publish job installs nothing.
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
+        with:
+          python-version: "3.12"
+      - run: pip install build twine
+      - run: python -m build
+      # Malformed metadata is rejected at upload — and a rejected upload still
+      # burns the version number, which PyPI never lets you reuse.
+      - run: twine check dist/*
+      # The tag is the only value a human types; everything else is derived from
+      # the tree. Three files must already agree (bump-audit checks one of them),
+      # and __version__ is what `mcpwatchman --version` reports, so a half-bump
+      # would ship a CLI that lies about itself — permanently, at this registry.
+      - name: Tag, artifact and source versions agree
+        run: |
+          set -euo pipefail
+          tag="${GITHUB_REF_NAME#v}"
+          built=$(python -c "import glob,os; print(os.path.basename(glob.glob('dist/*.whl')[0]).split('-')[1])")
+          proj=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          init=$(python -c "import re; print(re.search(r'__version__ = \"([^\"]+)\"', open('src/mcpwatchman/__init__.py').read()).group(1))")
+          echo "tag=$tag wheel=$built pyproject=$proj __version__=$init"
+          for v in "$built" "$proj" "$init"; do
+            [ "$v" = "$tag" ] || { echo "::error::version mismatch — tag $tag vs $v"; exit 1; }
+          done
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    # Actions are pinned to commit SHAs, not tags: a tag is mutable, and any
+    # code running in this job can request the PyPI credential. Dependabot
+    # keeps the pins current (.github/dependabot.yml) so they cannot go stale.
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8.0.1
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33  # v1.14.2
+        with:
+          # Explicit: the action's canonical `packages-dir` declares no default,
+          # and `dist` reaches it only via the deprecated `packages_dir` alias
+          # that upstream has marked for removal in v3+.
+          packages-dir: dist/

mcpwatchman-0.0.2/.gitignore

@@ -0,0 +1,51 @@
+# ── Internal design docs — NEVER committed (workspace policy) ──
+# Strategy, methodology internals, and project memory stay local-only.
+CLAUDE.md
+STATE.md
+.claude/
+/[0-9][0-9]-*.md
+/adrs/
+SPEC*.md
+/scratch/
+
+# ── Python ──
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+env/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.python-version
+
+# ── Node / Astro (site/) ──
+node_modules/
+site/dist/
+site/.astro/
+.astro/
+
+# ── Env / secrets ──
+.env
+.env.*
+!.env.example
+*.local
+
+# ── OS / editor ──
+.DS_Store
+Thumbs.db
+*.swp
+.idea/
+.vscode/
+
+# Wrapper-managed state file: indicates origin push is failing
+ops/autonomous/.push-broken
+
+# Run-log scratch file — local-only, like STATE.md
+RUNLOG.md

mcpwatchman-0.0.2/LICENSE

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

mcpwatchman-0.0.2/PKG-INFO

@@ -0,0 +1,183 @@
+Metadata-Version: 2.5
+Name: mcpwatchman
+Version: 0.0.2
+Summary: Independent security and quality audit for Model Context Protocol servers.
+Project-URL: Homepage, https://mcpwatchman.com
+Project-URL: Repository, https://github.com/kVadrum/mcpwatchman
+Author: kVadrum
+License-Expression: MIT
+License-File: LICENSE
+Keywords: audit,mcp,model-context-protocol,security,static-analysis,supply-chain
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Requires-Python: >=3.12
+Requires-Dist: click>=8.1
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic-settings>=2.3
+Requires-Dist: pydantic>=2.7
+Requires-Dist: rich>=13.7
+Provides-Extra: api
+Requires-Dist: fastapi>=0.111; extra == 'api'
+Requires-Dist: uvicorn[standard]>=0.30; extra == 'api'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest>=8.2; extra == 'dev'
+Requires-Dist: ruff~=0.16.7; extra == 'dev'
+Provides-Extra: workers
+Requires-Dist: alembic>=1.13; extra == 'workers'
+Requires-Dist: detect-secrets>=1.5; extra == 'workers'
+Requires-Dist: semgrep>=1.75; extra == 'workers'
+Requires-Dist: sqlalchemy>=2.0; extra == 'workers'
+Description-Content-Type: text/markdown
+
+# mcpwatchman
+
+**Independent security and quality audit for [Model Context Protocol](https://modelcontextprotocol.io) servers.**
+
+`mcpwatchman` continuously scans every server in the official MCP registry and publishes a transparent, evidence-linked assessment of each one — so you can answer "is this MCP server safe to install?" before you wire it into your agent.
+
+> **Status: early — building in public.**
+> The methodology and architecture are settled and the repository is scaffolded; the scanner, scoring engine, site, and CLI are under active construction.
+> **Nothing here is production-ready, and no scores have been published yet.**
+> Watch the repo to follow along.
+
+---
+
+## Why
+
+MCP adoption is accelerating across Claude Code, Cursor, Continue, Zed, Goose and more — and people are installing servers with the same blind trust they once gave `curl | bash`.
+Research on thousands of public MCP servers has found widespread server-side request forgery, unsafe command execution, and servers exposed over HTTP with no authentication at all.
+
+The official registry is **metadata-only by design** — it lists what exists, not what's safe.
+`mcpwatchman` is the independent safety layer on top of it.
+The closest analogues are [Mozilla Observatory](https://observatory.mozilla.org/) and [OpenSSF Scorecard](https://scorecard.dev/): independent, transparent, free, and trusted precisely because they aren't selling anything to the projects they score.
+
+## How it works
+
+A daily pass over the official registry, then per server:
+
+1. **Resolve** the declared source repository and package artifacts from registry metadata.
+2. **Fetch** published source and lockfiles — a shallow, sparse clone at a pinned commit, into a per-job sandboxed workspace with resource limits and no inbound network.
+3. **Analyze statically** — an MCP-specific [semgrep](https://semgrep.dev) ruleset for the patterns that matter in this ecosystem (tool-handler shell exec, unvalidated URL fetches, unsafe deserialization, path traversal), plus dependency CVE scanning, transport and auth inspection, and repository maintenance signals.
+4. **Score** each axis from the findings, with every point of the score traceable to the artifact that produced it.
+5. **Publish** to the site, JSON API, RSS feeds, and CLI.
+
+**The analysis is static, always.**
+We read published source, manifests and lockfiles.
+**We never execute the code we scan**, and we never connect to a running server instance.
+
+**So here is what a good score cannot tell you.**
+Static analysis reads what a server *publishes*, so the blind spot is whatever that source does not determine: behavior gated on remote configuration, code fetched or generated at runtime, or a deployed server that differs from the repository it declares.
+An unsafe pattern that merely *executes* at tool-invocation time is still detectable — catching those is the ruleset's core job — but a score here is evidence about published source, never a runtime guarantee.
+Running every server we scan is a substantially larger sandboxing problem than reading it, and we would rather be narrow and honest about it than broad and quietly wrong.
+
+## How it scores
+
+Every server is rated 0–100 on five axes, and **every score links to its evidence** — a file and line, a CVE identifier, a commit date.
+No mystery numbers.
+
+| Axis | Default weight | Captures |
+|---|---|---|
+| **Code Safety** | 30% | Static-analysis findings: shell exec, SSRF, deserialization, path traversal |
+| **Auth Posture** | 20% | Authentication model, transport security, secret handling, scope granularity |
+| **Dependency Health** | 20% | Known CVEs in direct and transitive dependencies |
+| **Maintenance** | 15% | Activity, release cadence, issue responsiveness, bus factor |
+| **Transparency** | 15% | License validity, documented behavior, declared scopes |
+
+**Per-axis scores ship first; the composite waits for calibration.**
+The weights above are *provisional* starting values informed by the threat literature — they live in [`src/mcpwatchman/workers/scoring/weights.py`](src/mcpwatchman/workers/scoring/weights.py) and are versioned like any other code.
+They become final only after calibration against a hand-audited gold set of roughly 30 servers spanning categories and a deliberate range of expected results.
+Until that regression suite is green, public surfaces show the per-axis scores and suppress the composite.
+A single blended number is the easiest thing to publish and the easiest thing to get quietly wrong, so it is the last thing we will ship.
+
+The full methodology is published openly — anyone can audit our auditing.
+
+## Principles
+
+- **Methodology over marketing.**
+  Every check, weight and threshold is documented and versioned.
+- **Evidence or it doesn't ship.**
+  A finding with no linked artifact doesn't appear.
+- **Facts, not characterizations.**
+  We describe observed code patterns, never intent.
+  Any finding can be appealed.
+- **Collaborative, not competitive.**
+  We overlay the official registry; we don't replace it.
+  A server exists here only if the official registry lists it.
+- **Free, and staying that way.**
+  The scanner, ruleset, site, API, RSS feeds and CLI are MIT-licensed and free.
+
+## Disclosure
+
+Findings fall into two tracks, and they are handled differently on purpose.
+
+**Track A — publicly observable patterns.**
+Static-analysis hits, license and transport facts: anyone can run the same tools against the same published source and see the same thing.
+There is no informational asymmetry to protect, so these are **not embargoed** — they appear on the server's page from the first scan that detects them.
+Maintainer notification before publication is the right courtesy; delaying a fact every reader could derive themselves is not.
+
+**Track B — findings that warrant coordination.**
+Default embargo is **14 days** from maintainer contact, shortened to **7** where there is evidence of active exploitation, and extended up to **45 days total** when a maintainer comes back with a concrete fix timeline.
+If we cannot reach a maintainer within 48 hours of the first attempt the clock still starts, and the target becomes **21 days from that first attempt** rather than 14 — being slow to check email is not the same as being unresponsive, and we don't punish it.
+
+**Appeals.**
+Anyone can contest a finding — maintainers and third parties alike, per finding, by ID.
+Scores are recomputed, not negotiated: if the evidence is wrong the finding goes, if the code changed a rescan reflects it, and where a finding is technically valid but mitigated by context our rules don't model, it stays on the page with the maintainer's explanation attached.
+
+## Surfaces
+
+| Surface | What it is |
+|---|---|
+| **Site** | Per-server pages with the evidence behind every axis, search and filtering, and the full methodology |
+| **JSON API** | The same data, machine-readable — built to be consumed by agents and CI as a first-class audience, not as an afterthought |
+| **RSS** | High-severity findings and score drops, for people who want to watch the ecosystem rather than one server |
+| **Badges** | An auto-updating SVG a maintainer can put in their own README |
+| **CLI** | `pip install mcpwatchman`, then `mcpwatchman check <server>` before you install it — with a `--threshold` exit code for CI |
+
+## Install
+
+```sh
+pip install mcpwatchman     # not yet published
+```
+
+Requires Python 3.12+.
+
+## Repository layout
+
+```
+rules/                 MCP-specific semgrep ruleset, by language and category
+src/mcpwatchman/
+  cli/                 the `mcpwatchman` command
+  api/                 JSON API (FastAPI)
+  client/              API client shared by the CLI
+  db/                  schema and models
+  workers/crawler/     registry polling and source resolution
+  workers/scanner/     static analysis and dependency scanning
+  workers/scoring/     axis scoring and the versioned weights
+evals/gold-set/        hand-audited servers the scoring calibrates against
+docker/                worker image
+site/                  public site (Astro)
+```
+
+## Contributing
+
+It is early, and the most useful contributions right now are adversarial ones: tell us where the methodology is wrong.
+Open an issue if a proposed check produces false positives you can demonstrate, if an axis misses a real class of MCP risk, or if a weight looks indefensible.
+Rule contributions become genuinely useful once the scanner lands — `rules/` is deliberately open so that the detection logic can be argued with rather than taken on faith.
+
+**Reporting a vulnerability in `mcpwatchman` itself** — not in a server we scan — goes through [GitHub's private vulnerability reporting](https://github.com/kVadrum/mcpwatchman/security/advisories/new) on this repository.
+We hold ourselves to the same disclosure terms we apply to everyone else, with no exception for ourselves.
+
+## License
+
+[MIT](./LICENSE).
+KeMeK Network © 2026.
+
+### Trademarks
+
+The "mcpwatchman" name is a trademark of KeMeK Network.
+It is not covered by the code or content licenses.
+No rights to use the name are granted by this repository.
+Independent forks must replace the brand name with their own.

mcpwatchman-0.0.2/README.md

@@ -0,0 +1,149 @@
+# mcpwatchman
+
+**Independent security and quality audit for [Model Context Protocol](https://modelcontextprotocol.io) servers.**
+
+`mcpwatchman` continuously scans every server in the official MCP registry and publishes a transparent, evidence-linked assessment of each one — so you can answer "is this MCP server safe to install?" before you wire it into your agent.
+
+> **Status: early — building in public.**
+> The methodology and architecture are settled and the repository is scaffolded; the scanner, scoring engine, site, and CLI are under active construction.
+> **Nothing here is production-ready, and no scores have been published yet.**
+> Watch the repo to follow along.
+
+---
+
+## Why
+
+MCP adoption is accelerating across Claude Code, Cursor, Continue, Zed, Goose and more — and people are installing servers with the same blind trust they once gave `curl | bash`.
+Research on thousands of public MCP servers has found widespread server-side request forgery, unsafe command execution, and servers exposed over HTTP with no authentication at all.
+
+The official registry is **metadata-only by design** — it lists what exists, not what's safe.
+`mcpwatchman` is the independent safety layer on top of it.
+The closest analogues are [Mozilla Observatory](https://observatory.mozilla.org/) and [OpenSSF Scorecard](https://scorecard.dev/): independent, transparent, free, and trusted precisely because they aren't selling anything to the projects they score.
+
+## How it works
+
+A daily pass over the official registry, then per server:
+
+1. **Resolve** the declared source repository and package artifacts from registry metadata.
+2. **Fetch** published source and lockfiles — a shallow, sparse clone at a pinned commit, into a per-job sandboxed workspace with resource limits and no inbound network.
+3. **Analyze statically** — an MCP-specific [semgrep](https://semgrep.dev) ruleset for the patterns that matter in this ecosystem (tool-handler shell exec, unvalidated URL fetches, unsafe deserialization, path traversal), plus dependency CVE scanning, transport and auth inspection, and repository maintenance signals.
+4. **Score** each axis from the findings, with every point of the score traceable to the artifact that produced it.
+5. **Publish** to the site, JSON API, RSS feeds, and CLI.
+
+**The analysis is static, always.**
+We read published source, manifests and lockfiles.
+**We never execute the code we scan**, and we never connect to a running server instance.
+
+**So here is what a good score cannot tell you.**
+Static analysis reads what a server *publishes*, so the blind spot is whatever that source does not determine: behavior gated on remote configuration, code fetched or generated at runtime, or a deployed server that differs from the repository it declares.
+An unsafe pattern that merely *executes* at tool-invocation time is still detectable — catching those is the ruleset's core job — but a score here is evidence about published source, never a runtime guarantee.
+Running every server we scan is a substantially larger sandboxing problem than reading it, and we would rather be narrow and honest about it than broad and quietly wrong.
+
+## How it scores
+
+Every server is rated 0–100 on five axes, and **every score links to its evidence** — a file and line, a CVE identifier, a commit date.
+No mystery numbers.
+
+| Axis | Default weight | Captures |
+|---|---|---|
+| **Code Safety** | 30% | Static-analysis findings: shell exec, SSRF, deserialization, path traversal |
+| **Auth Posture** | 20% | Authentication model, transport security, secret handling, scope granularity |
+| **Dependency Health** | 20% | Known CVEs in direct and transitive dependencies |
+| **Maintenance** | 15% | Activity, release cadence, issue responsiveness, bus factor |
+| **Transparency** | 15% | License validity, documented behavior, declared scopes |
+
+**Per-axis scores ship first; the composite waits for calibration.**
+The weights above are *provisional* starting values informed by the threat literature — they live in [`src/mcpwatchman/workers/scoring/weights.py`](src/mcpwatchman/workers/scoring/weights.py) and are versioned like any other code.
+They become final only after calibration against a hand-audited gold set of roughly 30 servers spanning categories and a deliberate range of expected results.
+Until that regression suite is green, public surfaces show the per-axis scores and suppress the composite.
+A single blended number is the easiest thing to publish and the easiest thing to get quietly wrong, so it is the last thing we will ship.
+
+The full methodology is published openly — anyone can audit our auditing.
+
+## Principles
+
+- **Methodology over marketing.**
+  Every check, weight and threshold is documented and versioned.
+- **Evidence or it doesn't ship.**
+  A finding with no linked artifact doesn't appear.
+- **Facts, not characterizations.**
+  We describe observed code patterns, never intent.
+  Any finding can be appealed.
+- **Collaborative, not competitive.**
+  We overlay the official registry; we don't replace it.
+  A server exists here only if the official registry lists it.
+- **Free, and staying that way.**
+  The scanner, ruleset, site, API, RSS feeds and CLI are MIT-licensed and free.
+
+## Disclosure
+
+Findings fall into two tracks, and they are handled differently on purpose.
+
+**Track A — publicly observable patterns.**
+Static-analysis hits, license and transport facts: anyone can run the same tools against the same published source and see the same thing.
+There is no informational asymmetry to protect, so these are **not embargoed** — they appear on the server's page from the first scan that detects them.
+Maintainer notification before publication is the right courtesy; delaying a fact every reader could derive themselves is not.
+
+**Track B — findings that warrant coordination.**
+Default embargo is **14 days** from maintainer contact, shortened to **7** where there is evidence of active exploitation, and extended up to **45 days total** when a maintainer comes back with a concrete fix timeline.
+If we cannot reach a maintainer within 48 hours of the first attempt the clock still starts, and the target becomes **21 days from that first attempt** rather than 14 — being slow to check email is not the same as being unresponsive, and we don't punish it.
+
+**Appeals.**
+Anyone can contest a finding — maintainers and third parties alike, per finding, by ID.
+Scores are recomputed, not negotiated: if the evidence is wrong the finding goes, if the code changed a rescan reflects it, and where a finding is technically valid but mitigated by context our rules don't model, it stays on the page with the maintainer's explanation attached.
+
+## Surfaces
+
+| Surface | What it is |
+|---|---|
+| **Site** | Per-server pages with the evidence behind every axis, search and filtering, and the full methodology |
+| **JSON API** | The same data, machine-readable — built to be consumed by agents and CI as a first-class audience, not as an afterthought |
+| **RSS** | High-severity findings and score drops, for people who want to watch the ecosystem rather than one server |
+| **Badges** | An auto-updating SVG a maintainer can put in their own README |
+| **CLI** | `pip install mcpwatchman`, then `mcpwatchman check <server>` before you install it — with a `--threshold` exit code for CI |
+
+## Install
+
+```sh
+pip install mcpwatchman     # not yet published
+```
+
+Requires Python 3.12+.
+
+## Repository layout
+
+```
+rules/                 MCP-specific semgrep ruleset, by language and category
+src/mcpwatchman/
+  cli/                 the `mcpwatchman` command
+  api/                 JSON API (FastAPI)
+  client/              API client shared by the CLI
+  db/                  schema and models
+  workers/crawler/     registry polling and source resolution
+  workers/scanner/     static analysis and dependency scanning
+  workers/scoring/     axis scoring and the versioned weights
+evals/gold-set/        hand-audited servers the scoring calibrates against
+docker/                worker image
+site/                  public site (Astro)
+```
+
+## Contributing
+
+It is early, and the most useful contributions right now are adversarial ones: tell us where the methodology is wrong.
+Open an issue if a proposed check produces false positives you can demonstrate, if an axis misses a real class of MCP risk, or if a weight looks indefensible.
+Rule contributions become genuinely useful once the scanner lands — `rules/` is deliberately open so that the detection logic can be argued with rather than taken on faith.
+
+**Reporting a vulnerability in `mcpwatchman` itself** — not in a server we scan — goes through [GitHub's private vulnerability reporting](https://github.com/kVadrum/mcpwatchman/security/advisories/new) on this repository.
+We hold ourselves to the same disclosure terms we apply to everyone else, with no exception for ourselves.
+
+## License
+
+[MIT](./LICENSE).
+KeMeK Network © 2026.
+
+### Trademarks
+
+The "mcpwatchman" name is a trademark of KeMeK Network.
+It is not covered by the code or content licenses.
+No rights to use the name are granted by this repository.
+Independent forks must replace the brand name with their own.

mcpwatchman-0.0.2/docker/Dockerfile

@@ -0,0 +1,15 @@
+# Worker image for mcpwatchman scanners (scaffold). See ADR-002 for the tool stack.
+#
+# The production image also installs osv-scanner (a Go binary) and pins the base
+# by SHA digest; this scaffold installs the Python worker deps only.
+FROM python:3.12-slim AS base
+
+# Scans run as a non-root user (uid 1000) per the sandboxing posture.
+RUN useradd --create-home --uid 1000 scanner
+
+WORKDIR /app
+COPY pyproject.toml README.md ./
+COPY src ./src
+RUN pip install --no-cache-dir ".[workers]"
+
+USER scanner

mcpwatchman-0.0.2/pyproject.toml

@@ -0,0 +1,73 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mcpwatchman"
+version = "0.0.2"
+description = "Independent security and quality audit for Model Context Protocol servers."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "kVadrum" }]
+keywords = ["mcp", "model-context-protocol", "security", "audit", "static-analysis", "supply-chain"]
+classifiers = [
+  "Development Status :: 2 - Pre-Alpha",
+  "Intended Audience :: Developers",
+  "Topic :: Security",
+  "Programming Language :: Python :: 3.12",
+]
+# Core deps = the CLI + API client only, so `pip install mcpwatchman` stays light.
+# Scanner/worker and API deps live in optional groups below.
+dependencies = [
+  "click>=8.1",
+  "rich>=13.7",
+  "httpx>=0.27",
+  "pydantic>=2.7",
+  "pydantic-settings>=2.3",
+]
+
+[project.optional-dependencies]
+api = [
+  "fastapi>=0.111",
+  "uvicorn[standard]>=0.30",
+]
+workers = [
+  # DB: ADR-004 (Postgres + SQLAlchemy 2.x + Alembic)
+  "sqlalchemy>=2.0",
+  "alembic>=1.13",
+  # Static analysis: ADR-002 (semgrep core; osv-scanner is an external Go binary)
+  "semgrep>=1.75",
+  "detect-secrets>=1.5",
+  # Queue: leaning Procrastinate (Postgres-native) over RQ — see STATE.md.
+  # Uncomment when the worker queue lands and the choice is ratified.
+  # "procrastinate>=2.0",
+]
+dev = [
+  # Pinned to a minor: ruff gates CI, and new lint rules ship in 0.x releases.
+  "ruff~=0.16.7",
+  "mypy>=1.10",
+  "pytest>=8.2",
+]
+
+[project.urls]
+Homepage = "https://mcpwatchman.com"
+Repository = "https://github.com/kVadrum/mcpwatchman"
+
+[project.scripts]
+mcpwatchman = "mcpwatchman.cli.main:cli"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mcpwatchman"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+src = ["src"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.pytest.ini_options]
+testpaths = ["src", "tests"]

mcpwatchman-0.0.2/rules/README.md

@@ -0,0 +1,23 @@
+# mcpwatchman semgrep rules
+
+The custom MCP-specific semgrep ruleset — the differentiating asset of mcpwatchman.
+Published openly under [MIT](../LICENSE).
+
+Organized by language and category:
+
+```
+rules/
+├── python/         # shell-exec, ssrf, deserialization, path-traversal, mcp-specific
+├── javascript/     # + prototype-pollution
+├── go/
+└── _meta/          # severity-mapping (rule_id -> severity, confidence), changelog
+```
+
+Each rule is tagged with a severity (`critical`/`high`/`medium`/`low`/`informational`)
+and a confidence (`high`/`medium`/`low`). `_meta/severity-mapping.yaml` is the
+canonical map consumed by the scoring engine.
+
+Every rule ships with fixture tests (true positive, true negative, and a
+false-positive-resistance case) and a documented false-positive rate measured
+against the calibration gold set. Rules above a 20% false-positive rate are
+demoted from high to medium confidence (smaller scoring deduction).

mcpwatchman-0.0.2/site/README.md

@@ -0,0 +1,8 @@
+# mcpwatchman site (Astro)
+
+The public site — per-server pages, search/filter, methodology pages, badges,
+and RSS feeds — is built here as a separate Astro project (static-first,
+Cloudflare Pages).
+
+Not scaffolded yet. It will be created with the workspace `frontend-design`
+skill rather than freehanded, to keep the design distinctive and accessible.

mcpwatchman-0.0.2/src/mcpwatchman/__init__.py

@@ -0,0 +1,3 @@
+"""mcpwatchman — independent security and quality audit for MCP servers."""
+
+__version__ = "0.0.2"

mcpwatchman-0.0.2/src/mcpwatchman/api/__init__.py

@@ -0,0 +1 @@
+"""JSON API for mcpwatchman (FastAPI)."""

mcpwatchman-0.0.2/src/mcpwatchman/api/main.py

@@ -0,0 +1,18 @@
+"""mcpwatchman JSON API (scaffold — only the health probe is live).
+
+Run with: uvicorn mcpwatchman.api.main:app  (requires the `api` extra).
+"""
+
+from __future__ import annotations
+
+from fastapi import FastAPI
+
+from mcpwatchman import __version__
+
+app = FastAPI(title="mcpwatchman API", version=__version__)
+
+
+@app.get("/v1/healthz")
+def healthz() -> dict[str, str]:
+    """Liveness probe."""
+    return {"status": "ok"}

mcpwatchman-0.0.2/src/mcpwatchman/cli/__init__.py

@@ -0,0 +1 @@
+"""Command-line interface for mcpwatchman."""

mcpwatchman-0.0.2/src/mcpwatchman/cli/main.py

@@ -0,0 +1,28 @@
+"""mcpwatchman command-line interface (scaffold)."""
+
+from __future__ import annotations
+
+import click
+
+from mcpwatchman import __version__
+
+
+@click.group()
+@click.version_option(__version__, prog_name="mcpwatchman")
+def cli() -> None:
+    """Independent security and quality audit for MCP servers."""
+
+
+@cli.command()
+@click.argument("server")
+def check(server: str) -> None:
+    """Show the trust score for SERVER (not implemented yet)."""
+    # Output formats (--format pretty/json/compact) return once scanning lands.
+    raise click.ClickException(
+        f"scanning {server!r} is not implemented yet — mcpwatchman is pre-v0.1. "
+        "Follow https://github.com/kVadrum/mcpwatchman"
+    )
+
+
+if __name__ == "__main__":
+    cli()

mcpwatchman-0.0.2/src/mcpwatchman/client/__init__.py

@@ -0,0 +1 @@
+"""Typed API client shared by the CLI and internal tooling."""

mcpwatchman-0.0.2/src/mcpwatchman/db/__init__.py

@@ -0,0 +1 @@
+"""Database layer (Postgres + SQLAlchemy 2.x). See ADR-004."""

mcpwatchman-0.0.2/src/mcpwatchman/db/models.py

@@ -0,0 +1,14 @@
+"""SQLAlchemy 2.x models (scaffold).
+
+The schema — servers, server_versions, scan_runs, findings, evidence, scores,
+score_history, and supporting tables — lands with the first Alembic migration.
+Requires the `workers` extra.
+"""
+
+from __future__ import annotations
+
+from sqlalchemy.orm import DeclarativeBase
+
+
+class Base(DeclarativeBase):
+    """Declarative base for all mcpwatchman models."""

mcpwatchman-0.0.2/src/mcpwatchman/workers/__init__.py

@@ -0,0 +1 @@
+"""Crawler, scanner, and scoring engine. Does not import from mcpwatchman.api."""

mcpwatchman-0.0.2/src/mcpwatchman/workers/crawler/__init__.py

@@ -0,0 +1 @@
+"""Registry poller + scan-job enqueue."""

mcpwatchman-0.0.2/src/mcpwatchman/workers/scanner/__init__.py

@@ -0,0 +1 @@
+"""Scan pipeline: source resolution, semgrep, osv-scanner, auth/transport/license detectors."""

mcpwatchman-0.0.2/src/mcpwatchman/workers/scoring/__init__.py

@@ -0,0 +1 @@
+"""Scoring engine: per-axis scores, composite, evidence helpers. The single source of axis math."""

mcpwatchman-0.0.2/src/mcpwatchman/workers/scoring/weights.py

@@ -0,0 +1,54 @@
+"""Versioned axis weights for the mcpwatchman composite score.
+
+These are PROVISIONAL starting values informed by the threat literature, not
+calibration outputs. The composite they produce MUST NOT be published on public
+surfaces until gold-set calibration validates the weights for a given
+methodology version — until then the site, badges, and CLI render per-axis
+scores only (the `COMPOSITE_PUBLISHED` gate below).
+
+Weights are versioned in lockstep with the scoring methodology version, and
+each version's weights sum to 1.0.
+"""
+
+from __future__ import annotations
+
+AXIS_WEIGHTS: dict[str, dict[str, float]] = {
+    "0.2.0": {
+        "code_safety": 0.30,
+        "auth_posture": 0.20,
+        "maintenance": 0.15,
+        "dependency_health": 0.20,
+        "transparency": 0.15,
+    },
+}
+
+CURRENT_METHODOLOGY_VERSION = "0.2.0"
+
+# Per-version gate: composite is exposed publicly only once calibration passes.
+COMPOSITE_PUBLISHED: dict[str, bool] = {
+    "0.2.0": False,
+}
+
+
+def weights_for(version: str = CURRENT_METHODOLOGY_VERSION) -> dict[str, float]:
+    """Return the axis-weight map for a methodology version."""
+    try:
+        return AXIS_WEIGHTS[version]
+    except KeyError:
+        known = ", ".join(sorted(AXIS_WEIGHTS))
+        raise ValueError(f"unknown methodology version {version!r}; known: {known}") from None
+
+
+def composite_published(version: str = CURRENT_METHODOLOGY_VERSION) -> bool:
+    """Whether the composite may be shown publicly for this methodology version.
+
+    Fails CLOSED: an unknown version answers False rather than raising, so a
+    version added to AXIS_WEIGHTS and forgotten here cannot publish an
+    uncalibrated composite. The omission is caught in CI by test_weights.py
+    instead — safe in production, loud where a human is looking.
+
+    Exists so no caller indexes COMPOSITE_PUBLISHED directly: a caller supplying
+    its own `.get(version, True)` default would reintroduce exactly the failure
+    this gate prevents.
+    """
+    return COMPOSITE_PUBLISHED.get(version, False)

mcpwatchman-0.0.2/tests/test_weights.py

@@ -0,0 +1,53 @@
+"""Invariants for the versioned axis weights.
+
+`weights.py` documents two rules and enforced neither: that each version's
+weights sum to 1.0, and that the composite gate has an entry per version.
+Both are hand-edited constants, so CI is the right place to hold them.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from mcpwatchman.workers.scoring.weights import (
+    AXIS_WEIGHTS,
+    COMPOSITE_PUBLISHED,
+    CURRENT_METHODOLOGY_VERSION,
+    composite_published,
+    weights_for,
+)
+
+
+@pytest.mark.parametrize("version", sorted(AXIS_WEIGHTS))
+def test_weights_sum_to_one(version: str) -> None:
+    # Composites are compared across methodology versions; a version summing to
+    # 0.95 silently rescales every score rather than failing.
+    assert sum(AXIS_WEIGHTS[version].values()) == pytest.approx(1.0)
+
+
+@pytest.mark.parametrize("version", sorted(AXIS_WEIGHTS))
+def test_every_version_declares_its_composite_gate(version: str) -> None:
+    # The accessor fails closed, so a missing entry is safe but invisible.
+    # This is the thing that makes it visible.
+    assert version in COMPOSITE_PUBLISHED
+
+
+def test_current_version_is_known() -> None:
+    assert CURRENT_METHODOLOGY_VERSION in AXIS_WEIGHTS
+
+
+def test_composite_stays_unpublished_until_calibration() -> None:
+    # Pins the project's first "Do not": no composite on any public surface
+    # until gold-set calibration passes. When that legitimately flips, this
+    # test fails — which is the point. Flipping it should be deliberate and
+    # reviewed, not a constant edited in passing.
+    assert composite_published() is False
+
+
+def test_unknown_version_fails_closed_not_loud() -> None:
+    assert composite_published("99.0.0") is False
+
+
+def test_weights_for_names_the_known_versions() -> None:
+    with pytest.raises(ValueError, match="known: 0.2.0"):
+        weights_for("99.0.0")