Knowledge & MCP

RAG pipeline

Upload PDFs and ask questions about their content using vector similarity search:

CHROMA_DIR=.chroma
RAG_COLLECTION_NAME=default
RAG_TOP_K=5
EMBEDDING_DEPLOYMENT_NAME=text-embedding-3-small
RAG_CHUNK_SIZE=800
RAG_CHUNK_OVERLAP=200
# RAG_CHUNK_MIN_SIZE=200   # unset -> RAG_CHUNK_SIZE // 4; 0 disables tail-merge

Workflow:

1. + -> Attach PDF to upload a document
2. Ask the agent: "Please ingest this document"
3. The batch job runs: PDF parsing -> chunking -> embedding -> ChromaDB storage
4. Ask: "What does the document say about X?"
5. The agent answers with source citations (filename, page)

Highlights: file-based ChromaDB storage, a singleton embedding client (one credential + TLS handshake per batch process), overlap chunking with tail-merge, metadata-based citation, automatic de-duplication on re-ingest, and PDF file cards in chat. RAG requires the Batch Processing server (below), which is bundled.

Batch processing

Long-running tasks (RAG ingestion, data pipelines) run as background jobs with a real-time dashboard. The bundled backend/mcp_servers.default.jsonc already registers the batch server -- copy it to backend/mcp_servers.jsonc only to customise the job directory or per-batch overrides:

{
  "mcpServers": {
    "batch": {
      "command": "uv",
      "args": ["run", "python", "-m", "app.mcp_batch.server"],
      // BATCH_JOBS_DIR and RAG_CHUNK_* live in backend/.env (loaded via
      // load_dotenv). Add keys here only to pin a per-batch override.
      "env": {},
      "load_prompts": false
    }
  }
}

• Conversation-based management -- submit, monitor, cancel, delete jobs via chat
• MCP Apps dashboard -- auto-refreshing progress bars, cancel/delete with confirmation
• File-based persistence -- each job is a JSON file (crash-resilient)
• Cooperative cancellation -- jobs check the cancel flag at each checkpoint

MCP integration

Connect external tools via the Model Context Protocol using the Claude Desktop-compatible config. ChatWalaʻau ships a bundled default (mcp_servers.default.jsonc) and prefers an operator override (mcp_servers.jsonc, gitignored) -- no manual copy on first run.

# Optional: defaults to mcp_servers.jsonc; set empty to disable MCP.
# MCP_CONFIG_FILE=mcp_servers.jsonc

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/workspace"]
    },
    "remote-api": {
      "url": "https://api.example.com/mcp",
      "headers": { "Authorization": "Bearer token" }
    }
  }
}

• JSONC -- // and /* */ comments are stripped; strict JSON is accepted unchanged, so existing Claude Desktop / Claude Code / Cursor configs reuse
• stdio servers (with command) are spawned; HTTP/SSE servers (with url) are connected to
• MCP tools appear alongside built-in tools and show a Plug icon
• Server lifecycle is managed automatically (with zombie-process prevention)
• Optional per-server fields: "load_prompts": true (for servers implementing prompts/list; default false), "load_tools": false, "request_timeout": 30

MCP Apps

When an MCP tool declares a _meta.ui resource, its HTML View renders as interactive UI inside the chat message, in a secure double-iframe sandbox.

# MCP_APPS_SANDBOX_PORT=8081   # optional sandbox proxy port

• Double-iframe sandbox -- Views run on a separate origin with no access to host DOM, cookies, or storage; CSP blocks external resources by default
• Auditable -- all View-to-Server interaction is proxied through the Host
• Display modes -- inline and fullscreen; session persistence stores View HTML for reload
• Progressive enhancement -- tools work as text when UI is unavailable

No configuration needed; MCP Apps activates automatically and the sandbox proxy starts alongside MCP servers.