Kontexo

Production-grade, multi-tenant SaaS platform that orchestrates cross-service workflows through an Agentic MCP (Model Context Protocol) Gateway.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│  FRONTEND — Next.js 14                                          │
│  DAG Editor · HITL Modal · Live Preview · Chat · State Graph    │
└────────────────────────────┬────────────────────────────────────┘
                             │ REST + SSE
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│  API GATEWAY — FastAPI                                           │
│  Firebase Auth · Rate Limit · Tenant Isolation · Audit           │
└────────────────────────────┬────────────────────────────────────┘
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│  LANGGRAPH AGENT PIPELINE                                        │
│  Classifier → Planner → Critic → HITL Gate → Executor →         │
│  Monitor → Synthesizer · RAG Retriever · RAG Responder           │
└────────────────────────────┬────────────────────────────────────┘
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│  MCP-GUARD SECURITY PROXY                                        │
│  SHA-256 hash · injection scan · param enforce · approval gate   │
└────────────────────────────┬────────────────────────────────────┘
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│  CUSTOM MCP SERVER — JSON-RPC 2.0 (stdio / SSE)                 │
│  GitHub (7) · Slack (3) · Sheets (3) · Trello (6) tools         │
└─────────────────────────────────────────────────────────────────┘

Key Features

Feature	Description
Custom MCP Server	JSON-RPC 2.0 protocol from scratch — 19 tools across 4 services
LangGraph State Machine	10-node graph with conditional routing, parallel execution
HITL DAG Editing	Pause, edit nodes/edges, resume from dirty set (no restart)
Live Platform Previews	SSE-streamed UI previews before tool execution
RAG Chatbot	ChromaDB vector search over executions, context-aware responses
Concurrency Runtime	Celery + Redis for 5+ simultaneous tenant workflows
Code Analysis	18 languages, 6 categories (bug, security, perf, quality, arch, CI/CD)
State Graph Visualization	Full LangGraph topology with active node overlays

Project Structure

kontexo-v2/
├── kontexo_mcp_server/           # Custom MCP server (Phase 1)
│   ├── protocol.py               # JSON-RPC 2.0 types + codec
│   ├── server.py                 # MCP request router
│   ├── registry.py               # Tool/resource/prompt registry
│   ├── client.py                 # MCP client for remote servers
│   ├── transport/                # stdio + SSE transports
│   ├── tools/                    # GitHub, Slack, Sheets, Trello tools
│   ├── resources/                # MCP resource providers
│   └── prompts/                  # MCP prompt templates
│
├── backend/
│   ├── app/
│   │   ├── agents/               # LangGraph nodes (Phase 2)
│   │   │   ├── state.py          # KontexoState TypedDict (33+ fields)
│   │   │   ├── graph.py          # 10-node state machine
│   │   │   ├── code_analyzer.py  # Multi-category static + LLM analysis
│   │   │   ├── fix_proposer.py   # PR/issue/Slack/Sheets proposals
│   │   │   └── language_detector.py  # 18-language detection
│   │   │
│   │   ├── concurrency/          # Celery + Redis (Phase 3)
│   │   │   ├── celery_app.py     # Celery config (Redis broker)
│   │   │   ├── redis_conn.py     # Sync + async Redis with pooling
│   │   │   ├── rate_limiter.py   # Per-tenant rate limiting
│   │   │   ├── sse_manager.py    # Redis pub/sub → SSE fan-out
│   │   │   └── tasks.py          # Async workflow/node tasks
│   │   │
│   │   ├── rag/                  # RAG engine (Phase 4)
│   │   │   ├── embedder.py       # ChromaDB client + tenant collections
│   │   │   ├── retriever.py      # Vector similarity search
│   │   │   └── indexer.py        # Document indexing pipeline
│   │   │
│   │   ├── mcp/                  # MCP integration (Phase 5)
│   │   │   ├── guard.py          # MCPGuard approval gating
│   │   │   └── preview_emitter.py  # PreviewEvent + service builders
│   │   │
│   │   ├── routers/              # FastAPI endpoints (Phase 6-8)
│   │   │   ├── executions.py     # HITL edit + DAG introspection
│   │   │   ├── chat.py           # RAG chatbot
│   │   │   ├── code_analysis.py  # Code analysis endpoints
│   │   │   └── state_graph.py    # State graph visualization
│   │   │
│   │   ├── llm/                  # LLM router
│   │   │   └── router.py         # Gemini Flash → Groq failover
│   │   │
│   │   └── models/               # Pydantic models
│   │       └── dag.py            # DAG, Node, Edge, AnalysisFinding
│   │
│   └── tests/                    # 618 tests
│
├── docker-compose.yml            # Redis, Celery, Chroma, Backend, MCP
├── .env.example                  # All environment variables
└── README.md

Tech Stack

Layer	Technology
Backend	Python 3.13, FastAPI, Pydantic 2
Agent Framework	LangGraph 1.1, LangChain Core 1.2
LLM	Gemini Flash (primary, env-configurable) → Groq (failover, key rotation)
Task Queue	Celery 5.6 + Redis 7
Vector Store	ChromaDB 1.5 (all-MiniLM-L6-v2 embeddings)
Graph Library	NetworkX 3.6 (DAG validation, cycle detection)
HTTP Client	httpx 0.28 (async, 30s/120s timeouts)
Frontend	Next.js 14, React 18, ReactFlow 11, Zustand, Firebase JS SDK, Tailwind CSS
Auth	Firebase Auth (Google + GitHub OAuth via signInWithPopup)
Protocol	JSON-RPC 2.0 (custom implementation, no SDK)

Quick Start

Prerequisites

• Python 3.12+
• Docker & Docker Compose
• Redis (or use Docker)

Development (local)

# Clone and setup
cd kontexo-v2
python -m venv venv
source venv/bin/activate
pip install -r backend/requirements.txt

# Configure environment
cp .env.example .env
# Edit .env with your API keys (GEMINI_API_KEY required)

# Start Redis (if not using Docker)
redis-server &

# Run tests
python -m pytest backend/tests/ kontexo_mcp_server/tests/ -v

# Start backend
uvicorn backend.app.main:app --host 0.0.0.0 --port 8080 --reload

# Start Celery worker (separate terminal)
celery -A backend.app.concurrency.celery_app worker --loglevel=info --queues=default,workflows

# Start frontend (separate terminal)
cd frontend && npm install && npm run dev
# Frontend: http://localhost:3000
# Login via Google or GitHub on the frontend

Docker Compose (production)

cp .env.example .env
# Edit .env with API keys

docker compose up -d

# Services:
#   Backend:  http://localhost:8080
#   MCP SSE:  http://localhost:8090
#   Redis:    localhost:6379
#   ChromaDB: http://localhost:8000

MCP Server

Custom JSON-RPC 2.0 implementation with 19 tools:

Service	Tools	Approval Required
GitHub	create_issue, create_pull_request, add_comment, list_issues, get_issue, list_repos, search_code	Write ops: Yes
Slack	send_message, list_channels, get_channel_history	send_message: Yes
Google Sheets	append_row, read_range, create_spreadsheet	Write ops: Yes
Trello	create_card, move_card, add_checklist, list_boards, list_cards, archive_card	Write ops: Yes

Transports: stdio (local) or SSE (remote HTTP)

LangGraph Pipeline

10-node state machine with conditional routing:

                    ┌──────────────┐
                    │  classifier  │
                    └──────┬───────┘
                    ┌──────┴───────┐
              ┌─────┤   planner    ├─────┐
              │     └──────────────┘     │
              ▼                          ▼
       ┌────────────┐           ┌───────────────┐
       │   critic   │           │ rag_retriever │
       └──────┬─────┘           └───────┬───────┘
              │                         ▼
       ┌──────┴─────┐           ┌───────────────┐
       │ replanner  │           │ rag_responder │
       └──────┬─────┘           └───────────────┘
              ▼
       ┌────────────┐
       │ hitl_gate  │
       └──────┬─────┘
              ▼
       ┌────────────┐
       │  executor  │
       └──────┬─────┘
              ▼
       ┌────────────┐
       │  monitor   │
       └──────┬─────┘
              ▼
       ┌─────────────┐
       │ synthesizer │
       └─────────────┘

Code Analysis Engine

Supports 18 programming languages across 6 analysis categories:

Languages: Python, JavaScript, TypeScript, Java, Go, Rust, C, C++, C#, PHP, Ruby, Kotlin, Swift, SQL, Bash, YAML, Dockerfile, Terraform

Categories:

• Bug Detection — Logic errors, null risks, async misuse
• Security — OWASP Top 10, hardcoded secrets, injection vulnerabilities
• Performance — N+1 queries, O(n²) patterns, SELECT *
• Code Quality — Dead code, deep nesting, TODO annotations
• Architecture — Circular deps, tight coupling, SOLID violations
• CI/CD — Dockerfile best practices, GitHub Actions security, Terraform

18 built-in static patterns + LLM-powered deep analysis.

Concurrency Model

• Celery workers with Redis broker for async workflow execution
• Per-tenant rate limiting (10 concurrent, 100/hour, 5 LLM calls)
• Redis pub/sub → SSE fan-out for real-time event streaming
• Distributed locks prevent concurrent execution of same workflow
• Tested with 5 simultaneous users without errors

Testing

# Run all tests (618 tests across 9 phases)
python -m pytest backend/tests/ kontexo_mcp_server/tests/ -v

# Phase-specific
python -m pytest backend/tests/test_phase2.py -v    # LangGraph
python -m pytest backend/tests/test_concurrency.py -v # Concurrency
python -m pytest backend/tests/test_phase8.py -v     # Code Analysis
python -m pytest kontexo_mcp_server/tests/ -v        # MCP Protocol

# Performance benchmark
python -m pytest backend/tests/test_phase9_benchmark.py -v

Environment Variables

Authentication

Firebase Auth on all /api/* routes. Public endpoint: /health.

Frontend: Users sign in via Google or GitHub popup (signInWithPopup). The Firebase JS SDK manages the session and provides ID tokens automatically.

Backend: The FastAPI get_current_user dependency verifies Firebase ID tokens using the Firebase Admin SDK. Custom claims role and tenant_id can be set via Firebase Admin.

# Get current user info (requires Firebase ID token)
curl -H "Authorization: Bearer <firebase-id-token>" http://localhost:8080/auth/me

# All /api/* routes require the same Bearer token
curl -H "Authorization: Bearer <firebase-id-token>" http://localhost:8080/api/state-graph

Variable	Required	Default	Description
FIREBASE_SERVICE_ACCOUNT_PATH	Yes	service-account.json	Path to Firebase Admin SDK service account JSON
GEMINI_API_KEY	Yes	—	Google Gemini Flash API key
GEMINI_FLASH_MODEL	No	gemini-2.5-flash	Gemini model name
GROQ_API_KEYS	No	—	JSON array of Groq API keys (round-robin rotation)
GROQ_MODEL	No	llama-3.1-70b-versatile	Groq model name
CORS_ORIGINS	No	["*"]	JSON array of allowed CORS origins
REDIS_URL	No	redis://localhost:6379/0	Redis connection URL
CHROMA_PERSIST_DIR	No	— (in-memory)	ChromaDB persistence path
GITHUB_TOKEN	No	—	GitHub personal access token
SLACK_BOT_TOKEN	No	—	Slack Bot OAuth token
TRELLO_API_KEY	No	—	Trello API key
TRELLO_TOKEN	No	—	Trello auth token
GOOGLE_SHEETS_ACCESS_TOKEN	No	—	Google Sheets OAuth token
GOOGLE_SHEETS_CREDENTIALS_JSON	No	—	Sheets service account JSON
LLM_CACHE_TTL	No	3600	LLM response cache TTL in seconds

Implementation Phases

Phase	Description	Tests
1	Custom MCP Server (JSON-RPC 2.0)	81
2	LangGraph State Machine (10 nodes)	79
3	Concurrency Infrastructure (Celery + Redis)	33
4	RAG-Powered Chatbot (ChromaDB)	43
5	Live Platform Previews (SSE)	62
6	Frontend DAG Editor (backend)	56
7	State Graph Visualization	50
8	Code Analysis (18 langs, 6 categories)	204
9	Integration & Polish	10
10	Frontend + Auth + Wiring	—
Total		618

Frontend

14 pages built with Next.js 14, React 18, ReactFlow 11, Zustand, and Tailwind CSS:

Page	Path	Description
Landing	/	Marketing page with feature highlights
Login	/login	Firebase Auth — Google + GitHub sign-in
Overview	/overview	Dashboard with health check + system status
Analytics	/analytics	Real-time metrics and charts
Workflows	/workflows	DAG Editor (ReactFlow) with Generate DAG → backend
Executions	/executions	Real-time execution list (Redis-backed)
Chat	/chat	RAG chatbot with SSE streaming
Code Analysis	/code-analysis	Monaco editor + findings list + heatmap
State Graph	/state-graph	LangGraph topology visualization
Connections	/connections	Service integration management
Settings	/settings	Profile, API config, workspace settings

License

Proprietary — All rights reserved.