flowchart TB
    subgraph source [Source]
        GitHub[GitHub Repo] --> GitClone[GitPython Shallow Clone]
        ReposYml[repos.yml] --> GitClone
    end

    subgraph parse [Parse & Ontology]
        GitClone --> JavaParser[javalang Java Parser]
        JavaParser --> ClassDocs[class / method / endpoint docs]
        JavaParser --> FlowBuilder[Flow Ontology Builder]
        FlowBuilder --> FlowDocs[flow docs + Mermaid]
        FlowBuilder --> GraphEdges[callsOut / calledBy edges]
    end

    subgraph solr [Solr 9]
        ClassDocs --> RawCol[product-raw collection]
        FlowDocs --> RawCol
        GraphEdges --> RawCol
        RawCol --> Embed[Local Embeddings bge-small-en-v1.5]
        Embed --> RAGCol[product-rag collection]
    end

    subgraph serve [Serving]
        RAGCol --> Retrieval[Hybrid Retrieval BM25 + kNN + RRF]
        Retrieval --> Intent[Intent Classifier]
        Intent --> MCP[FastMCP Server]
        MCP --> Client[Cursor / Claude / any MCP client]
    end

┌─────────────────────────────────────────────────────────────────────┐
│                     AI IDE (MCP Client)                             │
│              Cursor / Claude Desktop / VS Code                      │
└──────────────────────────┬──────────────────────────────────────────┘
                           │  HTTP (streamable-http) or stdio
┌──────────────────────────▼──────────────────────────────────────────┐
│                  MCP Server (ontology-rag serve)                  │
│                    10 tools · FastMCP + Python                      │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────────┐  │
│  │  Retriever   │  │  Intent      │  │  LLM Client (optional)   │  │
│  │  BM25+kNN    │  │  Classifier  │  │  OpenAI-compatible       │  │
│  └──────┬───────┘  └──────────────┘  └──────────────────────────┘  │
└─────────┼───────────────────────────────────────────────────────────┘
          │
┌─────────▼───────────────────────────────────────────────────────────┐
│                    Apache Solr 9.x                                  │
│  ┌─────────────────────┐    ┌─────────────────────────────────┐    │
│  │  {product}-raw      │───▶│  {product}-rag                  │    │
│  │  (source of truth)  │    │  (+ 384-dim embedding vectors)  │    │
│  └─────────────────────┘    └─────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────────┘

sequenceDiagram
    participant Agent as Cursor Agent
    participant Jenkins as Jenkins MCP
    participant Platform as ontology-rag-mcp
    participant GitHub as GitHub MCP
    participant SSH as Linux SSH MCP
    participant Target as Target Linux Host

    Agent->>Jenkins: trigger ontology-rag-onboard
    Note over Jenkins: Params: REPOS, BRANCH, PRODUCT, TARGET_HOST

    Jenkins->>Platform: checkout-platform
    Platform->>GitHub: fetch source + record commit SHA
    GitHub-->>Platform: file tree + metadata

    Platform->>Platform: parse + index + build flow ontology
    Platform->>Platform: embed into Solr

    Jenkins->>SSH: deploy-mcp to TARGET_HOST
    SSH->>Target: sync code, create venv, start MCP on free port
    SSH->>Target: health-check + tail logs

    Jenkins-->>Agent: {"petclinic-ontology": {"url": "http://host:port/mcp"}}

# 1. Clone and configure
cd C:\AI_Workspaces\Anti_Workspace\ontology-rag-mcp
copy .env.example .env

# 2. Start Solr + MCP server
docker compose up -d

# 3. Wait for Solr to be healthy (~30s), then ingest the sample repo
docker compose exec app ontology-rag ingest

# 4. One-shot RAG query
docker compose exec app ontology-rag ask "What REST endpoints does this expose?"

# 5. MCP server is already running — check startup logs for mcp.json snippet
docker compose logs app

=== Ingesting petclinic ===
Cloning https://github.com/spring-projects/spring-petclinic (branch=main)
Indexing 150+ documents into petclinic-raw
Embedding 150+ documents
Ingest complete: {'repos': 1, 'files': 80, 'docs': 150, 'embedded': 150}

cd C:\AI_Workspaces\Anti_Workspace\ontology-rag-mcp

# Create virtual environment
python -m venv .venv
.venv\Scripts\Activate.ps1

# Install
pip install -e ".[dev]"

# Copy config
copy .env.example .env

# Start Solr separately (or use docker compose up solr -d)
docker compose up solr -d

# Ingest
ontology-rag ingest

# Start MCP server
ontology-rag serve

{
  "ontology-rag": {
    "url": "http://localhost:8765/mcp"
  }
}

{
  "mcpServers": {
    "ontology-rag": {
      "url": "http://localhost:8765/mcp"
    }
  }
}

{
  "mcpServers": {
    "ontology-rag": {
      "command": "ontology-rag",
      "args": ["serve"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "SOLR_BASE_URL": "http://localhost:8983/solr",
        "RAG_PRODUCT": "petclinic"
      }
    }
  }
}

{
  "mcpServers": {
    "ontology-rag": {
      "url": "http://localhost:8765/mcp"
    }
  }
}

{
  "mcpServers": {
    "ontology-rag": {
      "command": "ontology-rag",
      "args": ["serve"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "SOLR_BASE_URL": "http://localhost:8983/solr",
        "RAG_PRODUCT": "petclinic"
      }
    }
  }
}

{
  "mcpServers": {
    "ontology-rag": {
      "url": "http://localhost:8765/mcp"
    }
  }
}

repos.yml / CLI --repos
        │
        ▼
┌───────────────────┐
│  Source Provider  │  SOURCE_PROVIDER=local → GitPython shallow clone
│                   │  SOURCE_PROVIDER=github → GitHub MCP (falls back to git)
└────────┬──────────┘
         │  Records commit SHA for incremental re-runs
         ▼
┌───────────────────┐
│  File Curation    │  Skips: target/, build/, .git/, node_modules/,
│                   │  *.class, *.jar, /test/, generated-sources/
└────────┬──────────┘
         ▼
┌───────────────────┐
│  Java Parser      │  javalang → class-level docs (+ optional method chunks)
│  (javalang)       │  Also: application.yml, README, OpenAPI specs
└────────┬──────────┘
         ▼
┌───────────────────┐
│  Flow Ontology    │  Endpoint extraction, call graph, flow docs + Mermaid
│  Builder          │  Cross-service: @FeignClient, RestTemplate, WebClient
└────────┬──────────┘
         ▼
┌───────────────────┐
│  Solr Raw Index   │  {product}-raw — source of truth, no vectors
└────────┬──────────┘
         ▼
┌───────────────────┐
│  Embed Pipeline   │  BAAI/bge-small-en-v1.5 → {product}-rag collection
│                   │  Optional LLM summaries if LLM_ENABLED=true
└───────────────────┘

1. [controller] com.example.OrderController#createOrder
2. [service]    com.example.OrderService#createOrder
3. [repository] com.example.OrderRepository#save

sequenceDiagram
    participant Client
    participant OrderController as OrderController
    participant OrderService as OrderService
    participant OrderRepository as OrderRepository
    Client->>OrderController: POST /api/orders
    OrderController->>OrderService: createOrder
    OrderService->>OrderRepository: save

User query
    │
    ▼
┌─────────────────────┐
│  Intent Classifier  │  regex-based (no LLM): flow / endpoint / class / config / default
└────────┬────────────┘
         ▼
┌─────────────────────┐     ┌─────────────────────┐
│  Solr BM25 (edismax)│     │  Solr kNN (384-dim) │
│  field boosts per   │     │  cosine similarity  │
│  intent profile     │     │                     │
└────────┬────────────┘     └────────┬────────────┘
         │                           │
         └───────────┬───────────────┘
                     ▼
         ┌───────────────────────┐
         │  RRF Fusion           │
         └───────────┬───────────┘
                     ▼
         ┌───────────────────────┐
         │  Quality Levers       │
         │  · down-rank getters│
         │  · MMR diversity    │
         │  · adaptive rerank  │
         │  · flow-doc seeding │
         │  · call-graph fusion│
         └───────────┬───────────┘
                     ▼
              Shaped results with citations
              (file path + line range + FQN)

ontology-rag ingest [--repos URL1,URL2] [--branch main]
ontology-rag serve
ontology-rag ask "your question here"

# Ingest a specific repo
ontology-rag ingest --repos https://github.com/spring-projects/spring-petclinic --branch main

# Ingest multiple repos (microservices)
ontology-rag ingest --repos https://github.com/org/order-service,https://github.com/org/payment-service

# Ask a flow question
ontology-rag ask "Walk me through what happens when a user creates an order"

# Ask about cross-service calls
ontology-rag ask "Which service calls the payment service?"

"Explain the OrderService class"
"How is authentication configured?"
"walk me through what happens when a user places an order"

find_rest_endpoints()
find_rest_endpoints(http_method="POST")
find_rest_endpoints(path_contains="/orders")

flow_of("/api/orders")
flow_of("OrderController")
flow_of("POST /api/orders")

callers_of("PaymentService")
callers_of("OrderService#createOrder")

uses_of("OrderController")
uses_of("PaymentService#processPayment")

┌─────────────────────────────────────────────────────────────┐
│                    ontology-rag-mcp CORE                    │
│         (always works: git + docker compose + CLI)          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────┐  ┌──────────────┐  ┌───────────────────┐  │
│  │  SOURCE     │  │ ORCHESTRATOR │  │  DEPLOY           │  │
│  │  PROVIDER   │  │              │  │  PROVIDER         │  │
│  ├─────────────┤  ├──────────────┤  ├───────────────────┤  │
│  │ local (git) │  │ local (CLI)  │  │ docker (compose)  │  │
│  │ github (MCP)│  │ jenkins (MCP)│  │ ssh (MCP)         │  │
│  └─────────────┘  └──────────────┘  └───────────────────┘  │
│       ↓ optional       ↓ optional        ↓ optional        │
│   GitHub MCP       Jenkins MCP       Linux SSH MCP         │
└─────────────────────────────────────────────────────────────┘

repos:
  - url: https://github.com/spring-projects/spring-petclinic
    branch: main
    name: petclinic

  - url: https://github.com/your-org/order-service
    branch: main
    name: orders
    subpath: order-service    # optional: index only this subdirectory

  - url: https://github.com/your-org/payment-service
    branch: develop
    name: payments

What REST endpoints does this expose?

Walk me through what happens when a user creates an order.

Which service calls the payment service?

Explain the OrderService class.

What database is configured in application.yml?

ontology-rag-mcp/
├── ontology_core/              # Config, Solr client, embeddings, retrieval, intent, MCP server, CLI
│   ├── config.py               # Pydantic settings from env vars
│   ├── models.py               # Shared DTOs (SearchHit, FlowResult, etc.)
│   ├── embeddings.py           # Local sentence-transformers embedder
│   ├── intent.py               # Offline regex intent classifier
│   ├── retrieval.py            # Hybrid BM25 + kNN + RRF + flow-aware fusion
│   ├── llm.py                  # Optional OpenAI-compatible LLM client
│   ├── mcp_server.py           # FastMCP server + 10 tools
│   ├── cli.py                  # ontology-rag CLI (ingest / serve / ask)
│   └── solr/
│       ├── client.py           # Solr 9 REST client
│       └── managed-schema.xml  # Collection schema
├── ontology_ingest/            # Source providers, parser, flow ontology, pipeline
│   ├── source/
│   │   ├── base.py             # SourceProvider interface + factory
│   │   ├── local_git.py        # GitPython shallow clone (default)
│   │   └── github_mcp.py       # Optional GitHub MCP adapter
│   ├── parser/
│   │   ├── java_parser.py      # javalang Java/Spring parser
│   │   └── spring_annotations.py
│   ├── ontology/
│   │   └── flow_builder.py     # REST flow tracing + call graph
│   ├── chunker.py              # Parsed artifacts → Solr docs
│   ├── pipeline.py             # End-to-end ingest orchestrator
│   └── embed_pipeline.py       # Raw → serving collection with vectors
├── ontology_deploy/            # Deploy providers + Jenkins orchestrator
│   ├── base.py                 # DeployProvider interface
│   ├── docker_provider.py      # docker compose (default)
│   ├── ssh_provider.py         # Optional Linux SSH MCP adapter
│   └── jenkins_orchestrator.py # Optional Jenkins MCP adapter
├── docker-compose.yml          # Solr 9.6 + app
├── Dockerfile
├── repos.yml                   # Default repos to ingest
├── Jenkinsfile                 # CI/CD pipeline for headless deploy
├── .env.example                # All env vars documented
├── pyproject.toml
├── tests/
│   ├── test_java_parser.py
│   ├── test_spring_annotations.py
│   ├── test_flow_builder.py
│   └── test_intent.py
└── README.md

# Install with dev dependencies
pip install -e ".[dev]"

# Run unit tests
pytest tests/ -v

# Lint
ruff check .

# Ingest a repo
ontology-rag ingest --repos https://github.com/spring-projects/spring-petclinic

# Start MCP server
ontology-rag serve

# One-shot query
ontology-rag ask "What REST endpoints does this expose?"

# Check Solr health
curl http://localhost:8983/solr/admin/info/system

# Restart Solr container
docker compose restart solr

# Wait for healthy status
docker compose ps

python -c "from sentence_transformers import SentenceTransformer; SentenceTransformer('BAAI/bge-small-en-v1.5')"

GITHUB_TOKEN=ghp_your_token_here