🦅 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. - 🏗️ Granular Step & DTO Generators (
generate_wpipe_step,generate_wpipe_dto): Scaffolds isolated@stepclasses and Pydantic v2 DTO contexts (dto/) with Google docstrings and Pytest suites. - 🗺️ Standalone DAG Generator (
generate_wpipe_dag): Statically parsespipelines.pyand compiles interactive multi-DAG Mermaid diagrams (pipelines.wpipe.mermaid). - 🏗️ 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, 0 compiled bytecode artifacts, 0 compliance bypass comments (# pylint: disable,# nosec,# noqa), AST Google docstring completeness, and 100% strict English compliance. - ⚙️ 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: 17 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, zero bytecode artifacts, strictly pinned dependencies, microservice test locations, and zero compliance bypass comments.
🏆 WPipe QA Compliance Rules
When implementing or validating WPipe pipelines, wpipe-mcp strictly enforces the following 17 Mandatory Quality Rules:
| Rule # | Requirement | Description |
|---|---|---|
| 1 | Strict English Policy (100% English) | All code, docstrings, variable names, functions, classes, comments, log messages, error messages, test names, and UI elements (Gradio tabs, buttons, labels, FAQs) MUST be strictly in English. |
| 2 | Exhaustive Google-Style Docstrings | Every module, class, method, and function MUST contain complete Google-style docstrings explicitly detailing all parameters (Args: with types and semantics), return values (Returns: with types), and raised exceptions (Raises: with trigger conditions). |
| 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. Inline suppression comments (# pylint: disable) are strictly forbidden (see Rule 17). |
| 5 | Dockerized Pytest & Coverage (>80%) | Unit tests must be placed in tests/, executed inside a Docker container via make pytest or run_tests_docker.sh, 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. |
| 9 | Maximum 200 Lines Per File | No source file (.py) should exceed 200 lines of code. Decompose complex logic into focused helper modules in utils/ and dedicated DTOs in dto/ to maintain strict modularity. |
| 10 | Strict Single Responsibility Principle (SRP) | Every Python file MUST have one single responsibility. Routers, view layouts, event controller handlers, in-memory data cubes, format loaders, and math algorithms must reside in dedicated, non-overlapping modules. |
| 11 | Zero Nested Closures in Steps | Defining inner functions (closures) inside @step __call__ methods is strictly prohibited. Helper algorithms and transformations must be extracted into standalone utility functions in app/utils/. |
| 12 | Mandatory User Inquiry & Decision Protocol | Agents must NEVER make silent assumptions regarding legacy code retention or cleanup. Always explicitly consult the user before deleting obsolete methods/files, keeping legacy wrappers, or making refactoring tradeoffs. |
| 13 | Zero Dead Code & Redundancy | Clean repository hygiene requiring unused functions, dead code blocks, obsolete legacy wrappers, and unused imports to be removed or explicitly brought to the user's attention. Zero duplicate files. |
| 14 | Distinct Pipeline Variable Identifiers for Multi-DAG Visualization | When multiple pipelines or factory builders are defined in a file (e.g. app/pipelines.py), each pipeline instance MUST be assigned to a distinct, unique, and descriptive variable identifier (e.g. hsi_analysis_pipeline = ..., hsi_preview_pipeline = ...), NEVER a generic repeated name (pipeline = ...). The WPipe VS Code extension uses this variable name to identify and deduplicate subgraphs; using unique names ensures all pipelines render simultaneously in the DAG Webview. |
| 15 | Strictly Pinned Requirements (Zero Floating Versions) | All external dependencies defined in requirements.txt or pyproject.toml MUST be strictly pinned to exact versions using == (e.g., package==X.Y.Z). Floating versions (>=, ~=) or unpinned bare names are strictly prohibited in production microservices to guarantee 100% deterministic, reproducible container builds. |
| 16 | Internal Test Suite Location (app/tests/ or app/test/) |
In dockerized microservice architectures (app/ layout), all unit test suites, fixtures, test mocks, and coverage runners MUST reside directly inside the microservice package itself (app/tests/ or app/test/), NOT loose in the root project folder. |
| 17 | Zero Compliance Bypass Comments (No # pylint: disable, # nosec, # noqa, # type: ignore) |
Inline suppression directives or comments used to bypass linters, type checkers, security scanners, or test coverage gates are strictly forbidden across all Python files (# pylint: disable=..., # nosec, # noqa, # type: ignore, # bandit: disable, # flake8: noqa, # ruff: noqa, # pragma: no cover). All warnings and issues MUST be resolved through proper typed models, architectural refactoring, safe coding practices, or project-level configuration files (.pylintrc), never silenced with inline bypass comments. |
🛠️ 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 17 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, 0 bytecode, 0 bypass comments, max 200 lines per file, and 0 nested function closures. |
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.5.2
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.5.2.tar.gz | 54.7 kB | Without provenance | Details for wpipe_mcp-0.5.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| wpipe_mcp-0.5.2-py3-none-any.whl | Python 3 | none | any | Details for wpipe_mcp-0.5.2-py3-none-any.whl |
Total release size: 97.4 kB
Release files / wpipe_mcp-0.5.2.tar.gz
| Download URL | wpipe_mcp-0.5.2.tar.gz |
|---|---|
| Size | 54.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
692a6c118bd7f9fa01c38c48b97ebe3a5e836a1c96d4ec5c8eae6b472c97813a
|
|
BLAKE2b-256 checksum How to use checksums |
51fe61ee35ecbcc95da2c3c35e3553b58f1cfb68fcf0d630a4785336f30b32f9
|
| 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.5.2-py3-none-any.whl
| Download URL | wpipe_mcp-0.5.2-py3-none-any.whl |
|---|---|
| Size | 42.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ebade53cce8a5f021fdb0d478f2eea35664d853063b0ed269bd075fd6327b8b4
|
|
BLAKE2b-256 checksum How to use checksums |
cd0918c2d68c6e02fa39c1049dda82b280cb37e06b3892fee25699f5d81fce4e
|
| 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.5.2
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.