Best Practices MCP

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, 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 or a guarded form-fill script, 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.

Related MCP server: repo-doctor

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.1.0-beta.1", "bestpractices-mcp"]
    }
  }
}

This lets the host launch an isolated installation from PyPI. Alternatively, install persistently with pipx install 'best-practices-mcp==0.1.0-beta.1' 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 host should discover nine tools. 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

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 overrides and script behavior.

• Authentication stays in your browser: public reads need no BadgeApp credentials. Applying proposals requires your own authenticated session and appropriate project permissions. The console script is a project-provided fallback, not an upstream-supported API.

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:

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.

Documentation

• Documentation index: the complete guide to maintained documentation and historical records.

• Design and architecture: responsibilities, data flow and the human-review boundary.

• Specification and contracts: tool behavior, exact payloads and operational limits.

• Upstream compatibility, transfer rules and schema compatibility: supported procedures and interoperability details.

• Contributing: development setup, tests, Inspector, native Windows commands and package verification.

• Live browser QA: a supervised check of generated artifacts against BadgeApp.

• Release procedure: qualification, publication and release QA.

• Roadmap: planned work and proposals under consideration.

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.