# Clone the repository
git clone https://github.com/l4b4r4b4b4/bim2sim-mcp
cd bim2sim-mcp

# Install dependencies
uv sync

# Run the server (stdio mode for Claude Desktop)
uv run bim2sim-mcp

# Run the server (SSE/HTTP mode for deployment)
uv run bim2sim-mcp --transport sse --port 8000

# Run directly with uvx (no install needed)
uvx bim2sim-mcp stdio

# Or install globally
uv tool install bim2sim-mcp
bim2sim-mcp --help

# Pull and run from GHCR
docker pull ghcr.io/l4b4r4b4b4/bim2sim-mcp:latest
docker run -p 8000:8000 ghcr.io/l4b4r4b4b4/bim2sim-mcp:latest

# Or build locally with Docker Compose
docker compose up

# Build images manually
docker compose --profile build build base
docker compose build

{
  "mcpServers": {
    "bim2sim-mcp": {
      "command": "uv",
      "args": ["run", "bim2sim-mcp"],
      "cwd": "/path/to/bim2sim-mcp"
    }
  }
}

bim2sim-mcp/
├── app/                     # Application code
│   ├── __init__.py          # Version export
│   ├── server.py            # Main server with tools
│   ├── tools/               # Tool modules
│   └── __main__.py          # CLI entry point
├── tests/                   # Test suite
│   ├── conftest.py          # Pytest fixtures
│   └── test_server.py       # Server tests
├── docker/
│   ├── Dockerfile.base      # Python slim base image with dependencies
│   ├── Dockerfile           # Production image (extends base)
│   └── Dockerfile.dev       # Development with hot reload
├── .github/
│   └── workflows/
│       ├── ci.yml           # CI pipeline (lint, test, security)
│       ├── publish.yml      # PyPI trusted publisher
│       └── release.yml      # Docker build & publish to GHCR
├── .agent/                  # AI assistant workspace
│   └── goals/
│       └── 00-Template-Goal/  # Goal tracking template
├── pyproject.toml           # Project config
├── docker-compose.yml       # Local development & production
├── flake.nix                # Nix dev shell
└── .rules                   # AI assistant guidelines

# Install dependencies
uv sync

# Install pre-commit and pre-push hooks
uv run pre-commit install --install-hooks
uv run pre-commit install --hook-type pre-push

uv run pytest
uv run pytest --cov  # With coverage

uv run ruff check . --fix
uv run ruff format .

uv run mypy app/

# Run development container with hot reload
docker compose --profile dev up

# Build base image (for publishing)
docker compose --profile build build base

# Build all images
docker compose build

nix develop  # Enter dev shell with all tools

uvx bim2sim-mcp --help

Commands:
  stdio             Start server in stdio mode (for Claude Desktop and local CLI)
  sse               Start server in SSE mode (Server-Sent Events)
  streamable-http   Start server in streamable HTTP mode (recommended for remote/Docker)

# Examples:
uvx bim2sim-mcp stdio                          # Local CLI mode
uvx bim2sim-mcp sse --port 8000                # SSE on port 8000
uvx bim2sim-mcp streamable-http --host 0.0.0.0 # Docker/remote mode

┌─────────────────────────────────────────────────────────────┐
│  Feature Branch → Open PR                                   │
│         ↓                                                    │
│  CI Runs (lint, test, security)                            │
│         ↓                                                    │
│  ✅ CI Must Pass (enforced by branch protection)           │
│         ↓                                                    │
│  Merge to main                                              │
└─────────────────────────────────────────────────────────────┘
                         ↓
┌─────────────────────────────────────────────────────────────┐
│  CI Re-runs on main                                         │
│         ↓                                                    │
│  Release Workflow waits for CI Success                      │
│         ↓                                                    │
│  Docker Images Built & Pushed to GHCR                       │
└─────────────────────────────────────────────────────────────┘
                         ↓
┌─────────────────────────────────────────────────────────────┐
│  Manually Create GitHub Release                             │
│         ↓                                                    │
│  Publish Workflow verifies Release succeeded                │
│         ↓                                                    │
│  Package Published to PyPI                                  │
└─────────────────────────────────────────────────────────────┘
                         ↓
┌─────────────────────────────────────────────────────────────┐
│  CD Workflow deploys (staging/production)                   │
└─────────────────────────────────────────────────────────────┘