# Understanding the Quality Tiers for Tree-Sitter Grammars in Codebase-Memory MCP

> Explore the three quality tiers for Tree-Sitter grammars: high, medium, and low. Learn how DeusData/codebase-memory-mcp assesses grammars for parsing completeness and LSP integration.

- Repository: [Martin Vogel/codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp)
- Tags: deep-dive
- Published: 2026-07-12

---

**The Codebase-Memory MCP server classifies its Tree-Sitter grammars into three distinct quality tiers—high, medium, and low—based on parsing completeness, query file availability, and Hybrid LSP integration.**

The **DeusData/codebase-memory-mcp** repository maintains parsers for 158 programming languages, not all of which offer the same level of syntactic or semantic detail. To manage expectations and optimize analysis pipelines, the project assigns each Tree-Sitter grammar to a specific **quality tier**. This classification determines whether the parser supports deep structural analysis, basic AST extraction, or experimental parsing only.

## The Three Quality Tiers for Tree-Sitter Grammars

The repository organizes grammars into a three-tier system that reflects parser maturity and feature completeness.

### High-Quality Tier (Hybrid LSP Enabled)

**High-quality grammars** represent the gold standard in the codebase. These parsers expose a complete set of node-type queries, support incremental parsing, and include the **Hybrid LSP** layer that adds type-resolution and cross-file symbol tracking. According to the project documentation, this tier delivers "high-quality parsing" through comprehensive Tree-Sitter AST analysis【grep 1†L10-L12】.

Languages in this tier contain full query file definitions in [`src/node-types.json`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/node-types.json) and [`src/grammar.json`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/grammar.json), and appear in the Hybrid LSP configuration section of [`docs/CONFIGURATION.md`](https://github.com/DeusData/codebase-memory-mcp/blob/main/docs/CONFIGURATION.md)【grep 1†L19-L21】.

### Medium-Quality Tier

Grammars classified as **medium-quality** reliably generate an Abstract Syntax Tree (AST) and expose core node-type queries. While functional for structural code exploration—such as extracting function definitions or class hierarchies—these grammars lack the extensive query sets and Hybrid LSP integration found in the high-quality tier.

These parsers are suitable for repo-wide navigation but may miss fine-grained semantic links between symbols.

### Low-Quality Tier

**Low-quality grammars** are early-stage or experimental parsers that provide only basic parsing capability. They often lack comprehensive query files ([`src/node-types.json`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/node-types.json) may be incomplete or missing) and fail to capture many language constructs. While included for completeness of language coverage, these grammars are not recommended for deep-analysis tasks.

## How Grammar Quality is Determined

The tier assignment depends on two technical criteria evaluated at build time:

1. **Query File Completeness**: The presence and richness of [`src/node-types.json`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/node-types.json) and [`src/grammar.json`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/grammar.json) within the grammar directory (`tools/tree-sitter-*/`). High-quality grammars contain exhaustive node type definitions, while low-quality grammars may have minimal or absent query files.

2. **Hybrid LSP Configuration**: Languages listed under the "Hybrid LSP" section in [`docs/CONFIGURATION.md`](https://github.com/DeusData/codebase-memory-mcp/blob/main/docs/CONFIGURATION.md) receive automatic promotion to the **high-quality** tier. This configuration indicates that the project adds semantic type-resolution on top of the raw Tree-Sitter AST【grep 1†L19-L21】.

The metadata for these classifications is maintained in [`scripts/new-languages.json`](https://github.com/DeusData/codebase-memory-mcp/blob/main/scripts/new-languages.json), which can include a `quality` field for each supported language entry.

## Checking Grammar Quality Programmatically

You can inspect grammar tiers through the CLI, C API, or Python bindings.

### Command Line Interface

Use the `list-grammars` command to view all supported languages and their assigned tiers:

```bash
$ mcp list-grammars

# Example output (truncated)

python      → high-quality   (Hybrid LSP enabled)
bash        → medium-quality
haskell     → low-quality

```

### C API

The internal C implementation exposes quality checking through the `cbm_grammar_quality` function defined in `internal/cbm/grammar_*.c` files:

```c
#include "cbm/grammar_c.h"

int tier = cbm_grammar_quality("python");   // Returns 2 for high-quality
printf("Python grammar tier: %d\n", tier);

```

### Python API

The Python bindings provide structured access to tier information via the `GrammarInfo` class:

```python
from codebase_memory_mcp import GrammarInfo

info = GrammarInfo("javascript")
print(info.tier)        # -> "high"

print(info.has_hybrid)  # -> True

```

## Summary

- **High-quality grammars** feature complete Tree-Sitter parsers with Hybrid LSP integration for semantic analysis, covering the majority of the 158 supported languages.
- **Medium-quality grammars** provide reliable AST generation suitable for structural exploration but lack advanced query capabilities.
- **Low-quality grammars** are experimental parsers with basic functionality only.
- Tier classification depends on the completeness of [`src/node-types.json`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/node-types.json) and inclusion in [`docs/CONFIGURATION.md`](https://github.com/DeusData/codebase-memory-mcp/blob/main/docs/CONFIGURATION.md)'s Hybrid LSP section.
- Runtime quality checks are available via `cbm_grammar_quality()` in the C API and the `GrammarInfo` class in Python.

## Frequently Asked Questions

### What distinguishes a high-quality grammar from a medium-quality one?

A high-quality grammar includes complete query definitions in [`src/node-types.json`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/node-types.json) and [`src/grammar.json`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/grammar.json), plus integration with the Hybrid LSP layer documented in [`docs/CONFIGURATION.md`](https://github.com/DeusData/codebase-memory-mcp/blob/main/docs/CONFIGURATION.md). This enables type-resolution and cross-file symbol tracking that medium-quality grammars lack, even though both may generate valid ASTs.

### How can I check which tier a specific language grammar belongs to?

You can check grammar tiers by running `mcp list-grammars` in the CLI, calling `cbm_grammar_quality("language")` in C, or instantiating `GrammarInfo("language")` in Python. These interfaces return the tier classification and Hybrid LSP status for any supported language.

### Can a low-quality grammar be upgraded to a higher tier?

Yes, grammars can move between tiers as the underlying Tree-Sitter parser improves. Upgrading requires enhancing the grammar's query files in `tools/tree-sitter-[language]/src/` to achieve full node-type coverage, and potentially adding Hybrid LSP support in [`docs/CONFIGURATION.md`](https://github.com/DeusData/codebase-memory-mcp/blob/main/docs/CONFIGURATION.md) to reach high-quality status.

### Where does the Codebase-Memory MCP repository store grammar quality metadata?

Quality metadata is stored in multiple locations: the [`scripts/new-languages.json`](https://github.com/DeusData/codebase-memory-mcp/blob/main/scripts/new-languages.json) file maintains the authoritative list with quality fields, individual grammar implementations reside in `tools/tree-sitter-*/`, and runtime classification logic is implemented in `internal/cbm/grammar_*.c` files.