Skip to content

Commit fe3c285

Browse files
committed
fix(mcp): annotate get_file_outline and ingest_traces as read-only (DeusData#2118)
v0.11.0 corrected the ten query tools reported in DeusData#2118, but two entries in TOOL_ANNOTATIONS still advertised the wrong behaviour in tools/list: - get_file_outline was {readOnlyHint:false, destructiveHint:true}. It was added after the read-only split and kept a conservative default, yet it reads through the same non-mutating resolve_store() query path as search_graph and friends and never writes. - ingest_traces was {readOnlyHint:false, idempotentHint:false}. Its handler only parses and counts the traces array (edge creation is not implemented), so it writes nothing and is idempotent. Clients that gate auto-approval on these hints prompted for, or skipped, two safe tools. Both are now read-only, non-destructive and idempotent. The handlers that write user-visible state (index_repository, manage_adr, delete_project) keep their annotations unchanged. A new test walks the registered tool list (cbm_mcp_tool_count / cbm_mcp_tool_name) rather than a mirrored table and asserts that only an explicit mutator allowlist may clear readOnlyHint and only its destructive subset may set destructiveHint, so a newly added tool cannot inherit a wrong default unnoticed. The exact-value table test is updated to match. Refs DeusData#2118 Signed-off-by: Martin Vogel <martin.vogel.tech@gmail.com>
1 parent 9d65f4c commit fe3c285

2 files changed

Lines changed: 90 additions & 7 deletions

File tree

‎src/mcp/mcp.c‎

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -769,14 +769,19 @@ typedef struct {
769769
* left in place, never quarantined or rebuilt — quarantine/rebuild is reserved
770770
* for write-side opens (index_repository, manage_adr writes). That is what
771771
* makes readOnlyHint=true honest for them and lets plan-mode clients expose
772-
* them (the "read-only analysis tools" surface described in #1100). */
772+
* them (the "read-only analysis tools" surface described in #1100).
773+
* get_file_outline reads through the same resolve_store() path, and
774+
* ingest_traces only validates and counts its input (edge creation is not
775+
* implemented), so both are read-only too (#2118). Only handlers that write
776+
* user-visible state -- index_repository, manage_adr, delete_project -- may
777+
* clear readOnlyHint. */
773778
static const tool_annotation_def_t TOOL_ANNOTATIONS[] = {
774779
{"index_repository", false, false, true, false},
775780
{"search_graph", true, false, true, false},
776781
{"query_graph", true, false, true, false},
777782
{"trace_path", true, false, true, false},
778783
{"get_code_snippet", true, false, true, false},
779-
{"get_file_outline", false, true, true, false},
784+
{"get_file_outline", true, false, true, false},
780785
{"get_graph_schema", true, false, true, false},
781786
{"compare_graphs", true, false, true, false},
782787
{"get_architecture", true, false, true, false},
@@ -787,7 +792,7 @@ static const tool_annotation_def_t TOOL_ANNOTATIONS[] = {
787792
{"check_index_coverage", true, false, true, false},
788793
{"detect_changes", true, false, true, false},
789794
{"manage_adr", false, true, false, false},
790-
{"ingest_traces", false, false, false, false},
795+
{"ingest_traces", true, false, true, false},
791796
};
792797

793798
static const tool_annotation_def_t *mcp_tool_annotations(const char *name) {

‎tests/test_mcp.c‎

Lines changed: 82 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1397,13 +1397,13 @@ TEST(mcp_tools_have_behavior_annotations) {
13971397
* left in place, never quarantined or rebuilt. Quarantine/rebuild is
13981398
* a write-side job (index_repository, manage_adr writes), so the
13991399
* read-only annotations are honest and plan-mode clients can expose
1400-
* these tools. get_file_outline arrived after this split and keeps
1401-
* its upstream conservative annotation. */
1400+
* these tools. get_file_outline reads through the same resolve_store
1401+
* path and is annotated the same way (#2118). */
14021402
{"search_graph", true, false, true, false},
14031403
{"query_graph", true, false, true, false},
14041404
{"trace_path", true, false, true, false},
14051405
{"get_code_snippet", true, false, true, false},
1406-
{"get_file_outline", false, true, true, false},
1406+
{"get_file_outline", true, false, true, false},
14071407
{"get_graph_schema", true, false, true, false},
14081408
{"compare_graphs", true, false, true, false},
14091409
{"get_architecture", true, false, true, false},
@@ -1414,7 +1414,10 @@ TEST(mcp_tools_have_behavior_annotations) {
14141414
{"check_index_coverage", true, false, true, false},
14151415
{"detect_changes", true, false, true, false},
14161416
{"manage_adr", false, true, false, false},
1417-
{"ingest_traces", false, false, false, false},
1417+
/* ingest_traces only validates and counts its input; it writes
1418+
* nothing, so it is read-only and idempotent until edge creation
1419+
* actually lands (#2118). */
1420+
{"ingest_traces", true, false, true, false},
14181421
};
14191422

14201423
char *json = cbm_mcp_tools_list();
@@ -1467,6 +1470,80 @@ TEST(mcp_tools_have_behavior_annotations) {
14671470
PASS();
14681471
}
14691472

1473+
/* #2118: annotations drive client auto-approval, so a mis-stamped read tool
1474+
* is a real integration bug. Walk the REGISTERED tool list (not a mirrored
1475+
* table) so a newly added tool cannot slip through: every tool must carry
1476+
* annotations, a read-only tool can never be destructive, and only the tools
1477+
* whose handlers actually mutate state may be non-read-only. */
1478+
static yyjson_val *find_tool_json(yyjson_val *tools, const char *name) {
1479+
yyjson_arr_iter iter;
1480+
yyjson_arr_iter_init(tools, &iter);
1481+
yyjson_val *tool;
1482+
while ((tool = yyjson_arr_iter_next(&iter)) != NULL) {
1483+
const char *tool_name = yyjson_get_str(yyjson_obj_get(tool, "name"));
1484+
if (tool_name && strcmp(tool_name, name) == 0) {
1485+
return tool;
1486+
}
1487+
}
1488+
return NULL;
1489+
}
1490+
1491+
static bool tool_in_list(const char *name, const char *const *list, size_t count) {
1492+
for (size_t i = 0; i < count; i++) {
1493+
if (strcmp(name, list[i]) == 0) {
1494+
return true;
1495+
}
1496+
}
1497+
return false;
1498+
}
1499+
1500+
TEST(mcp_tool_annotations_only_mutators_are_writable_issue2118) {
1501+
/* Handlers that write user-visible state: index_repository (builds the
1502+
* index), manage_adr (writes/overwrites ADR sections), delete_project
1503+
* (removes the index). Everything else must be read-only. */
1504+
static const char *const mutating[] = {"index_repository", "manage_adr", "delete_project"};
1505+
/* Of those, only the ones that can remove/overwrite existing data. */
1506+
static const char *const destructive[] = {"manage_adr", "delete_project"};
1507+
const size_t n_mut = sizeof(mutating) / sizeof(mutating[0]);
1508+
const size_t n_des = sizeof(destructive) / sizeof(destructive[0]);
1509+
1510+
char *json = cbm_mcp_tools_list();
1511+
ASSERT_NOT_NULL(json);
1512+
yyjson_doc *doc = yyjson_read(json, strlen(json), 0);
1513+
ASSERT_NOT_NULL(doc);
1514+
yyjson_val *tools = yyjson_obj_get(yyjson_doc_get_root(doc), "tools");
1515+
ASSERT_NOT_NULL(tools);
1516+
1517+
int count = cbm_mcp_tool_count();
1518+
ASSERT_GT(count, 0);
1519+
ASSERT_EQ(yyjson_arr_size(tools), (size_t)count);
1520+
for (int i = 0; i < count; i++) {
1521+
const char *name = cbm_mcp_tool_name(i);
1522+
ASSERT_NOT_NULL(name);
1523+
yyjson_val *tool = find_tool_json(tools, name);
1524+
ASSERT_NOT_NULL(tool);
1525+
yyjson_val *annotations = yyjson_obj_get(tool, "annotations");
1526+
ASSERT_NOT_NULL(annotations);
1527+
yyjson_val *read_only = yyjson_obj_get(annotations, "readOnlyHint");
1528+
yyjson_val *destr = yyjson_obj_get(annotations, "destructiveHint");
1529+
ASSERT_TRUE(yyjson_is_bool(read_only));
1530+
ASSERT_TRUE(yyjson_is_bool(destr));
1531+
bool is_mut = tool_in_list(name, mutating, n_mut);
1532+
bool is_des = tool_in_list(name, destructive, n_des);
1533+
if (yyjson_get_bool(read_only) == is_mut || yyjson_get_bool(destr) != is_des) {
1534+
printf(" tool %s: readOnlyHint=%d destructiveHint=%d (want %d/%d)\n", name,
1535+
(int)yyjson_get_bool(read_only), (int)yyjson_get_bool(destr), (int)!is_mut,
1536+
(int)is_des);
1537+
}
1538+
ASSERT_EQ(yyjson_get_bool(read_only), !is_mut);
1539+
ASSERT_EQ(yyjson_get_bool(destr), is_des);
1540+
}
1541+
1542+
yyjson_doc_free(doc);
1543+
free(json);
1544+
PASS();
1545+
}
1546+
14701547
TEST(mcp_index_repository_declares_name_override_issue571) {
14711548
char *json = cbm_mcp_tools_list();
14721549
ASSERT_NOT_NULL(json);
@@ -20446,6 +20523,7 @@ SUITE(mcp) {
2044620523
RUN_TEST(mcp_discovery_defaults_match_runtime_contract);
2044720524
RUN_TEST(mcp_metadata_byte_budget);
2044820525
RUN_TEST(mcp_tools_have_behavior_annotations);
20526+
RUN_TEST(mcp_tool_annotations_only_mutators_are_writable_issue2118);
2044920527
RUN_TEST(mcp_index_repository_declares_name_override_issue571);
2045020528
RUN_TEST(mcp_tools_array_schemas_have_items);
2045120529
RUN_TEST(mcp_ingest_traces_items_disallow_additional_properties_issue731);

0 commit comments

Comments
 (0)