Skip to content

Commit 8af6833

Browse files
committed
fix(mcp): serve every named label in BM25 search_graph, never a silent zero
In query (BM25) mode an explicit label naming File, Folder, Variable or Project returned 0 rows -- often with an exact "eq" total -- although those nodes are in nodes_fts and match the query: the noise exclusion meant for unlabelled queries was applied to labelled queries too. It now applies only when no label is given (one shared SQL fragment for the ranked and the count query), so such a label is served from its own label-scoped candidate window like any other label. Unlabelled queries are unchanged. A label no node carries as spelled (labels are case-sensitive) still answers 0 rows, as structural mode does, but no longer silently: the result carries a hint naming the stored spelling, or get_graph_schema when the label is unknown. An existing label with no matching row stays a plain zero. Measured on Django and meilisearch indexes (81 / 114 label queries): zero results 18 -> 0 and 21 -> 0 (8 and 18 of them reported an exact "eq" total); every other label returns byte-identical results, and unlabelled queries are byte-identical to main. Refs DeusData#2386 Signed-off-by: Martin Vogel <martin.vogel.tech@gmail.com>
1 parent a8477fe commit 8af6833

2 files changed

Lines changed: 206 additions & 14 deletions

File tree

‎src/mcp/mcp.c‎

Lines changed: 77 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -4052,6 +4052,19 @@ enum {
40524052
static const double BM25_LABEL_WEIGHT = 1.0;
40534053
static const double BM25_LABEL_WEIGHT_SCOPED = 0.0;
40544054

4055+
/* Labels an UNLABELLED query never ranks: path-shaped File/Folder nodes, the
4056+
* Project node and Variables match almost any token through their qualified
4057+
* name and file path, and would crowd definitions out of the result. They are
4058+
* still in nodes_fts, so an explicit `label` that names one of them is served
4059+
* from its own label-scoped window like any other label (?7 is the caller's
4060+
* label, NULL when none was given). Excluding them there too returned 0 rows
4061+
* -- often with an exact "eq" total -- although such nodes match. Section and
4062+
* Module are NOT excluded (#518/#519): they carry the prose the body column
4063+
* indexes. Shared by the ranked and the count query, so the two cannot
4064+
* desynchronise. */
4065+
#define BM25_UNLABELLED_EXCLUSION \
4066+
"(?7 IS NOT NULL OR n.label NOT IN ('File','Folder','Variable','Project'))"
4067+
40554068
/* Module-local SQLITE_TRANSIENT wrapper to dodge performance-no-int-to-ptr.
40564069
* See the matching helper in src/store/store.c for the same pattern. */
40574070
static sqlite3_destructor_type mcp_sqlite_transient(void) {
@@ -4134,6 +4147,52 @@ static double bm25_scope_match_to_label(const char *tokens, const char *label, c
41344147
return BM25_LABEL_WEIGHT_SCOPED;
41354148
}
41364149

4150+
/* A BM25 result is empty although nodes match when the label is spelled in a
4151+
* case no node carries: labels are case-sensitive, so `label=class` finds
4152+
* nothing while Class nodes match the query. Returns a hint (memory core,
4153+
* CBM_MEM_CLASS_OTHER) naming the label this project actually holds, or NULL
4154+
* when the label exists exactly (a true zero). The exact probe is an index
4155+
* seek on (project, label); the case-insensitive scan runs only when it
4156+
* misses. The caller's label is never echoed back, only the stored spelling. */
4157+
static char *bm25_label_zero_hint(sqlite3 *db, const char *project, const char *label) {
4158+
enum { HINT_BIND_PROJECT = 1, HINT_BIND_LABEL = 2, HINT_COL_LABEL = 0, HINT_PROBE_EXACT = 0 };
4159+
if (!db || !label || !label[0]) {
4160+
return NULL;
4161+
}
4162+
static const char *const probes[] = {
4163+
"SELECT label FROM nodes WHERE project = ?1 AND label = ?2 LIMIT 1",
4164+
"SELECT label FROM nodes WHERE project = ?1 AND label = ?2 COLLATE NOCASE LIMIT 1",
4165+
};
4166+
char found[CBM_SZ_256] = "";
4167+
for (size_t i = 0; i < sizeof(probes) / sizeof(probes[0]) && !found[0]; i++) {
4168+
sqlite3_stmt *st = NULL;
4169+
if (sqlite3_prepare_v2(db, probes[i], BM25_SQL_AUTO_LEN, &st, NULL) != SQLITE_OK) {
4170+
return NULL;
4171+
}
4172+
sqlite3_bind_text(st, HINT_BIND_PROJECT, project, BM25_SQL_AUTO_LEN, MCP_SQLITE_TRANSIENT);
4173+
sqlite3_bind_text(st, HINT_BIND_LABEL, label, BM25_SQL_AUTO_LEN, MCP_SQLITE_TRANSIENT);
4174+
if (sqlite3_step(st) == SQLITE_ROW) {
4175+
const char *stored = (const char *)sqlite3_column_text(st, HINT_COL_LABEL);
4176+
snprintf(found, sizeof(found), "%s", stored ? stored : "");
4177+
}
4178+
sqlite3_finalize(st);
4179+
if (found[0] && i == HINT_PROBE_EXACT) {
4180+
return NULL;
4181+
}
4182+
}
4183+
if (!found[0]) {
4184+
return cbm_mem_strdup(CBM_MEM_CLASS_OTHER,
4185+
"no node in this project carries this label; get_graph_schema "
4186+
"lists the labels this index holds");
4187+
}
4188+
char hint[CBM_SZ_512];
4189+
snprintf(hint, sizeof(hint),
4190+
"no node carries this label as spelled; labels are case-sensitive -- retry with "
4191+
"label=\"%s\"",
4192+
found);
4193+
return cbm_mem_strdup(CBM_MEM_CLASS_OTHER, hint);
4194+
}
4195+
41374196
static char *bm25_file_pattern_like(const char *file_pattern) {
41384197
if (!file_pattern) {
41394198
return NULL;
@@ -4185,7 +4244,8 @@ static void bm25_lines_str(char *out, size_t size, int start, int end) {
41854244

41864245
static void bm25_emit_metadata_tree(cbm_sb_t *sb, int total, int offset, int returned,
41874246
bool candidate_window_saturated, bool budget_hit,
4188-
bool floor_exceeded, size_t max_output_bytes) {
4247+
bool floor_exceeded, size_t max_output_bytes,
4248+
const char *zero_hint) {
41894249
bool has_more = total > offset + returned;
41904250
cbm_tree_scalar_int(sb, "total", total);
41914251
cbm_tree_scalar_str(sb, "total_relation", candidate_window_saturated ? "gte" : "eq");
@@ -4216,12 +4276,15 @@ static void bm25_emit_metadata_tree(cbm_sb_t *sb, int total, int offset, int ret
42164276
cbm_tree_scalar_str(sb, "hint",
42174277
"first identity row exceeds max_output_bytes; raise "
42184278
"max_output_tokens");
4279+
} else if (zero_hint) {
4280+
cbm_tree_scalar_str(sb, "hint", zero_hint);
42194281
}
42204282
}
42214283

42224284
static void bm25_emit_metadata_json(yyjson_mut_doc *doc, yyjson_mut_val *root, int total,
42234285
int offset, int returned, bool candidate_window_saturated,
4224-
bool budget_hit, bool floor_exceeded, size_t max_output_bytes) {
4286+
bool budget_hit, bool floor_exceeded, size_t max_output_bytes,
4287+
const char *zero_hint) {
42254288
bool has_more = total > offset + returned;
42264289
yyjson_mut_obj_add_int(doc, root, "total", total);
42274290
yyjson_mut_obj_add_str(doc, root, "total_relation", candidate_window_saturated ? "gte" : "eq");
@@ -4253,12 +4316,14 @@ static void bm25_emit_metadata_json(yyjson_mut_doc *doc, yyjson_mut_val *root, i
42534316
yyjson_mut_obj_add_str(doc, root, "hint",
42544317
"first identity row exceeds max_output_bytes; raise "
42554318
"max_output_tokens");
4319+
} else if (zero_hint) {
4320+
yyjson_mut_obj_add_strcpy(doc, root, "hint", zero_hint);
42564321
}
42574322
}
42584323

42594324
static char *bm25_render(const bm25_output_row_t *rows, int returned, int total, int offset,
42604325
bool candidate_window_saturated, bool tree_format, bool budget_hit,
4261-
bool floor_exceeded, size_t max_output_bytes) {
4326+
bool floor_exceeded, size_t max_output_bytes, const char *zero_hint) {
42624327
if (tree_format) {
42634328
cbm_sb_t sb;
42644329
cbm_sb_init(&sb);
@@ -4276,7 +4341,7 @@ static char *bm25_render(const bm25_output_row_t *rows, int returned, int total,
42764341
cbm_tree_row_end(&sb);
42774342
}
42784343
bm25_emit_metadata_tree(&sb, total, offset, returned, candidate_window_saturated,
4279-
budget_hit, floor_exceeded, max_output_bytes);
4344+
budget_hit, floor_exceeded, max_output_bytes, zero_hint);
42804345
return cbm_sb_finish(&sb);
42814346
}
42824347

@@ -4303,7 +4368,7 @@ static char *bm25_render(const bm25_output_row_t *rows, int returned, int total,
43034368
}
43044369
yyjson_mut_obj_add_val(doc, root, "rows", result_rows);
43054370
bm25_emit_metadata_json(doc, root, total, offset, returned, candidate_window_saturated,
4306-
budget_hit, floor_exceeded, max_output_bytes);
4371+
budget_hit, floor_exceeded, max_output_bytes, zero_hint);
43074372
char *json = yy_doc_to_str(doc);
43084373
yyjson_mut_doc_free(doc);
43094374
return json;
@@ -4372,12 +4437,7 @@ static char *bm25_search(cbm_store_t *store, const char *project, const char *qu
43724437
") fts "
43734438
"JOIN nodes n ON n.id = fts.rowid "
43744439
"WHERE n.project = ?2 "
4375-
/* Section and Module are NO LONGER excluded (#518/#519): they are the
4376-
* labels that carry prose — a Markdown section's body, a config file's
4377-
* description — so excluding them made the body column unreachable.
4378-
* This exclusion list is MIRRORED in the count query below; the two
4379-
* must be changed together or results desynchronise from counts. */
4380-
" AND n.label NOT IN ('File','Folder','Variable','Project') "
4440+
" AND " BM25_UNLABELLED_EXCLUSION " "
43814441
" AND (?6 IS NULL OR n.file_path LIKE ?6) "
43824442
/* The caller's label filter applies in query mode exactly as it does
43834443
* in the structural mode (2026-09-16 probe: `label=Class` was ignored
@@ -4444,7 +4504,7 @@ static char *bm25_search(cbm_store_t *store, const char *project, const char *qu
44444504
/* MIRRORS the ranked query's filter verbatim — same weights, same
44454505
* label exclusions. Changing one alone reports a total that does
44464506
* not describe the rows returned. */
4447-
" AND n.label NOT IN ('File','Folder','Variable','Project')"
4507+
" AND " BM25_UNLABELLED_EXCLUSION " "
44484508
" AND (?6 IS NULL OR n.file_path LIKE ?6)"
44494509
" AND (?7 IS NULL OR n.label = ?7)"
44504510
" AND (?9 IS NULL OR (CASE WHEN json_valid(n.properties) "
@@ -4535,13 +4595,15 @@ static char *bm25_search(cbm_store_t *store, const char *project, const char *qu
45354595
if (!rows) {
45364596
return heap_strdup("out of memory");
45374597
}
4598+
/* Never a silent zero for a label the index spells differently. */
4599+
char *zero_hint = total == 0 ? bm25_label_zero_hint(db, project, label) : NULL;
45384600

45394601
int returned = row_count;
45404602
bool budget_hit = false;
45414603
char *payload = NULL;
45424604
for (;;) {
45434605
payload = bm25_render(rows, returned, total, offset, candidate_window_saturated,
4544-
tree_format, budget_hit, false, max_output_bytes);
4606+
tree_format, budget_hit, false, max_output_bytes, zero_hint);
45454607
if (!payload || strlen(payload) <= max_output_bytes || returned == 0) {
45464608
break;
45474609
}
@@ -4554,8 +4616,9 @@ static char *bm25_search(cbm_store_t *store, const char *project, const char *qu
45544616
if (!payload || strlen(payload) > max_output_bytes || (row_count > 0 && returned == 0)) {
45554617
free(payload);
45564618
payload = bm25_render(rows, 0, total, offset, candidate_window_saturated, tree_format, true,
4557-
row_count > 0, max_output_bytes);
4619+
row_count > 0, max_output_bytes, zero_hint);
45584620
}
4621+
cbm_free(CBM_MEM_CLASS_OTHER, zero_hint);
45594622
bm25_output_rows_free(rows, row_count);
45604623
return payload;
45614624
}

‎tests/test_mcp.c‎

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4602,6 +4602,133 @@ TEST(tool_search_graph_bm25_label_scope_keeps_rank_order) {
46024602
PASS();
46034603
}
46044604

4605+
/* An unlabelled BM25 query never ranks File, Folder, Variable or Project nodes
4606+
* (they match almost any token through their path), but an explicit label
4607+
* naming one of them must be served: those nodes are in nodes_fts, and
4608+
* excluding them there too answered `query=config label=Folder` with 0 rows
4609+
* and an exact "eq" total. One node per label shares the query tokens with a
4610+
* Function. */
4611+
static void bm25_unranked_labels_fixture(cbm_store_t *store, const char *project) {
4612+
cbm_store_upsert_project(store, project, "/tmp/bm25-noise");
4613+
struct {
4614+
const char *label, *name, *qn, *file;
4615+
} rows[] = {
4616+
{"Function", "loadconfig", "bm25-noise.app.loadconfig", "app/config.py"},
4617+
{"File", "__file__", "bm25-noise.app.config.py", "app/config.py"},
4618+
{"Folder", "config", "bm25-noise.app.config", "app/config"},
4619+
{"Variable", "CONFIG_PATH", "bm25-noise.app.config.CONFIG_PATH", "app/config.py"},
4620+
{"Project", "bm25-noise", "bm25-noise", ""},
4621+
};
4622+
for (size_t i = 0; i < sizeof(rows) / sizeof(rows[0]); i++) {
4623+
cbm_node_t node = {.project = project,
4624+
.label = rows[i].label,
4625+
.name = rows[i].name,
4626+
.qualified_name = rows[i].qn,
4627+
.file_path = rows[i].file,
4628+
.start_line = (int)i + 1,
4629+
.end_line = (int)i + 1};
4630+
cbm_store_upsert_node(store, &node);
4631+
}
4632+
cbm_store_exec(store, "INSERT INTO nodes_fts(nodes_fts) VALUES('delete-all');");
4633+
cbm_store_exec(store, "INSERT INTO nodes_fts(rowid, name, qualified_name, label, "
4634+
"file_path) SELECT id, cbm_camel_split(name), qualified_name, "
4635+
"label, file_path FROM nodes;");
4636+
}
4637+
4638+
static char *bm25_noise_search(cbm_mcp_server_t *srv, const char *query, const char *label) {
4639+
char req[512];
4640+
char label_arg[128] = "";
4641+
if (label) {
4642+
snprintf(label_arg, sizeof(label_arg), ",\"label\":\"%s\"", label);
4643+
}
4644+
snprintf(req, sizeof(req),
4645+
"{\"jsonrpc\":\"2.0\",\"id\":2423,\"method\":\"tools/call\","
4646+
"\"params\":{\"name\":\"search_graph\",\"arguments\":{"
4647+
"\"project\":\"bm25-noise\",\"query\":\"%s\"%s,\"limit\":10,\"format\":\"json\"}}}",
4648+
query, label_arg);
4649+
char *resp = cbm_mcp_server_handle(srv, req);
4650+
char *inner = resp ? extract_text_content(resp) : NULL;
4651+
free(resp);
4652+
return inner;
4653+
}
4654+
4655+
TEST(tool_search_graph_bm25_serves_unranked_labels_when_named) {
4656+
cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
4657+
ASSERT_NOT_NULL(srv);
4658+
cbm_store_t *store = cbm_mcp_server_store(srv);
4659+
ASSERT_NOT_NULL(store);
4660+
cbm_mcp_server_set_project(srv, "bm25-noise");
4661+
bm25_unranked_labels_fixture(store, "bm25-noise");
4662+
4663+
static const struct {
4664+
const char *label, *qn;
4665+
} named[] = {
4666+
{"File", "\"bm25-noise.app.config.py\",\"File\""},
4667+
{"Folder", "\"bm25-noise.app.config\",\"Folder\""},
4668+
{"Variable", "\"bm25-noise.app.config.CONFIG_PATH\",\"Variable\""},
4669+
{"Project", "\"bm25-noise\",\"Project\""},
4670+
};
4671+
for (size_t i = 0; i < sizeof(named) / sizeof(named[0]); i++) {
4672+
char *inner = bm25_noise_search(srv, "noise config", named[i].label);
4673+
ASSERT_NOT_NULL(inner);
4674+
ASSERT_NOT_NULL(strstr(inner, "\"search_mode\":\"bm25\""));
4675+
ASSERT_NOT_NULL(strstr(inner, named[i].qn));
4676+
ASSERT_NOT_NULL(strstr(inner, "\"total\":1,"));
4677+
ASSERT_NOT_NULL(strstr(inner, "\"total_relation\":\"eq\""));
4678+
ASSERT_NULL(strstr(inner, "\"hint\""));
4679+
free(inner);
4680+
}
4681+
4682+
/* Without a label the four stay out of the ranking: only the Function. */
4683+
char *inner = bm25_noise_search(srv, "noise config", NULL);
4684+
ASSERT_NOT_NULL(inner);
4685+
ASSERT_NOT_NULL(strstr(inner, "\"bm25-noise.app.loadconfig\",\"Function\""));
4686+
ASSERT_NOT_NULL(strstr(inner, "\"total\":1,"));
4687+
ASSERT_NULL(strstr(inner, "\"File\""));
4688+
ASSERT_NULL(strstr(inner, "\"Folder\""));
4689+
ASSERT_NULL(strstr(inner, "\"Variable\""));
4690+
ASSERT_NULL(strstr(inner, "\"Project\""));
4691+
free(inner);
4692+
4693+
cbm_mcp_server_free(srv);
4694+
PASS();
4695+
}
4696+
4697+
/* Labels are case-sensitive. A BM25 query whose label no node carries as
4698+
* spelled answers 0 rows like the structural path does, but never silently:
4699+
* the hint names the stored spelling, or get_graph_schema when the label is
4700+
* unknown. An existing label with no matching row is a true zero: no hint. */
4701+
TEST(tool_search_graph_bm25_zero_hint_names_the_label) {
4702+
cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
4703+
ASSERT_NOT_NULL(srv);
4704+
cbm_store_t *store = cbm_mcp_server_store(srv);
4705+
ASSERT_NOT_NULL(store);
4706+
cbm_mcp_server_set_project(srv, "bm25-noise");
4707+
bm25_unranked_labels_fixture(store, "bm25-noise");
4708+
4709+
char *inner = bm25_noise_search(srv, "config", "folder");
4710+
ASSERT_NOT_NULL(inner);
4711+
ASSERT_NOT_NULL(strstr(inner, "\"total\":0,"));
4712+
ASSERT_NOT_NULL(strstr(inner, "\"hint\":"));
4713+
ASSERT_NOT_NULL(strstr(inner, "retry with label=\\\"Folder\\\""));
4714+
free(inner);
4715+
4716+
inner = bm25_noise_search(srv, "config", "Widget");
4717+
ASSERT_NOT_NULL(inner);
4718+
ASSERT_NOT_NULL(strstr(inner, "\"total\":0,"));
4719+
ASSERT_NOT_NULL(strstr(inner, "get_graph_schema"));
4720+
free(inner);
4721+
4722+
inner = bm25_noise_search(srv, "zzznomatch", "Function");
4723+
ASSERT_NOT_NULL(inner);
4724+
ASSERT_NOT_NULL(strstr(inner, "\"total\":0,"));
4725+
ASSERT_NULL(strstr(inner, "\"hint\""));
4726+
free(inner);
4727+
4728+
cbm_mcp_server_free(srv);
4729+
PASS();
4730+
}
4731+
46054732
/* The definition whose NAME is the query ranks first: the `Table` class above
46064733
* its own methods and above test methods that repeat "table" three times; the
46074734
* `get_object_or_404` function above the test methods that contain it. */
@@ -25207,6 +25334,8 @@ SUITE(mcp) {
2520725334
RUN_TEST(tool_search_graph_bm25_applies_label_filter);
2520825335
RUN_TEST(tool_search_graph_bm25_label_filter_selects_candidate_window);
2520925336
RUN_TEST(tool_search_graph_bm25_label_scope_keeps_rank_order);
25337+
RUN_TEST(tool_search_graph_bm25_serves_unranked_labels_when_named);
25338+
RUN_TEST(tool_search_graph_bm25_zero_hint_names_the_label);
2521025339
RUN_TEST(tool_search_graph_bm25_ranks_exact_name_first);
2521125340
RUN_TEST(tool_search_graph_rejects_bm25_and_semantic_query_together);
2521225341
RUN_TEST(tool_search_graph_semantic_ceiling_never_emits_unusable_continuation);

0 commit comments

Comments
 (0)