{"id":"05a909a4-7e09-44f1-953b-b1c77e63296f","slug":"aidancorrell-arcana","kind":"mcp","name":"arcana","summary":"Agent-first data catalog. MCP server that gives AI agents the context to write correct SQL — semantic search, auto-documentation, lineage-aware retrieval, and a self-improving feedback loop.","owner":"aidancorrell","repoUrl":"https://github.com/aidancorrell/arcana","license":"MIT","licenseTier":"permissive","trust":"community","stars":9,"match":null,"fewStars":false,"format":"mcp","createdAt":"2026-03-19T03:12:28.000Z","addedAt":"2026-10-21T17:00:08.237Z","logoUrl":"https://avatars.githubusercontent.com/u/82123712?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["memory-knowledge","databases","search"],"tags":[],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-26T00:58:17.455Z","sample":false,"url":"https://conduits.dev/tools/aidancorrell-arcana","language":"Rust","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# Arcana\n\nAn agent-first data catalog that gives AI the context to write correct SQL on the first try.\n\nText-to-SQL accuracy improves dramatically when agents know which tables matter, what columns mean, and what business rules apply. Arcana builds a semantic knowledge layer over your data warehouse — indexing table schemas, column definitions, lineage graphs, and business documentation into a unified search index — then serves exactly the right context to any MCP-compatible agent (Claude Code, Cursor, Copilot, or any custom toolchain).\n\nWritten in Rust for single-binary deployment, sub-millisecond search latency, and zero runtime dependencies. Token-minimal by design — the recommender returns only the highest-relevance context within a configurable budget, so agents spend tokens on reasoning, not sifting through schema dumps. Adapter-based architecture means Arcana works with any warehouse (Snowflake, BigQuery, Databricks) and any modeling framework (dbt, LookML, raw DDL) — ship one adapter and the entire platform lights up. SQLite-backed for zero-ops local use; deploy as a shared HTTP/SSE server when the team is ready.\n\n## Features\n\n| Feature | Description |\n|---------|-------------|\n| **Hybrid search** | BM25 full-text + vector cosine similarity, fused via Reciprocal Rank Fusion |\n| **Confidence scoring** | Every definition has a trust score that decays over time unless refreshed |\n| **Lineage expansion** | Search results include upstream/downstream tables automatically |\n| **Auto-enrichment** | LLM-generated descriptions for undocumented tables and columns |\n| **Feedback loop** | Agents report query outcomes; successful definitions get boosted |\n| **Redundancy detection** | Semantic clustering to surface duplicate tables |\n| **Cost estimation** | Pre-execution Snowflake EXPLAIN-based cost estimates |\n| **Document ingestion** | Index Markdown docs, runbooks, and data dictionaries |\n\n## Quick Start\n\n### Option 1: Build from source\n\n```bash\ngit clone https://github.com/aidancorrell/arcana\ncd arcana\ncargo build --release\n```\n\n### Option 2: Docker\n\n```bash\ndocker compose up -d\n```\n\nThis starts Arcana with HTTP/SSE transport on port 8477 — multiple engineers can share one instance.\n\n### Initialize and sync\n\n```bash\n# Create a minimal config (see below)\ncp config/arcana.example.toml arcana.toml\n\n# Initialize the metadata store\narcana --config arcana.toml init\n\n# Sync from your dbt project\narcana --config arcana.toml sync --adapter dbt\n\n# Embed all definitions for semantic search\narcana --config arcana.toml reembed\n\n# Test it\narcana --config arcana.toml ask \"monthly revenue by region\"\n```\n\n### Connect to Claude Code\n\nAdd to your Claude Code MCP config (`~/.claude.json` or project settings):\n\n```json\n{\n  \"mcpServers\": {\n    \"arcana\": {\n      \"command\": \"/path/to/arcana\",\n      \"args\": [\"--config\", \"/path/to/arcana.toml\", \"serve\", \"--stdio\"]\n    }\n  }\n}\n```\n\n## Minimal Configuration\n\n```toml\n[database]\nurl = \"sqlite://arcana.db\"\n\n[embeddings]\nprovider = \"openai\"\nopenai_api_key = \"sk-...\"  # or set OPENAI_API_KEY env var\nopenai_model = \"text-embedding-3-small\"\ndimensions = 1536\n\n[dbt]\nproject_path = \"./my-dbt-project\"\n```\n\nThat's it. Snowflake, enrichment, sync, and MCP sections are all optional. See [`config/arcana.example.toml`](config/arcana.example.toml) for the full reference.\n\n## CLI Commands\n\n```\narcana init         Initialize the metadata store\narcana sync         Sync metadata from dbt and/or Snowflake\narcana ingest       Ingest Markdown documents\narcana reembed      Embed (or re-embed) all semantic definitions\narcana enrich       Generate LLM descriptions for undocumented entities\narcana ask          Semantic search from the command line\narcana dedup        Detect redundant/duplicate tables\narcana status       Show entity counts and definition coverage\narcana serve        Start MCP server (--stdio for local, HTTP for team)\n```\n\n## MCP Tools\n\nWhen connected as an MCP server, Arcana exposes:\n\n| Tool | What it does |\n|------|-------------|\n| `get_context` | Semantic search — returns relevant tables, columns, and definitions for a query |\n| `describe_table` | Full metadata for a specific table including columns, definitions, and lineage |\n| `estimate_cost` | Pre-execution Snowflake cost estimate for a SQL query |\n| `update_context` | Push corrections or new definitions back into the store |\n| `find_similar_tables` | Find duplicate or near-duplicate tables via semantic similarity |\n| `report_outcome` | Report query success/failure to adjust confidence scores |\n\n## Architecture\n\nArcana is a Rust workspace with 6 crates:\n\n```\narcana-core          Metadata store, entity types, embedding index, confidence system\narcana-adapters      Snowflake + dbt metadata adapters\narcana-documents     Document ingestion pipeline (Markdown)\narcana-recommender   Context ranker + token-budget-aware serializer\narcana-mcp           MCP server (stdio + HTTP/SSE transports)\narcana-cli           CLI binary wiring everything together\n```\n\nSee [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) for the full design document.\n\n## Development\n\n```bash\ncargo test --workspace    # 30+ tests, no API keys needed\ncargo check --workspace\ncargo fmt --all\ncargo clippy --workspace\n```\n\n### Sandbox testing\n\n```bash\ncd sandbox && ./setup.sh  # Clones jaffle-shop, generates dbt artifacts, inits store\n```\n\nFor scale testing with 3,400+ models, see [`sandbox/README.md`](sandbox/README.md).\n\n## License\n\n[MIT](LICENSE)\n"}