mcp-gatekeeper 0.1.0__tar.gz

mcp_gatekeeper-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,29 @@
+name: Bug report
+description: Report a problem with mcpgate
+labels: [bug]
+body:
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: Include the exact `mcpgate` command and full output.
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: mcpgate version
+      placeholder: "0.1.0"
+    validations:
+      required: true
+  - type: input
+    id: python
+    attributes:
+      label: Python version
+    validations:
+      required: true
+  - type: textarea
+    id: server
+    attributes:
+      label: MCP server being linted
+      description: Command or URL. Redact anything private.

mcp_gatekeeper-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,17 @@
+name: Feature request
+description: Suggest a rule or feature
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What quality defect or workflow is not covered?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+    validations:
+      required: true

mcp_gatekeeper-0.1.0/.github/SECURITY.md

@@ -0,0 +1,20 @@
+# Security Policy
+
+## Supported versions
+
+| Version | Supported |
+|---------|-----------|
+| 0.1.x   | ✅        |
+
+## Reporting a vulnerability
+
+Do **not** open a public issue for security vulnerabilities. Use GitHub's
+"Report a vulnerability" (Security → Advisories → New draft security advisory),
+or open a minimal issue pointing to a draft advisory. You will get a response
+within 7 days.
+
+## Scope
+
+`mcpgate` connects to MCP servers you point it at. Vulnerabilities of interest
+include: command injection via server command strings, unsafe deserialization of
+server responses, and SARIF/JSON output injection.

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

@@ -0,0 +1,35 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: uv sync --all-extras
+      - name: Lint
+        run: uv run ruff check .
+      - name: Format check
+        run: uv run ruff format --check .
+      - name: Types
+        run: uv run mypy src
+      - name: Test
+        run: |
+          uv run coverage run -m pytest
+          uv run coverage report
+      - name: Build
+        run: |
+          uv build
+          uv run --with twine twine check dist/*

mcp_gatekeeper-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,19 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Build
+        run: uv build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

mcp_gatekeeper-0.1.0/.gitignore

@@ -0,0 +1,23 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+dist/
+build/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+uv.lock.bak
+.DS_Store
+
+# AI/planning docs — local only
+PLAN.md
+IMPLEMENTATION_PLAN.md
+AGENTS.md
+CLAUDE.md
+GEMINI.md
+.claude/
+copilot-instructions.md

mcp_gatekeeper-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,14 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.4
+    hooks:
+      - id: ruff-format
+      - id: ruff
+        args: [--fix]
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.13.0
+    stages: [pre-push]
+    hooks:
+      - id: mypy
+        files: ^src/
+        additional_dependencies: [pydantic>=2.0, click>=8.1, types-click]

mcp_gatekeeper-0.1.0/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-09-02
+
+### Added
+- feat: automated release script with semver bump decision
+- feat: pytest plugin with mcp_server fixture and tool_contract
+- feat: lint/doctor CLI with text, json and sarif output
+- feat: 15 lint rules with decorator registry (MCP101-MCP401)
+- feat: protocol client and normalized snapshot models
+
+### Fixed
+- fix: rename PyPI distribution to mcp-gatekeeper
+- fix: rename PyPI package to mcp-gate (mcpgate is taken)
+- fix: snapshot servers that lack resources/prompts capabilities
+
+### Changed
+- docs: drop AGENTS.md link from README
+- docs: self-contained public CONTRIBUTING guide
+- docs: full README with rule table, comparison and examples; coverage gate at 90%
+
+### Other
+- chore: keep AI and planning docs untracked
+- chore: scaffold package, OSS files, CI and release workflows
+
+## [0.1.0] - 2026-09-02
+
+### Added
+- `mcpgate lint` with 15 rules (MCP101–MCP401), text/json/sarif output, CI-friendly exit codes.
+- `mcpgate doctor` health report.
+- Pytest plugin: `mcp_server` fixture + `tool_contract` helper.

mcp_gatekeeper-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,60 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement by opening a
+private GitHub issue marked as a conduct report. All complaints will be reviewed
+and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the
+[Contributor Covenant](https://www.contributor-covenant.org), version 2.1.

mcp_gatekeeper-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,62 @@
+# Contributing to mcpgate
+
+Thanks for helping make MCP servers better for the agents that use them!
+
+## Getting started
+
+```bash
+git clone https://github.com/ofsazib/mcpgate
+cd mcpgate
+uv sync --all-extras     # install deps (dev + test extras)
+
+uv run coverage run -m pytest   # tests (fully offline)
+uv run coverage report          # coverage, gate at 90%
+uv run ruff check .             # lint
+uv run ruff format .            # format
+uv run mypy src                 # strict type check
+```
+
+Requires Python 3.10–3.13 and [uv](https://docs.astral.sh/uv/).
+
+## Project layout
+
+| Module | Responsibility |
+|---|---|
+| `src/mcpgate/cli.py` | click app: `mcpgate lint \| doctor` |
+| `src/mcpgate/client.py` | connect over in-memory/stdio/HTTP; snapshot definitions |
+| `src/mcpgate/model.py` | pydantic models: `ToolInfo`, `Finding`, `ServerSnapshot`, … |
+| `src/mcpgate/engine.py` | rule runner, text/json/sarif formatters, exit codes |
+| `src/mcpgate/doctor.py` | health report |
+| `src/mcpgate/testing/plugin.py` | pytest plugin (`mcp_server` fixture, `tool_contract`) |
+| `src/mcpgate/rules/` | rule registry + rule modules |
+
+## Adding a lint rule
+
+Rule codes are grouped by prefix: `MCP1xx` descriptions, `MCP2xx` schemas,
+`MCP3xx` security, `MCP4xx` token cost.
+
+1. Write a small pure function over `ServerSnapshot` returning
+   `(source, message-kwargs)` tuples, in the right `rules/*.py` module.
+2. Register it with the `@rule("MCPxxx", "severity", "message template")` decorator
+   from `rules/base.py`.
+3. Add a positive and a negative test in `tests/test_rules.py` — one of each per
+   rule, no exceptions.
+4. If it is user-visible, add a row to the rule table in `README.md`.
+
+## Ground rules
+
+- **Runtime dependencies** are frozen at `mcp`, `click`, `pydantic` — anything else
+  needs prior discussion in an issue.
+- **Tests are offline.** Use the `mcp` SDK's in-memory transport; mark network
+  tests with `@pytest.mark.network` (deselected by default).
+- **Typing is strict.** No `# type: ignore` without a comment explaining why.
+- **Commits** follow Conventional Commits (`feat:`, `fix:`, `docs:`, …).
+- Every PR must keep `pytest`, `ruff` and `mypy src` green.
+
+## Reporting bugs and security issues
+
+Bugs and feature requests: open a GitHub issue using the templates.
+Security vulnerabilities: **never** in a public issue — see
+[SECURITY.md](.github/SECURITY.md).
+
+By participating you agree to the [Code of Conduct](CODE_OF_CONDUCT.md).

mcp_gatekeeper-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mcpgate contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_gatekeeper-0.1.0/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.5
+Name: mcp-gatekeeper
+Version: 0.1.0
+Summary: Automated quality gate for MCP servers — ruff + pytest for MCP.
+Project-URL: Homepage, https://github.com/ofsazib/mcpgate
+Project-URL: Changelog, https://github.com/ofsazib/mcpgate/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/ofsazib/mcpgate/issues
+Author: mcpgate contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,lint,mcp,model-context-protocol,pytest,quality-gate
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1
+Requires-Dist: mcp<2,>=1.0
+Requires-Dist: pydantic>=2.0
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.24; extra == 'test'
+Requires-Dist: pytest-cov>=5.0; extra == 'test'
+Requires-Dist: pytest>=8.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# mcpgate
+
+> Automated quality gate for MCP servers — **ruff + pytest for MCP**.
+
+[![CI](https://github.com/ofsazib/mcpgate/actions/workflows/ci.yml/badge.svg)](https://github.com/ofsazib/mcpgate/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/mcpgate)](https://pypi.org/project/mcp-gatekeeper/)
+[![Python](https://img.shields.io/pypi/pyversions/mcpgate)](https://pypi.org/project/mcp-gatekeeper/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Coverage](https://codecov.io/gh/ofsazib/mcpgate/branch/main/graph/badge.svg)](https://codecov.io/gh/ofsazib/mcpgate)
+
+## The problem
+
+When an MCP tool description is vague, the AI agent misuses the tool — even though
+the code behind it is perfect. This failure is invisible to unit tests because it
+happens at the AI-interpretation layer. Research documents the scale:
+
+- An arXiv study of 103 major MCP servers (856 tools) found tool descriptions
+  systematically "smelly and costly" ([arXiv:2602.14878](https://arxiv.org/abs/2602.14878)).
+- An AWS-led study found **97.1% of MCP tool descriptions contain at least one
+  quality defect**.
+
+`mcpgate` catches these defects before agents hit them in production. It speaks the
+real protocol, so it works with any server — FastMCP, the official Python SDK, or
+TypeScript servers — over stdio or HTTP.
+
+## Quickstart
+
+```bash
+uv tool install mcp-gatekeeper    # or: pip install mcp-gatekeeper
+
+mcpgate lint "uvx mcp-server-fetch"
+mcpgate doctor "uvx mcp-server-fetch"
+```
+
+Exit codes are CI-friendly: `0` clean, `1` findings (fail the build), `2` connection
+or protocol error.
+
+## Example output
+
+```text
+    warning  MCP101  Tool `delete_record`: description too short (7 words; minimum 8)  src: tools/delete_record
+    warning  MCP105  Tool `delete_record`: description does not state error/return behavior  src: tools/delete_record
+    warning  MCP303  Tool `delete_record`: destructive operation without a confirmation parameter  src: tools/delete_record
+    error    MCP301  Tool `run_command`: suggests command execution without a safety note  src: tools/run_command
+    warning  MCP101  Tool `run_command`: description too short (7 words; minimum 8)  src: tools/run_command
+    warning  MCP105  Tool `run_command`: description does not state error/return behavior  src: tools/run_command
+    warning  MCP101  Tool `search`: description too short (2 words; minimum 8)  src: tools/search
+    warning  MCP105  Tool `search`: description does not state error/return behavior  src: tools/search
+    info     MCP204  Tool `search`: description repeats the tool name (wasted tokens)  src: tools/search
+    ———
+    found 9 problems (1 errors, 7 warnings)
+    run `mcpgate lint --explain CODE` for details
+```
+
+Formats: `--format text|json|sarif` (SARIF plugs into GitHub code scanning).
+Filter with `--select MCP3xx --ignore MCP401`; inspect a rule with
+`--explain MCP101`; fail on warnings with `--strict`.
+
+## Rules (v0.1)
+
+| Code | Severity | What it checks |
+|------|----------|----------------|
+| MCP101 | warning | Tool description missing or shorter than 8 words |
+| MCP102 | warning | Description is vague ("does stuff", "handles things", "various") |
+| MCP103 | warning | Description just restates the tool name |
+| MCP104 | warning | Tools with 2+ parameters where parameters lack descriptions |
+| MCP105 | warning | Description does not state error/return behavior |
+| MCP106 | warning | Description longer than 1024 chars (token bloat) |
+| MCP201 | error | Input schema missing or not a JSON object schema |
+| MCP202 | warning | Required parameter is not described |
+| MCP203 | info | `additionalProperties: false` schema but description states no constraints |
+| MCP204 | info | Description repeats the tool name (wasted tokens) |
+| MCP205 | error | Declared output schema is invalid |
+| MCP301 | error | Command-execution tool without a safety note |
+| MCP302 | warning | Parameter name looks like a secret (`api_key`, `token`, …) |
+| MCP303 | warning | Destructive operation without a confirmation parameter |
+| MCP401 | info | Full definition snapshot costs more than ~10k tokens |
+
+## Pytest plugin
+
+Install with the `test` extra, then contract-test your tools over the real protocol:
+
+```bash
+pip install "mcp-gatekeeper[test]"
+```
+
+```python
+import pytest
+from my_server import mcp  # your FastMCP / MCP server object
+
+
+@pytest.mark.parametrize("mcp_server", [mcp], indirect=True)
+def test_search(mcp_server):
+    result = mcp_server.call_tool("search", {"query": "hello"})
+    assert result.is_error is False
+
+
+@pytest.mark.parametrize("mcp_server", [mcp], indirect=True)
+def test_contract(mcp_server):
+    mcp_server.tool_contract("search")
+    # asserts: described, valid object schema, described required params,
+    # and the error path returns is_error instead of crashing
+```
+
+Or point a whole suite at one server: `pytest --mcp-server "uvx mcp-server-fetch"`.
+Works in-memory for server objects (fully offline), stdio/HTTP for commands and URLs.
+
+## How it compares
+
+| | MCP Inspector | mcplint-cli | mcp-doctor | **mcpgate** |
+|---|---|---|---|---|
+| Purpose | interactive debugger | description lint | diagnostics | unified quality gate |
+| CLI-first, CI exit codes | ✗ | ✓ | partial | ✓ (0/1/2) |
+| Definition lint rules | ✗ | ✓ | ✗ | ✓ (15 rules) |
+| Doctor / health check | ✓ | ✗ | ✓ | ✓ |
+| pytest plugin | ✗ | ✗ | ✗ | ✓ |
+| JSON + SARIF output | ✗ | ✗ | ✗ | ✓ |
+| Framework-agnostic (speaks MCP) | ✓ | ✓ | ✓ | ✓ |
+
+## Roadmap
+
+- **v0.2** — `--fix`: LLM-assisted rewriting of weak descriptions (the engine already
+  carries the context needed per finding)
+- Declarative YAML test suites and `--baseline` files
+- Custom user rule plugins and a pre-commit hook package
+- GitHub Action and official MCP servers registry integration
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). MIT licensed — see [LICENSE](LICENSE).

mcp_gatekeeper-0.1.0/README.md

@@ -0,0 +1,130 @@
+# mcpgate
+
+> Automated quality gate for MCP servers — **ruff + pytest for MCP**.
+
+[![CI](https://github.com/ofsazib/mcpgate/actions/workflows/ci.yml/badge.svg)](https://github.com/ofsazib/mcpgate/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/mcpgate)](https://pypi.org/project/mcp-gatekeeper/)
+[![Python](https://img.shields.io/pypi/pyversions/mcpgate)](https://pypi.org/project/mcp-gatekeeper/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Coverage](https://codecov.io/gh/ofsazib/mcpgate/branch/main/graph/badge.svg)](https://codecov.io/gh/ofsazib/mcpgate)
+
+## The problem
+
+When an MCP tool description is vague, the AI agent misuses the tool — even though
+the code behind it is perfect. This failure is invisible to unit tests because it
+happens at the AI-interpretation layer. Research documents the scale:
+
+- An arXiv study of 103 major MCP servers (856 tools) found tool descriptions
+  systematically "smelly and costly" ([arXiv:2602.14878](https://arxiv.org/abs/2602.14878)).
+- An AWS-led study found **97.1% of MCP tool descriptions contain at least one
+  quality defect**.
+
+`mcpgate` catches these defects before agents hit them in production. It speaks the
+real protocol, so it works with any server — FastMCP, the official Python SDK, or
+TypeScript servers — over stdio or HTTP.
+
+## Quickstart
+
+```bash
+uv tool install mcp-gatekeeper    # or: pip install mcp-gatekeeper
+
+mcpgate lint "uvx mcp-server-fetch"
+mcpgate doctor "uvx mcp-server-fetch"
+```
+
+Exit codes are CI-friendly: `0` clean, `1` findings (fail the build), `2` connection
+or protocol error.
+
+## Example output
+
+```text
+    warning  MCP101  Tool `delete_record`: description too short (7 words; minimum 8)  src: tools/delete_record
+    warning  MCP105  Tool `delete_record`: description does not state error/return behavior  src: tools/delete_record
+    warning  MCP303  Tool `delete_record`: destructive operation without a confirmation parameter  src: tools/delete_record
+    error    MCP301  Tool `run_command`: suggests command execution without a safety note  src: tools/run_command
+    warning  MCP101  Tool `run_command`: description too short (7 words; minimum 8)  src: tools/run_command
+    warning  MCP105  Tool `run_command`: description does not state error/return behavior  src: tools/run_command
+    warning  MCP101  Tool `search`: description too short (2 words; minimum 8)  src: tools/search
+    warning  MCP105  Tool `search`: description does not state error/return behavior  src: tools/search
+    info     MCP204  Tool `search`: description repeats the tool name (wasted tokens)  src: tools/search
+    ———
+    found 9 problems (1 errors, 7 warnings)
+    run `mcpgate lint --explain CODE` for details
+```
+
+Formats: `--format text|json|sarif` (SARIF plugs into GitHub code scanning).
+Filter with `--select MCP3xx --ignore MCP401`; inspect a rule with
+`--explain MCP101`; fail on warnings with `--strict`.
+
+## Rules (v0.1)
+
+| Code | Severity | What it checks |
+|------|----------|----------------|
+| MCP101 | warning | Tool description missing or shorter than 8 words |
+| MCP102 | warning | Description is vague ("does stuff", "handles things", "various") |
+| MCP103 | warning | Description just restates the tool name |
+| MCP104 | warning | Tools with 2+ parameters where parameters lack descriptions |
+| MCP105 | warning | Description does not state error/return behavior |
+| MCP106 | warning | Description longer than 1024 chars (token bloat) |
+| MCP201 | error | Input schema missing or not a JSON object schema |
+| MCP202 | warning | Required parameter is not described |
+| MCP203 | info | `additionalProperties: false` schema but description states no constraints |
+| MCP204 | info | Description repeats the tool name (wasted tokens) |
+| MCP205 | error | Declared output schema is invalid |
+| MCP301 | error | Command-execution tool without a safety note |
+| MCP302 | warning | Parameter name looks like a secret (`api_key`, `token`, …) |
+| MCP303 | warning | Destructive operation without a confirmation parameter |
+| MCP401 | info | Full definition snapshot costs more than ~10k tokens |
+
+## Pytest plugin
+
+Install with the `test` extra, then contract-test your tools over the real protocol:
+
+```bash
+pip install "mcp-gatekeeper[test]"
+```
+
+```python
+import pytest
+from my_server import mcp  # your FastMCP / MCP server object
+
+
+@pytest.mark.parametrize("mcp_server", [mcp], indirect=True)
+def test_search(mcp_server):
+    result = mcp_server.call_tool("search", {"query": "hello"})
+    assert result.is_error is False
+
+
+@pytest.mark.parametrize("mcp_server", [mcp], indirect=True)
+def test_contract(mcp_server):
+    mcp_server.tool_contract("search")
+    # asserts: described, valid object schema, described required params,
+    # and the error path returns is_error instead of crashing
+```
+
+Or point a whole suite at one server: `pytest --mcp-server "uvx mcp-server-fetch"`.
+Works in-memory for server objects (fully offline), stdio/HTTP for commands and URLs.
+
+## How it compares
+
+| | MCP Inspector | mcplint-cli | mcp-doctor | **mcpgate** |
+|---|---|---|---|---|
+| Purpose | interactive debugger | description lint | diagnostics | unified quality gate |
+| CLI-first, CI exit codes | ✗ | ✓ | partial | ✓ (0/1/2) |
+| Definition lint rules | ✗ | ✓ | ✗ | ✓ (15 rules) |
+| Doctor / health check | ✓ | ✗ | ✓ | ✓ |
+| pytest plugin | ✗ | ✗ | ✗ | ✓ |
+| JSON + SARIF output | ✗ | ✗ | ✗ | ✓ |
+| Framework-agnostic (speaks MCP) | ✓ | ✓ | ✓ | ✓ |
+
+## Roadmap
+
+- **v0.2** — `--fix`: LLM-assisted rewriting of weak descriptions (the engine already
+  carries the context needed per finding)
+- Declarative YAML test suites and `--baseline` files
+- Custom user rule plugins and a pre-commit hook package
+- GitHub Action and official MCP servers registry integration
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). MIT licensed — see [LICENSE](LICENSE).

mcp_gatekeeper-0.1.0/examples/bad_server.py

@@ -0,0 +1,29 @@
+"""An example MCP server that violates many mcpgate rules (for docs).
+
+Run: uv run mcpgate lint "python3 examples/bad_server.py"
+"""
+
+import logging
+
+from mcp.server.fastmcp import FastMCP
+
+logging.getLogger("mcp").setLevel(logging.WARNING)
+
+mcp = FastMCP("example-bad-server")
+
+TOOLS = {
+    "search": "Search stuff.",
+    "run_command": "Runs any shell command you pass it.",
+    "delete_record": "Removes a record from the database permanently.",
+}
+
+
+def _register() -> None:
+    for name, desc in TOOLS.items():
+        mcp.tool(name=name, description=desc)(lambda: None)
+
+
+_register()
+
+if __name__ == "__main__":
+    mcp.run()