Hugging Face's logo

Spaces:
nothingworry
/
IntegraChat
Sleeping

App Files Community
IntegraChat / README.md
nothingworry's picture
nothingworry
update the readme.md files
4749f94
preview code
|
raw
history blame
12.8 kB

IntegraChat — Enterprise MCP Autonomous Agent Platform

Track: MCP in Action
Category: Enterprise
Tag: mcp-in-action-track-enterprise

Overview

IntegraChat is an enterprise-grade, multi-tenant AI platform that demonstrates the full capabilities of the Model Context Protocol (MCP) in a production-style environment. Built with enterprise governance and observability in mind, IntegraChat combines autonomous tool-using agents, RAG retrieval, live web search, and admin compliance under strict tenant isolation.

This platform showcases how MCP can power intelligent, governed, multi-tenant AI systems with real-time analytics, regex-based red-flag detection, and comprehensive tool orchestration.

Features

Core Capabilities

  • 🤖 Autonomous Multi-Step MCP Agents – Intelligent tool-aware agent that plans and executes multi-step workflows across RAG, Web, Admin, and LLM tools with memory of previous tool outputs
  • 📚 Enhanced Knowledge Base Management – Upload raw text, URLs, or documents (PDF/DOCX/TXT/MD) with rich metadata (source URL, timestamp, document type) and optimized chunking (400-600 tokens)
  • 🗑️ Document Management – Delete individual documents or bulk delete all documents for a tenant with confirmation dialogs
  • 🛡️ Enterprise Admin Governance – Regex-based red-flag pattern matching with severity levels (low/medium/high/critical) and automatic admin alerts
  • 📊 Comprehensive Analytics & Observability – Full tenant-level analytics logging with SQLite backend:
    • Tool usage breakdown (RAG, Web, Admin, LLM) with latency and token tracking
    • RAG recall/precision indicators (average hits, scores, top scores)
    • Per-tenant query volume and active users
    • Red-flag violations with timestamps and confidence scores
    • LLM token logs and latency metrics
  • 🌐 Live Web Search – DuckDuckGo-based MCP server with English-biased results
  • 🏢 Multi-Tenant Isolation – Complete tenant isolation with centralized tenant ID management; backend enforces strict isolation for chat, ingestion, and admin ops
  • 🔄 Intelligent Multi-Tool Orchestration – MCP agent orchestrator autonomously selects optimal tool chains (RAG + Web + LLM, etc.) based on query intent and context
  • ⚡ Robust Error Handling – Structured error responses, retry mechanisms, and graceful fallbacks (e.g., if RAG fails → fallback to LLM-only)

Enterprise Features

  • 🔍 Regex-Based Red-Flag Detection – Support for complex regex patterns with keyword fallback and semantic scoring
  • 📈 Real-Time Analytics Dashboard – Per-tenant analytics with configurable time windows (7, 30, 90 days)
  • 🛠️ Admin API Endpoints – /admin/violations, /admin/tools/logs, /admin/tenants for comprehensive governance
  • 🧠 Agent Debug & Planning – /agent/debug and /agent/plan endpoints for observability and tool selection inspection
  • 💾 Persistent Analytics Storage – SQLite-based analytics store with indexes for fast queries

How to Run the Space

Prerequisites

  1. Backend services running:
    • FastAPI API (uvicorn backend.api.main:app --port 8000)
    • MCP servers (RAG 8001, Web 8002, Admin 8003) as described in backend/README.md
    • Optional: Ollama / Groq credentials for the LLM client
  2. Python 3.10+ with the dependencies in requirements.txt

Installation

  1. Install dependencies:

    pip install -r requirements.txt

  2. Start the Gradio app:

    python app.py

  3. Access the interface:

    • Local: http://localhost:7860
    • The app will automatically connect to the backend at http://localhost:8000

Usage

The Gradio UI exposes four tabs once you launch app.py:

  1. Chat – enter your Tenant ID, ask questions, and see multi-tool MCP responses.
  2. Document Ingestion – toggle between Raw Text, URL, or File Upload to populate the tenant RAG index. View and manage your ingested documents with delete functionality.
  3. Admin Analytics – click "Fetch Analytics Snapshot" to view overview/tool-usage/red-flag/activity metrics.
  4. Admin Rules & Compliance – upload/delete governance rules that are stored via the backend /admin/rules API.

Tip: Every action requires a tenant ID. The tenant ID is now managed centrally and persists across page refreshes.

Frontend (Next.js) Operator Console

The companion Next.js frontend (frontend/) now exposes dedicated pages for each workflow:

URL Description
/ Landing page with hero + quick access panels
/ingestion Data ingestion walkthrough (text/URL/files) with document management
/chat Chat console wrapper around the MCP agent
/analytics Analytics overview and explainer
/admin-rules Admin rule ingestion explainer
/knowledge-base View all ingested documents with search, filter, and delete functionality

Key Features:

  • Centralized Tenant ID Management – Tenant ID is managed globally via React Context and persists in localStorage
  • Document Management – View, search, filter, and delete documents from the knowledge base
  • Improved Error Handling – Clear error messages with retry options for failed operations
  • Real-time Updates – Document lists automatically refresh after ingestion or deletion

Run the console locally with:

cd frontend
npm install
npm run dev

Then open http://localhost:3000. The navbar links on the landing page route to each section, and you can link directly to those URLs for demo purposes. The tenant ID selector is available in the navbar on all pages.

API Endpoints

Agent Endpoints

Purpose Method & Path Description
Chat with agent POST /agent/message Main chat endpoint with tenant_id, message, optional history
Agent debug POST /agent/debug Returns detailed debugging info: reasoning trace, tool selection, intent classification
Agent plan POST /agent/plan Returns tool selection plan without execution (intent, tool scores, planned steps)

RAG Endpoints

Purpose Method & Path Description
Ingest document POST /rag/ingest-document Accepts source_type, content, metadata (filename, URL, doc_id)
Ingest file POST /rag/ingest-file Multipart upload with x-tenant-id header (PDF/DOCX/TXT/MD)
List documents GET /rag/list Returns all documents for a tenant with pagination
Delete document DELETE /rag/delete/{document_id} Deletes a specific document by ID
Delete all documents DELETE /rag/delete-all Deletes all documents for a tenant

Admin & Governance Endpoints

Purpose Method & Path Description
List rules GET /admin/rules?detailed=true Get all rules (use detailed=true for regex/severity metadata)
Add rule POST /admin/rules Add rule with optional pattern (regex), severity (low/medium/high/critical), description
Delete rule DELETE /admin/rules/{rule} Delete a specific rule
List violations GET /admin/violations?days=30&limit=50 Get red-flag violations with timestamps and confidence scores
Tool logs GET /admin/tools/logs?tool_name=rag&days=7 Get detailed tool usage logs with latency and token counts
Manage tenants GET/POST/DELETE /admin/tenants Tenant management endpoints (placeholder implementation)

Analytics Endpoints

Purpose Method & Path Description
Overview GET /analytics/overview?days=30 Comprehensive analytics: total queries, tool usage, red-flag count, RAG quality
Tool usage GET /analytics/tool-usage?days=30 Detailed tool usage stats: counts, latency, tokens, success/error rates
Red flags GET /analytics/redflags?limit=50&days=30 Recent red-flag violations for tenant
Activity GET /analytics/activity?days=30 Tenant activity summary: queries, active users, last query timestamp
RAG quality GET /analytics/rag-quality?days=30 RAG quality metrics: avg hits, scores, latency (recall/precision indicators)

All calls are proxied through the FastAPI backend running at http://localhost:8000. Ensure those services are online before launching the Space.

Architecture Highlights

Enterprise-Grade Features

  1. Autonomous Multi-Step Planning: The agent uses LLM-powered planning to determine optimal tool sequences, with memory of previous tool outputs in multi-step workflows.

  2. Regex-Based Governance: Admin rules support regex patterns with fallback to keyword matching and semantic similarity scoring for flexible policy enforcement.

  3. Comprehensive Analytics: All tool usage, RAG searches, LLM calls, and red-flag violations are logged to SQLite with indexed queries for fast analytics retrieval.

  4. Enhanced RAG Pipeline: Documents are chunked with optimal size (400-600 tokens) and enriched with metadata (source URL, timestamp, document type) for better retrieval.

  5. Structured Error Handling: All errors are logged with context, and the system gracefully falls back (e.g., if RAG fails → use LLM-only, if web fails → skip web).

Data Storage

  • SQLite Databases (for demo/development):

    • data/admin_rules.db - Admin rules with regex patterns and severity
    • data/analytics.db - Analytics events, tool usage, violations, RAG metrics

  • Production Ready: Can easily swap SQLite for PostgreSQL/Supabase for production deployments.

Testing & Diagnostics

IntegraChat ships with several helper scripts to validate the full stack end-to-end:

  • python verify_tenant_isolation.py
    Runs a comprehensive suite that covers analytics logging, admin rule storage, API reachability, and—most importantly—multi-tenant RAG isolation.

    • ✅ Prerequisites: FastAPI backend plus all MCP servers (RAG/Web/Admin) running locally.
    • ✅ What it checks:
      1. Direct database writes via the analytics and rules stores
      2. CRUD over the /admin/* and /analytics/* endpoints
      3. RAG ingestion and isolation by issuing queries as multiple tenants and ensuring secrets never leak across IDs
    • ✅ Pass criteria: At least 80 % of the sub-tests succeed (the RAG isolation test must pass for overall success).

  • python check_rag_database.py
    Provides a low-level inspection of the RAG datastore. It connects straight to the pgvector/Postgres instance, lists all tenant IDs, prints sample chunks, and runs search_vectors() directly to ensure the SQL WHERE tenant_id = … filter is behaving as expected. Use this script when diagnosing suspected cross-tenant leakage or when seeding demo data.

  • python test_manual.py
    The existing manual test runner remains useful for smoke-testing analytics logging, admin rule CRUD, and API response codes. Run it whenever you adjust schemas or update MCP endpoints.

Tip: All scripts assume the Python virtual environment is active (source venv/bin/activate or .\venv\Scripts\activate) and that .env contains the MCP server URLs/LLM settings noted earlier.

Demo Video

🎥 [Demo Video Placeholder] - Coming soon!

Watch how IntegraChat uses MCP to power autonomous agents with multi-tool selection, RAG retrieval, and enterprise governance.

Social Media

📱 [Social Media Post Placeholder] - Coming soon!

Follow us for updates and demos of IntegraChat in action!

Team Member(s)

  • Your Name Here - Developer & MCP Enthusiast

License

This project is licensed under the MIT License - see the LICENSE file for details.

Technical Stack

  • Backend: FastAPI with async/await for high-performance MCP orchestration
  • Frontend: Gradio interface + Next.js operator console
  • LLM Integration: Ollama (local) or Groq (cloud) via configurable backend
  • Vector Store: pgvector (via Supabase) or SQLite embeddings
  • Analytics: SQLite with indexed queries for fast analytics
  • MCP Servers: RAG (8001), Web (8002), Admin (8003)

Acknowledgments

Made with ❤️ for the MCP Hackathon

IntegraChat: Enterprise-Grade MCP Autonomous Agent Platform

⬆ Back to Top