backend/README.md

Backend Documentation

This folder contains the production-ready FastAPI stack plus the companion MCP servers that power IntegraChat.

Directory Overview

• api/ – FastAPI application (routes, services, storage helpers, MCP clients)
• mcp_server/ – Unified MCP server exposing rag/web/admin tools via namespaces
• workers/ – Celery workers and schedulers for async ingestion + analytics maintenance

Prerequisites

• Python 3.10+
• PostgreSQL (with the vector extension) for RAG data, or Supabase with pgvector enabled
• SQLite (auto-created in data/) for analytics and admin rules
• Optional: Ollama running locally (default) or Groq API credentials for remote LLMs

Create a virtual environment at the repo root, then:

pip install -r requirements.txt
cp env.example .env   # update MCP URLs + LLM settings

Running the Services Locally

1. FastAPI core

   uvicorn backend.api.main:app --port 8000 --reload
   

2. Unified MCP server (rag/web/admin)

   python backend/mcp_server/server.py
   

   Or use the provided startup script:

   start.bat  # Windows - launches MCP server on port 8900 and FastAPI on port 8000
   

   This single server (default port 8900) exposes the following namespaced tools:

   • rag.search - Semantic search across tenant documents
   • rag.ingest - Ingest text content into knowledge base
   • rag.delete - Delete individual or all documents for a tenant
   • rag.list - List all documents for a tenant with pagination
   • web.search - DuckDuckGo-based web search
   • admin.getRules, admin.addRule, admin.deleteRule, admin.logViolation

   HTTP Endpoints (for direct API access):

   • GET /rag/list?tenant_id={id}&limit={n}&offset={n} - List documents
   • POST /rag/ingest - Ingest content
   • POST /rag/search - Search documents
   • DELETE /rag/delete/{document_id}?tenant_id={id} - Delete specific document
   • DELETE /rag/delete-all?tenant_id={id} - Delete all documents
   • POST /web/search - Web search
   • POST /admin/* - Admin operations

3. Optional workers (if running Celery-based ingestion/analytics jobs):

   celery -A backend.workers.ingestion_worker worker --loglevel=info
   celery -A backend.workers.analytics_worker worker --loglevel=info
   

The Gradio UI (python app.py) and the Next.js operator console (see frontend/README.md) both talk to the FastAPI layer at http://localhost:8000.

Key Endpoints

All endpoints require the x-tenant-id header unless otherwise noted.

Service	Path	Notes
Agent	POST /agent/message	Autonomous orchestration (RAG/Web/Admin/LLM)
Agent Debug	POST /agent/debug	Full reasoning trace + tool plan
Agent Plan	POST /agent/plan	Dry-run planning without executing tools
RAG	POST /rag/ingest-document	Rich ingestion (text, URL, metadata)
RAG	POST /rag/ingest-file	File upload (PDF/DOCX/TXT/MD)
RAG	GET /rag/list	Paginated document listing per tenant (requires x-tenant-id header)
RAG	DELETE /rag/delete/{document_id}	Delete specific document (requires x-tenant-id header)
RAG	DELETE /rag/delete-all	Delete all documents for tenant (requires x-tenant-id header)
Admin	POST /admin/rules	Regex + severity rule ingestion
Analytics	GET /analytics/overview	Summary metrics (queries, tokens, red flags)

Refer to the root README.md for the complete endpoint tables.

Diagnostics & Tenant Isolation

Use the helper scripts in the repo root when validating backend changes:

• python verify_tenant_isolation.py – Exercises analytics logging, admin rule CRUD, API reachability, and proves RAG tenant isolation by ingesting + querying as multiple tenants.
• python check_rag_database.py – Talks directly to the pgvector database to list tenant IDs, preview stored chunks, and run safeguarded searches via search_vectors(). Helpful when troubleshooting suspected cross-tenant leakage.
• python test_manual.py – Legacy manual smoke test harness (analytics store, admin rules, API surface).

Troubleshooting tip: If the isolation script reports a failure, first run check_rag_database.py to confirm documents are tagged with the correct tenant_id, then restart the unified MCP server so it reloads the updated SQL filtering logic.

Recent Improvements

Tenant ID Normalization

• All database operations now normalize tenant IDs to handle whitespace and formatting differences
• Documents can be listed and deleted consistently even if stored with slightly different tenant_id formatting
• The system automatically matches tenant IDs after normalization, ensuring operations work across different input formats

HTTP Endpoint Support

• Added GET support for /rag/list endpoint (previously POST-only)
• Added DELETE support for /rag/delete/{document_id} and /rag/delete-all endpoints
• All endpoints support both MCP protocol (POST with JSON payload) and direct HTTP methods (GET/DELETE with query parameters)

Response Format

• MCP server responses are wrapped in a standard format with status, data, and metadata fields
• RAG client automatically unwraps responses for seamless integration
• Error responses include detailed messages for better debugging

Environment Variables (excerpt)

Defined in env.example:

• RAG_MCP_URL - Default: http://localhost:8900/rag (unified MCP server)
• WEB_MCP_URL - Default: http://localhost:8900/web (unified MCP server)
• ADMIN_MCP_URL - Default: http://localhost:8900/admin (unified MCP server)
• MCP_PORT - Port for unified MCP server (default: 8900)
• MCP_HOST - Host for unified MCP server (default: 0.0.0.0)
• POSTGRESQL_URL - PostgreSQL connection string with pgvector extension
• OLLAMA_URL, OLLAMA_MODEL (or GROQ_API_KEY + LLM_BACKEND=groq)
• SUPABASE_URL, SUPABASE_SERVICE_KEY (optional admin integrations)
• APP_ENV, LOG_LEVEL, API_PORT

Update these before starting the servers to ensure the agent can reach every MCP endpoint and LLM runtime.

Note: The unified MCP server runs on a single port (default 8900) and handles all namespaced tools. The start.bat script automatically configures the correct URLs.

Unified MCP tool instructions

Agents that speak the Model Context Protocol should connect to the integrachat server id defined in backend/mcp_server/server.py and call the namespaced tools directly:

Namespace	Tool	Purpose	HTTP Endpoint
rag	search	Retrieve tenant-scoped document chunks	POST /rag/search
rag	ingest	Chunk + store new knowledge	POST /rag/ingest
rag	list	List all documents for tenant	GET /rag/list?tenant_id={id}
rag	delete	Remove one/all stored documents	DELETE /rag/delete/{id}?tenant_id={id} or DELETE /rag/delete-all?tenant_id={id}
web	search	DuckDuckGo English-biased search	POST /web/search
admin	getRules	Fetch tenant governance rules (list or detailed)	POST /admin/getRules
admin	addRule	Insert or update a rule	POST /admin/addRule
admin	deleteRule	Remove a rule by text	POST /admin/deleteRule
admin	logViolation	Persist a red-flag event into analytics	POST /admin/logViolation

Important Notes:

• Always send tenant_id in the payload (or as query parameter for GET/DELETE requests) so the shared middleware can enforce isolation and log analytics
• The MCP server automatically normalizes tenant IDs to ensure consistent matching across operations
• All endpoints support both POST (with JSON payload) and direct HTTP methods (GET for list, DELETE for delete operations)
• Tenant ID normalization handles whitespace and ensures documents can be listed and deleted consistently