🦅 WPipe-MCP — Agentic Architecture & Orchestration Hub
Transform your AI Agents into expert WPipe Architects.
wpipe-mcp is a production-grade Model Context Protocol (MCP) server that empowers AI Coding Agents (OpenCode, Gemini CLI / Antigravity CLI, Cursor, Claude Desktop) to design, refactor, validate, test, document, and optimize high-throughput pipeline architectures using the WPipe standard.
🏗️ Architecture & Agent Flow
flowchart LR
subgraph Clients ["AI Coding Agents & IDEs"]
OC["OpenCode"]
AGY["Antigravity / Gemini CLI"]
CUR["Cursor IDE"]
CL["Claude Desktop"]
end
subgraph MCP ["wpipe-mcp Server (stdio / SSE)"]
direction TB
Catalog["Catalog & Blueprints Engine"]
Scaffold["Scaffolding & Monolith Refactoring"]
QA["Strict QA & Compliance Validator"]
Optimizer["Static Context Flow & Optimizer"]
end
subgraph Targets ["WPipe Pipelines & Microservices"]
DTO["dto/ (Pydantic Contexts)"]
STATES["states/ (@step Callables)"]
PIPE["pipelines.py (Declarative DAG)"]
MAIN["main.py (Runtime Entrypoint)"]
end
Clients -->|MCP JSON-RPC| MCP
MCP -->|Enforces Standards| Targets
✨ Key Features
- 🔍 Expert Catalog Search (
search_wpipe_step): Search 100+ production-ready pipeline steps across official and community catalogs. - 🏗️ Strict Architecture Enforcement (
get_wpipe_architect_manual): Directs AI agents to follow modular folder separation:dto/for Pydantic Context models,states/for atomic@stepcomponents,pipelines.pyfor declarative DAG assembly, andmain.pyfor runtime entrypoints. - 🚀 Declarative Pipeline Definition (
app/pipelines.py): Dedicated specification and blueprint for standalone pipeline assembly with inline step instantiation (set_steps([MyStep(), ...])) and typed execution helper wrappers. - 🛡️ Automated QA Architectural Validation (
validate_wpipe_project): Deep static analysis checking directory structure,@steplocations, BaseModel placement, 0 dynamic reflection violations, and 0 compiled bytecode artifacts. - ⚙️ Automated Monolith Refactoring (
refactor_monolith_to_wpipe): Converts procedural monolithic Python scripts into modular class-based WPipe steps (@step) and shared Pydantic contexts. - 📊 Automatic Pipeline Documentation (
document_wpipe_project): Generates comprehensive Mermaid DAG flowcharts, step tables, and technical specifications directly inside the project's rootREADME.md. - 🧪 Unit Test Generation (
generate_wpipe_tests): Scaffolds isolatedpytesttest suites with extensive English docstrings and mocked execution contexts. - 🔍 Static Context Data Flow Analysis (
validate_context_flow): Statically validates data contracts and catches missing keys or type mismatches passed between pipeline steps. - ⚙️ Pipeline Dry Run Simulation (
dry_run_pipeline): Simulates step transitions to verify context mutation order without calling heavy AI models, databases, or external APIs. - ⚡ Performance & Monitoring Optimization (
optimize_wpipe_pipeline): Statically computes pipeline compliance scores and outputs actionable optimization advice for timeouts, memory profiling, and concurrency. - 🏆 Enforced WPipe Quality Rules: Strict standards for English-only code/docs, Google-style docstrings,
mypytyping, Pylint >= 9.3, Dockerized tests with >80% coverage, Black/Isort formatting, zero dynamic reflection, and zero bytecode artifacts.
🏆 WPipe QA Compliance Rules
When implementing or validating WPipe pipelines, wpipe-mcp strictly enforces the following 8 Mandatory Quality Rules:
| Rule # | Requirement | Description |
|---|---|---|
| 1 | Strict English Policy | All code, docstrings, variable names, comments, and log messages MUST be strictly in English. |
| 2 | Google-Style Docstrings | Every module, class, method, and function MUST contain Google-style docstrings (Args, Returns, Attributes, Raises). |
| 3 | Full Typing & Mypy Compliance | Every function parameter and return type must have explicit type annotations passing mypy --ignore-missing-imports. |
| 4 | Pylint Score >= 9.3 | Code must achieve a static analysis score of at least 9.3/10 in Pylint. |
| 5 | Dockerized Pytest & Coverage (>80%) | Unit tests must be placed in tests/, executed inside a Docker container via make pytest or docker run, and maintain >80% statement coverage. |
| 6 | Formatting & Preserved Functionality | Code must pass black and isort without altering or breaking existing execution entrypoints. |
| 7 | Zero hasattr / getattr Usage |
Dynamic reflection with hasattr() or getattr() is strictly forbidden in WPipe pipelines. Context fields must be typed explicitly using Pydantic models, dataclasses, vars(), or explicit dictionary lookups (dict.get()). Line-by-line checks in validate_wpipe_project flag violations. |
| 8 | Zero Bytecode Artifacts | All repositories and microservices must maintain 0 __pycache__ directories and 0 .pyc compiled files to prevent stale bytecode bugs and container volume pollution. Always enforce PYTHONDONTWRITEBYTECODE=1. |
🛠️ Key Technologies & Libraries
This package is engineered with the following core technologies:
- Model Context Protocol (MCP): High-speed, typed JSON-RPC communication protocol standardizing AI-to-tool integrations.
- FastMCP (mcp-sdk-python): Lightweight, asynchronous framework for exposing MCP tools, resources, and prompt templates.
- Pydantic v2: High-performance data parsing, validation, and schema definitions for pipeline contexts and MCP payloads.
- Pytest & Pytest-Cov: Comprehensive test harness with automated statement coverage calculation.
- Black & Isort: Deterministic code formatting and import sorting according to PEP 8 standards.
- Ruff & Codespell: Ultra-fast linting and spelling verification across codebase and documentation.
- Docker: Containerized execution environment for reproducible test suites and production deployments.
📦 Installation
Install wpipe-mcp directly from PyPI:
# Standard installation
pip install wpipe-mcp
# Upgrade to latest release
pip install -U wpipe-mcp
Alternatively, install locally in editable mode from source:
git clone https://github.com/wisrovi/wpipe-mcp.git
cd wpipe-mcp
pip install -e .
🔌 AI Agent & IDE Configuration
wpipe-mcp seamlessly integrates into popular AI coding agents and development environments.
1. OpenCode
Add wpipe-mcp to your global configuration (~/.opencode/mcp.json) or your project's local .opencode/mcp.json:
{
"mcpServers": {
"wpipe-mcp": {
"command": "python",
"args": ["-m", "wpipe_mcp.server", "run"]
}
}
}
Note: Replace "python" with the absolute path of your Python interpreter (e.g. /home/user/miniconda3/bin/python) if running in a specific virtual environment.
2. Gemini CLI / Antigravity CLI (AGY)
Use the built-in MCP command to register wpipe-mcp:
# Using Antigravity CLI
agy mcp add wpipe-mcp $(which python) -m wpipe_mcp.server run
# Using Gemini CLI
gemini mcp add wpipe-mcp $(which python) -m wpipe_mcp.server run
Alternatively, configure it inside ~/.gemini/antigravity-cli/mcp_config.json:
{
"mcpServers": {
"wpipe-mcp": {
"command": "python",
"args": ["-m", "wpipe_mcp.server", "run"]
}
}
}
3. Cursor IDE
- Open Cursor Settings (
Ctrl+,orCmd+,). - Navigate to Features > MCP.
- Click + Add New MCP Server.
- Configure the server:
- Name:
wpipe-mcp - Type:
command - Command:
wpipe-mcp(orpython -m wpipe_mcp.server run)
- Name:
Or edit .cursor/mcp.json directly in your workspace:
{
"mcpServers": {
"wpipe-mcp": {
"command": "wpipe-mcp",
"args": ["run"]
}
}
}
4. Claude Desktop
Add the server to your claude_desktop_config.json (located at ~/.config/Claude/claude_desktop_config.json on Linux, or %APPDATA%\Claude\claude_desktop_config.json on Windows):
{
"mcpServers": {
"wpipe-mcp": {
"command": "python",
"args": ["-m", "wpipe_mcp.server", "run"]
}
}
}
5. CLI Dynamic Auto-Configuration
You can automatically detect your active Python environment and print ready-to-use configuration blocks at any time:
wpipe-mcp config
To output the JSON block directly without additional formatting:
wpipe-mcp config --print
🧰 Available MCP Tools Reference
wpipe-mcp provides the following MCP tools for AI Agents:
| Tool Name | Parameters | Purpose |
|---|---|---|
get_wpipe_architect_blueprints |
(none) | Returns production blueprints for states, declarative pipelines.py, and monolith migration examples. |
get_wpipe_architect_manual |
(none) | Returns the official WPipe Architectural Manual with step-by-step guides and all 8 WPipe Quality Rules. |
search_wpipe_step |
query: str |
Queries the official steps catalog for reusable pre-built steps (e.g., Kafka, Redis, OpenCV, YOLO). |
deploy_wpipe_scaffolding |
target_path: str, project_name: str, pipeline_type: str, include_tests: bool |
Generates a complete WPipe standard project with dto/, states/, pipelines.py, and main.py. |
validate_wpipe_project |
project_path: str |
Deep architectural compliance auditor checking directories, step decorators, BaseModel placement, 0 reflection, and 0 bytecode. |
refactor_monolith_to_wpipe |
source_file: str, target_dir: str |
Automatically analyzes and slices monolithic scripts into atomic steps and Pydantic context models. |
document_wpipe_project |
project_path: str |
Generates automated Mermaid flowcharts and documentation directly into the project's README.md. |
generate_wpipe_tests |
project_path: str |
Automatically builds a container-ready pytest test suite with extensive English comments and mocks. |
validate_context_flow |
project_path: str |
Statically checks data key flow between sequential steps, preventing runtime missing attribute errors. |
dry_run_pipeline |
project_path: str, initial_context: dict |
Simulates pipeline transitions in-memory without invoking heavy downstream dependencies. |
optimize_wpipe_pipeline |
project_path: str |
Analyzes code quality, step granularity, and performance bottlenecks, providing actionable scoring. |
🧪 Running Tests
Unit tests are written with pytest. You can run them using any of the following methods:
1. Locally
PYTHONPATH=src pytest tests/ -v
2. Inside Docker (Containerized)
./run_tests_docker.sh
3. Code Coverage Calculation
./run_coverage.sh
The test suite generates a terminal summary and an HTML report at htmlcov/index.html.
📂 Project Structure
wpipe-mcp/
├── src/
│ └── wpipe_mcp/
│ ├── __init__.py # Package initialization and exports
│ ├── server.py # Core MCP tools and JSON-RPC dispatchers
│ ├── catalog.py # GitHub catalog synchronization & caching
│ └── templates.py # Boilerplate templates for scaffolding
├── tests/
│ └── test_wpipe_mcp.py # Complete test suite (25 test cases)
├── pyproject.toml # PEP 517/621 packaging metadata
├── CHANGELOG.md # Version history & release notes
├── Makefile # Automation recipes (clean, build, publish)
├── run_tests_docker.sh # Docker test runner
├── run_coverage.sh # Coverage calculation script
└── README.md # Comprehensive documentation
📄 License
This project is licensed under the MIT License — see the LICENSE file for details.
👤 Author & Official Affiliation
- William Steve Rodriguez Villamizar (Wisrovi)
- Role: Principal AI Engineer & Applied AI Solutions Architect | Scientific Researcher
- 📧 Email: wisrovi.rodriguez@gmail.com
- 🌐 Official Website: wisrovi.dev
- 💼 LinkedIn: wisrovi-rodriguez
- 🆔 ORCID: 0009-0005-0710-1861
- 📦 PyPI: pypi.org/user/wisrovi/
- 🐙 GitHub: @wisrovi
Metadata
Release files for wpipe-mcp 0.4.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| wpipe_mcp-0.4.3.tar.gz | 37.7 kB | Without provenance | Details for wpipe_mcp-0.4.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| wpipe_mcp-0.4.3-py3-none-any.whl | Python 3 | none | any | Details for wpipe_mcp-0.4.3-py3-none-any.whl |
Total release size: 67.4 kB
Release files / wpipe_mcp-0.4.3.tar.gz
| Download URL | wpipe_mcp-0.4.3.tar.gz |
|---|---|
| Size | 37.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
32ca414edef15f17c899525664768686d71471e4261275205d6fbcc69335c0f0
|
|
BLAKE2b-256 checksum How to use checksums |
1a4fb6ab56d64be832366d672284a5ea1f716c70d37eda095b1539258d5667de
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.5
|
Release files / wpipe_mcp-0.4.3-py3-none-any.whl
| Download URL | wpipe_mcp-0.4.3-py3-none-any.whl |
|---|---|
| Size | 29.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
99a247bfa160774a4168334415fc40e4cd6f5dc509490f4443c59c8bacfbcfd8
|
|
BLAKE2b-256 checksum How to use checksums |
550e9ab9a7449fa44bcdfb4b6c885ee3d8ed2ab3fc130bbdaccd2eea9aaa5ec1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.5
|
Security for wpipe-mcp 0.4.3
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.
No provenance found
None of the files in this release were uploaded with provenance metadata.
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.