MCP Testing Sensei
This project implements an MCP (Model Context Protocol) stdio server designed to enforce and guide agentic coding tools (like Gemini CLI or Claude Code) in adhering to language agnostic unit testing principles.
Core Principles Enforced
This tool aims to promote the following unit testing principles:
- Tests should be written before implementation. (BDD/TDD for the win)
- Tests should document the behavior of the system under test.
- Tests should be small, clearly written, and have a single concern.
- Tests should be deterministic and isolated from the side effects of their environment and other tests.
- Tests should be written in a declarative manner and never have branching logic.
Features
lint_codetool: Analyzes provided code snippets for violations of the defined unit testing standards.get_testing_principlestool: Provides the core unit testing principles to guide LLMs in generating better tests.unit-testing-principlesresource: Exposes testing principles as an MCP resource.
Installation
Option 1: Standalone Executable (No Python Required)
Download the pre-built executable for your platform from the latest release:
- Linux:
mcp-testing-sensei-linux - macOS:
mcp-testing-sensei-macos - Windows:
mcp-testing-sensei-windows.exe
Make the file executable (Linux/macOS):
chmod +x mcp-testing-sensei-linux
./mcp-testing-sensei-linux
Option 2: Install from PyPI
If you have Python installed, you can use pip:
pip install mcp-testing-sensei
This installs the mcp-testing-sensei command globally.
Option 3: Install from npm
If you prefer using npm:
npm install -g @kourtni/mcp-testing-sensei
Note: This still requires Python to be installed on your system.
Option 4: Using Docker
docker pull kourtni/mcp-testing-sensei
Option 5: Development Setup with Nix
For development or if you want to build from source:
Prerequisites
- Nix (for reproducible development environment)
Development Environment Setup
To enter the development environment with all dependencies:
nix develop
Building the Standalone Executable
To build the standalone executable using Nix, run the following command:
nix build
This will create a result symlink in your project root, pointing to the built executable.
Running the Server
Using the Standalone Executable
After building, you can run the MCP stdio server directly from the result symlink:
./result/bin/mcp-testing-sensei
This will start the MCP server that communicates via standard input/output.
Running from Development Environment
Alternatively, if you are in the nix develop shell, you can run the MCP server:
python mcp_server.py
The server communicates via stdio, reading JSON-RPC messages from stdin and writing responses to stdout.
Using with MCP Clients
The server can be integrated with MCP-compatible clients like Claude Desktop or other tools that support the Model Context Protocol.
Configuration for Claude Desktop
If installed via pip:
{
"mcpServers": {
"testing-sensei": {
"command": "mcp-testing-sensei"
}
}
}
If installed via npm:
{
"mcpServers": {
"testing-sensei": {
"command": "npx",
"args": ["@kourtni/mcp-testing-sensei"]
}
}
}
If using Docker:
{
"mcpServers": {
"testing-sensei": {
"command": "docker",
"args": ["run", "-i", "kourtni/mcp-testing-sensei"]
}
}
}
If running from source:
{
"mcpServers": {
"testing-sensei": {
"command": "python",
"args": ["/path/to/mcp-testing-sensei/mcp_server.py"]
}
}
}
Testing the Server
To verify the server is working correctly, you can use the integration test script:
# For development testing
python test_mcp_integration.py
This will:
- Start the MCP server
- Send test requests to verify the tools are working
- Display the responses
The server itself doesn't have a standalone test mode - it's designed to be used with MCP clients.
Development
Running Tests
To run the unit tests locally, first ensure you are in the Nix development environment:
nix develop
Then, execute pytest:
pytest
Project Structure
flake.lock
flake.nix
linter.py # Core linting logic
mcp_server.py # MCP stdio server implementation
main.py # Legacy HTTP server (can be removed)
pyproject.toml
test_mcp_integration.py # Integration test script for the MCP server
tests/
test_linter.py # Unit tests for the linter logic
Contributing
Contributions are welcome! Please ensure your changes adhere to the established unit testing principles and project conventions.
Additional Documentation
- DISTRIBUTION.md - Detailed guide for all distribution methods
- RELEASE.md - Release process and version management