MCP Integration¶

The MCP Layer exposes all PatternOps capabilities as Model Context Protocol tools for AI agent integration. The DefaultMCPLayer implementation provides 14 tools across 5 categories with role-based access control.

Architecture¶

graph LR
    AI[AI Agent] --> MCP[DefaultMCPLayer]
    MCP --> AC[AccessController]
    AC --> PT[PipelineTools]
    AC --> ST[StateTools]
    AC --> OT[OperationsTools]
    AC --> DT[DocumentationTools]
    AC --> AT[ArchitectureTools]

Tool Catalog¶

Pipeline Tools¶

Tool	Safety Class	Description
`pipeline_validate`	VALIDATION	Validates a pipeline config against the declarative schema
`pipeline_parse`	READ_ONLY	Parses pipeline config into structured representation
`pipeline_print`	READ_ONLY	Formats a pipeline for human-readable output
`pipeline_plan`	READ_ONLY	Generates an execution plan with stage ordering

State Tools¶

Tool	Safety Class	Description
`state_get`	READ_ONLY	Retrieves current pipeline execution state
`state_transition`	CONTROLLED_WRITE	Transitions a pipeline to a new state
`state_recovery_metadata`	READ_ONLY	Retrieves recovery metadata for failed executions

Operations Tools¶

Tool	Safety Class	Description
`metrics_query`	READ_ONLY	Queries metrics for a pipeline or dataset
`lineage_query`	READ_ONLY	Queries data lineage in FORWARD/BACKWARD/IMPACT direction
`events_query`	READ_ONLY	Queries events matching a filter
`quality_query`	READ_ONLY	Queries data quality results

Documentation Tools¶

Tool	Safety Class	Description
`docs_generate`	READ_ONLY	Generates documentation in MKDOCS/OPENAPI/JSON_SCHEMA/MCP format

Architecture Tools¶

Tool	Safety Class	Description
`architecture_resolve_bindings`	VALIDATION	Resolves capability→provider bindings
`architecture_dependency_graph`	READ_ONLY	Generates stage and capability dependency graphs

Safety Classifications¶

Class	Allowed Roles	Description
`READ_ONLY`	viewer, operator, admin	No side effects
`VALIDATION`	operator, admin	Check but don't modify
`CONTROLLED_WRITE`	operator, admin	Write with controlled scope
`RESTRICTED_ADMIN`	admin only	Elevated privileges required

Usage¶

Discover Available Tools¶

MCPLayer mcp = new DefaultMCPLayer();
MCPToolCatalog catalog = mcp.discover();

// 14 tools sorted by category then name
for (MCPToolDescriptor tool : catalog.tools()) {
    System.out.printf("[%s] %s (%s) - %s%n",
        tool.category(), tool.name(), tool.safetyClass(), tool.description());
}

Invoke a Tool¶

Identity operator = new Identity("ops-agent", List.of("operator"), "acme", "production");

// Validate a pipeline
MCPResult result = mcp.invoke("pipeline_validate", Map.of(
    "config", """
        name: daily-ingest
        tenancy: acme
        namespace: production
        dataset: orders
        executionMode: batch
        stages:
          - name: ingest
            capability: source-acquisition
        """
), operator);

if (result.success()) {
    Map<String, Object> data = (Map<String, Object>) result.data();
    boolean valid = (boolean) data.get("valid");
}

Query Lineage¶

Identity viewer = new Identity("data-analyst", List.of("viewer"), "acme", "analytics");

MCPResult result = mcp.invoke("lineage_query", Map.of(
    "dataset", "enriched-orders",
    "direction", "BACKWARD"
), viewer);

State Transition (requires operator role)¶

MCPResult result = mcp.invoke("state_transition", Map.of(
    "tenancy", "acme",
    "namespace", "production",
    "dataset", "orders",
    "pipeline", "daily-ingest",
    "business_date", "2024-01-15",
    "run_id", "run-001",
    "target_state", "RUNNING",
    "event", "pipeline-submitted"
), operator);

Access Denied Example¶

Identity viewer = new Identity("analyst", List.of("viewer"), "acme", "prod");

// Viewer cannot invoke CONTROLLED_WRITE tools
MCPResult result = mcp.invoke("state_transition", params, viewer);
// result.success() == false
// result.error() == "Access denied: identity 'analyst' with roles [viewer] cannot invoke tools with safety class CONTROLLED_WRITE"

State Machine (valid transitions)¶

PENDING → INITIALIZING, CANCELLED
INITIALIZING → RUNNING, FAILED, CANCELLED
RUNNING → SUCCEEDED, FAILED, CANCELLED
SUCCEEDED → PENDING
FAILED → RETRYING, RECOVERING, CANCELLED, PENDING
RETRYING → RUNNING, FAILED, CANCELLED
CANCELLED → PENDING
RECOVERING → RUNNING, FAILED, CANCELLED

Agent Pipeline Constructor Integration¶

The Agent module uses MCP tools internally to build pipelines from signals:

AgentPipelineConstructor agent = new DefaultAgentPipelineConstructor();

// 1. Analyse signals
AnalysisResult analysis = agent.analyse(List.of(
    new InputSignal("metadata", "catalog", Map.of("format", "parquet", "record_count", 50000), Map.of()),
    new InputSignal("schema", "db", Map.of("id", "integer", "name", "string"), Map.of()),
    new InputSignal("log", "app", "batch job processing spark records", Map.of()),
    new InputSignal("config", "pipeline", Map.of("mode", "batch"), Map.of())
));

// 2. Generate pipeline with confidence scores
GeneratedPipelinePresentation presentation = agent.generate(analysis);
Pipeline pipeline = presentation.pipeline();           // Generated pipeline
String explanation = presentation.explanation();        // Design decisions explained
Map<String, Double> scores = presentation.componentScores(); // Per-component confidence
List<Alternative> alternatives = presentation.alternatives(); // Other approaches

// 3. Refine based on feedback
UserFeedback feedback = new UserFeedback("modify", "transform", "Increase timeout", Map.of("timeout_minutes", 30));
GeneratedPipelinePresentation refined = agent.refine(generatedPipeline, feedback);

// 4. Validate
ValidationResult<Pipeline> validation = agent.validate(refined.pipeline());