Skip to content

Commit 22f83b2

Browse files
DeusDataKirchlive
andcommitted
fix(mcp): get_architecture overview subset, aspects enum + validation
Distills the design from PR DeusData#560 onto current main: - "overview" now expands to every aspect except file_tree (the per-file listing that alone can push the payload past the MCP output cap). Previously the token matched nothing and silently degraded to just {total_nodes,total_edges}. Both aspect gates (want_aspect in store.c, aspect_wanted in mcp.c) share one predicate, cbm_store_arch_aspect_in_overview, declared in store.h so the two sites cannot drift. - The aspects items schema gains an enum of the 13 valid tokens (advisory, client-side), mirroring VALID_ASPECTS. - Server-side validation (authoritative): unknown aspect tokens now return an isError result listing the valid values instead of a silent near-empty response. Bounded snprintf; respects the existing 16-token aspects cap. Reproduce-first tests: overview-subset and unknown-aspect tests fail on the unfixed code; a parsed tools/list guard pins the schema enum. Co-authored-by: Kirchlive <roberto.livebox@gmail.com> Signed-off-by: Martin Vogel <martin.vogel.tech@gmail.com>
1 parent 09148ab commit 22f83b2

4 files changed

Lines changed: 258 additions & 4 deletions

File tree

‎src/mcp/mcp.c‎

Lines changed: 68 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -437,11 +437,15 @@ static const tool_def_t TOOLS[] = {
437437
"representative top_nodes, and the packages/edge_types that bind it) — use these to grasp "
438438
"the real architectural seams, which often cut across the folder layout. Optional path scopes "
439439
"analysis to nodes under that directory prefix (file_path).",
440+
/* The aspects enum mirrors VALID_ASPECTS (see aspect_is_valid) — update both together. */
440441
"{\"type\":\"object\",\"properties\":{\"project\":{\"type\":\"string\"},\"path\":{\"type\":"
441442
"\"string\",\"description\":\"Optional directory prefix to scope architecture (e.g. "
442443
"apps/hoa)\"},"
443-
"\"aspects\":{\"type\":\"array\",\"items\":{\"type\":\"string\"}}},\"required\":[\"project\"]"
444-
"}"},
444+
"\"aspects\":{\"type\":\"array\",\"items\":{\"type\":\"string\",\"enum\":[\"all\","
445+
"\"overview\",\"structure\",\"dependencies\",\"routes\",\"languages\",\"packages\","
446+
"\"entry_points\",\"hotspots\",\"boundaries\",\"layers\",\"file_tree\",\"clusters\"]},"
447+
"\"description\":\"Aspects to include. 'all' = everything; 'overview' = compact summary "
448+
"(all except file_tree); omit = all.\"}},\"required\":[\"project\"]}"},
445449

446450
{"search_code", "Search code",
447451
"Graph-augmented code search. Finds text patterns via grep, then enriches results with "
@@ -2244,7 +2248,29 @@ static char *handle_delete_project(cbm_mcp_server_t *srv, const char *args) {
22442248
return result;
22452249
}
22462250

2247-
/* Check if an aspect is requested (NULL aspects = all, or array contains "all" or the name). */
2251+
/* Canonical list of valid aspect tokens for get_architecture. Single source
2252+
* of truth for the server-side validation (authoritative); the JSON-Schema
2253+
* enum in the TOOLS entry above is the advisory client-side mirror — update
2254+
* both together when the aspect set changes. */
2255+
static const char *VALID_ASPECTS[] = {
2256+
"all", "overview", "structure", "dependencies", "routes", "languages", "packages",
2257+
"entry_points", "hotspots", "boundaries", "layers", "file_tree", "clusters", NULL};
2258+
2259+
static bool aspect_is_valid(const char *name) {
2260+
if (!name) {
2261+
return false;
2262+
}
2263+
for (int i = 0; VALID_ASPECTS[i]; i++) {
2264+
if (strcmp(name, VALID_ASPECTS[i]) == 0) {
2265+
return true;
2266+
}
2267+
}
2268+
return false;
2269+
}
2270+
2271+
/* Check if an aspect is requested. NULL aspects = all. The array can contain
2272+
* "all" (everything), "overview" (everything except file_tree — see
2273+
* cbm_store_arch_aspect_in_overview in store.c), or the aspect name itself. */
22482274
static bool aspect_wanted(yyjson_doc *aspects_doc, yyjson_val *aspects_arr, const char *name) {
22492275
if (!aspects_arr) {
22502276
return true; /* no filter = all */
@@ -2254,7 +2280,16 @@ static bool aspect_wanted(yyjson_doc *aspects_doc, yyjson_val *aspects_arr, cons
22542280
yyjson_val *val;
22552281
while ((val = yyjson_arr_iter_next(&iter)) != NULL) {
22562282
const char *s = yyjson_get_str(val);
2257-
if (s && (strcmp(s, "all") == 0 || strcmp(s, name) == 0)) {
2283+
if (!s) {
2284+
continue;
2285+
}
2286+
if (strcmp(s, "all") == 0) {
2287+
return true;
2288+
}
2289+
if (strcmp(s, "overview") == 0 && cbm_store_arch_aspect_in_overview(name)) {
2290+
return true;
2291+
}
2292+
if (strcmp(s, name) == 0) {
22582293
return true;
22592294
}
22602295
}
@@ -2331,6 +2366,35 @@ static char *handle_get_architecture(cbm_mcp_server_t *srv, const char *args) {
23312366
}
23322367
}
23332368

2369+
/* Server-side validation: reject unknown aspect tokens with an isError
2370+
* result listing the valid values. The JSON-Schema enum is advisory —
2371+
* many MCP clients do not validate arguments against tool schemas — so
2372+
* without this check a typo degraded to a silent near-empty payload. */
2373+
for (int i = 0; i < aspects_strs_count; i++) {
2374+
if (!aspect_is_valid(aspects_strs[i])) {
2375+
char valid_list[CBM_SZ_256];
2376+
size_t off = 0;
2377+
for (int j = 0; VALID_ASPECTS[j] && off < sizeof(valid_list); j++) {
2378+
int n = snprintf(valid_list + off, sizeof(valid_list) - off, "%s%s",
2379+
j > 0 ? ", " : "", VALID_ASPECTS[j]);
2380+
if (n < 0) {
2381+
break;
2382+
}
2383+
off += (size_t)n;
2384+
}
2385+
char msg[CBM_SZ_512];
2386+
snprintf(msg, sizeof(msg), "Unknown aspect '%s'. Valid: %s.", aspects_strs[i],
2387+
valid_list);
2388+
char *err = cbm_mcp_text_result(msg, true);
2389+
free(project);
2390+
free(scope_path);
2391+
if (aspects_doc) {
2392+
yyjson_doc_free(aspects_doc);
2393+
}
2394+
return err;
2395+
}
2396+
}
2397+
23342398
cbm_schema_info_t schema = {0};
23352399
/* Counts-only: this handler renders label/type counts but never property
23362400
* keys, and full key discovery json_each-scans every row (seconds-to-

‎src/store/store.c‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5450,6 +5450,15 @@ static int arch_clusters(cbm_store_t *s, const char *project, const char *path,
54505450

54515451
/* ── GetArchitecture dispatch ──────────────────────────────────── */
54525452

5453+
/* "overview" = compact architecture summary: every aspect EXCEPT the large
5454+
* per-file listing (file_tree), which alone dominates the payload on real
5455+
* repos and can push the MCP response past the output cap. Declared in
5456+
* store.h and shared with aspect_wanted in src/mcp/mcp.c so the store-side
5457+
* DB gate and the MCP-side serialization gate cannot drift. */
5458+
bool cbm_store_arch_aspect_in_overview(const char *name) {
5459+
return strcmp(name, "file_tree") != 0;
5460+
}
5461+
54535462
static bool want_aspect(const char **aspects, int aspect_count, const char *name) {
54545463
if (!aspects || aspect_count == 0) {
54555464
return true;
@@ -5458,6 +5467,9 @@ static bool want_aspect(const char **aspects, int aspect_count, const char *name
54585467
if (strcmp(aspects[i], "all") == 0) {
54595468
return true;
54605469
}
5470+
if (strcmp(aspects[i], "overview") == 0 && cbm_store_arch_aspect_in_overview(name)) {
5471+
return true;
5472+
}
54615473
if (strcmp(aspects[i], name) == 0) {
54625474
return true;
54635475
}

‎src/store/store.h‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -333,6 +333,12 @@ bool cbm_store_arch_path_scoped(const char *path);
333333
/* When scoped, writes normalized directory prefix into norm_out. Returns false if unscoped. */
334334
bool cbm_store_normalize_arch_path(const char *path, char *norm_out, size_t norm_sz);
335335

336+
/* True when architecture aspect `name` belongs to the "overview" subset:
337+
* every aspect EXCEPT the large per-file listing (file_tree). Shared by both
338+
* aspect gates — want_aspect (store.c) and aspect_wanted (mcp.c) — so the
339+
* two sites cannot drift. */
340+
bool cbm_store_arch_aspect_in_overview(const char *name);
341+
336342
/* Delete all nodes for a project (cascade deletes edges). */
337343
int cbm_store_delete_nodes_by_project(cbm_store_t *s, const char *project);
338344

‎tests/test_mcp.c‎

Lines changed: 172 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -361,6 +361,75 @@ TEST(mcp_ingest_traces_items_disallow_additional_properties_issue731) {
361361
PASS();
362362
}
363363

364+
/* Guard for PR #560 (schema enum): the get_architecture aspects items schema
365+
* must carry an enum of the valid tokens — including the new "overview" —
366+
* mirroring VALID_ASPECTS in mcp.c. Parsed structurally like
367+
* mcp_ingest_traces_items_disallow_additional_properties_issue731. */
368+
TEST(mcp_get_architecture_aspects_schema_enum_pr560) {
369+
char *json = cbm_mcp_tools_list();
370+
ASSERT_NOT_NULL(json);
371+
372+
yyjson_doc *doc = yyjson_read(json, strlen(json), 0);
373+
ASSERT_NOT_NULL(doc);
374+
yyjson_val *root = yyjson_doc_get_root(doc);
375+
ASSERT_NOT_NULL(root);
376+
yyjson_val *tools = yyjson_obj_get(root, "tools");
377+
ASSERT_NOT_NULL(tools);
378+
ASSERT_TRUE(yyjson_is_arr(tools));
379+
380+
yyjson_val *tool;
381+
yyjson_arr_iter iter;
382+
yyjson_arr_iter_init(tools, &iter);
383+
yyjson_val *get_arch = NULL;
384+
while ((tool = yyjson_arr_iter_next(&iter)) != NULL) {
385+
yyjson_val *name = yyjson_obj_get(tool, "name");
386+
if (name && yyjson_is_str(name) && strcmp(yyjson_get_str(name), "get_architecture") == 0) {
387+
get_arch = tool;
388+
break;
389+
}
390+
}
391+
ASSERT_NOT_NULL(get_arch);
392+
393+
yyjson_val *input_schema = yyjson_obj_get(get_arch, "inputSchema");
394+
ASSERT_NOT_NULL(input_schema);
395+
yyjson_val *properties = yyjson_obj_get(input_schema, "properties");
396+
ASSERT_NOT_NULL(properties);
397+
yyjson_val *aspects = yyjson_obj_get(properties, "aspects");
398+
ASSERT_NOT_NULL(aspects);
399+
ASSERT_STR_EQ(yyjson_get_str(yyjson_obj_get(aspects, "type")), "array");
400+
yyjson_val *items = yyjson_obj_get(aspects, "items");
401+
ASSERT_NOT_NULL(items);
402+
ASSERT_STR_EQ(yyjson_get_str(yyjson_obj_get(items, "type")), "string");
403+
yyjson_val *enum_arr = yyjson_obj_get(items, "enum");
404+
ASSERT_NOT_NULL(enum_arr);
405+
ASSERT_TRUE(yyjson_is_arr(enum_arr));
406+
407+
/* The enum must be exactly the valid-token set — no more, no less. */
408+
static const char *expected[] = {"all", "overview", "structure", "dependencies",
409+
"routes", "languages", "packages", "entry_points",
410+
"hotspots", "boundaries", "layers", "file_tree",
411+
"clusters"};
412+
size_t expected_count = sizeof(expected) / sizeof(expected[0]);
413+
ASSERT_EQ(yyjson_arr_size(enum_arr), expected_count);
414+
for (size_t i = 0; i < expected_count; i++) {
415+
bool found = false;
416+
yyjson_val *ev;
417+
yyjson_arr_iter eiter;
418+
yyjson_arr_iter_init(enum_arr, &eiter);
419+
while ((ev = yyjson_arr_iter_next(&eiter)) != NULL) {
420+
if (yyjson_is_str(ev) && strcmp(yyjson_get_str(ev), expected[i]) == 0) {
421+
found = true;
422+
break;
423+
}
424+
}
425+
ASSERT_TRUE(found);
426+
}
427+
428+
yyjson_doc_free(doc);
429+
free(json);
430+
PASS();
431+
}
432+
364433
TEST(mcp_text_result) {
365434
char *json = cbm_mcp_text_result("{\"total\":5}", false);
366435
ASSERT_NOT_NULL(json);
@@ -1118,6 +1187,106 @@ TEST(tool_get_architecture_emits_populated_sections) {
11181187
PASS();
11191188
}
11201189

1190+
/* Distills PR #560 (overview subset): "overview" must expand to a compact
1191+
* subset — every aspect EXCEPT file_tree. Before the fix, "overview" was not
1192+
* registered in either aspect gate (want_aspect in store.c, aspect_wanted in
1193+
* mcp.c), so aspects=["overview"] silently degraded to just
1194+
* {total_nodes,total_edges}. RED on unfixed code: no "entry_points" key. */
1195+
TEST(tool_get_architecture_overview_compact_subset_pr560) {
1196+
cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
1197+
ASSERT_NOT_NULL(srv);
1198+
1199+
cbm_store_t *st = cbm_mcp_server_store(srv);
1200+
ASSERT_NOT_NULL(st);
1201+
1202+
const char *proj = "arch560";
1203+
cbm_mcp_server_set_project(srv, proj);
1204+
cbm_store_upsert_project(st, proj, "/tmp/arch560");
1205+
1206+
cbm_node_t main_fn = {0};
1207+
main_fn.project = proj;
1208+
main_fn.label = "Function";
1209+
main_fn.name = "main";
1210+
main_fn.qualified_name = "arch560.cmd.main";
1211+
main_fn.file_path = "cmd/main.go";
1212+
main_fn.start_line = 1;
1213+
main_fn.end_line = 3;
1214+
main_fn.properties_json = "{\"is_entry_point\":true}";
1215+
ASSERT_GT(cbm_store_upsert_node(st, &main_fn), 0);
1216+
1217+
/* A File node so the file_tree aspect has real content — makes the
1218+
* "overview drops file_tree" assertion below non-vacuous. */
1219+
cbm_node_t file_node = {.project = proj,
1220+
.label = "File",
1221+
.name = "main.go",
1222+
.qualified_name = "arch560.cmd.main.go",
1223+
.file_path = "cmd/main.go"};
1224+
ASSERT_GT(cbm_store_upsert_node(st, &file_node), 0);
1225+
1226+
/* Sanity: with "all", both entry_points and file_tree surface. */
1227+
char *resp_all = cbm_mcp_server_handle(
1228+
srv, "{\"jsonrpc\":\"2.0\",\"id\":560,\"method\":\"tools/call\","
1229+
"\"params\":{\"name\":\"get_architecture\","
1230+
"\"arguments\":{\"project\":\"arch560\",\"aspects\":[\"all\"]}}}");
1231+
ASSERT_NOT_NULL(resp_all);
1232+
char *inner_all = extract_text_content(resp_all);
1233+
ASSERT_NOT_NULL(inner_all);
1234+
ASSERT_NOT_NULL(strstr(inner_all, "\"entry_points\""));
1235+
ASSERT_NOT_NULL(strstr(inner_all, "\"file_tree\""));
1236+
free(inner_all);
1237+
free(resp_all);
1238+
1239+
/* "overview": substantive content (entry_points, node_labels) but NO
1240+
* file_tree section. */
1241+
char *resp = cbm_mcp_server_handle(
1242+
srv, "{\"jsonrpc\":\"2.0\",\"id\":561,\"method\":\"tools/call\","
1243+
"\"params\":{\"name\":\"get_architecture\","
1244+
"\"arguments\":{\"project\":\"arch560\",\"aspects\":[\"overview\"]}}}");
1245+
ASSERT_NOT_NULL(resp);
1246+
char *inner = extract_text_content(resp);
1247+
ASSERT_NOT_NULL(inner);
1248+
ASSERT_NOT_NULL(strstr(inner, "\"entry_points\""));
1249+
ASSERT_NOT_NULL(strstr(inner, "\"node_labels\""));
1250+
ASSERT_NULL(strstr(inner, "\"file_tree\""));
1251+
1252+
free(inner);
1253+
free(resp);
1254+
cbm_mcp_server_free(srv);
1255+
PASS();
1256+
}
1257+
1258+
/* Distills PR #560 (server-side validation): unknown aspect tokens must be
1259+
* rejected with an isError result listing the valid values. Before the fix
1260+
* the JSON-Schema accepted any string and both aspect gates simply never
1261+
* matched, so a typo like "bogus_aspect" produced a silent near-empty payload
1262+
* with isError:false. RED on unfixed code: no isError, no "Unknown aspect". */
1263+
TEST(tool_get_architecture_rejects_unknown_aspect_pr560) {
1264+
cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
1265+
ASSERT_NOT_NULL(srv);
1266+
1267+
cbm_store_t *st = cbm_mcp_server_store(srv);
1268+
ASSERT_NOT_NULL(st);
1269+
1270+
const char *proj = "arch560v";
1271+
cbm_mcp_server_set_project(srv, proj);
1272+
cbm_store_upsert_project(st, proj, "/tmp/arch560v");
1273+
1274+
char *resp = cbm_mcp_server_handle(
1275+
srv, "{\"jsonrpc\":\"2.0\",\"id\":562,\"method\":\"tools/call\","
1276+
"\"params\":{\"name\":\"get_architecture\","
1277+
"\"arguments\":{\"project\":\"arch560v\",\"aspects\":[\"bogus_aspect\"]}}}");
1278+
ASSERT_NOT_NULL(resp);
1279+
ASSERT_NOT_NULL(strstr(resp, "\"isError\":true"));
1280+
ASSERT_NOT_NULL(strstr(resp, "Unknown aspect 'bogus_aspect'"));
1281+
/* The error must teach the valid vocabulary, including the new token. */
1282+
ASSERT_NOT_NULL(strstr(resp, "overview"));
1283+
ASSERT_NOT_NULL(strstr(resp, "file_tree"));
1284+
1285+
free(resp);
1286+
cbm_mcp_server_free(srv);
1287+
PASS();
1288+
}
1289+
11211290
/* Reproduce-first for #640: query handlers must accept the `project_name`
11221291
* alias, not only the canonical `project` key. list_projects surfaces the field
11231292
* as "name" and the error hint says "pass the project name", so a caller
@@ -3736,6 +3905,7 @@ SUITE(mcp) {
37363905
RUN_TEST(mcp_index_repository_declares_name_override_issue571);
37373906
RUN_TEST(mcp_tools_array_schemas_have_items);
37383907
RUN_TEST(mcp_ingest_traces_items_disallow_additional_properties_issue731);
3908+
RUN_TEST(mcp_get_architecture_aspects_schema_enum_pr560);
37393909
RUN_TEST(mcp_text_result);
37403910
RUN_TEST(mcp_text_result_skips_structured_content_for_plain_text);
37413911
RUN_TEST(mcp_cancel_matches_request_id);
@@ -3797,6 +3967,8 @@ SUITE(mcp) {
37973967
RUN_TEST(tool_delete_project_not_found);
37983968
RUN_TEST(tool_get_architecture_empty);
37993969
RUN_TEST(tool_get_architecture_emits_populated_sections);
3970+
RUN_TEST(tool_get_architecture_overview_compact_subset_pr560);
3971+
RUN_TEST(tool_get_architecture_rejects_unknown_aspect_pr560);
38003972
RUN_TEST(tool_get_architecture_accepts_project_name_alias_issue640);
38013973
RUN_TEST(tool_search_graph_accepts_project_name_alias_issue640);
38023974
RUN_TEST(tool_get_architecture_path_scoping);

0 commit comments

Comments
 (0)