umlforge 0.1.0__tar.gz

umlforge-0.1.0/.claude/settings.json

@@ -0,0 +1,19 @@
+{
+  "permissions": {
+    "allow": [
+      "mcp__umlforge__umlforge_threat_model",
+      "mcp__umlforge__umlforge_suggest",
+      "mcp__umlforge__umlforge_reverse_engineer",
+      "mcp__umlforge__umlforge_stakeholder_arch",
+      "mcp__umlforge__umlforge_api_sequence",
+      "mcp__umlforge__umlforge_state_machine",
+      "mcp__umlforge__umlforge_erd_schema",
+      "mcp__umlforge__umlforge_frontend_components",
+      "mcp__umlforge__umlforge_event_driven",
+      "mcp__umlforge__umlforge_ai_agent",
+      "mcp__umlforge__umlforge_deployment",
+      "mcp__umlforge__umlforge_living_docs",
+      "mcp__umlforge__umlforge_onboarding"
+    ]
+  }
+}

umlforge-0.1.0/.env.example

@@ -0,0 +1,57 @@
+# UML Forge — Environment Variables
+# Copy this file to .env and fill in your values
+# NEVER commit .env to version control
+
+# ── LLM Provider ───────────────────────────────────────
+# Choose one provider. Default is Anthropic (claude-sonnet-4-6).
+LLM_PROVIDER=anthropic          # anthropic | openai | google | ollama
+LLM_MODEL=claude-sonnet-4-6     # model ID for the chosen provider
+
+# Anthropic (required when LLM_PROVIDER=anthropic)
+ANTHROPIC_API_KEY=sk-ant-...
+
+# OpenAI (required when LLM_PROVIDER=openai)
+# Models: gpt-4o | gpt-4o-mini | o1 | o1-mini | o3-mini
+# OPENAI_API_KEY=sk-...
+
+# Google Gemini (required when LLM_PROVIDER=google)
+# Models: gemini-2.0-flash | gemini-2.5-pro | gemini-1.5-flash
+# GOOGLE_API_KEY=AIza...
+
+# Ollama — local provider, no API key needed
+# Pull a model first: ollama pull llama3.2
+# Models: llama3.2 | mistral | codellama | qwen2.5-coder | phi4
+# LLM_PROVIDER=ollama
+# LLM_MODEL=llama3.2
+# OLLAMA_BASE_URL=http://localhost:11434   # change if Ollama runs on another host
+
+# ── Database (Neon PostgreSQL) ─────────────────────────
+# Use the POOLED connection string from Neon → Connection Details → Pooled.
+# IMPORTANT: asyncpg uses ?ssl=require — NOT ?sslmode=require (that's psycopg2 syntax).
+DATABASE_URL=postgresql+asyncpg://user:password@ep-xxx.pooler.neon.tech/neondb?ssl=require
+
+# ── Paystack ───────────────────────────────────────────
+PAYSTACK_SECRET_KEY=sk_live_...
+PAYSTACK_WEBHOOK_SECRET=your_webhook_secret_here
+
+# ── Security ───────────────────────────────────────────
+# Generate with: python -c "import secrets; print(secrets.token_hex(32))"
+API_SECRET_SALT=your_random_32_char_hex_string_here
+JWT_SECRET_KEY=your_random_32_char_hex_string_here
+
+# ── App Config ─────────────────────────────────────────
+ENVIRONMENT=development        # development | production
+API_VERSION=1.0.0
+DASHBOARD_URL=http://localhost:3000
+ALLOWED_ORIGINS=http://localhost:3000,http://localhost:5173
+
+# ── Email (Resend) ─────────────────────────────────────
+# Create account at resend.com — free tier: 3,000 emails/month, 100/day
+# Add and verify the umlforge.dev domain in Resend dashboard first.
+# Leave blank in development — verification links print to the console instead.
+RESEND_API_KEY=re_...
+RESEND_FROM_EMAIL=UML Forge <noreply@umlforge.dev>
+
+# ── Rate Limiting ──────────────────────────────────────
+FREE_TIER_MONTHLY_LIMIT=5
+ABUSE_RATE_LIMIT_PER_HOUR=100

umlforge-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,56 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  api-tests:
+    name: API tests (Python 3.12)
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install dependencies
+        run: |
+          pip install -r requirements.txt -r requirements-dev.txt
+
+      - name: Run tests
+        run: pytest tests/ -q --tb=short
+        env:
+          PYTHONPATH: ${{ github.workspace }}
+          DATABASE_URL: "sqlite+aiosqlite:///:memory:"
+          JWT_SECRET_KEY: "ci-test-secret-key-at-least-32-chars-long"
+          ANTHROPIC_API_KEY: "sk-ant-ci-placeholder"
+          ALLOWED_ORIGINS: "http://localhost:3000"
+          DASHBOARD_URL: "http://localhost:3000"
+
+  dashboard-typecheck:
+    name: Dashboard typecheck (Node 22)
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: dashboard
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: npm
+          cache-dependency-path: dashboard/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Type-check
+        run: npx tsc --noEmit

umlforge-0.1.0/.gitignore

@@ -0,0 +1,64 @@
+# UML Forge — Git Ignore
+
+# ── Environment & Secrets ──────────────────────────────
+.env
+.env.local
+.env.production
+*.pem
+*.key
+
+# ── Python ─────────────────────────────────────────────
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+.venv/
+venv/
+env/
+ENV/
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+
+# ── Testing & Coverage ─────────────────────────────────
+.pytest_cache/
+.coverage
+coverage.xml
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# ── Node / Dashboard ───────────────────────────────────
+node_modules/
+.next/
+out/
+dashboard/.env.local
+dashboard/.env.production
+
+# ── IDE ────────────────────────────────────────────────
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+
+# ── Logs ───────────────────────────────────────────────
+*.log
+logs/
+
+# ── Alembic ────────────────────────────────────────────
+# Keep alembic/versions/ tracked — migrations are version controlled
+
+# ── Internal Business Docs ─────────────────────────────
+# Strategy, roadmap, IP, and architecture docs — never public
+/docs/
+
+# ── Sample Diagram Outputs ─────────────────────────────
+# Generated during local testing — not project source
+diagram_*.mmd
+diagram_*.png
+diagram_*.svg
+umlforge_backup_*.txt

umlforge-0.1.0/.mcp.json

@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "umlforge": {
+      "command": "python",
+      "args": ["-m", "connector"],
+      "cwd": "${workspaceFolder}"
+    }
+  }
+}

umlforge-0.1.0/.railway/README.md

@@ -0,0 +1,98 @@
+# UML Forge — Railway Deployment
+
+## Required Environment Variables
+
+Set ALL of the following in the Railway dashboard before deploying.
+**Never commit secrets to the repository.**
+
+### Anthropic
+
+| Variable | Description | Example |
+|---|---|---|
+| `ANTHROPIC_API_KEY` | Anthropic API key for diagram generation | `sk-ant-api03-...` |
+
+### Database (Neon)
+
+| Variable | Description | Example |
+|---|---|---|
+| `DATABASE_URL` | **Pooled** Neon connection string — use the pooled endpoint for production | `postgresql+asyncpg://user:pass@ep-xxx.pooler.neon.tech/neondb?sslmode=require` |
+
+> ⚠️ Use the **pooled** connection string (endpoint contains `.pooler.neon.tech`), not
+> the direct connection. Railway containers spin up/down frequently; pooled connections
+> avoid exhausting Neon's connection limit.
+
+### Paystack Billing
+
+| Variable | Description | Example |
+|---|---|---|
+| `PAYSTACK_SECRET_KEY` | Live secret key from Paystack dashboard | `sk_live_...` |
+| `PAYSTACK_WEBHOOK_SECRET` | Webhook signature secret from Paystack | (random 32+ char string) |
+
+> After deploy, update the webhook URL in Paystack dashboard to:
+> `https://api.umlforge.dev/webhooks/paystack`
+
+### Security
+
+| Variable | Description | Example |
+|---|---|---|
+| `API_SECRET_SALT` | Random 32+ char string for key generation entropy | `openssl rand -hex 32` |
+| `JWT_SECRET_KEY` | Random 32+ char string for dashboard session tokens | `openssl rand -hex 32` |
+
+### Application
+
+| Variable | Description | Value |
+|---|---|---|
+| `ENVIRONMENT` | Must be `production` to lock down API docs + CORS | `production` |
+| `API_VERSION` | Shown in /health response | `1.0.0` |
+| `DASHBOARD_URL` | Used in email verification links and Paystack callback | `https://umlforge.dev` |
+| `ALLOWED_ORIGINS` | Comma-separated CORS origins | `https://umlforge.dev,https://www.umlforge.dev` |
+
+---
+
+## Deploy Steps
+
+```bash
+# 1. Install Railway CLI
+npm install -g @railway/cli
+
+# 2. Authenticate
+railway login
+
+# 3. Link to your Railway project
+railway link
+
+# 4. Deploy
+railway up
+
+# 5. Watch startup logs
+railway logs --follow
+```
+
+## Post-Deploy Verification
+
+```bash
+# Health check — must return {"status": "ok", "version": "1.0.0"}
+curl https://api.umlforge.dev/health
+
+# Docs must be disabled in production
+curl -s -o /dev/null -w "%{http_code}" https://api.umlforge.dev/docs
+# Expected: 404
+
+# Test webhook signature (should return 401 — tampered)
+curl -X POST https://api.umlforge.dev/webhooks/paystack \
+  -H "Content-Type: application/json" \
+  -d '{"event":"test"}' \
+  -w "\nHTTP %{http_code}\n"
+# Expected: 401
+```
+
+## Production Security Checklist
+
+- [ ] `ENVIRONMENT=production` — disables /docs, /redoc, /openapi.json
+- [ ] All secrets set as Railway env vars, none in code
+- [ ] `DATABASE_URL` uses Neon **pooled** connection string
+- [ ] `PAYSTACK_WEBHOOK_SECRET` matches value in Paystack dashboard
+- [ ] `ALLOWED_ORIGINS` contains only production dashboard domains
+- [ ] Paystack webhook URL updated to `https://api.umlforge.dev/webhooks/paystack`
+- [ ] `DASHBOARD_URL=https://umlforge.dev` (HTTPS, not localhost)
+- [ ] JWT and salt secrets are 32+ chars and randomly generated

umlforge-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,151 @@
+# UML Forge
+
+> AI-powered UML diagram generation inside your coding environment.
+> Exposes 12 specialised prompt tools as an MCP server — works natively
+> in Claude Code, Cursor, Windsurf, Cline, and Continue.dev.
+
+---
+
+## What It Does
+
+UML Forge generates professional, valid Mermaid diagrams directly inside
+your coding agent. Call a tool, get a diagram. No context switching,
+no diagramming tools, no stale documentation.
+
+**12 built-in tools:**
+- Reverse-engineer codebase to class/sequence diagrams
+- Stakeholder architecture (C4 + UML hybrid)
+- API and microservices sequence diagrams
+- State machine design for domain entities
+- Living documentation maintainer (sprint/PR workflow)
+- Database ERD and schema narrative
+- Security threat model with STRIDE analysis
+- Frontend component architecture
+- Event-driven and async system design
+- Team onboarding and knowledge transfer package
+- AI agent and orchestration pipeline design
+- Deployment and DevOps topology
+
+**Pro tier:** Socratic mode — the tool asks you 3–5 targeted clarifying
+questions before generating, producing significantly richer diagrams.
+
+---
+
+## Quick Start
+
+### 1. Get an API key
+
+Sign up at [umlforge.dev](https://umlforge.dev) — free tier, no credit card.
+
+### 2. Install the connector
+
+```bash
+pip install umlforge-connector
+```
+
+### 3. Configure
+
+```toml
+# ~/.umlforge/config.toml
+api_key = "uf_live_your_key_here"
+socratic_mode = false   # set true for Pro users
+```
+
+### 4. Add to your coding agent
+
+**Claude Code** (`.mcp.json`):
+```json
+{
+  "mcpServers": {
+    "umlforge": {
+      "command": "python",
+      "args": ["-m", "umlforge_connector"]
+    }
+  }
+}
+```
+
+**Cursor** (MCP Settings):
+```json
+{
+  "umlforge": {
+    "command": "python",
+    "args": ["-m", "umlforge_connector"]
+  }
+}
+```
+
+### 5. Generate your first diagram
+
+In your coding agent:
+```
+Generate a threat model for my FastAPI authentication service
+```
+
+---
+
+## Development Setup
+
+```bash
+# Clone
+git clone https://github.com/yourname/uml-forge
+cd uml-forge
+
+# Virtual environment
+python3.12 -m venv .venv
+source .venv/bin/activate
+
+# Install dependencies
+pip install -r requirements.txt
+pip install -r requirements-dev.txt
+
+# Configure environment
+cp .env.example .env
+# Edit .env with your keys
+
+# Run locally
+uvicorn api.main:app --reload --port 8000
+
+# Health check
+curl http://localhost:8000/health
+```
+
+---
+
+## Project Structure
+
+```
+uml-forge/
+├── api/                    # Hosted API (Railway) — PRIVATE
+│   ├── prompts/            # 12 prompt modules — never distributed
+│   ├── models/             # Pydantic input/output models
+│   ├── config.py           # Environment configuration
+│   ├── main.py             # FastAPI application
+│   ├── auth.py             # API key validation
+│   ├── db.py               # Database connection
+│   └── ...
+├── connector/              # Thin MCP connector — PUBLIC
+│   ├── server.py           # FastMCP stdio server
+│   └── tools.py            # 13 MCP tool definitions
+├── infra/db/               # Database schema
+├── railway.toml            # Production deployment config
+└── requirements.txt        # Pinned, verified dependencies
+```
+
+---
+
+## Tech Stack
+
+- **Python 3.12** | **FastAPI 0.136** | **Pydantic v2**
+- **SQLAlchemy 2.0 async** + **asyncpg** + **Alembic**
+- **Neon** (serverless PostgreSQL)
+- **MCP SDK 1.27** (FastMCP built-in)
+- **Anthropic claude-sonnet-4-6**
+- **Paystack** (billing) | **Vercel** (dashboard)
+
+---
+
+## License
+
+Proprietary. All prompt engineering and server-side logic is closed source.
+The MCP connector (`connector/`) is MIT licensed.

umlforge-0.1.0/alembic/README

@@ -0,0 +1 @@
+Generic single-database configuration.

umlforge-0.1.0/alembic/env.py

@@ -0,0 +1,85 @@
+# alembic/env.py
+"""
+UML Forge — Alembic Migration Environment
+Configured for async SQLAlchemy 2.0 + asyncpg + Neon PostgreSQL.
+"""
+
+import asyncio
+from logging.config import fileConfig
+
+from sqlalchemy import pool
+from sqlalchemy.engine import Connection
+from sqlalchemy.ext.asyncio import async_engine_from_config
+
+from alembic import context
+
+# ── Load app config ───────────────────────────────────────────────────────────
+# Import Base and all models so Alembic can detect schema changes
+from api.db import Base
+import api.models.orm  # noqa: F401 — registers all models with Base.metadata
+
+# ── Alembic config ────────────────────────────────────────────────────────────
+config = context.config
+
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+target_metadata = Base.metadata
+
+
+def get_url() -> str:
+    """Load DATABASE_URL from environment via app settings."""
+    from api.config import get_settings
+    return get_settings().database_url
+
+
+# ── Offline migrations (generate SQL scripts) ─────────────────────────────────
+def run_migrations_offline() -> None:
+    url = get_url()
+    context.configure(
+        url=url,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+        compare_type=True,
+    )
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+# ── Online migrations (run against live DB) ───────────────────────────────────
+def do_run_migrations(connection: Connection) -> None:
+    context.configure(
+        connection=connection,
+        target_metadata=target_metadata,
+        compare_type=True,
+    )
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+async def run_async_migrations() -> None:
+    configuration = config.get_section(config.config_ini_section, {})
+    configuration["sqlalchemy.url"] = get_url()
+
+    connectable = async_engine_from_config(
+        configuration,
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,    # NullPool for migrations — no connection reuse
+        connect_args={"ssl": "require"},  # Neon requires SSL; asyncpg uses 'ssl' not 'sslmode'
+    )
+
+    async with connectable.connect() as connection:
+        await connection.run_sync(do_run_migrations)
+
+    await connectable.dispose()
+
+
+def run_migrations_online() -> None:
+    asyncio.run(run_async_migrations())
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

umlforge-0.1.0/alembic/script.py.mako

@@ -0,0 +1,28 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+${imports if imports else ""}
+
+# revision identifiers, used by Alembic.
+revision: str = ${repr(up_revision)}
+down_revision: Union[str, Sequence[str], None] = ${repr(down_revision)}
+branch_labels: Union[str, Sequence[str], None] = ${repr(branch_labels)}
+depends_on: Union[str, Sequence[str], None] = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+    ${downgrades if downgrades else "pass"}