mcp-linter 1.2.0__tar.gz

mcp_linter-1.2.0/.github/workflows/ci.yml

@@ -0,0 +1,74 @@
+name: CI
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+# A newer push to the same branch cancels the run still in progress.
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Tests (py${{ matrix.python-version }}, ${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+        include:
+          - os: windows-latest
+            python-version: "3.13"
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install package
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e .
+
+      - name: Run tests
+        run: python -m unittest discover -s tests -v
+
+  build:
+    name: Build package
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+
+      - name: Install the built wheel and smoke-test the CLI
+        run: |
+          python -m venv /tmp/wheel-env
+          /tmp/wheel-env/bin/pip install dist/*.whl
+          /tmp/wheel-env/bin/mcp-lint --help
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          retention-days: 7

mcp_linter-1.2.0/.github/workflows/lock-action.yml

@@ -0,0 +1,85 @@
+name: Lock action
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  lock-check:
+    name: Lock action (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install package (the demo server needs the MCP SDK)
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e .
+
+      - name: Clean lock passes
+        id: clean
+        uses: ./
+        with:
+          command: python tests/fixtures/demo_server.py
+          lock: tests/fixtures/demo.lock
+          setup-python: "false"
+
+      - name: Tampered lock fails
+        id: tampered
+        continue-on-error: true
+        uses: ./
+        with:
+          command: python tests/fixtures/demo_server.py
+          lock: tests/fixtures/demo_tampered.lock
+          setup-python: "false"
+
+      - name: Require that the tampered check failed
+        env:
+          TAMPERED_OUTCOME: ${{ steps.tampered.outcome }}
+        shell: bash
+        run: |
+          if [ "$TAMPERED_OUTCOME" != "failure" ]; then
+            echo "::error::expected the tampered lock check to fail, got outcome: $TAMPERED_OUTCOME"
+            exit 1
+          fi
+          echo "Tampered lock check failed as expected."
+
+      - name: Start HTTP demo server
+        if: runner.os == 'Linux'
+        shell: bash
+        run: |
+          # Detach the server from this step's stdout, or the step can wait on it.
+          nohup python tests/fixtures/demo_server.py --http 8765 > "$RUNNER_TEMP/demo-http.log" 2>&1 &
+          for i in $(seq 1 30); do
+            if timeout 1 bash -c 'exec 3<>/dev/tcp/127.0.0.1/8765' 2>/dev/null; then
+              echo "HTTP demo server is up."
+              exit 0
+            fi
+            sleep 1
+          done
+          echo "::error::HTTP demo server did not open port 8765 within 30 seconds"
+          exit 1
+
+      - name: HTTP lock check
+        if: runner.os == 'Linux'
+        uses: ./
+        with:
+          url: http://127.0.0.1:8765/mcp
+          lock: tests/fixtures/demo.lock
+          fail-on: error
+          setup-python: "false"

mcp_linter-1.2.0/.github/workflows/release.yml

@@ -0,0 +1,93 @@
+name: Release
+
+# Builds the package on every run. A published GitHub release publishes to PyPI.
+# A manual run (workflow_dispatch) publishes to TestPyPI instead.
+# Publishing uses PyPI Trusted Publishing (OIDC): no API token is stored.
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build and check distributions
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install build tools
+        run: python -m pip install --upgrade pip build twine
+
+      - name: Check that the release tag matches the package version
+        if: github.event_name == 'release'
+        env:
+          TAG: ${{ github.event.release.tag_name }}
+        run: python scripts/check_release_version.py "$TAG"
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Check package metadata
+        run: python -m twine check --strict dist/*
+
+      - name: Install the built wheel and smoke-test the CLI
+        run: |
+          python -m venv /tmp/wheel-env
+          /tmp/wheel-env/bin/pip install dist/*.whl
+          /tmp/wheel-env/bin/mcp-lint --help
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          retention-days: 7
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: build
+    if: github.event_name == 'release'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment:
+      name: pypi
+      url: https://pypi.org/p/mcp-linter
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish distributions to PyPI (Trusted Publishing)
+        uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086  # v1.14.3
+
+  publish-testpypi:
+    name: Publish to TestPyPI
+    needs: build
+    if: github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/mcp-linter
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish distributions to TestPyPI (Trusted Publishing)
+        uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086  # v1.14.3
+        with:
+          repository-url: https://test.pypi.org/legacy/

mcp_linter-1.2.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+build/
+dist/
+.pytest_cache/
+report.json
+.env
+survey/sandbox/
+.claude/settings.local.json
+eval/results/*.lock

mcp_linter-1.2.0/.pre-commit-hooks.yaml

@@ -0,0 +1,7 @@
+- id: mcp-lint-lock
+  name: mcp-lint lock --check
+  description: Fail if an MCP server's tools changed since mcp-lint.lock was written.
+  entry: mcp-lint lock --check
+  language: python
+  pass_filenames: false
+  always_run: true

mcp_linter-1.2.0/CLAUDE.md

@@ -0,0 +1,58 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+mcp-lint lints MCP servers against Anthropic's "Writing effective tools for agents" guidance. It reads a server's tool definitions (and optionally calls the tools) and reports findings, a token-weighted score, and can serve the server back through a fixing proxy. Python 3.10+, one runtime dependency (`mcp>=2.1`), built with hatchling.
+
+## Commands
+
+```bash
+python -m venv .venv
+.venv/Scripts/pip install -e .          # Linux/macOS: .venv/bin/pip
+
+python -m unittest discover -s tests                        # full suite (what CI runs)
+python -m unittest discover -s tests -p test_cli.py         # one file
+python -m unittest tests.test_cli.CheckCommandTests         # one class
+python -m unittest tests.test_cli -k fails_on_error         # by name substring
+
+python -m build                                              # sdist + wheel into dist/
+mcp-lint check tests/fixtures/sample_tools.json              # lint a saved tools/list offline
+mcp-lint run -- python tests/fixtures/demo_server.py         # lint a live stdio server
+python tests/fixtures/demo_server.py --http 8000             # serve the demo over Streamable HTTP at 127.0.0.1:8000/mcp (run in another terminal)
+mcp-lint run --url http://127.0.0.1:8000/mcp                 # lint that HTTP server
+```
+
+- Tests use stdlib `unittest`, not pytest. `tests/` has no `__init__.py`, so don't pass `-t .` to discover.
+- The package must be installed (`pip install -e .`) for tests to import `mcp_lint`.
+- `mcp-lint check`/`run` exit 1 whenever a finding is at or above `--fail-on` (default `error`), so exit 1 on a sample file is normal. Exit 2 is a usage or connection error.
+- Some tests start `tests/fixtures/demo_server.py` as a real MCP server through `sys.executable`. The server's tracebacks in test output (e.g. `UnexpectedToolError: Error executing tool search_contacts`) are expected, not failures.
+- No linter or formatter is configured.
+- CI (`.github/workflows/ci.yml`) runs the suite on Ubuntu with Python 3.10–3.13 and Windows with 3.13, and builds and installs the wheel. `lock-action.yml` tests the Action on Ubuntu and Windows, and `release.yml` builds on every run and publishes on a GitHub release.
+
+## Architecture
+
+Pipeline for `run`/`check` (`cli.py:main`): get `ToolDef`s → `rules.run_static` → (`run` with `--probe`/`--error-probes`) `client.fetch_and_probe` + `rules.probe.run_probe_rules` → `report.render_*` / `to_json` → `score.score_server` → exit code.
+
+- **`models.py`**: `ToolDef`, `Finding`, `Severity`. Rules work on these, never on MCP SDK objects, so rules are testable without a server. `ToolDef.read_only` is true only for an explicit `readOnlyHint: true`. That is the probe safety gate; `destructiveHint: false` does not count.
+- **Rules** are plain functions returning `list[Finding]`, registered in lists that the runners iterate:
+  - `rules/static.py`: `STATIC_RULES` (per tool: S1–S3) and `TOOLSET_RULES` (whole tool list: S4–S7).
+  - `rules/security.py`: `SECURITY_RULES` (S8 hidden text). S8 is not scored.
+  - `rules/probe.py`: `PROBE_RULES` (P1–P5), each taking `(tools_by_name, probe_results)`.
+  - A new rule needs adding to its list, and to `score.FIXED_COSTS` (or `score.MEASURED`) if it should affect the score. The README's rule tables document every rule ID and threshold; keep them in sync.
+- **`client.py`**: stdio and Streamable HTTP (`--url`) connections via the MCP SDK, paginated `tools/list`, probe calls on one session. HTTP uses `HttpTarget` (URL plus headers), `parse_headers` (name and value checks, no duplicates, and `--header-env` refused over plain `http://` unless the host is loopback) and `redact`. The URL and header values never reach output, reports or the lock; only `command_sha256` of `["--url", scheme://host:port/path]` is stored (`cli._http_identity`). `--header-env` values and URL user info/query are secret: `run` and `lock --check` scrub them from server text at the source and in the rendered output, and `lock`/`init-fixtures` refuse to write them. Plain `http://` clients ignore proxy env vars (`build_http_client`). Stdio servers get only the SDK's minimal default environment plus names passed with `--pass-env` (`--pass-env` doesn't apply to `--url`). Never forward the full environment: keeping API keys away from linted servers is a stated guarantee. `safe_exec.py` applies the same minimal environment when the eval launches servers directly.
+- **`fixtures.py` / `probe.py`**: the fixtures file format, argument and safety checks before any call (non-read-only tools need `"allow_destructive": true`), generated bad-argument probes for P4 (read-only tools only), and `ProbeResult` capture.
+- **`score.py`**: turns findings into estimated wasted tokens per session; scores halve every `HALF_LIFE` tokens. All cost constants live here.
+- **`text.py`**: token estimation (4 chars per token of compact JSON; always labelled as an estimate), name splitting and naming-style detection.
+- **`install.py`** (`mcp-lint check-config`, and the pre-launch refusal in `run`/`proxy`/`lock`/`init-fixtures`): install lint, rule I1. A backstop scans every argv piece for `KNOWN_BAD` regardless of the parser. `lint_command(argv)` flags unpinned packages and sources, images without a digest, pip installs without hashes, and `KNOWN_BAD` releases; `run` shows the other findings under the server section, while a `known_bad` launch is refused on stderr before any connection. `load_client_config()` reads the server maps of client config files and never keeps `env` values. I1 is not in `score.py`. New kinds need a row in the README's Install lint table.
+- **`proxy.py`** (`mcp-lint proxy`): an MCP server that wraps an upstream one and applies the fixes (paging with `offset`/`limit`, description replacement from `eval/fixes/*.json`, `isError` on error-as-success). Its pure functions (`rewrite_tool`, `page_text`, `fix_result`) are unit-tested without a server.
+- **`lock.py`** (`mcp-lint lock`, `lock --check`): the rug-pull lockfile. `canonical()` normalises a `ToolDef` (every MCP `Tool` field) so equal schemas hash equal; `diff_lock()` classifies changes as `Finding(rule="LOCK", kind=...)`. The rule it enforces: any change to text the model or user reads, or that makes a schema accept or ask for more, is an error; anything else that changes the hash is at least a warning (fail closed). New change classes need a row in the README's Lockfile table. The lock never stores the raw launch command, only its hash.
+- **`eval.py` / `evaltasks.py`** (`mcp-lint eval`): before/after experiment that runs headless `claude -p` against each server directly (`baseline`) and behind the proxy (`fixed`, plus single-fix ablations). Results append to `eval/results/results.jsonl` and the runner is resumable. `--run` makes real Claude Code calls; don't start it unless asked.
+- **`action.yml` + `scripts/action_lock_check.py`**: composite GitHub Action for `lock --check`. Inputs reach the script only through environment variables, and the script runs mcp-lint from an argv list without a shell. Never put `${{ inputs.* }}` into a `run:` script.
+- **`.pre-commit-hooks.yaml`**: pre-commit hook `mcp-lint-lock` (`lock --check`, always runs).
+- **`.github/workflows/release.yml` + `scripts/check_release_version.py`**: a published GitHub release checks that the tag matches the version in both `pyproject.toml` and `__init__.py`, builds, and publishes to PyPI with Trusted Publishing (no token). A manual run publishes to TestPyPI. The PyPI name is `mcp-linter`.
+
+## Data directories
+
+- `tests/fixtures/`: demo MCP servers and tool lists used by tests (`poisoned_tools.json` holds S8 attack strings on purpose).
+- `survey/tools/`: saved `tools/list` results from 18 real servers. `tests/test_survey_tools.py` fails if S8 raises a warning or error on any of them, so S8 changes must stay quiet on this benign corpus. `survey/fixtures/` and `make_sandbox.py` reproduce the probe numbers in `RESULTS.md`.
+- `eval/`: tasks, hand-written description fixes, recorded results, and `REPORT.md`. Results files are experiment records, not generated scratch; don't rewrite them.

mcp_linter-1.2.0/LICENSE

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