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

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 and src/grammar.json, and appear in the Hybrid LSP configuration section of 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 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 and 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 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, 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:

$ 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:

#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:

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 and inclusion in 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 and src/grammar.json, plus integration with the Hybrid LSP layer documented in 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}