Integrates with Google Gemini models to produce diverse test inputs for characterization.
Integrates with local Ollama models (e.g., Qwen2.5 Coder) to generate test inputs without external API calls.
Integrates with OpenAI's models (e.g., GPT-4o-mini) to generate input cases for functions and methods.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Pinion characterise legacy/order_service.py::calculate_total and write tests to tests/test_order_service_pinned.py"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Lock legacy code behavior into pytest β so you can finally refactor it.
Pinion is an AI-powered characterization-test generator that reads a Python function or class method, synthesizes representative inputs, captures the function's actual behavior in a sandbox, and emits a self-contained pytest file that locks that behavior in. It runs as a CLI and as a stdio Model Context Protocol (MCP) server, so it works inside Claude Code, Claude Desktop, Cursor, Cline, Codex CLI, Gemini CLI, Zed, revfactory/harness, and any other MCP-aware client.
π°π· νκ΅μ΄ READMEλ μ¬κΈ°λ‘ β π°π· νκ΅μ΄ μ¬μ©μ 맀λ΄μΌμ μ¬κΈ°λ‘ β
Legacy modernization has a chicken-and-egg problem. To refactor safely you need tests. To write tests you need to understand the code. To understand the code you need to refactor it. Most teams stall here for years.
Existing tools have not closed this gap:
ApprovalTests / pinning-test libraries require a human to choose the inputs.
Hypothesis / property-based testing requires a human to write strategies.
EvoSuite is Java-only and search-based.
Vendor AI assistants can suggest tests in chat, but they don't run, validate coverage, or capture real behavior.
Pinion treats input selection as a reasoning task and gives it to an LLM β then validates the result with deterministic tools (AST analysis, sandboxed execution, coverage.py) before emitting a regular pytest file you can read, edit, and commit.
The AI component is essential, not decorative: removing it leaves you with a sandbox that has nothing to run.
Related MCP server: Chaos-MCP
pip install pinion-mcpPinion supports five LLM backends β Anthropic Claude, OpenAI ChatGPT, Google Gemini, local Ollama, or an internal enterprise gateway. Pick whichever you already have or grab the free Gemini tier:
# (a) Anthropic Claude β default
export ANTHROPIC_API_KEY="sk-ant-..."
# (b) OpenAI / ChatGPT
export PINION_LLM_PROVIDER=openai
export OPENAI_API_KEY="sk-..."
# (c) Google Gemini (free tier β https://aistudio.google.com/apikey)
export PINION_LLM_PROVIDER=gemini
export GEMINI_API_KEY="AIza..."pinion characterize ./legacy/order_service.py \
--function calculate_total \
--out tests/test_order_service_pinned.pyDrop --function to characterise every pure top-level function in the module.
pinion characterize ./legacy/cart.py \
--class Cart --method total \
--out tests/test_cart_total_pinned.pyDrop --method to characterise every public method on the class. Pinion automatically figures out how to construct the instance and which helper methods (add_item, apply_discount, β¦) to call first to put the instance into a meaningful state. Plain classes, @dataclass, and pydantic.BaseModel all work.
claude mcp add pinion -- pinion-mcp serveThen, in any MCP-aware client:
"Use pinion to characterise
legacy/order_service.py::calculate_totaland write the tests totests/test_order_service_pinned.py."
Pinion exposes four MCP tools:
characterize_function(file_path, function_name, β¦) β v1
characterize_method(file_path, class_name, method_name, β¦) β v2.0
characterize_module(file_path, β¦)
health_check(probe=False)
The next section lists every MCP client we've registered Pinion with.
MCP is an open protocol. Pinion is not Claude-only β anything that speaks stdio MCP can mount it.
Client | How to register Pinion |
Claude Code (CLI) |
|
Claude Desktop |
|
Cursor |
|
Cline (VS Code) | Extension settings β MCP Servers β |
Continue.dev (VS Code / JetBrains) |
|
Codex CLI (OpenAI) |
|
Gemini CLI (Google) |
|
Zed Editor |
|
|
|
Custom client | Anthropic's |
Same payload shape, different config file locations.
+-----------+ +------------+ +-----------+ +------------+ +----------+
| analyzer | --> | synthesizer| --> | sandbox | --> | coverage | --> | emitter |
| (AST) | | (LLM) | | (subproc | | (line+arc) | | (pytest) |
| profile | | inputs | | + rlimit)| | gate | | code |
+-----------+ +------------+ +-----------+ +------------+ +----------+
deterministic LLM deterministic deterministic
If coverage < threshold, the synthesizer is invoked again with
the missing branches as additional context. Up to 3 rounds.Profile. Static AST analysis pulls the signature, type hints, docstring, branch structure, and external calls. For class methods (v2.0) it also produces a ClassProfile with the constructor signature and instance attributes.
Synthesize. The profile (not the source) goes to the LLM together with the missing-branch hints. The LLM returns a JSON list of input cases β for methods, each case includes a setup block describing how to construct the instance and which helper methods to invoke first. The output is validated against a Pydantic schema before it is trusted.
Capture. Each input is executed in a fresh subprocess with CPU, memory, file-descriptor, environment, and network limits in place. Return values, exceptions, and stdout/stderr tails are captured. v2.0.1 attributes exceptions to the right phase (construction / post-init / target-method).
Validate. coverage.py measures line and branch coverage. If we are below threshold (default 0.8), the synthesizer is asked for more cases targeting the missing branches.
Emit. A clean, reviewable pytest file is produced β for methods, with @pytest.fixture per unique setup hash so cases that share a setup also share a fixture.
Pinion ships honest. It refuses, never silently degrades.
What works today (v1 + v2.0)
β Top-level pure functions
β
Class methods on plain classes, @dataclass, and pydantic.BaseModel
β Five LLM providers via env-var-only switching
β Provider-and-model-aware retry on truncated JSON
β
@pytest.fixture sharing for class methods
β macOS and Linux
What v1/v2.0 deliberately refuse
Pure functions only by default. Functions touching the filesystem, network, databases, or subprocess are refused unless --allow-impure is set, in which case there is no correctness guarantee.
No abstract base classes, metaclass-heavy classes, or __init_subclass__ users. v2.0 refuses these because the construction path is not safe to drive automatically.
JSON-friendly arguments only. Constructors and method calls take JSON-serialisable values. User-defined-class arguments are properly supported once v2.2 (mock adapters) ships.
Process-level sandbox, not a security boundary. Run Pinion only on code you have read, on disposable workstations or CI runners. The sandbox protects you from runaway loops and accidental I/O, not from a determined adversary.
No async functions yet. v2.1 adds those.
Windows is best-effort. No resource.setrlimit.
These boundaries are explicit in docs/SPEC.md Β§10 and in the code paths themselves.
Provider |
| Default model | Notes |
Anthropic Claude (default) |
|
|
|
OpenAI / ChatGPT |
|
|
|
Google Gemini |
|
|
|
Local Ollama |
|
|
|
Internal Enterprise Gateway |
| (set explicitly) | OpenAI-compatible endpoint, see below |
Override the default model any time with PINION_LLM_MODEL=<model-name>.
The enterprise-gateway slot is wired but inactive by default. To use a private internal LLM gateway (assuming OpenAI-compatible API), set:
export PINION_LLM_PROVIDER=enterprise-gateway
export PINION_LLM_MODEL=<gateway-model-name>
export PINION_GATEWAY_URL=https://internal-llm.example.com/v1
export PINION_GATEWAY_API_KEY=<token>No code change required. pinion-mcp exposes a health_check(probe=true) tool to verify connectivity. If your internal gateway is not OpenAI-compatible, add a thin adapter β the abstraction lives in pinion/providers.py.
All configuration is via environment variables. See docs/SPEC.md Β§8 for the complete list. Key ones:
PINION_LLM_PROVIDER=anthropic # anthropic | openai | gemini | ollama | enterprise-gateway
PINION_LLM_MODEL=claude-sonnet-4-5 # provider-specific
PINION_DEFAULT_THRESHOLD=0.8 # coverage gate
PINION_MAX_ROUNDS=3 # max LLM re-synthesis rounds
PINION_SANDBOX_TIMEOUT=5.0 # seconds per case
PINION_SANDBOX_MEMORY_MB=256 # RLIMIT_AS per caseWe point Pinion at Pinion. The full report β including two real limitations the run surfaced and the fix we shipped because of them β lives at examples/dogfooding/README.md.
Run | Mode | Target | Outcome |
1 | v1 (function) |
| Tests passed, but exposed the JSON-only input contract limitation when the function takes a typed-class argument (motivates v2.2) |
2 | v2 (method) |
| 100% coverage in 1 LLM round; initially 6/8 emitted tests passed β exposed a v2.0 setup-vs-method exception attribution bug we then fixed in v2.0.1 (now 8/8) |
The dogfooding run also drove one user-visible default change: DEFAULT_MAX_TOKENS was raised from 4096 to 8192 after Gemini truncated long routing-function responses.
The point of dogfooding is not "the tool worked perfectly." It is "the tool worked, and here is exactly where it does not." Both runs reproduce on the Gemini free tier at $0 total.
Shipped
β v1 β top-level pure functions, five LLM providers, MCP server, CLI, demo, full test suite (80 tests)
β
v2.0 β class methods on plain classes / @dataclass / pydantic models; per-setup @pytest.fixture sharing; new characterize_method MCP tool (110 tests total)
β v2.0.1 β setup-phase vs method-phase exception attribution fix (112 tests total)
Next (designed in docs/V2_ROADMAP.md)
v2.1 β async functions (async def) with isolated event loops
v2.2 β user-supplied mock adapters (replay / stub / route) for I/O-heavy functions
v2.3 β pinion diff orig.py --against new.py golden-master diff mode for refactor reviews
v2.4 β source-hash cache so unchanged code skips LLM re-synthesis
Further out (v3)
TypeScript via tree-sitter (vitest emitter)
Java + JUnit emitter
Property-based test synthesis (Hypothesis strategies)
VS Code extension
The full roadmap, with design notes and DoDs, is in docs/V2_ROADMAP.md.
Pinion is Apache 2.0 licensed and welcomes contributions. The design contract is frozen in docs/SPEC.md; please read it before opening a PR that changes interfaces. For bug fixes and additional fixtures, just open an issue or PR.
Apache License 2.0. See LICENSE.
Generate characterization (regression) pytest tests for a single Python pure function. Returns a CharacterizationResult including the emitted pytest code.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | ||
| function_name | Yes | ||
| max_cases | No | ||
| coverage_threshold | No | ||
| max_rounds | No | ||
| output_path | No | ||
| allow_impure | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must bear the full burden. It mentions the tool works for 'pure functions' and returns pytest code, but it does not disclose side effects (e.g., file output via output_path), permissions needed, or details about how 'allow_impure' affects behavior. The description is insufficient for understanding the tool's impact.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences that convey the core purpose. However, it could improve structure by briefly listing key parameters or use cases. It is not overly verbose, but it sacrifices completeness for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters, 0% schema coverage, no output schema, and no annotations, the description is severely lacking. It does not explain parameter meanings, return value structure, or behavioral considerations like file creation. The agent would struggle to use this tool correctly without additional information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any of the 7 parameters (file_path, function_name, max_cases, etc.). The agent must rely solely on the parameter names, which is inadequate for correct usage. The description adds no value to parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Generate characterization (regression) pytest tests for a single Python pure function.' It specifies the verb (generate), resource (characterization tests), and scope (single function), distinguishing it from siblings like characterize_method and characterize_module.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide guidance on when to use this tool versus alternatives (e.g., characterize_method, characterize_module). It implies it's for pure functions but lacks explicit context or exclusions, leaving the agent to infer usage without clear direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
v2: Generate characterization tests for a single Python class method. Returns a CharacterizationResult including the emitted pytest code with @pytest.fixture-based instance setup.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | ||
| class_name | Yes | ||
| method_name | Yes | ||
| max_cases | No | ||
| coverage_threshold | No | ||
| max_rounds | No | ||
| output_path | No | ||
| allow_impure | No | ||
| allow_stateful | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full burden. It lacks disclosure of side effects (e.g., does writing to output_path happen?), permissions, or rate limits. The return type is mentioned but behavioral traits beyond 'returns' are absent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a single sentence that covers purpose and return type. The 'v2' prefix adds minor noise but doesn't detract significantly. It could be restructured to front-load key info, but it's already brief.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 9 parameters and no output schema, the description is too brief. It explains the returned type but not parameter behavior, side effects, or usage constraints, leaving the agent with insufficient context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description must compensate but does not. It only mentions the return type and that it uses fixture-based setup, leaving parameters like max_cases, allow_impure, and coverage_threshold without explanation beyond their names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool generates characterization tests for a single Python class method, distinguishing it from sibling tools like characterize_function and characterize_module by specifying 'class method'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for class methods only, effectively differentiating from siblings which target functions or modules. It is explicit enough to guide an AI agent to choose this tool over others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate characterization tests for every pure top-level function in a module. Returns a list of CharacterizationResult, one per function (or per-function error dict). Failures don't abort the whole call.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | ||
| max_cases_per_function | No | ||
| coverage_threshold | No | ||
| max_rounds | No | ||
| output_dir | No | ||
| allow_impure | No | ||
| name_pattern | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; the description discloses return format (list of CharacterizationResult or error dict) and error handling behavior (non-aborting), adding useful behavioral context beyond the tool name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences front-loading purpose and key behavior; no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Explains purpose and return format, but for a tool with 7 parameters and no output schema, the description lacks parameter details and output structure, making it incomplete for correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description adds no explanation for any of the 7 parameters, leaving the agent to infer their meanings from names alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it generates characterization tests for every pure top-level function in a module, distinguishing it from sibling tools like characterize_function (single function) and characterize_method (methods).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for testing all pure top-level functions at once, and mentions that failures don't abort the call, but does not explicitly contrast with alternatives or provide when-not conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check Pinion configuration and LLM provider reachability.
When probe is False (default), only inspects environment variables
and config β no network call. When True, sends a minimal LLM ping.
| Name | Required | Description | Default |
|---|---|---|---|
| probe | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations were provided, so the description carries full burden. It explains the two behavioral modes (no network vs. network ping) and their triggers. It lacks details on error handling or permissions, but for a health check tool, the key behavior is disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences and a clear explanation of the probe parameter. Every sentence adds value, and it is front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (one parameter, no output schema), the description covers input behavior and the two modes. However, it does not describe what the tool returns (e.g., status summary), which would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description fully explains the 'probe' parameter: default value and the two behaviors (env/config only when False, LLM ping when True). This adds significant meaning beyond the schema, which only provides type and default.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Check Pinion configuration and LLM provider reachability.' It uses a specific verb ('check') and names the resources ('configuration and reachability'), distinguishing it from sibling tools which characterize functions, methods, and modules.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use each mode of the tool: when 'probe' is False, it only inspects environment variables and config with no network call; when True, it sends an LLM ping. This provides clear context for parameter usage, though it does not explicitly compare to sibling tools or state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.3.1characterize_functioncharacterize_methodcharacterize_modulehealth_checkEach tool targets a distinct scope: single pure function, class method, or entire module, plus a standalone health check. No overlap.
All tool names follow the same snake_case verb_noun pattern (characterize_*, health_check) with no deviations.
4 tools is well-scoped for a focused server that generates characterization tests and provides a health check.
Covers the main use cases (function, method, module) but could add support for classes or async functions. Minor gap.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Generates unit tests for Python code with coverage before/after reports and concrete edge cases.
Proves AI-generated Python does what you asked: lint, types, security, sandbox run, exact fixes.
Pre-commit code quality guardian. Detects semantic drift in AI-generated code.
AI-callable tools for API mocking, testing, monitoring, security, and automation.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/namojo/pinion'
If you have feedback or need assistance with the MCP directory API, please join our Discord server