Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
224 lines (158 loc) · 9.99 KB

CONTRIBUTING.md

File metadata and controls

224 lines (158 loc) · 9.99 KB

Contributing to MCTS

Thank you for helping make MCP security testing accessible to everyone.

New to the project? Read Getting Started and the Glossary first.

Quick start for first-time contributors

A minimal path from zero to your first merged PR:

Step What to do
1. Find an issue Browse open issues. Good entry points: priority:P3, type:docs, type:task, or issues tagged good first issue if present. For larger work, pick an item from Part 11 of the Feature Expansion Plan and open a feature request first.
2. Label the work New issue: apply one type:*, one priority:P*, and at least one component:* before you start — see Issue labeling guide. Existing issue: confirm labels match the scope you plan to implement; comment that you are working on it to avoid duplicate PRs.
3. Set up locally Fork → clone → uv sync --all-extras → pre-commit install (details below).
4. Create a branch git checkout -b fix/short-description or feat/short-description off latest main.
5. Implement + test Keep the change focused. Run uv run pytest and uv run ruff check src tests before pushing.
6. Submit a PR Open a PR against main with a clear summary, link the issue (Fixes #123), and note any doc or CHANGELOG updates. CI must pass the test check. 
git clone https://github.com/YOUR_USER/MCTS.git
cd MCTS
uv sync --all-extras
pre-commit install
git checkout -b feat/my-first-contribution
uv run pytest
uv run mcts scan examples/vulnerable-mcp-server/server.py   # sanity check
# … make changes …
uv run pytest && uv run ruff check src tests
git push -u origin feat/my-first-contribution
# Open PR on GitHub

Where code usually lives: see Codebase overview below.

Codebase overview for contributors

MCTS is a pipeline: discover MCP surfaces → run analyzers → score → report. Most feature work touches one layer.

flowchart TB
  CLI["CLI / API\ncli/main.py · api/app.py"]
  CFG["ScanConfig\ncore/config.py"]
  DISC["Discovery\nmcp/client.py · discovery/*"]
  INFO["MCPServerInfo\nmcp/models.py"]
  ANA["Analyzers\nanalyzers/*.py"]
  COMP["Compliance\ncompliance/checks.py"]
  GRAPH["Attack graph\nscoring/graph.py"]
  V1["Legacy score\nengine.py"]
  V2["v2 score\nengine_v2.py"]
  OUT["ScanReport\nreporting/models.py"]
  TERM["Terminal / JSON / SARIF / HTML"]

  CLI --> CFG
  CFG --> DISC
  DISC --> INFO
  INFO --> ANA
  ANA --> COMP
  COMP --> GRAPH
  GRAPH --> V1
  V1 --> V2
  V2 --> OUT
  OUT --> TERM
Loading

Orchestrator: Scanner in src/mcts/core/scanner.py wires discovery, analyzers, compliance, attack graph, legacy scoring, and optional v2 scoring (scoring_mode default both).

Layer Directory Typical contribution
CLI & config cli/, core/config.py New flags, subcommands, presets
Discovery discovery/, mcp/client.py, probe/ New languages, live/remote transport, inventory
Analyzers analyzers/ New security checks (subclass BaseAnalyzer)
SAST / rules sast/, taxonomy/sigma/ Tree-sitter taint, Semgrep rules, Sigma metadata
Scoring & reports scoring/, governance/, reporting/, report/ v1/v2 engines, corpus stats, gates, SARIF, HTML dashboard
Tests tests/, tests/fixtures/regression/ Unit tests, technique regression fixtures

Adding an analyzer (common task):

  1. Create src/mcts/analyzers/your_analyzer.py — subclass BaseAnalyzer, implement analyze().
  2. Register in Scanner._build_analyzers() (core/scanner.py).
  3. Add tests and, when applicable, a fixture under tests/fixtures/regression/MCTS-T-*/.
  4. Document in Security Checks and assign a technique_id.

Full pipeline detail: Architecture · Scoring guide · Extension points

Local environment setup

If you skipped the quick start commands above:

  1. Fork and clone the repository
  2. Install uv
  3. Run uv sync --all-extras
  4. Install pre-commit hooks: pre-commit install

See Getting Started (user guide) and CLI Reference for scan usage beyond development.

Development Workflow

# Run tests
uv run pytest

# Lint & format
uv run ruff check .
uv run ruff format src tests

# Try the CLI locally
uv run mcts scan examples/vulnerable-mcp-server/server.py

# Generate the HTML security dashboard
uv run mcts scan examples/vulnerable-mcp-server/server.py -o report.json
uv run mcts report report.json -o security-report.html

Filing Issues

Before opening a GitHub issue:

  1. Search existing issues for duplicates
  2. Reproduce on the latest main branch
  3. Apply the label taxonomy: one type:*, one priority:P*, and at least one component:*

Full guide: Issue Labeling & Creation — types, priorities, components, finding labels, status workflow, body template, and examples.

Use the repo templates when possible: bug report · feature request

Pull Request Guidelines

  • Keep PRs focused — one feature or fix per PR
  • Add tests for new behavior
  • Update CHANGELOG.md under [Unreleased] for user-facing changes
  • Follow existing code style (ruff enforces this in CI)
  • Update documentation when adding user-facing features

Branch Protection

Branch Who can update Policy
main (current release) Maintainers (maintain) and Admins PRs required; test + scoring-v2 must pass; branch up to date; no force-push or deletion
main_* (pinned releases, e.g. main_0.1.2) Maintainers and Admins Same as main — for version-specific hotfix lines
develop (integration) Admins only test + scoring-v2 must pass; no force-push or deletion; contributors land work via PRs from feature branches

Contributors typically have Write (feature branches only). Assign Maintain to release maintainers who merge into main. Assign Admin to owners who push integration work to develop.

Definitions live in .github/rulesets/ (main.json, develop.json). See rulesets README for bypass actors and role IDs.

Enable on GitHub (one-time, repo admin)

Option A — Script (recommended)

./scripts/enable-branch-protection.sh MCP-Audit/MCTS

The script is idempotent: re-running it updates existing rulesets (Protect release branches, Protect develop) instead of creating duplicates. Use --dry-run to preview without applying changes.

Option B — GitHub UI

  1. Go to Settings → Rules → Rulesets → New branch ruleset
  2. Target: default branch (main) or develop
  3. Add rules: Restrict updates (role bypass), Require pull request (main only), Require status checks, Block force pushes, Restrict deletions
  4. Bypass actors: main → Maintain (PR merge) + Admin; develop → Admin only
  5. Required checks: test, scoring-v2
  6. Save and enable enforcement

Planning & Roadmap

Before large features, read:

Document What it covers
Documentation index All user and contributor docs
Glossary Term definitions
Feature Expansion Plan Gap analysis, implementation how-to, prioritized backlog
Product Roadmap Phased deliverables and success criteria
Product Positioning Positioning, differentiation, and roadmap gaps

When proposing parity with another MCP security tool, cite the capability layer (static scan, supply chain, runtime, governance, graph) and confirm it fits MCTS's local-first MCP-boundary scope — see Feature Expansion Plan Part 8.

Pick a phase item from Part 11 or the full GAP appendix and open a feature request or Discussion to align on design.

Adding a New Analyzer

See Codebase overview — Adding an analyzer for the short checklist. Extended steps:

  1. Create a module under src/mcts/analyzers/
  2. Subclass BaseAnalyzer and implement analyze()
  3. Register it in Scanner._build_analyzers() (src/mcts/core/scanner.py)
  4. Add benchmark fixture in examples/bench/ when applicable
  5. Assign technique_id (MCTS-T-*) — see Threat Taxonomy
  6. Add tests under tests/ and regression fixtures when applicable
  7. Document the check in Security Checks Reference

Full guide: Architecture — Extension points

Code of Conduct

This project follows the Contributor Covenant.

Questions?

Open a GitHub Discussion or an issue using the labeling guide.