Skip to main content

MCP 1.0 LinkedIn Portal ORCID License

🦅 WPipe-MCP — Agentic Architecture & Orchestration Hub

PyPI Version Python Versions Version License MCP

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 @step classes and Pydantic v2 DTO contexts (dto/) with Google docstrings and Pytest suites.
  • 🗺️ Standalone DAG Generator (generate_wpipe_dag): Statically parses pipelines.py and 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 @step components, pipelines.py for declarative DAG assembly, and main.py for 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, @step locations, 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 root README.md.
  • 🧪 Unit Test Generation (generate_wpipe_tests): Scaffolds isolated pytest test 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, mypy typing, 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. Omitting or disabling mandatory compliance rules via .pylintrc (such as disable= ignoring docstrings, line limits, or broad exceptions) is strictly forbidden. Inline suppression comments (# pylint: disable) are likewise prohibited (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 formatting without altering or breaking existing execution entrypoints. Directives to alter or bypass formatting or import sorting order (such as # isort: split, # isort: skip, or # fmt: off) are strictly forbidden (see Rule 17).
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 & Configs Inline suppression directives or comments used to bypass linters, type checkers, security scanners, formatting checkers, 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, # isort: split, # isort: skip, # fmt: off). Likewise, omitting compliance rules via .pylintrc configurations (disable=...) is strictly prohibited. All warnings and issues MUST be genuinely resolved through proper typed models, exhaustive Google docstrings, architectural refactoring, and safe coding practices, never bypassed or silenced.

🛠️ 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

  1. Open Cursor Settings (Ctrl+, or Cmd+,).
  2. Navigate to Features > MCP.
  3. Click + Add New MCP Server.
  4. Configure the server:
    • Name: wpipe-mcp
    • Type: command
    • Command: wpipe-mcp (or python -m wpipe_mcp.server run)

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

Metadata

Release files for wpipe-mcp 0.5.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for wpipe-mcp 0.5.3
File Size Uploaded Provenance Actions
wpipe_mcp-0.5.3.tar.gz 56.0 kB Without provenance Details for wpipe_mcp-0.5.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for wpipe-mcp 0.5.3
File Interpreter ABI Platform Actions
wpipe_mcp-0.5.3-py3-none-any.whl Python 3 none any Details for wpipe_mcp-0.5.3-py3-none-any.whl

Total release size: 99.6 kB

Release files / wpipe_mcp-0.5.3.tar.gz

Download URL wpipe_mcp-0.5.3.tar.gz
Size 56.0 kB
Tags Source
SHA-256 checksum
How to use checksums
f2f5738648049b0359da2800d2e757eb839ac9fd8e021f0b3c4496a3aa9afc7f
BLAKE2b-256 checksum
How to use checksums
bc5598ca5e2cdf8e1687eb460649d265134b11911d50fecdc3355928ec64b9a5
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.3-py3-none-any.whl

Download URL wpipe_mcp-0.5.3-py3-none-any.whl
Size 43.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
368df6fb13f1815936658a66fb62503355ccdd63e7a08e95d54d0032a35493c0
BLAKE2b-256 checksum
How to use checksums
ca4ff5036bbae13d3885d1d16d71065ebb1fceebea80f9f29e23e8b1e58c4644
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.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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page