Skip to main content

Best Practices MCP

OpenSSF Baseline — project 16754

Description

Best Practices MCP lets an MCP-compatible assistant look up projects on the OpenSSF Best Practices Badge website (BadgeApp), inspect badge criteria and progress, retrieve badge images and README snippets, prepare draft answers, and generate proposed updates for review in the browser.

The server provides the tools; your assistant decides how to assess the project and organize the work. It can prepare an edit-page URL, but does not authenticate to BadgeApp or save changes. You review the actual form before deciding to save.

Maintained by Reponomics. This is an independent project, not affiliated with, sponsored by, endorsed by, or an official project of OpenSSF, the Linux Foundation, or the OpenSSF Best Practices Badge project or its contributors.

Quickstart

Use an MCP host that supports local stdio servers, with Python 3.11 or newer available. The project you are assessing can use any programming language.

Install uv if needed, then add the following server to your host's MCP configuration. Hosts with a settings form can use the same command and arguments; the configuration file location and surrounding format depend on the host.

{
  "mcpServers": {
    "bestpractices": {
      "command": "uvx",
      "args": ["--from", "best-practices-mcp==0.5.0", "bestpractices-mcp"]
    }
  }
}

This lets the host launch an isolated installation from PyPI. Alternatively, install persistently with pipx install 'best-practices-mcp==0.5.0' and configure the host to launch the installed bestpractices-mcp executable with no arguments.

Use an absolute executable path if the host cannot find uvx or bestpractices-mcp on its PATH. On Windows, JSON paths need escaped backslashes, for example C:\Users\you must be written as "C:\\Users\\you". The package name is best-practices-mcp; the executable name is bestpractices-mcp.

Reload the host's MCP connections, then try a request such as:

Find the BadgeApp project for https://github.com/reponomics/PolicyChecks and show its silver-level progress. Do not prepare any changes yet.

The table below describes the ten tools in the current source. Releases through beta.4 also included the console-script tool, removed by ADR 0003. Starting the executable directly in a terminal waits for MCP messages; it is not an interactive CLI. For a source checkout or connection debugging with Inspector, see Contributing.

Tools

Tool What it does Network or storage effects
find_project Find public project candidates by ID, repository/homepage URL, or text; the host selects the intended project. Public BadgeApp GETs
get_criteria Read the bundled criteria by badge level and criterion. Offline
get_project_progress Read all-level percentages or selected saved answers and progress, with source and fetch time. Public BadgeApp GETs
get_project_badge_status Quickly read one badge family's status, progress and project-record update time. Public BadgeApp JSON GET
get_project_badge_svg Retrieve a badge SVG and dynamic README embed snippet for one badge family. Public BadgeApp SVG GET
build_draft Create or patch a document supplied by the host. Offline; no stored files changed
read_draft Read the complete locally stored draft for a project. Local read
update_draft Create or patch a locally stored project draft. Local write; no BadgeApp update
validate_draft Check supplied answers against the bundled criteria's mechanical requirements. Offline; may read a stored draft
prepare_update_url Generate a proposed edit-page URL and report included/excluded fields. Public BadgeApp GETs; no remote write

See the tool specification and payload contracts for arguments, results and errors.

Usage notes

  • Compatibility: Python 3.11 is the supported minimum. The CI compatibility matrix targets Python 3.11/3.12 on Linux, macOS and Windows. The protocol baseline is MCP 2026-07-28; transport is stdio. Node and Ruby are not required to run the server.
  • Catalog and language: criteria are bundled from a pinned upstream revision, not fetched live. The current catalog is English and generated edit links use English paths. Translation support is proposed.
  • Validation is advisory: it checks mechanical requirements, not whether claims are true or evidence is sufficient. Validation is optional and does not gate artifact generation.
  • Review in the browser: artifacts include eligible supplied fields even when they match saved values. Reports describe what was included or excluded, not what BadgeApp will retain or save. BadgeApp documents trimming leading/trailing whitespace from URL-proposed justifications. See transfer rules for override behavior.
  • Authentication stays in your browser: public reads need no BadgeApp credentials. Applying proposals requires your own authenticated session and appropriate project permissions.

Badge status and README images

After selecting a project, get_project_badge_status(project_id=123) reads its compact Best Practices status; set family="baseline" for Baseline. Best Practices reports tiered progress, while the Baseline percentage refers only to level 1. Use get_project_progress for individual-level percentages, all-six-level summaries or saved criterion answers. The project's updated_at reports its record update time; fetched_at records when the response was retrieved.

get_project_badge_svg(project_id=123, family="best_practices") returns SVG text, a dynamic image URL and a Markdown snippet. The host can insert the snippet in a README or save the SVG. Prefer the dynamic URL for a badge that follows future project changes; downloaded SVG is a snapshot. The server does not render SVG or modify repository files. Both tools support best_practices and baseline, and neither creates drafts.

Optional draft storage

A host can keep drafts itself and pass them explicitly, or use one server-stored .bestpractices.json per project across badge levels. For validation and artifact generation, an explicit document, including {}, bypasses storage; omitting it reads the selected project's stored draft. Only update_draft writes files.

Default storage locations are:

Platform Data directory
macOS ~/Library/Application Support/bestpractices-mcp
Linux $XDG_DATA_HOME/bestpractices-mcp when XDG is absolute; otherwise ~/.local/share/bestpractices-mcp
Windows %LOCALAPPDATA%/bestpractices-mcp

To choose another location, set BESTPRACTICES_DATA_DIR in the server's environment through your MCP host. Use an absolute path; ~ is not expanded. Avoid simultaneous writers from separate server processes or external editors to the same project draft. After an uncertain update result, use read_draft before deciding whether to issue another patch. See persistence boundaries.

If you prefer a dot directory in your home directory, add an env entry to the server configuration, for example "env": {"BESTPRACTICES_DATA_DIR": "/home/yourname/.bestpractices-mcp"}. Replace that example with your actual absolute home path (on macOS, typically /Users/yourname/.bestpractices-mcp). Changing the setting does not move existing drafts: either keep using their original directory or stop the server instances and move the existing projects directory into the new data directory, taking care not to overwrite drafts already there.

Share your experience

Help improve best-practices-mcp by sharing how you used it. A brief account in your own words is enough: what you tried, how it went, which assistant/model(s) you used if known, and any additional feedback. Successful, partial, and unsuccessful interactions are all welcome.

Reports are voluntary and self-reported. We may summarize them in the interaction log, with a link to the original issue.

Documentation

License

Original project code is copyright Reponomics and licensed under the MIT License. Bundled upstream material has its own license and attribution requirements; see Third-party notices. References to BadgeApp, OpenSSF and the Linux Foundation describe compatibility and attribution, not endorsement.

Metadata

Release files for best-practices-mcp 0.5.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for best-practices-mcp 0.5.0
File Size Uploaded Provenance Actions
best_practices_mcp-0.5.0.tar.gz 602.5 kB With provenance Details for best_practices_mcp-0.5.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for best-practices-mcp 0.5.0
File Interpreter ABI Platform Actions
best_practices_mcp-0.5.0-py3-none-any.whl Python 3 none any Details for best_practices_mcp-0.5.0-py3-none-any.whl

Total release size: 695.4 kB

Release files / best_practices_mcp-0.5.0.tar.gz

Download URL best_practices_mcp-0.5.0.tar.gz
Size 602.5 kB
Tags Source
SHA-256 checksum
How to use checksums
d5dbfb2755341f1f754e7c8da6d673be021dbb984f90652745514d693ee38c0f
BLAKE2b-256 checksum
How to use checksums
c290de33a0230010a968771c376b4fab1f5dd9d81e194e6543540a761935bbe6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / best_practices_mcp-0.5.0-py3-none-any.whl

Download URL best_practices_mcp-0.5.0-py3-none-any.whl
Size 92.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
591cf87db66388a043dcb91a583a79b817b978d2dc371f1c5b9c6b95d842d1da
BLAKE2b-256 checksum
How to use checksums
82b4561ff8f8c6cb43ba1062241117a1c8041336f1a38c92e1e711e2affd9148
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Security for best-practices-mcp 0.5.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for best_practices_mcp-0.5.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page