Skip to content

Repository navigation

v2.0.0 — The Hybrid Engine

Choose a tag to compare

View all tags
@freebuff-web freebuff-web released this 14 Jul 10:26
· 19 commits to main since this release
v2.0.0
a37a9c7

🚀 v2.0.0 — The Hybrid Engine

Project Tango is now a production-grade MCP server powered by a three-pillar hybrid architecture: SQLite persistence, prefix-trie instant search, and a reactive event broker with saga rollback.

Previous release: v1.0.0

🏗️ Architecture

┌───────────────────────────────────┐
│     Client (Claude / LLM)         │
└──────────────┬────────────────────┘
               │  MCP Protocol (stdio)
               ▼
┌───────────────────────────────────┐
│    Project Tango MCP Server       │
└──────────────┬────────────────────┘
               │
    ┌──────────┴──────────┐
    ▼ (Atomic Writes)     ▼ (Read Cache)
┌─────────────────┐  ┌─────────────────┐
│    SQLite DB    │──►│  Prefix Trie    │
│  (Single Source)│  │ (O(k) Search)   │
└─────────────────┘  └─────────────────┘
    │                       │
    └────── Event Broker ───┘
          (Real-time Subs)

Three Pillars

1. 🗄️ SQLite Persistence (src/database.ts)

  • Full relational schema: products, orders, order_items with foreign keys
  • WAL mode for concurrent reads, journaled writes for crash safety
  • Parameterized queries — zero SQL injection risk
  • DataProvider interface implemented against SQLite: all 6 provider methods

2. ⚡ Prefix Trie Search (src/trie.ts)

  • In-memory Trie indexing every token from product names, SKUs, categories, and tags
  • Search in O(k) where k = query length (not O(n) like a linear scan)
  • Prefix matching, wildcard support, relevance scoring
  • Fully atomic index rebuild on server start — always in sync with SQLite

3. 🔄 Reactive Event Broker & Saga Rollback (src/engine.ts)

  • Event bus emits typed events (product:updated, order:placed, inventory:changed)
  • Subscribers push notifications/resources/updated to the MCP client in real time
  • Saga rollback: on any mid-transaction failure, the engine restores the before-state — no partial mutations, no corrupted data

🛠️ 7 MCP Tools

Tool Description
list_all_products Browse/search catalog with category & price filtering
search_products 🆕 New! Trie-powered instant prefix search — returns results in <1ms
get_low_stock_alerts Scan inventory for low/critical stock levels
analyze_sales_metrics Gross revenue, AOV, top sellers, order-status breakdown
smart_restock_predictor Recommends reorder quantities from demand velocity
draft_product_copy Generates marketing copy + SEO tags for a SKU
simulate_order_placement Places a simulated order with stock validation

🔒 All Fixes & Hardening (v1.0.0 → v2.0.0)

Critical

  • ✅ addOrder now clones before storing — prevents caller mutation of internal state
  • ✅ .convex/ secrets removed from tracking — adminKey and instanceSecret no longer at risk
  • ✅ prod_006 data inconsistency fixed — stock 1→3, order qty 2→1 to reflect available inventory

High

  • ✅ Order IDs use crypto.randomUUID() — unique even at sub-millisecond concurrency
  • ✅ Saga rollback on order failure — inventory restore, cache rebuild, structured telemetry

Medium

  • ✅ Input validation bounds added — .max() on all string parameters (category, sku, customer_name, product_id)
  • ✅ Error boundaries — withSanitizedErrors wrapper on all 7 tool handlers, no stack leaks
  • ✅ npm test script added — run npm test to execute the 38-check integration suite
  • ✅ .gitignore updated — node_modules/, .env*, .convex/ all protected
  • ✅ Unused imports & dead code removed from integration test

Low

  • ✅ formatZodIssues — human-readable validation error output (not raw JSON)
  • ✅ Stale JSDoc corrected (“four methods” → “6 methods”)
  • ✅ .prettierrc added — project-wide formatting config
  • ✅ as TReturn cast documented with safety notes

📁 File Structure

project-tango/
├── src/
│   ├── index.ts          # MCP server entry — 7 tools + reactive broker
│   ├── types.ts          # Shared TypeScript interfaces
│   ├── trie.ts           # Prefix trie data structure
│   ├── database.ts       # SQLite connection, schema, queries, seed
│   ├── engine.ts         # Hybrid engine (SQLite + Trie + Events + Saga)
│   ├── mcpHelpers.ts     # withSanitizedErrors, formatZodIssues
│   └── mockData.ts       # In-memory DataProvider (legacy)
├── test/
│   └── integration.test.ts  # 38-check MCP integration test
├── .prettierrc
├── .gitignore
├── package.json
├── tsconfig.json
└── README.md

📊 Performance

Operation v1.0.0 (in-memory) v2.0.0 (hybrid)
Product search (13 products) O(n) scan O(k) trie lookup
Order placement In-memory only Durable + atomic via SQLite WAL
Read isolation Clone on read Clone on read + primary source in SQLite
Crash recovery Lost on restart Full recovery from disk
Concurrent safety Module-level mutex Mutex + saga rollback

🚀 Getting Started

npm install
npm start        # Launch MCP server over stdio
npm test         # Run 38-check integration suite
npm run build    # Compile to dist/
npm run inspect  # Debug with MCP Inspector

No env vars required — runs entirely locally with SQLite.

Release prepared by the v2.0.0 hardening audit and full architectural rewrite.

Assets 2
Loading