# keygraph

> keygraph is an open-source, read-only schema map that gives data analyst agents, text-to-SQL agents and other LLM agents schema context: join paths, keys, grain and status codes, through an MCP server or CLI. It maps how the tables in your database connect (keys, indexes, declared and inferred foreign keys, business context and value profiles) so people and AI agents can find the right join path and the right data. Open source (MIT), Python 3.11+, read-only, no LLM calls. Works with MySQL/MariaDB, PostgreSQL, SQLite, SQL Server, ClickHouse, Metabase, MongoDB and information_schema dumps; serves agents through MCP, a CLI with --json, a Claude Code skill and markdown files.

## Start here

- [README](https://github.com/alikarami76/keygraph/blob/main/README.md): what keygraph is, when to use it, quickstart in three commands.
- [Why a prebuilt map](https://github.com/alikarami76/keygraph/blob/main/README.md#why-a-prebuilt-map-beats-no-context-or-context-made-on-the-fly): why a deterministic, curated schema map gives agents more correct SQL than no context or context they explore and generate in each session.
- [When to use keygraph](https://github.com/alikarami76/keygraph/blob/main/README.md#when-to-use-keygraph): join paths, missing foreign keys, ER diagrams, schema context for text-to-SQL, status codes.
- [Supported sources](https://github.com/alikarami76/keygraph/blob/main/README.md#supported-sources): what each database source reads and the read-only guarantee.

## For AI agents

- [Build a data analyst agent with keygraph](https://github.com/alikarami76/keygraph/blob/main/README.md#how-do-i-build-a-data-analyst-agent-with-keygraph): the search, describe, path, keys, write SQL, check loop and how to plug it into any agent that can call MCP tools or run a CLI.
- [AGENTS.md](https://github.com/alikarami76/keygraph/blob/main/AGENTS.md): the command sequence (search, describe, path, keys), how to read confidence, what not to do.
- [Claude Code skill](https://github.com/alikarami76/keygraph/blob/main/skills/keygraph/SKILL.md): when to use each command and how to build and extend the graph.
- [MCP server setup](https://github.com/alikarami76/keygraph/blob/main/README.md#mcp): fifteen tools (fourteen read-only, one that logs queries) and configs for Claude Code, Claude Desktop, Cursor and Codex.
- [Use with AI agents](https://github.com/alikarami76/keygraph/blob/main/README.md#use-with-ai-agents): MCP, CLI --json and the generated areas/ and tables/ markdown.

## Concepts

- [How relations are inferred](https://github.com/alikarami76/keygraph/blob/main/README.md#how-relations-are-inferred): confidence, evidence, hubs, areas, path penalties, mirrors.
- [Business context and value profiles](https://github.com/alikarami76/keygraph/blob/main/README.md#business-context-and-value-profiles): concepts, status codes, metrics, sampled profiles and the PII rule.
- [Code index and query log](https://github.com/alikarami76/keygraph/blob/main/README.md#code-index-and-query-log): link source code (ORM declarations, SQL, property uses) to tables and columns, and log the queries people and agents ran with timing and business question.
- [Comparison](https://github.com/alikarami76/keygraph/blob/main/README.md#comparison): keygraph next to SchemaSpy, dbdocs, DataHub, OpenMetadata, database IDE diagrams, dbdiagram and schema linking.
- [FAQ](https://github.com/alikarami76/keygraph/blob/main/README.md#faq): common questions about join paths, foreign keys, safety and MCP setup.

## Examples and docs

- [examples/shop](https://github.com/alikarami76/keygraph/blob/main/examples/shop/README.md): a fictional 35-table webshop you can build and query in a minute.
- [How keygraph works (PDF)](https://github.com/alikarami76/keygraph/blob/main/docs/how-it-works.pdf): a guided tour with screenshots of every explorer view.
- [Design system](https://github.com/alikarami76/keygraph/blob/main/design/DESIGN.md): the explorer's visual design rules.

## Optional

- [Changelog](https://github.com/alikarami76/keygraph/blob/main/CHANGELOG.md): release notes.
- [License](https://github.com/alikarami76/keygraph/blob/main/LICENSE): MIT.
