How klavis-ai/klavis works
Project Type and Purpose
• Full-stack open-source integration platform (“Klavis AI”)
• Provides:
– Client SDKs (Python, TypeScript)
– Bot apps (Discord, Slack, Web, WhatsApp)
– Microservice MCP servers (100+ individual integrations)
– CI/CD pipelines and code generation (via Fern)
– Documentation & examples
Main Architectural Components
A. Client Layer
1. AI Agent / LLM or custom application
2. Klavis SDKs (Python klavis package, TS klavis npm module)
3. Bot Containers (Discord, Slack, Web, WhatsApp - in mcp-clients/)
B. API Layer
4. API Gateway or Router (generated via Fern, exposing REST/OpenAPI endpoints)
5. Authentication & OAuth endpoints
C. Microservices Layer
6. MCP Server Instances (each subfolder in mcp_servers/ is a separate Dockerized microservice)
– Each runs its own HTTP server (Python, Node.js/TypeScript, Go)
– Implements a standardized MCP protocol (create instance, list tools, call tools)
D. External Services
7. Third-party APIs (Gmail, Google Drive, Airtable, GitHub, Slack, etc.)
8. OAuth providers (handle OAuth redirects, callbacks)
E. Infrastructure
9. Codegen & API definitions (Fern: fern.config.json, generators.yml)
10. CI/CD pipelines (GitHub Actions workflows for linting, SDK releases)
11. Documentation site & examples (Docs in docs/, Jupyter notebooks in examples/)
Relationships & Data Flows
– AI Agent → SDK calls → API Gateway → MCP Server microservice → External service
– SDK initiates OAuth flows: API Gateway returns oauthUrl, user redirects, callback → MCP Server stores tokens
– For function-calling: LLM <→> SDK <→> MCP Server tools API <→> External API
– Bots (Discord/Slack) receive webhooks/events → local Bot app → SDK → MCP Server → external API → Bot responds
Architectural Patterns & Principles
– Microservices per integration for isolation and scaling
– Monorepo for all servers+clients + codegen config
– Standardized MCP protocol across languages/platforms
– Separation of concerns:
• Clients (SDK & bots) vs API Gateway vs Server implementations
• Auth management centralized in MCP Servers
– Infrastructure as code: Dockerfiles in every service directory, GitHub Actions for CI/CD
Relevant Technologies
– Python (FastAPI or Flask) for Python-based MCP Servers & Python SDK
– TypeScript/Node.js (Express, Cloudflare Workers, GraphQL) for many servers & TS SDK
– Go (GitHub MCP server implementation)
– Docker for containerization
– Fern codegen for API definitions and documentation
– GitHub Actions for linting, releases
– OpenAPI/SSE for streaming responses