Iris — Camada de Inteligência de Contexto Empresarial
Xeebs/iris
Indexação semântica de contexto empresarial sem equipe de dados
Ver no GitHubMCP server que conecta sistemas operacionais (CRM, docs, bases de dados, SaaS) e constrói um índice semanticamente enriquecido de entidades, métricas e relacionamentos da empresa. Serve contexto governado a qualquer ferramenta de IA via protocolo aberto, reduzindo consumo de tokens em até 93% comparado a colar dados brutos em prompts.
Instalação
npx convez-ai Xeebs/iris1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Consultores de IA que precisam responder perguntas de negócio com dados reais da empresa
- Equipes sem engenheiros de dados que querem camada semântica unificada
- Agentes internos que precisam de acesso governado a múltiplos SaaS e bases
Veredito

Iris resolve um problema real e medido: unificar contexto empresarial fragmentado em 40+ ferramentas sem exigir data team. A compressão de tokens (76%+ de redução verificada em benchmark) é vantagem operacional genuína. Implementação auto-hospedada em TypeScript; melhor para empresas com infraestrutura e necessidade de governança rigorosa sobre dados sensíveis.
README
A tradução para o português deste README ainda está na fila.
Iris
Make every AI tool in your company actually know your business — without a data team, and at a fraction of the token cost.
Iris is a self-hosted business context server. It connects to the systems where your operational data already lives (CRM, docs, databases, SaaS tools), builds a semantically enriched index of your entities, metrics, and relationships, and serves that context to any AI tool over the open Model Context Protocol. Ask Claude "who owns our largest open deal?" and it answers from your data — correctly, governed, and measurably cheaper than pasting spreadsheets into a prompt.
In its first end-to-end benchmark, Iris answered a set of canonical business questions with 76.4% fewer tokens than the raw-data-paste baseline (per-question savings up to 93.6%), verified twice from a clean database in CI. Measured, not estimated — the report is generated by scripts/slice-demo.sh and you can reproduce it in one command.
The problem
AI assistants are everywhere in business, but they are generic. They don't know your deal stages, your customers, your metric definitions, or what "enterprise tier" means at your company. Every team works around this, and every workaround fails somewhere:
| Workaround | Where it breaks |
|---|---|
| Pasting exports into prompts | Unscalable, ungoverned, leaks data, burns tokens on every single question |
| Custom RAG pipelines | Requires engineers to build and keep maintaining; most SMBs have none to spare |
| Enterprise semantic layers | Built for data teams, $30K+/year, months to deploy |
| Vendor-locked AI (Einstein, Copilot in Fabric, etc.) | Each only knows its own silo; your business spans 40+ SaaS apps |
The gap: nothing unifies semantically enriched, AI-ready context across a company's tools at a price and setup effort that works for a team without data engineers. Iris is built to be that layer.
Why MCP changes the equation
Iris speaks the Model Context Protocol — the open standard adopted by Claude, ChatGPT, Copilot, Cursor, and a fast-growing ecosystem of agents. That means:
- Connect once, use everywhere. One Iris deployment serves every MCP-capable AI tool your team uses today, and the ones you'll adopt next year. No per-tool integration work.
- No platform bet. Switch AI vendors freely; your business context layer doesn't change.
- Agent-ready. Internal agents and automations get the same governed, budgeted context interface humans do.
Most MCP servers are thin wrappers that proxy API calls. Iris is different: context is pre-indexed, semantically deduplicated, and token-compressed before any AI ever asks, so answers are fast, relevant, and cheap.
┌─────────────────────────────────────────────────────────────┐
│ AI Tools Layer │
│ Claude │ ChatGPT │ Copilot │ Cursor │ Custom Agents │
└───────────────────────────┬─────────────────────────────────┘
│ MCP (open standard)
┌───────────────────────────▼─────────────────────────────────┐
│ Iris MCP Server │
│ context query tools │ access control │ audit & governance │
└───────────────────────────┬─────────────────────────────────┘
┌───────────────────────────▼─────────────────────────────────┐
│ Context Engine │
│ retrieval (vector+graph) │ compression │ semantic cache │
└───────────────────────────┬─────────────────────────────────┘
┌───────────────────────────▼─────────────────────────────────┐
│ Semantic Index │
│ entity graph │ metric registry │ business glossary │
│ vector store (pgvector / Qdrant) │
└───────────────────────────┬─────────────────────────────────┘
┌───────────────────────────▼─────────────────────────────────┐
│ Connector Layer │
│ HubSpot │ Salesforce │ Postgres │ Notion │ Snowflake │ … │
└─────────────────────────────────────────────────────────────┘
- Connect — pre-built connectors sync CRM, docs, databases, and SaaS data on a schedule
- Index — entities, relationships, metrics, and terminology are extracted into a semantic graph with vector embeddings
- Compress — a multi-layer efficiency stack strips redundancy before anything reaches an LLM
- Serve — an MCP-compliant server exposes query tools any AI platform can call
- Govern — workspace-scoped API keys, role-based access, PII exclusion from embeddings, and an audit trail of every context read
Who Iris helps, and why
The ops-aware founder or COO (20–150 people). You use Claude or ChatGPT daily and are tired of re-explaining your business in every prompt. You have no data team and aren't going to hire one. Iris gives your AI tools a persistent, current understanding of your customers, pipeline, and metrics — set up from a dashboard, not a codebase.
The RevOps / BizOps manager (150–2,000 people). You're the person responsible for making AI actually useful across the team. You need answers grounded in the CRM and the warehouse, role-appropriate access so the AI never shows a rep someone else's comp data, and a defensible audit trail. Iris gives you one governed gateway between your stack and every AI tool, with token spend you can see and control.
The developer building internal agents. You'd rather not build retrieval, deduplication, caching, token budgeting, and connector auth from scratch — again. Iris is an extensible, strictly-typed context server: a connector SDK with a four-method contract, zod-validated MCP tools, and open REST APIs. Self-host it and build on top.
What you can expect
-
Correct, grounded answers. Responses are assembled from your indexed entities, not model guesses. The end-to-end benchmark asserts factual correctness against known data — accuracy is a tested invariant, not a hope.
-
Measured token savings. Every response respects an explicit
contextBudget(default 2,000 tokens). The efficiency stack attacks cost at every layer:Layer Technique Effect Index-time Semantic deduplication (cosine ≥ 0.85) 30–50% fewer stored entities Index-time Structured extraction — a 2KB raw CRM record becomes a ~200-token semantic entity 80–90% per record Retrieval Top-k relevance filtering within the context budget query-specific Cache Semantic response cache (cosine ≥ 0.92) for equivalent queries near-zero repeat cost Cache Static-first context layout for provider prefix-cache hits ~90% on prefix tokens -
Your data stays yours. Self-hosted — runs on your hardware (it develops itself on a Raspberry Pi 5). Local embedding via Ollama is supported, so the full pipeline can run with no external API at all. OAuth tokens are encrypted at rest; fields marked PII are never embedded.
-
Honest maturity. Iris is early-stage and built in the open. The core chain — connect → sync → index → serve → query → measure — is proven and CI-guarded (
docs/VERTICAL_SLICE.md, achieved 2026-06-10). The current milestone (docs/SLICE_2.md) is making every link production-real: live data sources, real embedding models, a 20+ question accuracy benchmark, and a guided onboarding path. Until it reads ACHIEVED, treat features beyond the proven chain as implemented but still being hardened.
How Iris fits into your organization
Iris sits between your systems of record and your AI tools — it doesn't replace either. Your data stays in HubSpot, Postgres, and Notion; your team keeps using Claude, ChatGPT, or Cursor. Iris is the governed middle layer that makes the two sides understand each other.
A typical rollout:
- Week 1 — one source, one team. Deploy Iris (Docker Compose), connect your CRM, let the initial sync index your entities. Add Iris to your AI tool with one MCP config block. The pilot team starts asking real questions.
- Validate. The audit log shows what's being asked and what context was served; the token report shows what it costs versus the paste-it-in alternative. Adjust the business glossary and metric definitions so answers use your vocabulary.
- Expand. Add connectors (docs, database, support tools), scope API keys per team or role, and open access to more of the company — including internal agents and automations, which consume the same governed interface.
Operationally, Iris is one self-hosted service backed by Postgres (pgvector) and Redis. There is no per-seat pricing trap and no data leaves your infrastructure except the queries you route to your chosen AI provider.
Getting started
Prerequisites: Node.js 20+, pnpm 9+, Docker.
git clone https://github.com/Xeebs/iris && cd iris
pnpm install
cp .env.example .env.local # fill in keys as needed
docker-compose -f infra/docker/docker-compose.yml up -d # Postgres/pgvector, Redis, Qdrant
pnpm db:migrate
pnpm dev
The single most useful command — the end-to-end proof with a token-savings report:
bash scripts/slice-demo.sh # exit 0 = the whole chain works, from a fresh database
Connect Claude Desktop / Claude Code:
{
"mcpServers": {
"iris": {
"command": "pnpm",
"args": ["mcp:start"],
"cwd": "/path/to/iris"
}
}
}
Other commands:
pnpm build / pnpm test / pnpm typecheck / pnpm lint
pnpm test:integration # requires Docker services
pnpm mcp:start # start just the MCP server
pnpm mcp:inspect # MCP inspector for interactive debugging
pnpm connector:scaffold <name> # scaffold a new connector
Under the hood
apps/
mcp-server/ — MCP-compliant context server (the product)
api/ — REST API: dashboard, webhooks, connector management
dashboard/ — Next.js admin UI
packages/
connector-sdk/ — BaseConnector contract, SemanticEntity types, registry
connectors/ — 14 connector implementations
core/ — Logger, error types, config loader
semantic-core/ — Embedding, indexing, retrieval, glossary, metric registry
cache/ — Semantic + prefix cache (Redis-backed)
compression/ — Context compression pipeline
graph/ — Knowledge graph interface (Neo4j)
| Concern | Technology |
|---|---|
| Language | TypeScript, strict mode (Node.js 20+) |
| MCP | Official MCP TypeScript SDK¹ |
| API framework | Hono |
| Embeddings | OpenAI text-embedding-3-small, Ollama (local), Azure, Cohere — one model system-wide |
| Vector store | pgvector (Postgres) + Qdrant |
| Cache | Redis 7 |
| Build | pnpm workspaces + Turborepo |
| Validation / errors | zod everywhere; neverthrow Result<T, E> |
| Testing | Vitest + MSW + Playwright |
¹ Tool registration goes through apps/mcp-server/src/register-tool.ts rather than the SDK's generic registerTool() — the SDK 1.29 × zod 3.25 generics blow up TypeScript's checker. See the helper's doc comment before touching tool registration.
Connectors (in packages/connectors/): HubSpot, Salesforce, Postgres, Notion, Google Drive, Snowflake, Airtable, Jira, Confluence, NetSuite, QuickBooks, Slack, Linear, GitHub. Every connector extends BaseConnector (connect / sync / getSchema / healthCheck), transforms raw records into compact SemanticEntity objects — never raw API responses — and ships with MSW-mocked tests.
MCP tools: the primary tool is query-context — semantic search over the indexed graph within a token budget. Around it sit list-entities, get-entity, get-metric, list-glossary, and advanced tools (aggregation, comparison, trend analysis, streaming context). All tools validate input with zod, enforce contextBudget, log token estimates to the audit table, and return structured errors instead of throwing.
Built by an autonomous pipeline
Iris doubles as a long-running experiment in autonomous software development. A daemon on a Raspberry Pi spawns Claude Code sessions in a loop; each session checks CI health (no feature work on red CI), picks the top task from pipeline/queue.md, implements it under the rules in .claude/rules/, tests, and pushes. The development history — including the deliberate pivot from breadth to a proven vertical slice — is in pipeline/changelog.md and the docs/ milestone files, in the open like everything else here.
License
MIT