Skip to content
BranchesTags

Repository files navigation

Kontexo V2 — Agentic MCP Gateway

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.

About

MCP Server Agent

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages