# javergar/z3_mcp architecture

> Architecture diagram of the GitHub repository javergar/z3_mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/javergar/z3_mcp
- Repository: https://github.com/javergar/z3_mcp

## Overview

Based on your provided file tree and README, this project is a Python abstraction layer over the Z3 Theorem Prover. It exposes constraint solving and relationship analysis through a standardized Model Context Protocol (MCP) server. The implementation leverages functional programming paradigms (such as pure functions, immutable data structures, and monadic error handling) along with libraries like “returns” and “pydantic.”

##### Main Components
- Core Modules: The "core" directory contains the primary logic for solving constraint satisfaction problems (solver.py) and performing relationship analysis (relationships.py).
- Data Models: Located in the "models" directory, these files (constraints.py and relationships.py) define the mutable/immutable representations for the constraints and relationship data. They are likely built using Pydantic to enforce validations.
- MCP Server: The “server” directory houses the implementation (main.py) of the MCP server that exposes the Z3 functionalities via a standardized channel. This is the entry point for external clients that interact with the Z3 solver.
- Examples: The "examples" directory contains demonstration scripts that showcase different use cases (e.g., N-Queens, Family Relationship Inference, Cryptarithmetic puzzles).

##### Interactions and Relationships
- Server Business Logic: Within the MCP server, incoming requests are translated into calls to the underlying core functionality – either invoking the constraint solver or relationship analyzer.
- Core Operations: The core modules (solver and relationships) perform the heavy lifting. They interact with models for input validation and transform business logic into queries for the Z3 solver.
- Additional Data Flow: Show that the models (defined by Pydantic) act as the data contract for both incoming requests and outgoing responses between the server and the core modules.

##### Architectural Patterns and Design Principles
- Layered Architecture: The separation into core, models, and server reflects a decision to isolate business logic from data representations and external interfaces.
- Functional Programming: The use of immutable data structures, monadic error handling (using the “returns” library), and do-notation based pipelines is a key design principle.
- Extensibility: With dedicated directories for “examples” and clear separations, the architecture is designed for easy extension and testing.
- Dependency Injection (Implicit): Though not explicitly stated, the architecture suggests that dependencies (like the Z3 solver and configuration via the uv dependency manager) are cleanly injected into the components.

##### Additional Elements
- Clearly label configuration and dependency management components (like uv dependency management) if relevant to understanding deployment.
- A note on “Extensibility Points” – mention that the server supports multiple "MCP tools" (such as solve_constraint_problem, simple_constraint_solver, analyze_relationships, etc.) and that additional tools could be integrated as needed.

Happy diagramming!

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Entities
    subgraph "External Layer"
        EC("External Clients"):::external
    end

    %% Server Component
    subgraph "Server Layer"
        MCP("MCP Server (API Entry)"):::internal
    end

    %% Core Business Logic
    subgraph "Core Modules"
        CS("Core - Constraint Solver"):::internal
        RA("Core - Relationship Analyzer"):::internal
    end

    %% Data Models
    subgraph "Data Models"
        DM1("Data Models - Constraints"):::datamodel
        DM2("Data Models - Relationships"):::datamodel
    end

    %% External Service
    Z3("Z3 Theorem Prover"):::externalservice

    %% Demo / Example Scripts
    EX("Examples/Demos"):::internal

    %% Functional Programming Note
    FP("Note: Functional Programming drives core logic (immutability, monads, pure functions)"):::note

    %% Interactions / Data Flow
    EC -->|"RequestProcessing"| MCP
    MCP -->|"ConstraintCall"| CS
    MCP -->|"RelationshipCall"| RA
    CS -->|"Validation"| DM1
    RA -->|"Validation"| DM2
    CS -->|"ConstraintEvaluation"| Z3
    RA -->|"RelationshipEvaluation"| Z3
    MCP -->|"DemoRequests"| EX
    CS --- FP
    RA --- FP

    %% Click Events
    click CS "https://github.com/javergar/z3_mcp/blob/master/z3_mcp/core/solver.py"
    click RA "https://github.com/javergar/z3_mcp/blob/master/z3_mcp/core/relationships.py"
    click DM1 "https://github.com/javergar/z3_mcp/blob/master/z3_mcp/models/constraints.py"
    click DM2 "https://github.com/javergar/z3_mcp/blob/master/z3_mcp/models/relationships.py"
    click MCP "https://github.com/javergar/z3_mcp/blob/master/z3_mcp/server/main.py"
    click EX "https://github.com/javergar/z3_mcp/blob/master/z3_mcp/examples/main.py"

    %% Styles
    classDef external fill:#AEDFF7,stroke:#333,stroke-width:2px;
    classDef internal fill:#C1E1C1,stroke:#333,stroke-width:2px;
    classDef datamodel fill:#FFEDBA,stroke:#333,stroke-width:2px;
    classDef externalservice fill:#F7A6A6,stroke:#333,stroke-width:2px;
    classDef note fill:#FFF2CC,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5;
```
