behavior MCP server
Commit Nov 14, 2026Performs regression testing for MCP tool responses and the observable state changes they cause in files, databases, or custom probes.
Also known as GWeale/mcp-behavior
- Stars
- 1
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 14, 2026
- License
- Apache-2.0
What is behavior MCP?
behavior performs regression testing for MCP tool responses and the observable state changes they cause in files, databases, or custom probes.
Summary generated from the project's README
About behavior MCP server
Verifying that MCP tool responses match the actual changes made to files or databases is the primary function of mcp-behavior. Developers use this tool to perform regression testing by declaring specific checks in YAML files. It goes beyond simple response validation by observing side effects in files, directories, SQLite databases, or through custom probes. This ensures that a tool returning a success message actually performed the correct operation on the underlying system.
Users run this locally using Python 3.11+ and the uv package manager. The setup requires no API keys or existing servers to start, as it can run standalone demos. You can initialize testing environments using templates for SQLite or response-only checks. The system provides a clear verdict of MATCH, DIVERGE, or INCONCLUSIVE, and generates evidence bundles including JSON, Markdown, or JUnit reports for integration into CI workflows via GitHub Actions.
What you can do with it
- 1Detecting hidden state regressionsVerify if a tool returns a success message while actually writing incorrect data to a file.
- 2Testing database integrityEnsure that tool executions result in the correct rows being updated within a SQLite database.
- 3Validating filesystem operationsCheck that file edits maintain correct line endings or byte content after a tool runs.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablegweale/mcp-behavior is public and reachablegithub.com/gweale/mcp-behavior ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-14github.com/gweale/mcp-behavior ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubYour MCP tool returned success. Did it write the right thing?
Regression tests for MCP tool responses and the state they change. Declare file, directory, SQLite, or custom-probe checks in YAML; compare against expectations, a baseline, or another server.
Same successful response. Different file bytes.
The official filesystem server's edit_file used to replace CRLF line endings with LF while returning the expected edit diff. Upstream fixed it in PR #5011. We reproduced the historical regression using published versions:
MATCH 2026.8.31 response-only actual: c\nb\n
DIVERGE 2026.8.31 state-observed expected: c\r\nb\r\n
MATCH 2.0.0 fixed-control actual: c\r\nb\r\n
Watch the recorded demo · Reproduce it · Read the captured output
A direct SDK test with the same file assertion catches this too. MCP Behavior gives you one contract, verdict, and evidence bundle. It checks the effects you declare; it does not discover every side effect.
Try it
Requires uv and Python 3.11+. No API key or existing server needed.
uvx --from git+https://github.com/GWeale/mcp-behavior.git@v0.1.0 mcp-behavior demo
This separate, intentional invoice fixture runs three real checks and removes its temporary files. It writes 109 while returning saved: true for a requested total of 100:
MATCH response only: file total = 109
DIVERGE response + file state: file total = 109
MATCH corrected implementation: file total = 100
Test your server
uv tool install git+https://github.com/GWeale/mcp-behavior.git@v0.1.0
mcp-behavior init
The starter includes a file assertion. Edit the server command, tool arguments, expected path, and contents in mcp-behavior.yaml, then run:
mcp-behavior verify mcp-behavior.yaml
Use mcp-behavior init --template sqlite for database rows, or --template response for tools with no state changes. For semantic JSON comparisons, adapt the working JSON probe. See the complete example, observers, and contract reference.
| Result | Meaning | Exit |
|---|---|---|
MATCH |
The selected checks agree. | 0 |
DIVERGE |
A response or declared effect differs. | 1 |
INCONCLUSIVE |
The run could not establish a result. | 2 |
Each run saves evidence and differences. Export reports as JSON, Markdown, or JUnit, or use the GitHub Action in CI.
Found a response that hides a wrong state change? Open a minimal, sanitized case with server/version, request, expected state, and actual state. Reproducible cases are especially useful.
Reference
CLI · Python API · Evidence · Examples · Authenticated HTTP · Contributing
Alpha: install from the pinned GitHub tag or download a wheel from v0.1.0. See compatibility for schema guarantees. Configured servers and probes run as trusted code; see security. No telemetry or model calls.
behavior MCP questions
What does mcp-behavior test?
It provides regression tests for MCP tool responses and the state they change, such as files, directories, or SQLite databases.
What are the possible exit codes for a test run?
The tool returns 0 for MATCH (checks agree), 1 for DIVERGE (response or effect differs), and 2 for INCONCLUSIVE (run could not establish a result).
Does this tool require an API key?
No, no API key or existing server is needed to try it.