ontomics
ontomics is an MCP server that gives coding agents instant semantic understanding of a codebase — replacing dozens of file reads with a single tool call by building a domain ontology, naming convention index, and behavioral similarity index entirely on your machine.
Concepts & Vocabulary
query_concept— Look up variants, abbreviations, related concepts, signatures, and file locations for a termlocate_concept— Find the best entry points (key functions, classes, files) for understanding a concepttrace_concept— Trace how a domain concept flows through the codebase via call chainslist_concepts— List top domain concepts ranked by importancelist_entities— List classes and functions filtered by concept, semantic role, or kind
Symbol & File Inspection
describe_symbol— Get a function or class's signature, parameters, callers, callees, and related concepts without reading sourcedescribe_file— Overview a file's entities, concepts, and relationships without reading it
Naming Conventions
list_conventions— List all detected naming patterns (prefixes, suffixes, casing rules, etc.)check_naming— Check an identifier against project conventions and get the canonical formsuggest_name— Generate a project-consistent identifier from a natural language descriptionvocabulary_health— Measure convention coverage, naming consistency, and cluster cohesionontology_diff— Show new, changed, or removed domain concepts since a given git ref
Behavioral Similarity
find_similar_logic— Find functions with behaviorally similar implementations using code embeddings, regardless of namingdescribe_logic— Get a function's raw body, logic cluster membership, and structural centralitycompact_context— Assemble token-efficient context (concepts + logic + structure) optimized for LLM consumption
Codebase Structure & Data Flow
concept_map— Show which modules/directories concentrate which domain conceptstype_flows— Show dominant types and how data flows through the codebase along call edgestrace_type— Trace how a specific type (e.g.Tensor) propagates across files and call sites
Export & Resources
export_domain_pack— Export domain knowledge (abbreviations, conventions, terms, associations) as a portable YAML packontomics://briefing— Session briefing summarizing top conventions, abbreviations, key concepts, and vocabulary warnings
ontomics
ontomics gives any coding agent instant knowledge of your codebase. One tool call instead of 19. ~20x fewer tokens.
https://github.com/user-attachments/assets/01afa8a0-1bc2-4686-94d7-965fef7610c3
Visualization for the voxelmorph project -- a library for unsupervised learning in image registration
Benchmark
Tested with Claude Sonnet — same question, with and without ontomics.
"What does 'transform' mean in this codebase?" on voxelmorph (full transcript):
With ontomics | Without | |
Tool calls | 1 | 19 |
Tokens | ~3.7k | ~76k |
Time | 5s | 1m 15s |
Answer quality | Complete | Complete |
"What are the main domain concepts in this codebase?" on ScribblePrompt (full transcript):
With ontomics | Without | |
Tool calls | 1 | 26 |
Tokens | ~3.7k | ~61.6k |
Time | ~5s | 56s |
Answer quality | Complete | Complete |
Both conditions produced complete, correct answers. ontomics got there in one call.
Related MCP server: Code-Index-MCP
What it does that search can't
Search tells you where a string appears. An LSP tells you where a symbol is defined and referenced. Neither answers: what are the domain concepts in this codebase? How do they relate? What naming conventions emerged? What changed in the domain vocabulary since last release? Which functions behave similarly, regardless of what they're named?
ontomics builds a semantic index of your project's domain — clustering related symbols into concepts, detecting naming conventions from usage frequency, resolving abbreviations, grouping functions by behavioral similarity, and tracking how the vocabulary evolves over time. That index can be exported as a portable artifact to bootstrap conventions in other repos.
Behavioral similarity
Beyond naming and concepts, ontomics embeds raw function bodies using CodeRankEmbed (768-dim, contrastive code retrieval) and clusters them by behavioral similarity. This surfaces relationships that neither naming nor call graphs expose:
❯ What functions behave like spatial_transform()?
random_transform() nn/functional.py:352 0.80
spatial_transform() functional.py:596 0.69
random_transform() functional.py:1399 0.67
random_disp() nn/functional.py:275 0.65
integrate_disp() functional.py:764 0.65
compose() nn/functional.py:216 0.63
disp_to_trf() functional.py:343 0.62The result also reveals that random_transform appears at two locations with different similarity scores — a sign of implementation duplication that concept-level search would miss entirely.
Install
Install once, available in every project. No configuration needed — ontomics auto-detects the repo and indexes it on first run.
ontomics requires a git repository (.git/ directory). It will refuse to index home, root, or temp directories. To index a non-git directory, pass --force.
1. Install the binary
npm (macOS/Linux):
npm install -g @ontomics/ontomicsmacOS (Homebrew):
brew install EtienneChollet/tap/ontomicsShell installer (macOS/Linux):
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/EtienneChollet/ontomics/releases/latest/download/ontomics-installer.sh | shFrom source:
git clone https://github.com/EtienneChollet/ontomics.git
cd ontomics
cargo build --release2. Register with your harness
Claude Code:
claude mcp add -s user ontomics -- ontomicsCodex:
codex mcp add ontomics -- ontomicsOpenClaw:
openclaw mcp set ontomics '{"command":"ontomics"}'pi-coding-agent:
pi install npm:@ontomics/ontomicsShare with your team — drop an .mcp.json in your repo root:
{
"mcpServers": {
"ontomics": {
"command": "npx",
"args": ["-y", "@ontomics/ontomics", "--repo", "."]
}
}
}Supported languages
Python, TypeScript, JavaScript, Rust. Auto-detected from file extensions.
Tools
Concepts and vocabulary
Tool | What it does |
| Find all variants, related concepts, and occurrences of a term |
| Find the key signatures, classes, and files for a concept |
| Get the signature, docstring, and relationships for a function or class |
| Trace how a concept flows through the codebase via call chains |
| List the top domain concepts by frequency |
| List all detected naming patterns (prefixes, suffixes, conversions) |
| List code entities (classes, functions) filtered by concept, role, or kind |
| Check an identifier against project conventions; suggests the canonical form |
| Generate an identifier name that fits the project's vocabulary |
| Measure convention coverage, naming consistency, and cluster cohesion |
| Show new, changed, or removed domain concepts since a git ref |
| Export domain knowledge as portable YAML for use in other repos |
Behavioral similarity
Tool | What it does |
| Find functions with behaviorally similar implementations, ranked by embedding similarity |
| Get the behavioral description, body text, and logic cluster membership for a function |
| Assemble tiered context (concepts + logic) for a symbol, optimized for LLM consumption |
Codebase structure
Tool | What it does |
| Overview of a file's entities, concepts, and relationships |
| Show which modules contain which domain concepts |
| Show dominant types and how data flows through the codebase |
| Trace how a specific type propagates across files and call sites |
Resources
Resource | What it does |
| Session briefing: top conventions, abbreviations, key concepts, contrastive pairs, and vocabulary warnings. Also available via |
How it works
ontomics runs a multi-stage pipeline entirely on your machine — no API keys required:
Parse — tree-sitter extracts every identifier, signature, and call site from your source files
Analyze — TF-IDF scoring identifies domain-specific concepts and detects naming conventions
Embed (concepts) — BGE-small (384-dim) clusters related concepts by semantic similarity
Embed (logic) — CodeRankEmbed (768-dim) embeds raw function bodies and clusters them by behavioral similarity
Centrality — PageRank scores entities by structural importance
Both embedding models are downloaded once on first run and cached locally. The index lives at <repo>/.ontomics/index.db — subsequent startups load from cache and watch for file changes.
Configuration via .ontomics/config.toml in the repo root. All fields have sensible defaults. See SPEC.md for the full design contract.
Available Tools
19 toolscheck_namingA
Check if an identifier follows project naming conventions — detects inconsistencies like 'n_dims' vs the project's 'ndim' convention, or 'numFeatures' vs 'nb_features'. Returns a consistent/inconsistent verdict with the canonical form and suggestions. Use before committing new code or when reviewing identifier names.
Inputs: identifier (required).
compact_contextA
Assemble minimal, token-efficient context for a concept, entity, or file — combines function body + structural summary + domain concepts + logic cluster into a compact text block suitable for LLM prompt injection. Much smaller than full source while preserving behavioral and structural information. Use when assembling context for another LLM, when asked to 'summarize X compactly', or when building prompts about codebase entities.
Inputs: scope (required), max_tokens.
concept_mapA
Semantic topology of the codebase — shows which directories concentrate which domain concepts, with entity counts and concept density. Use as a first call to understand codebase layout before drilling into specific concepts or symbols.
Inputs: no named parameters.
describe_fileA
Describe a file's structure WITHOUT reading it — returns classes, functions, and methods annotated with domain concepts and semantic roles. Use when you need to understand a file's shape, what symbols it contains, or what concepts it implements. Accepts partial paths (e.g. 'networks.py' matches 'src/networks.py'). Use describe_symbol to drill into any symbol shown.
Inputs: path (required).
describe_logicA
Describe the behavioral logic of a function or class — returns the raw function body, logic cluster membership (which other entities behave similarly), and structural centrality (PageRank importance in the dependency graph). Use when asked 'what does this function do internally', 'how does X work at a high level', or 'what is the logic of X'.
Inputs: name (required).
describe_symbolA
Describe a function or class WITHOUT reading its source file — returns signature, parameters, callers, callees, and related domain concepts. Faster and more informative than Read for understanding what a symbol does and how it fits into the codebase. Use when asked 'what does function X do' or 'what is class X'.
Inputs: name (required).
export_domain_packA
Export the project's full domain knowledge as a portable YAML pack — abbreviations, conventions, domain terms, and concept associations. Use when asked to 'export conventions', 'create a domain pack', or 'share naming rules'. The output can be reviewed, curated, and saved for use in other projects or tools.
Inputs: no named parameters.
find_similar_logicA
Find entities with similar behavioral patterns — uses logic embeddings to find functions/classes that do similar things regardless of naming. Returns similarity scores. Use when asked 'what other functions do the same thing', 'find similar implementations', or 'what behaves like X'.
Inputs: name (required), top_k.
list_conceptsA
List the project's domain vocabulary ranked by importance — a semantic overview of what this codebase is about that reading individual files cannot provide. Returns concept names as a ranked list. Use query_concept or locate_concept to drill into any result. Use when asked 'what is this project about', 'what are the main concepts', or when orienting in an unfamiliar codebase.
Inputs: top_k.
list_conventionsA
List the project's actual naming conventions detected from code — prefix patterns (nb_, is_, has_), suffix patterns, conversion patterns (x_to_y), and casing rules, each with real examples from the codebase. More accurate than guessing from a few files. Use when asked about coding style, before writing new code, or when onboarding to a project.
Inputs: no named parameters.
list_entitiesA
Find all classes and functions matching a concept — e.g. all loss functions, all network architectures, all transform utilities. Returns entity names with their domain concept tags. Use describe_symbol to drill into any result. Impossible with grep alone because it understands which functions implement a concept, not just mention it. Use when asked 'what loss functions exist', 'show me the network classes', 'what uses concept X', or 'list all X'.
Inputs: concept, role, kind, top_k.
locate_conceptA
Find the best entry points for understanding a concept — returns a ranked shortlist of key functions, classes, and files to read, plus contrastive concepts that clarify boundaries. Saves reading dozens of grep matches by surfacing the most important locations first. Use when asked 'how does X work', 'where should I look for X', or 'where are X defined'.
Inputs: term (required).
ontology_diffA
Compare the domain ontology between two git revisions — shows concepts that were added, removed, or changed. Useful for understanding how the project's vocabulary evolved across commits or for reviewing whether a PR introduced naming inconsistencies.
Inputs: since.
query_conceptA
Semantic concept lookup — returns all variants (including abbreviations like trf for transform), related concepts, naming conventions, function signatures, and file locations in one call. Richer than grep: querying 'transform' also finds 'trf', 'spatial_transform', 'apply_transform', and related concepts like 'displacement'. Use when asked 'what is X', 'what does X mean', or 'where is X used'.
Inputs: term (required), max_related, max_occurrences, max_variants, +1 more.
suggest_nameA
Generate project-consistent identifier names from a natural language description. Uses the project's actual conventions (prefixes like nb_, patterns like is_/has_, conversion patterns like x_to_y) to suggest names that fit the existing codebase style. Use when naming new functions, variables, or parameters.
Inputs: description (required).
trace_conceptA
Trace how a domain concept flows through the codebase via function call chains — shows which functions produce the concept, which consume it, and the call path between them including bridge functions on the path. Returns an ordered call chain with file locations and producer/ consumer roles. Use when asked 'how does concept X propagate', 'what calls what for X', or 'trace X through the code'.
Inputs: concept (required), max_depth.
trace_typeA
Find all data-flow edges involving a specific type. Shows which functions pass and receive this type through call edges. Use when asked 'where does Tensor flow', 'how is type X passed around', or 'which functions use type X'.
Inputs: type_name (required).
type_flowsA
Trace how types flow through the codebase along call edges. Shows which types dominate the data pipeline and how they propagate between functions. Returns all typed data-flow edges, dominant types ranked by frequency, and counts of typed vs untyped call edges.
Inputs: no named parameters.
vocabulary_healthA
Measure the vocabulary health of this codebase — returns convention coverage (how many identifiers follow conventions), consistency ratio (how uniformly concepts are spelled), and cluster cohesion (how well semantic clusters hold together). Use when asked about code quality, naming consistency, or vocabulary health. Returns an overall score plus top inconsistencies and uncovered identifiers.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 19 tools
The tools are mostly distinct in intent, but several clusters are easy to confuse: describe_file vs describe_symbol vs describe_logic, query_concept vs locate_concept vs list_concepts vs concept_map, and type_flows vs trace_type. An agent would need to read descriptions carefully to pick the right one.
Most tools follow a verb_noun pattern (query_concept, describe_file, trace_concept), but several use noun-ish names like type_flows, ontology_diff, concept_map, and vocabulary_health. The naming is descriptive and snake_case throughout, but the verb placement is inconsistent.
19 tools is on the heavy side and there is functional overlap in the concept/type/naming clusters. However, the domain is broad enough that most tools have a distinct purpose, so the count is defensible but borderline.
The toolset covers file/symbol/logic description, concept queries, type flow tracing, naming-convention analysis, ontology diffing, and context generation. It's read-only and lacks direct code editing or ontology update tools, but for analysis-oriented ontology tasks it is quite complete.
Maintenance
Related MCP Connectors
Codebase knowledge graph — architectural awareness for AI coding agents via MCP
Shared context for your codebase: a hosted code knowledge graph over MCP. Free plan, OAuth sign-up.
Hosted code graph over MCP: exact callers, dependencies, and cross-repo blast radius for AI agents.
Stateless agentic tools over MCP: concept extraction, long-context, knowledge graph, planning.
Related MCP Servers
- AlicenseAqualityCmaintenanceA Model Context Protocol (MCP) server that helps large language models index, search, and analyze code repositories with minimal setup22142,325 PyPI1,004MIT
- AlicenseNot gradedqualityBmaintenanceLocal-first code indexer that provides deep code understanding for Claude and other LLMs with symbol/text search across 48+ languages, semantic search capabilities, and real-time index updates through the Model Context Protocol.61MIT
- AlicenseAqualityAmaintenanceA local-first codebase intelligence tool that enables AI assistants to research codebases using semantic search, multi-hop relationship discovery, and structural parsing. It allows users to extract architectural patterns and institutional knowledge across 30+ programming languages through an MCP-compatible interface.2741 PyPI1,464MIT
- AlicenseNot gradedqualityDmaintenancePersistent codebase knowledge layer for AI agents. Pre-digests codebases into structured knowledge (symbols, dependency graphs, co-change patterns, architectural decisions) and serves via MCP. 28 languages, 14 tools, ~85% token reduction.22 npm10MIT