Architecture

HTS MCP is a monolithic Python application with three interface adapters sharing a common core.

System Overview


┌──────────────────────────────────────────────────────────┐
│                     Interface Layer                      │
│                                                          │
│  ┌──────────────┐  ┌──────────────┐  ┌────────────────┐  │
│  │  MCP Server  │  │  REST API    │  │  CLI (Click)   │  │
│  │  (FastMCP)   │  │  (FastAPI)   │  │                │  │
│  └──────┬───────┘  └──────┬───────┘  └───────┬────────┘  │
│         │                 │                  │           │
│         └─────────────────┼──────────────────┘           │
│                           │                              │
├───────────────────────────┼──────────────────────────────┤
│                     Core Layer                           │
│                           │                              │
│  ┌────────────┐  ┌────────┴───────┐  ┌────────────────┐  │
│  │   Search   │  │   Enrichment   │  │    Graph       │  │
│  │   Engine   │  │   Pipeline     │  │   Pipeline     │  │
│  └──────┬─────┘  └───────┬────────┘  └──────┬─────────┘  │
│         │                │                  │            │
│  ┌──────┴────────────────┴──────────────────┴─────────┐  │
│  │              Database Layer (psycopg2)             │  │
│  │              Connection Pool (2-10)                │  │
│  └────────────────────────┬───────────────────────────┘  │
│                           │                              │
├───────────────────────────┼──────────────────────────────┤
│                     External Services                    │
│                           │                              │
│  ┌────────────────────────┼───────────────────────────┐  │
│  │    PostgreSQL          │      OpenAI API           │  │
│  │    + pgvector          │      (embeddings + LLM)   │  │
│  └────────────────────────┴───────────────────────────┘  │
└──────────────────────────────────────────────────────────┘

Interface Adapters

All three adapters call the same underlying core functions:

Adapter	Protocol	Framework	Entry Point
MCP	stdio (Model Context Protocol)	FastMCP	`src/hts/mcp/server.py`
REST	HTTP/JSON	FastAPI	`src/hts/api/`
CLI	Terminal	Click	`src/hts/cli/__main__.py`

Core Components

Component	Purpose	Key Files
Search Engine	Hybrid semantic/lexical search	`core/search/engine.py`
Enrichment Pipeline	AI descriptions and embeddings	`core/enrichment/`
Semantic Graph	Relationship classification	`core/graph/`
Database	PostgreSQL with pgvector	`core/db/`

Data Flow

Query Path (Read)


User Query → Interface Adapter → Search Engine → pgvector → Results

Pipeline Path (Write)


Source Data → Loader → Bronze Table → Enricher → Embeddings → KNN → Classifier → Graph

Technology Stack

Layer	Technology
Language	Python 3.11+
Package manager	uv
MCP framework	FastMCP
REST framework	FastAPI + Uvicorn
CLI framework	Click
Database	PostgreSQL + pgvector
Embeddings	OpenAI text-embedding-3-small (1536D)
LLM	GPT-5.4 Nano (enrichment + classification)
Hosting	Supabase (PostgreSQL), any Python host (MCP/API/CLI)