umlforge 0.1.0__py3-none-any.whl

connector/README.md

@@ -0,0 +1,54 @@
+# UML Forge MCP Connector
+
+**AI-powered UML diagram generation for coding agents.**
+
+[UML Forge](https://umlforge.dev) gives Claude Code, Cursor, Windsurf, and any
+MCP-compatible coding agent a suite of 13 specialised tools for producing
+professional UML diagrams from your codebase, schema, or architecture
+descriptions.
+
+## Quick start
+
+**Claude Code:**
+```json
+{
+  "mcpServers": {
+    "umlforge": {
+      "command": "uvx",
+      "args": ["umlforge"],
+      "env": { "UMLFORGE_API_KEY": "your-api-key" }
+    }
+  }
+}
+```
+
+**Cursor / Windsurf** — add the same block to your MCP settings.
+
+Get your API key at [umlforge.dev](https://umlforge.dev).
+
+## Tools included
+
+| Tool | Description |
+|------|-------------|
+| `umlforge_reverse_engineer` | Class, sequence, and state diagrams from a codebase or GitHub URL |
+| `umlforge_api_sequence` | Sequence diagrams from OpenAPI / REST endpoints |
+| `umlforge_erd_schema` | Entity-relationship diagrams from SQL schema or ORM models |
+| `umlforge_state_machine` | State diagrams from business rules or UI flows |
+| `umlforge_frontend_components` | Component hierarchy and data-flow diagrams |
+| `umlforge_deployment` | Infrastructure and deployment diagrams |
+| `umlforge_threat_model` | STRIDE threat model + attack surface diagram |
+| `umlforge_event_driven` | Event flow and pub/sub architecture diagrams |
+| `umlforge_ai_agent` | Agent topology and tool-call flow diagrams |
+| `umlforge_stakeholder_arch` | C4 context diagrams for stakeholder communication |
+| `umlforge_living_docs` | Living documentation diagrams synced to code |
+| `umlforge_onboarding` | Onboarding maps for new team members |
+| `umlforge_suggest` | Recommends the best diagram type for a description |
+
+## Requirements
+
+- Python 3.11+
+- An API key from [umlforge.dev](https://umlforge.dev) (free tier available)
+
+## License
+
+Proprietary. The connector is open to install and use with a UML Forge account.

connector/__main__.py

@@ -0,0 +1,10 @@
+"""Entry point for `uvx umlforge` and `python -m connector`."""
+from connector.server import mcp
+
+
+def main() -> None:
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

connector/api_client.py

@@ -0,0 +1,154 @@
+"""
+UML Forge Connector — API Client
+
+Thin HTTP client for the UML Forge hosted API.
+ZERO business logic. ZERO prompt text.
+All diagram generation happens server-side.
+"""
+
+from __future__ import annotations
+
+import httpx
+
+from connector.config import load_config
+
+# Timeout for diagram generation — Anthropic calls can take up to ~60s
+_GENERATE_TIMEOUT = 210.0
+_SUGGEST_TIMEOUT  = 30.0
+
+
+async def generate(
+    tool: str,
+    params: dict,
+    guided_mode: bool = False,
+) -> str:
+    """
+    Call POST /v1/generate on the UML Forge API.
+    Returns a formatted Markdown string ready for display in a coding agent.
+    """
+    config = load_config()
+
+    async with httpx.AsyncClient(timeout=_GENERATE_TIMEOUT) as client:
+        response = await client.post(
+            f"{config.api_base_url}/v1/generate",
+            json={
+                "tool": tool,
+                "params": params,
+                "guided_mode": guided_mode and config.guided_mode,
+            },
+            headers={
+                "Authorization": f"Bearer {config.api_key}",
+                "Content-Type": "application/json",
+            },
+        )
+
+    if response.status_code == 402:
+        body = response.json()
+        upgrade_url = body.get("upgrade_url", "https://umlforge.dev/billing")
+        return (
+            f"**Monthly diagram limit reached.**\n\n"
+            f"{body.get('error', 'Upgrade to Pro for unlimited diagrams.')}\n\n"
+            f"Upgrade at: {upgrade_url}"
+        )
+
+    if response.status_code == 401:
+        return (
+            "**Authentication failed.** Check that your API key in "
+            "your UMLFORGE_API_KEY is correct and active."
+        )
+
+    response.raise_for_status()
+    return _format_generate_response(response.json())
+
+
+async def suggest(task_description: str) -> str:
+    """
+    Call POST /v1/suggest on the UML Forge API.
+    Returns a formatted recommendation string.
+    """
+    config = load_config()
+
+    async with httpx.AsyncClient(timeout=_SUGGEST_TIMEOUT) as client:
+        response = await client.post(
+            f"{config.api_base_url}/v1/suggest",
+            json={"task_description": task_description},
+            headers={
+                "Authorization": f"Bearer {config.api_key}",
+                "Content-Type": "application/json",
+            },
+        )
+
+    if response.status_code == 401:
+        return (
+            "**Authentication failed.** Check that your API key in "
+            "your UMLFORGE_API_KEY is correct and active."
+        )
+
+    if response.status_code == 402:
+        body = response.json()
+        upgrade_url = body.get("upgrade_url", "https://umlforge.dev/billing")
+        return (
+            f"**Monthly diagram limit reached.**\n\n"
+            f"{body.get('error', 'Upgrade to Pro for unlimited diagrams.')}\n\n"
+            f"Upgrade at: {upgrade_url}"
+        )
+
+    response.raise_for_status()
+    body = response.json()
+
+    return (
+        f"**Recommended tool:** `{body['recommended_tool']}`\n\n"
+        f"{body['reasoning']}\n\n"
+        f"**Alternative:** `{body['alternative_tool']}`  \n"
+        f"{body['alternative_reasoning']}\n\n"
+        f"*Call the recommended tool with your task details to generate the diagram.*"
+    )
+
+
+# ── Response formatter ────────────────────────────────────────────────────────
+
+def _format_generate_response(body: dict) -> str:
+    """
+    Format a /v1/generate response body into readable Markdown.
+
+    Output shape:
+      ## Diagram Title [⚠️ if validation warning]
+
+      ```mermaid
+      [content]
+      ```
+
+      [supplementary tables / notes]
+
+      ---
+      *Generated by UML Forge | X diagrams remaining this month*
+    """
+    parts: list[str] = []
+
+    for diagram in body.get("diagrams", []):
+        title   = diagram.get("title", "Diagram")
+        mermaid = diagram.get("mermaid", "").strip()
+        warning = " ⚠️ _validation warning — review before using_" \
+                  if diagram.get("validation_warning") else ""
+
+        parts.append(f"## {title}{warning}\n\n```mermaid\n{mermaid}\n```")
+
+    # Supplementary sections (STRIDE table, implementation notes, etc.)
+    supplementary = body.get("supplementary", {})
+    for key, content in supplementary.items():
+        if isinstance(content, str) and content.strip():
+            parts.append(content.strip())
+
+    # Usage footer
+    usage     = body.get("usage", {})
+    remaining = usage.get("diagrams_remaining")
+    tier      = usage.get("tier", "free")
+
+    if remaining is not None:
+        footer = f"*Generated by UML Forge | {remaining} diagrams remaining this month*"
+    else:
+        footer = f"*Generated by UML Forge | {tier.title()} — unlimited diagrams*"
+
+    parts.append("---\n" + footer)
+
+    return "\n\n".join(parts)

connector/config.py

@@ -0,0 +1,94 @@
+"""
+UML Forge Connector — Configuration
+
+Resolution order (first match wins):
+  1. Environment variables — set via .mcp.json "env" block (recommended)
+       UMLFORGE_API_KEY        required
+       UMLFORGE_GUIDED_MODE    optional, "true"/"false" (default: false)
+       UMLFORGE_API_BASE_URL   optional (default: https://api.umlforge.dev)
+
+  2. Config file fallback — ~/.umlforge/config.toml
+       api_key       = "uf_live_your_key_here"
+       api_base_url  = "https://api.umlforge.dev"   # optional
+       guided_mode   = false                         # optional, Pro tier only
+"""
+
+import os
+import sys
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+
+CONFIG_PATH = Path.home() / ".umlforge" / "config.toml"
+
+_SETUP_INSTRUCTIONS = """\
+UML Forge: no API key found.
+
+Add the key via your .mcp.json "env" block (recommended):
+
+  {
+    "mcpServers": {
+      "umlforge": {
+        "command": "uvx",
+        "args": ["umlforge"],
+        "env": {
+          "UMLFORGE_API_KEY": "uf_live_your_key_here"
+        }
+      }
+    }
+  }
+
+Or create ~/.umlforge/config.toml:
+
+  api_key = "uf_live_your_key_here"
+  guided_mode = false
+
+Get your key at https://umlforge.dev
+"""
+
+
+@dataclass
+class ConnectorConfig:
+    api_key: str
+    api_base_url: str = "https://api.umlforge.dev"
+    guided_mode: bool = False
+
+
+def load_config() -> ConnectorConfig:
+    """
+    Load connector configuration from env vars (primary) or config file (fallback).
+    Exits with setup instructions if no API key is found.
+    """
+    # ── 1. Environment variables (set by MCP host via .mcp.json "env" block) ──
+    api_key = os.environ.get("UMLFORGE_API_KEY", "").strip()
+    if api_key:
+        return ConnectorConfig(
+            api_key=api_key,
+            api_base_url=os.environ.get(
+                "UMLFORGE_API_BASE_URL", "https://api.umlforge.dev"
+            ).rstrip("/"),
+            guided_mode=os.environ.get("UMLFORGE_GUIDED_MODE", "false").lower() == "true",
+        )
+
+    # ── 2. Config file fallback ────────────────────────────────────────────────
+    if CONFIG_PATH.exists():
+        with open(CONFIG_PATH, "rb") as fh:
+            data = tomllib.load(fh)
+
+        if "api_key" not in data:
+            print(
+                f"UML Forge: 'api_key' not found in {CONFIG_PATH}\n"
+                "Add: api_key = \"uf_live_your_key_here\"",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+
+        return ConnectorConfig(
+            api_key=data["api_key"],
+            api_base_url=data.get("api_base_url", "https://api.umlforge.dev").rstrip("/"),
+            guided_mode=bool(data.get("guided_mode", False)),
+        )
+
+    # ── 3. Nothing found ───────────────────────────────────────────────────────
+    print(_SETUP_INSTRUCTIONS, file=sys.stderr)
+    sys.exit(1)

connector/requirements.txt

@@ -0,0 +1,12 @@
+# UML Forge — MCP Connector Dependencies
+# Installed on developer's machine
+# Python 3.12.x required (tomllib is stdlib in 3.11+, no extra dep needed)
+
+# ── MCP ────────────────────────────────────────────────
+mcp[cli]>=1.27.0,<2.0.0
+
+# ── HTTP Client ────────────────────────────────────────
+httpx>=0.27.0,<1.0.0
+
+# ── Data Validation ────────────────────────────────────
+pydantic>=2.7.0,<3.0.0

connector/server.py

@@ -0,0 +1,33 @@
+"""
+UML Forge Connector — MCP Server Entry Point
+
+Starts the FastMCP stdio server with all 13 UML Forge tools registered.
+
+Installation:
+    uvx umlforge          # recommended — isolated, no pip install needed
+
+Claude Code (.mcp.json):
+    {
+      "mcpServers": {
+        "umlforge": {
+          "command": "uvx",
+          "args": ["umlforge"],
+          "env": {
+            "UMLFORGE_API_KEY": "uf_live_your_key_here"
+          }
+        }
+      }
+    }
+
+Cursor / other MCP hosts:
+    Same structure — set UMLFORGE_API_KEY in the "env" block.
+
+Config fallback (power users): ~/.umlforge/config.toml
+    api_key     = "uf_live_your_key_here"
+    guided_mode = false
+"""
+
+from connector.tools import mcp
+
+if __name__ == "__main__":
+    mcp.run()

connector/tools.py

@@ -0,0 +1,568 @@
+"""
+UML Forge Connector — MCP Tool Definitions
+
+Registers all 13 UML Forge tools with the FastMCP server.
+
+CRITICAL CONSTRAINTS (enforced by architecture):
+  - ZERO business logic in this file
+  - ZERO prompt text in this file
+  - NO Anthropic API calls
+  - Every tool body is a single call to api_client.generate() or api_client.suggest()
+
+The tool docstrings are what coding agents (Claude Code, Cursor, etc.) read
+to decide which tool to call — write them clearly and specifically.
+"""
+
+from __future__ import annotations
+
+from mcp.server.fastmcp import FastMCP
+from mcp.types import ToolAnnotations
+
+from connector import api_client
+from connector.config import load_config
+
+mcp = FastMCP("umlforge_mcp")
+
+_READ_ONLY = ToolAnnotations(
+    readOnlyHint=True,
+    destructiveHint=False,
+    idempotentHint=False,
+    openWorldHint=True,
+)
+
+
+# ── 1. Reverse Engineer ────────────────────────────────────────────────────────
+
+@mcp.tool(annotations=_READ_ONLY)
+async def umlforge_reverse_engineer(
+    codebase: str = "",
+    github_url: str | None = None,
+    max_nodes: int = 20,
+) -> str:
+    """
+    Reverse-engineer a codebase into UML class, sequence, and state diagrams.
+
+    Analyses the provided code and produces:
+    - Class diagram: entities, attributes, relationships, multiplicities
+    - Sequence diagram: primary execution flow or dominant use case
+    - State diagram: entity lifecycle (if stateful entities are found)
+    - Architectural smell flags: god classes, circular deps, anemic models
+
+    Best for: legacy system audits, onboarding, code review preparation,
+    technical debt assessment.
+
+    Provide EITHER codebase OR github_url — not required to supply both.
+
+    Args:
+        codebase: Code snippets, file contents, or structured description
+                  of the codebase. Use this when you have code in context
+                  or want to paste specific files.
+        github_url: Public GitHub URL — the server fetches the code for you.
+                    Accepted formats:
+                      github.com/owner/repo
+                      github.com/owner/repo/tree/branch/path/to/dir
+                      github.com/owner/repo/blob/branch/path/to/file.py
+        max_nodes: Maximum classes/components per diagram (default 20).
+                   Increase for large codebases; decrease for readability.
+    """
+    config = load_config()
+    return await api_client.generate(
+        "umlforge_reverse_engineer",
+        {"codebase": codebase, "github_url": github_url, "max_nodes": max_nodes},
+        guided_mode=config.guided_mode,
+    )
+
+
+# ── 2. Stakeholder Architecture ───────────────────────────────────────────────
+
+@mcp.tool(annotations=_READ_ONLY)
+async def umlforge_stakeholder_arch(
+    system_description: str,
+    audience_description: str,
+) -> str:
+    """
+    Generate a C4 architecture diagram (Context + Container + Component levels).
+
+    Produces three diagrams scaled for a mixed technical/non-technical audience:
+    - C4 Context: system boundary, external actors, primary integrations
+    - C4 Container: deployable units, tech stack labels, communication protocols
+    - C4 Component: internals of the most complex container
+
+    Best for: investor presentations, client onboarding, architecture review boards,
+    pre-demo documentation.
+
+    Args:
+        system_description: What the system does, who uses it, its major components.
+        audience_description: Who will read this (e.g. "CTO and backend engineers",
+                              "non-technical investors").
+    """
+    config = load_config()
+    return await api_client.generate(
+        "umlforge_stakeholder_arch",
+        {
+            "system_description": system_description,
+            "audience_description": audience_description,
+        },
+        guided_mode=config.guided_mode,
+    )
+
+
+# ── 3. API Sequence ───────────────────────────────────────────────────────────
+
+@mcp.tool(annotations=_READ_ONLY)
+async def umlforge_api_sequence(
+    services: str,
+    user_journey: str,
+) -> str:
+    """
+    Generate a detailed sequence diagram for an API or microservices interaction.
+
+    Produces:
+    - Sequence diagram: happy path + at least 2 failure/exception paths,
+      activation boxes, sync vs async arrows, performance boundary annotation
+    - Inter-service dependency table: caller, callee, protocol, failure mode, mitigation
+
+    Best for: new service integration design, API contract definition,
+    QA test planning, incident post-mortems.
+
+    Args:
+        services: Participants in the interaction, e.g.
+                  "API Gateway, Auth Service, Order Service, Payment Provider, User DB".
+        user_journey: The user action or flow to diagram in plain English,
+                      e.g. "User places an order through checkout".
+    """
+    config = load_config()
+    return await api_client.generate(
+        "umlforge_api_sequence",
+        {"services": services, "user_journey": user_journey},
+        guided_mode=config.guided_mode,
+    )
+
+
+# ── 4. State Machine ──────────────────────────────────────────────────────────
+
+@mcp.tool(annotations=_READ_ONLY)
+async def umlforge_state_machine(
+    entity: str,
+    states: str,
+    events: str,
+    business_rules: str = "",
+) -> str:
+    """
+    Design a state machine diagram for a complex domain entity.
+
+    Produces:
+    - stateDiagram-v2: all states with entry/exit actions, transitions with
+      guard conditions, composite states, explicit ERROR and TERMINAL states
+    - State transition table: current state → event → guard → next state → action
+    - Implementation notes: which transitions need DB writes, domain events,
+      and race condition guards
+    - Assumption flags for any ambiguous business rules
+
+    Best for: domain-driven design, workflow/approval systems, order/job lifecycle,
+    IoT device management.
+
+    Args:
+        entity: Domain entity name (e.g. "Order", "Subscription", "JobApplication").
+        states: Known lifecycle states (e.g. "pending, active, suspended, cancelled").
+        events: Triggers that cause state transitions (e.g. "payment_received, user_cancels").
+        business_rules: Constraints on transitions (optional).
+    """
+    config = load_config()
+    return await api_client.generate(
+        "umlforge_state_machine",
+        {
+            "entity": entity,
+            "states": states,
+            "events": events,
+            "business_rules": business_rules,
+        },
+        guided_mode=config.guided_mode,
+    )
+
+
+# ── 5. Living Docs ────────────────────────────────────────────────────────────
+
+@mcp.tool(annotations=_READ_ONLY)
+async def umlforge_living_docs(
+    current_diagrams: str,
+    sprint_changes: str,
+    affected_files: str = "",
+) -> str:
+    """
+    Update existing UML diagrams to reflect sprint or PR changes.
+
+    Diffs your current diagrams against described changes and produces:
+    - Updated diagrams only for affected sections (with %% changelog headers)
+    - New diagrams for any newly introduced architectural patterns
+    - Architecture evolution note suitable for pasting into a project wiki
+    - Explicit flags for intentionally removed nodes/relationships
+
+    Best for: sprint retrospectives, PR documentation, wiki maintenance,
+    architecture changelog management.
+
+    Args:
+        current_diagrams: Existing Mermaid diagram(s) to update — paste the
+                          full content including ```mermaid fences.
+        sprint_changes: What changed: new components, removed flows, renamed
+                        services, modified behaviour.
+        affected_files: Files or modules touched in this sprint/PR (optional).
+    """
+    config = load_config()
+    return await api_client.generate(
+        "umlforge_living_docs",
+        {
+            "current_diagrams": current_diagrams,
+            "sprint_changes": sprint_changes,
+            "affected_files": affected_files,
+        },
+        guided_mode=config.guided_mode,
+    )
+
+
+# ── 6. ERD & Schema ───────────────────────────────────────────────────────────
+
+@mcp.tool(annotations=_READ_ONLY)
+async def umlforge_erd_schema(
+    domain_description: str,
+    entities: str,
+    access_patterns: str = "",
+    db_technology: str = "PostgreSQL",
+) -> str:
+    """
+    Design a database ERD with schema narrative and integrity checklist.
+
+    Produces:
+    - erDiagram: all entities with typed attributes, relationships, cardinality,
+      and foreign key labels
+    - Schema narrative: one paragraph per entity — business purpose, index
+      recommendations, denormalisation decisions
+    - Data integrity checklist: uniqueness, FK integrity, null policies, constraints
+    - Performance risk flags for N+1 query patterns
+
+    Best for: new feature schema design, migration planning, ORM model definition,
+    data architecture reviews.
+
+    Args:
+        domain_description: What the database stores (e.g. "E-commerce platform:
+                            users, products, orders, payments").
+        entities: Known entities and key attributes (e.g. "User(id, email, tier),
+                  Order(id, user_id, status, total)").
+        access_patterns: Most frequent read/write operations (optional, used
+                         for index recommendations).
+        db_technology: Database technology — PostgreSQL, MySQL, MongoDB, etc.
+                       (default: PostgreSQL).
+    """
+    config = load_config()
+    return await api_client.generate(
+        "umlforge_erd_schema",
+        {
+            "domain_description": domain_description,
+            "entities": entities,
+            "access_patterns": access_patterns,
+            "db_technology": db_technology,
+        },
+        guided_mode=config.guided_mode,
+    )
+
+
+# ── 7. Threat Model ───────────────────────────────────────────────────────────
+
+@mcp.tool(annotations=_READ_ONLY)
+async def umlforge_threat_model(
+    system_description: str,
+    auth_mechanism: str,
+    trust_boundaries: list[str] | None = None,
+    sensitive_data: list[str] | None = None,
+    compliance_framework: str | None = None,
+) -> str:
+    """
+    Generate a security threat model with full STRIDE analysis.
+
+    Produces:
+    - Authentication flow sequence diagram with trust boundary annotations and
+      all failure paths (invalid creds, expired token, insufficient permissions)
+    - Data flow diagram with sensitivity labels (PUBLIC/INTERNAL/CONFIDENTIAL/SECRET)
+    - STRIDE threat table: all 6 categories with likelihood, mitigation, status
+    - Critical flags (🚨) for unencrypted sensitive data flows and high-risk gaps
+
+    Best for: pre-production security reviews, auth flow design,
+    compliance documentation (GDPR, NDPA 2023, SOC2, PCI-DSS),
+    penetration test preparation.
+
+    Pro users: set UMLFORGE_GUIDED_MODE=true in your .mcp.json env block.
+
+    Args:
+        system_description: What the system does, how users access it, main components.
+        auth_mechanism: Authentication in use (e.g. "JWT Bearer token", "API Key",
+                        "OAuth2 + PKCE").
+        trust_boundaries: Trust boundary crossings (e.g. ["public internet → API",
+                          "API → database"]).
+        sensitive_data: Sensitive data types (e.g. ["user emails", "payment tokens"]).
+        compliance_framework: Compliance scope (e.g. "GDPR", "NDPA 2023", "PCI-DSS").
+    """
+    config = load_config()
+    return await api_client.generate(
+        "umlforge_threat_model",
+        {
+            "system_description": system_description,
+            "auth_mechanism": auth_mechanism,
+            "trust_boundaries": trust_boundaries or [],
+            "sensitive_data": sensitive_data or [],
+            "compliance_framework": compliance_framework,
+        },
+        guided_mode=config.guided_mode,
+    )
+
+
+# ── 8. Frontend Components ────────────────────────────────────────────────────
+
+@mcp.tool(annotations=_READ_ONLY)
+async def umlforge_frontend_components(
+    feature_description: str,
+    framework: str = "React",
+    state_management: str = "",
+    interactions: str = "",
+) -> str:
+    """
+    Generate a frontend component architecture diagram.
+
+    Produces:
+    - Component hierarchy graph: parent-child relationships, props (downward),
+      events/callbacks (upward), state store connections (dashed), API call origins
+    - Interaction sequence diagram: most complex user interaction — loading,
+      success, and error states
+    - Component responsibility table: responsibilities, state owned, reusability
+    - Accessibility note: ARIA roles needed, keyboard navigation, WCAG risks
+    - God component flags (⚠️) for components with too many responsibilities
+
+    Best for: new feature UI design, design system development,
+    component library documentation, frontend architecture reviews.
+
+    Args:
+        feature_description: The UI feature or page to diagram.
+        framework: Frontend framework — React, Vue, Angular, Svelte, Next.js, etc.
+                   (default: React).
+        state_management: State approach — Redux, Zustand, Context API, Pinia, etc.
+                          (optional).
+        interactions: Key user interactions (optional, improves diagram quality).
+    """
+    config = load_config()
+    return await api_client.generate(
+        "umlforge_frontend_components",
+        {
+            "feature_description": feature_description,
+            "framework": framework,
+            "state_management": state_management,
+            "interactions": interactions,
+        },
+        guided_mode=config.guided_mode,
+    )
+
+
+# ── 9. Event-Driven ───────────────────────────────────────────────────────────
+
+@mcp.tool(annotations=_READ_ONLY)
+async def umlforge_event_driven(
+    system_context: str,
+    producers: str,
+    consumers: str,
+    broker: str = "",
+    events: str = "",
+) -> str:
+    """
+    Design an event-driven or async system architecture.
+
+    Produces:
+    - Event flow sequence diagram: producers → broker → consumers with ack,
+      retry loops, and dead-letter queue handling
+    - Event catalogue table: name, producer, consumers, payload, ordering,
+      idempotency, retention
+    - Choreography vs orchestration assessment with coupling risk flags
+    - Failure mode analysis table: scenario, impact, detection, recovery
+
+    Best for: event sourcing design, CQRS, microservices decoupling,
+    message broker integration, async workflow design.
+
+    Args:
+        system_context: What the event-driven system does and why it uses messaging.
+        producers: Services that emit events (e.g. "Order Service emits order.placed").
+        consumers: Services that consume events (e.g. "Notification, Inventory, Analytics").
+        broker: Message broker (e.g. "Kafka", "RabbitMQ", "AWS SQS/SNS") (optional).
+        events: Named domain events (e.g. "order.placed, payment.failed") (optional).
+    """
+    config = load_config()
+    return await api_client.generate(
+        "umlforge_event_driven",
+        {
+            "system_context": system_context,
+            "producers": producers,
+            "consumers": consumers,
+            "broker": broker,
+            "events": events,
+        },
+        guided_mode=config.guided_mode,
+    )
+
+
+# ── 10. Team Onboarding ───────────────────────────────────────────────────────
+
+@mcp.tool(annotations=_READ_ONLY)
+async def umlforge_onboarding(
+    system_description: str,
+    tech_stack: str,
+    key_workflows: str,
+    pain_points: str = "",
+) -> str:
+    """
+    Generate a complete team onboarding and knowledge-transfer diagram package.
+
+    Produces four diagrams plus a gotchas table:
+    - System overview (C4 Container): the lay-of-the-land on day one
+    - Developer workflow sequence: local dev → test → CI → staging → production,
+      plus the most common debugging path
+    - Data lifecycle (activity diagram): how data enters, transforms, stores, deletes
+    - Module dependency map: internal modules + external deps, circular dep flags
+    - Gotchas & constraints table: what the code does, why it does it that way,
+      what breaks if you change it
+
+    Best for: developer onboarding, module handover, team scaling,
+    documentation-before-departure.
+
+    Args:
+        system_description: High-level description of the system being handed over.
+        tech_stack: Languages, frameworks, and infrastructure (e.g. "FastAPI,
+                    PostgreSQL, React, Redis, Railway").
+        key_workflows: 2-3 most important flows a new developer must understand.
+        pain_points: Known gotchas, non-obvious decisions, workarounds (optional).
+    """
+    config = load_config()
+    return await api_client.generate(
+        "umlforge_onboarding",
+        {
+            "system_description": system_description,
+            "tech_stack": tech_stack,
+            "key_workflows": key_workflows,
+            "pain_points": pain_points,
+        },
+        guided_mode=config.guided_mode,
+    )
+
+
+# ── 11. AI Agent ──────────────────────────────────────────────────────────────
+
+@mcp.tool(annotations=_READ_ONLY)
+async def umlforge_ai_agent(
+    pipeline_purpose: str,
+    agents: str,
+    tools_available: str = "",
+    orchestration_approach: str = "",
+    memory_strategy: str = "",
+) -> str:
+    """
+    Design an AI agent and orchestration pipeline architecture.
+
+    Produces:
+    - Agent pipeline sequence diagram: agents as participants with model names,
+      tool calls as self-calls, human-in-the-loop gates, retry/fallback logic
+    - Agent component map: agents, tool deps, memory components, external integrations
+    - Agent responsibility matrix: model, role, tools, inputs, outputs, failure behaviour
+    - Risk & observability note: hallucination hotspots, validation gates, logging points
+    - Tool overload flags (⚠️) for agents with more than 5 tools
+
+    Best for: multi-agent system design, LLM pipeline architecture,
+    AI product development, agentic workflow documentation.
+
+    Args:
+        pipeline_purpose: What the agent system does (e.g. "Research pipeline that
+                          searches the web and drafts a report").
+        agents: Agents in the pipeline and their roles (e.g. "Planner Agent
+                [claude-opus-4], Research Agent [claude-sonnet-4]").
+        tools_available: Tools agents can call (e.g. "web_search, execute_code") (optional).
+        orchestration_approach: How agents coordinate — sequential, DAG, hierarchical,
+                                parallel fan-out (optional).
+        memory_strategy: Memory approach — shared context, vector memory, Redis,
+                         none (optional).
+    """
+    config = load_config()
+    return await api_client.generate(
+        "umlforge_ai_agent",
+        {
+            "pipeline_purpose": pipeline_purpose,
+            "agents": agents,
+            "tools_available": tools_available,
+            "orchestration_approach": orchestration_approach,
+            "memory_strategy": memory_strategy,
+        },
+        guided_mode=config.guided_mode,
+    )
+
+
+# ── 12. Deployment ────────────────────────────────────────────────────────────
+
+@mcp.tool(annotations=_READ_ONLY)
+async def umlforge_deployment(
+    system_name: str,
+    cloud_provider: str,
+    environments: str,
+    services: str,
+    cicd_tool: str = "",
+) -> str:
+    """
+    Generate a deployment topology and CI/CD pipeline diagram.
+
+    Produces:
+    - Deployment diagram: nodes, artefacts, network paths with protocol/port labels,
+      internet-facing vs internal traffic distinction
+    - CI/CD pipeline flow: all stages from commit to production, automated gates,
+      manual approvals, rollback paths, environment promotion sequence
+    - Deployment environment table: infrastructure, triggers, data classification,
+      monitoring, rollback strategy per environment
+    - Infrastructure risk note: single points of failure, missing redundancy,
+      environment parity gaps
+    - Observability gap flags (⚠️) for services without /health endpoints
+
+    Best for: infrastructure provisioning, CI/CD pipeline design, cloud architecture
+    documentation, DevOps handover, disaster recovery planning.
+
+    Args:
+        system_name: Name of the system (e.g. "UML Forge API").
+        cloud_provider: Cloud provider(s) (e.g. "AWS", "Railway + Vercel", "GCP").
+        environments: Deployment environments (e.g. "development, staging, production").
+        services: Services and infrastructure to deploy (e.g. "FastAPI API, Next.js
+                  frontend, PostgreSQL, Redis").
+        cicd_tool: CI/CD pipeline tool (e.g. "GitHub Actions", "GitLab CI") (optional).
+    """
+    config = load_config()
+    return await api_client.generate(
+        "umlforge_deployment",
+        {
+            "system_name": system_name,
+            "cloud_provider": cloud_provider,
+            "environments": environments,
+            "services": services,
+            "cicd_tool": cicd_tool,
+        },
+        guided_mode=config.guided_mode,
+    )
+
+
+# ── 13. Suggest ───────────────────────────────────────────────────────────────
+
+@mcp.tool(annotations=_READ_ONLY)
+async def umlforge_suggest(task_description: str) -> str:
+    """
+    Recommend the best UML Forge tool for your task.
+
+    Given a plain-English description of what you want to diagram,
+    returns a ranked recommendation with reasoning and an alternative option.
+
+    Use this when you are not sure which of the 12 diagram tools fits
+    your task best.
+
+    Args:
+        task_description: Plain-English description of what you want to diagram
+                          (e.g. "I want to document the lifecycle of an order"
+                          or "I need to show how our auth service works").
+    """
+    return await api_client.suggest(task_description)

umlforge-0.1.0.dist-info/METADATA

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: umlforge
+Version: 0.1.0
+Summary: UML Forge MCP connector — AI-powered UML diagram generation for coding agents
+Project-URL: Homepage, https://umlforge.dev
+Project-URL: Documentation, https://umlforge.dev/docs
+License: Proprietary
+Keywords: ai,architecture,class-diagram,claude,cursor,diagram,mcp,sequence-diagram,uml
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: httpx<1.0.0,>=0.27.0
+Requires-Dist: mcp[cli]<2.0.0,>=1.27.0
+Requires-Dist: pydantic<3.0.0,>=2.7.0
+Description-Content-Type: text/markdown
+
+# UML Forge MCP Connector
+
+**AI-powered UML diagram generation for coding agents.**
+
+[UML Forge](https://umlforge.dev) gives Claude Code, Cursor, Windsurf, and any
+MCP-compatible coding agent a suite of 13 specialised tools for producing
+professional UML diagrams from your codebase, schema, or architecture
+descriptions.
+
+## Quick start
+
+**Claude Code:**
+```json
+{
+  "mcpServers": {
+    "umlforge": {
+      "command": "uvx",
+      "args": ["umlforge"],
+      "env": { "UMLFORGE_API_KEY": "your-api-key" }
+    }
+  }
+}
+```
+
+**Cursor / Windsurf** — add the same block to your MCP settings.
+
+Get your API key at [umlforge.dev](https://umlforge.dev).
+
+## Tools included
+
+| Tool | Description |
+|------|-------------|
+| `umlforge_reverse_engineer` | Class, sequence, and state diagrams from a codebase or GitHub URL |
+| `umlforge_api_sequence` | Sequence diagrams from OpenAPI / REST endpoints |
+| `umlforge_erd_schema` | Entity-relationship diagrams from SQL schema or ORM models |
+| `umlforge_state_machine` | State diagrams from business rules or UI flows |
+| `umlforge_frontend_components` | Component hierarchy and data-flow diagrams |
+| `umlforge_deployment` | Infrastructure and deployment diagrams |
+| `umlforge_threat_model` | STRIDE threat model + attack surface diagram |
+| `umlforge_event_driven` | Event flow and pub/sub architecture diagrams |
+| `umlforge_ai_agent` | Agent topology and tool-call flow diagrams |
+| `umlforge_stakeholder_arch` | C4 context diagrams for stakeholder communication |
+| `umlforge_living_docs` | Living documentation diagrams synced to code |
+| `umlforge_onboarding` | Onboarding maps for new team members |
+| `umlforge_suggest` | Recommends the best diagram type for a description |
+
+## Requirements
+
+- Python 3.11+
+- An API key from [umlforge.dev](https://umlforge.dev) (free tier available)
+
+## License
+
+Proprietary. The connector is open to install and use with a UML Forge account.

umlforge-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+connector/README.md,sha256=e6kNXkutToRooOHh2RSBnUqq2cooamYt9xQduLQw4XM,1926
+connector/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+connector/__main__.py,sha256=BKk-_KmGsvn0ZdXIV8YM6OBUSCah7jJ4ptugv4krIuQ,173
+connector/api_client.py,sha256=7U4mUdiumopcyuzMWpv--VdSbLTa3Gpff4yak690ZvY,4899
+connector/config.py,sha256=k4P_Kx8PyN4g1kcwp7xQXThfK_u-qvYyv8UjZwIP3-s,3034
+connector/requirements.txt,sha256=MXi1U11guMwxSXMeE7TWtuZp06OHU289K5vxGwGkdMY,670
+connector/server.py,sha256=sd3330HhQR2Ev4sVEyG_zwZo_6qst_pjuLR7gHE0Hsg,754
+connector/tools.py,sha256=csIFkmOCe2GB5tXhyglu85TIc_YuRf5g029cRmI_MpU,23350
+umlforge-0.1.0.dist-info/METADATA,sha256=UQfIhy5bo2-LW5fKMmiz0sLZ3XvkK30ybYGKqUhHUgc,2871
+umlforge-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+umlforge-0.1.0.dist-info/entry_points.txt,sha256=0zs7k8SNUjC7-XB_Mj89GR8VAkEQqrXbodhDkxbVqUA,53
+umlforge-0.1.0.dist-info/RECORD,,

umlforge-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

umlforge-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+umlforge = connector.__main__:main