Skip to content

Commit 4843a34

Browse files
committed
feat(mcp): TOON compact output for search_graph — ~90% fewer response tokens
Tool responses land in an LLM agent's context window, where the legacy per-node JSON objects were dominated by data no agent can use: the similarity/semantic pipeline intermediates fp (~450B minhash hex), bt (body-token bag) and sp (structural profile) plus 14 complexity metrics were grafted onto every result by enrich_node_properties — ~64% of every node emission, ~370 tokens per search hit. search_graph now defaults to TOON (Token-Oriented Object Notation, toonformat.dev): scalars as 'key: value' lines and results as a 'results[N]{qn,label,file,lines,in,out}:' header + one row per hit. Published benchmarks show equal-or-better LLM retrieval accuracy at 40-60% fewer tokens than JSON; rows now also carry line ranges, which the legacy output lacked. - fields:[...] opts into per-node property columns (complexity, signature, docstring, ...); fp/sp/bt are blocklisted even there - format:"json" restores the legacy verbose objects byte-identically; include_connected forces it (nested neighbor lists) - BM25 and semantic modes emit the same table shape (rank/score column) - semantic-only calls no longer run the unfiltered regex search that silently prepended up to 200 enriched nodes (102.8KB -> 4.2KB) - default limit 200 -> 50 (BM25 100 -> 50): cheap first page, page via has_more/offset as before - new emitter module src/mcp/compact_out.{c,h} (string builder + TOON scalar/table emission with spec quoting rules) Measured on a real index (14-hit regex search): 20,793B -> 1,327B (-94%); BM25 19,667B -> 5,081B; semantic 102,837B -> 4,181B. A typical discovery session drops ~50.9K -> ~4.7K tokens combined with the follow-up slices. Guards: tool_search_graph_toon_never_leaks_internal_fields (sentinel fp/sp/bt never emitted, even when requested), rewritten tool_search_graph_includes_node_properties pins default-lean/fields- opt-in/json-escape-hatch; suite 5983 passed, smoke green. Signed-off-by: Martin Vogel <martin.vogel.tech@gmail.com>
1 parent 2dca0a3 commit 4843a34

8 files changed

Lines changed: 724 additions & 45 deletions

File tree

‎Makefile.cbm‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -174,7 +174,7 @@ STORE_SRCS = src/store/store.c
174174
CYPHER_SRCS = src/cypher/cypher.c
175175

176176
# MCP server module (new)
177-
MCP_SRCS = src/mcp/mcp.c src/mcp/index_supervisor.c
177+
MCP_SRCS = src/mcp/mcp.c src/mcp/index_supervisor.c src/mcp/compact_out.c
178178

179179
# Discover module (new)
180180
DISCOVER_SRCS = \

‎scripts/smoke-test.sh‎

Lines changed: 18 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -174,7 +174,9 @@ PROJECT=$(echo "$RESULT" | python3 -c "import json,sys; d=json.loads(sys.stdin.r
174174
if ! SEARCH=$(cli search_graph --project "$PROJECT" --name-pattern compute); then
175175
echo "FAIL: search_graph (flag form) exited non-zero"; cat "$CLI_STDERR"; exit 1
176176
fi
177-
TOTAL=$(echo "$SEARCH" | python3 -c "import json,sys; d=json.loads(sys.stdin.read()); print(d.get('total',0))" 2>/dev/null || echo "0")
177+
# search_graph default output is TOON (key: value scalars + header/rows tables)
178+
TOTAL=$(echo "$SEARCH" | sed -n 's/^total: //p' | head -1)
179+
TOTAL=${TOTAL:-0}
178180
if [ "$TOTAL" -lt 1 ]; then
179181
echo "FAIL: search_graph for 'compute' returned 0 results"
180182
exit 1
@@ -207,7 +209,8 @@ echo "OK: schema has $LABELS node labels"
207209
if ! FOLDERS=$(cli search_graph --project "$PROJECT" --label Folder); then
208210
echo "FAIL: search_graph --label Folder exited non-zero"; cat "$CLI_STDERR"; exit 1
209211
fi
210-
FOLDER_COUNT=$(echo "$FOLDERS" | python3 -c "import json,sys; d=json.loads(sys.stdin.read()); print(d.get('total',0))" 2>/dev/null || echo "0")
212+
FOLDER_COUNT=$(echo "$FOLDERS" | sed -n 's/^total: //p' | head -1)
213+
FOLDER_COUNT=${FOLDER_COUNT:-0}
211214
if [ "$FOLDER_COUNT" -lt 2 ]; then
212215
echo "FAIL: expected at least 2 Folder nodes (src, src/pkg), got $FOLDER_COUNT"
213216
exit 1
@@ -396,36 +399,39 @@ echo "=== Phase 3h: CLI input-mode guards (flags / stdin / --args-file / --help
396399

397400
# Small helper: assert its stdin is a JSON object (exit non-zero otherwise).
398401
assert_json_obj() { python3 -c "import json,sys; d=json.loads(sys.stdin.read()); sys.exit(0 if isinstance(d,dict) else 1)" 2>/dev/null; }
402+
# search_graph emits TOON by default: a results/semantic table header proves
403+
# the tool parsed its typed flags and produced a well-formed response.
404+
assert_toon_table() { grep -qE '^(results|semantic)\[[0-9]+\]\{'; }
399405

400-
# B1: INTEGER flag — --limit is schema-typed integer; must parse to valid JSON.
406+
# B1: INTEGER flag — --limit is schema-typed integer; must parse and answer.
401407
if ! IM_INT=$(cli search_graph --project "$PROJECT" --name-pattern compute --limit 5); then
402408
echo "FAIL B1: search_graph --limit 5 exited non-zero"; cat "$CLI_STDERR"; exit 1
403409
fi
404-
if echo "$IM_INT" | assert_json_obj; then
405-
echo "OK B1: INTEGER flag (--limit 5) parsed → valid JSON"
410+
if echo "$IM_INT" | assert_toon_table; then
411+
echo "OK B1: INTEGER flag (--limit 5) parsed → TOON results table"
406412
else
407-
echo "FAIL B1: --limit 5 did not produce valid JSON"; echo "$IM_INT" | head -c 300; exit 1
413+
echo "FAIL B1: --limit 5 did not produce a TOON results table"; echo "$IM_INT" | head -c 300; exit 1
408414
fi
409415

410416
# B2: BOOLEAN bare flag — --exclude-entry-points with no value → true; must succeed.
411417
if ! IM_BOOL=$(cli search_graph --project "$PROJECT" --exclude-entry-points); then
412418
echo "FAIL B2: search_graph --exclude-entry-points exited non-zero"; cat "$CLI_STDERR"; exit 1
413419
fi
414-
if echo "$IM_BOOL" | assert_json_obj; then
420+
if echo "$IM_BOOL" | assert_toon_table; then
415421
echo "OK B2: BOOLEAN bare flag (--exclude-entry-points) → success"
416422
else
417-
echo "FAIL B2: --exclude-entry-points did not produce valid JSON"; echo "$IM_BOOL" | head -c 300; exit 1
423+
echo "FAIL B2: --exclude-entry-points did not produce a TOON results table"; echo "$IM_BOOL" | head -c 300; exit 1
418424
fi
419425

420426
# B3: ARRAY flag — repeated --semantic-query accumulates into a JSON array.
421-
# semantic_results may be empty (index-mode dependent); only assert valid JSON.
427+
# Semantic-only calls emit ONLY the semantic table (may be empty, header stays).
422428
if ! IM_ARR=$(cli search_graph --project "$PROJECT" --semantic-query send --semantic-query publish); then
423429
echo "FAIL B3: search_graph repeated --semantic-query exited non-zero"; cat "$CLI_STDERR"; exit 1
424430
fi
425-
if echo "$IM_ARR" | assert_json_obj; then
426-
echo "OK B3: ARRAY flag (repeated --semantic-query) → valid JSON"
431+
if echo "$IM_ARR" | grep -qE '^semantic\[[0-9]+\]\{'; then
432+
echo "OK B3: ARRAY flag (repeated --semantic-query) → semantic TOON table"
427433
else
428-
echo "FAIL B3: repeated --semantic-query did not produce valid JSON"; echo "$IM_ARR" | head -c 300; exit 1
434+
echo "FAIL B3: repeated --semantic-query did not produce a semantic table"; echo "$IM_ARR" | head -c 300; exit 1
429435
fi
430436

431437
# B4: STDIN — piped JSON resolves; this path must NOT emit a deprecation warning.

‎src/foundation/constants.h‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -70,11 +70,11 @@ enum {
7070

7171
/* ── Default pagination limits ───────────────────────────────── */
7272
/* Default page size for search_graph and the underlying store-layer search.
73-
* Chosen so a typical broad query (e.g. file_pattern="**" on a 12k-node
74-
* project) stays well within MCP tool-result size budgets. Callers that
75-
* want more results paginate via offset+limit; the response always carries
76-
* 'total' and 'has_more' so agents can detect truncation. */
77-
enum { CBM_DEFAULT_SEARCH_LIMIT = 200 };
73+
* Responses land in an LLM agent's context window, so the default favors a
74+
* cheap first page (~50 TOON rows ≈ 1.5K tokens) over raw coverage; the
75+
* response always carries 'total' and 'has_more', and agents page via
76+
* offset+limit or narrow with label/file_pattern when has_more is true. */
77+
enum { CBM_DEFAULT_SEARCH_LIMIT = 50 };
7878

7979
/* ── Time conversion factors ─────────────────────────────────── */
8080
#define CBM_NSEC_PER_SEC 1000000000ULL

‎src/mcp/compact_out.c‎

Lines changed: 230 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,230 @@
1+
/* compact_out.c — TOON emission helpers. See compact_out.h for the contract. */
2+
#include "mcp/compact_out.h"
3+
4+
#include <ctype.h>
5+
#include <stdio.h>
6+
#include <stdlib.h>
7+
#include <string.h>
8+
9+
enum { SB_INITIAL_CAP = 1024 };
10+
11+
void cbm_sb_init(cbm_sb_t *sb) {
12+
sb->buf = NULL;
13+
sb->len = 0;
14+
sb->cap = 0;
15+
sb->oom = false;
16+
}
17+
18+
static bool sb_reserve(cbm_sb_t *sb, size_t extra) {
19+
if (sb->oom) {
20+
return false;
21+
}
22+
if (sb->len + extra + 1 <= sb->cap) {
23+
return true;
24+
}
25+
size_t ncap = sb->cap ? sb->cap : SB_INITIAL_CAP;
26+
while (ncap < sb->len + extra + 1) {
27+
ncap *= 2;
28+
}
29+
char *nbuf = (char *)realloc(sb->buf, ncap);
30+
if (!nbuf) {
31+
sb->oom = true;
32+
return false;
33+
}
34+
sb->buf = nbuf;
35+
sb->cap = ncap;
36+
return true;
37+
}
38+
39+
void cbm_sb_append_n(cbm_sb_t *sb, const char *s, size_t n) {
40+
if (!s || n == 0 || !sb_reserve(sb, n)) {
41+
return;
42+
}
43+
memcpy(sb->buf + sb->len, s, n);
44+
sb->len += n;
45+
sb->buf[sb->len] = '\0';
46+
}
47+
48+
void cbm_sb_append(cbm_sb_t *sb, const char *s) {
49+
if (s) {
50+
cbm_sb_append_n(sb, s, strlen(s));
51+
}
52+
}
53+
54+
char *cbm_sb_finish(cbm_sb_t *sb) {
55+
if (sb->oom) {
56+
free(sb->buf);
57+
cbm_sb_init(sb);
58+
return NULL;
59+
}
60+
if (!sb->buf) {
61+
/* Empty but valid: return an owned empty string. */
62+
char *empty = (char *)calloc(1, 1);
63+
return empty;
64+
}
65+
char *out = sb->buf;
66+
cbm_sb_init(sb);
67+
return out;
68+
}
69+
70+
void cbm_sb_free(cbm_sb_t *sb) {
71+
free(sb->buf);
72+
cbm_sb_init(sb);
73+
}
74+
75+
/* ── TOON quoting ───────────────────────────────────────────────── */
76+
77+
/* True when `s` parses as an integer or real literal (sign, digits, one dot). */
78+
static bool looks_numeric(const char *s) {
79+
if (!s || !*s) {
80+
return false;
81+
}
82+
const char *p = s;
83+
if (*p == '-' || *p == '+') {
84+
p++;
85+
}
86+
bool digit = false;
87+
bool dot = false;
88+
for (; *p; p++) {
89+
if (isdigit((unsigned char)*p)) {
90+
digit = true;
91+
} else if (*p == '.' && !dot) {
92+
dot = true;
93+
} else {
94+
return false;
95+
}
96+
}
97+
return digit;
98+
}
99+
100+
static bool needs_quotes(const char *s) {
101+
if (!s || !*s) {
102+
return true; /* empty cell must be visible as "" */
103+
}
104+
if (isspace((unsigned char)s[0]) || isspace((unsigned char)s[strlen(s) - 1])) {
105+
return true;
106+
}
107+
for (const char *p = s; *p; p++) {
108+
if (*p == ',' || *p == '"' || *p == '\n' || *p == '\r') {
109+
return true;
110+
}
111+
}
112+
if (strcmp(s, "true") == 0 || strcmp(s, "false") == 0 || strcmp(s, "null") == 0) {
113+
return true;
114+
}
115+
return looks_numeric(s);
116+
}
117+
118+
static void append_quoted(cbm_sb_t *sb, const char *s) {
119+
cbm_sb_append_n(sb, "\"", 1);
120+
for (const char *p = s ? s : ""; *p; p++) {
121+
switch (*p) {
122+
case '"':
123+
cbm_sb_append_n(sb, "\\\"", 2);
124+
break;
125+
case '\\':
126+
cbm_sb_append_n(sb, "\\\\", 2);
127+
break;
128+
case '\n':
129+
cbm_sb_append_n(sb, "\\n", 2);
130+
break;
131+
case '\r':
132+
cbm_sb_append_n(sb, "\\r", 2);
133+
break;
134+
default:
135+
cbm_sb_append_n(sb, p, 1);
136+
break;
137+
}
138+
}
139+
cbm_sb_append_n(sb, "\"", 1);
140+
}
141+
142+
static void append_value(cbm_sb_t *sb, const char *s) {
143+
if (needs_quotes(s)) {
144+
append_quoted(sb, s);
145+
} else {
146+
cbm_sb_append(sb, s);
147+
}
148+
}
149+
150+
/* ── Scalars ────────────────────────────────────────────────────── */
151+
152+
void cbm_toon_scalar_str(cbm_sb_t *sb, const char *key, const char *val) {
153+
cbm_sb_append(sb, key);
154+
cbm_sb_append_n(sb, ": ", 2);
155+
append_value(sb, val);
156+
cbm_sb_append_n(sb, "\n", 1);
157+
}
158+
159+
void cbm_toon_scalar_int(cbm_sb_t *sb, const char *key, long long v) {
160+
char num[32];
161+
snprintf(num, sizeof(num), "%lld", v);
162+
cbm_sb_append(sb, key);
163+
cbm_sb_append_n(sb, ": ", 2);
164+
cbm_sb_append(sb, num);
165+
cbm_sb_append_n(sb, "\n", 1);
166+
}
167+
168+
void cbm_toon_scalar_bool(cbm_sb_t *sb, const char *key, bool v) {
169+
cbm_sb_append(sb, key);
170+
cbm_sb_append_n(sb, ": ", 2);
171+
cbm_sb_append(sb, v ? "true" : "false");
172+
cbm_sb_append_n(sb, "\n", 1);
173+
}
174+
175+
/* ── Tables ─────────────────────────────────────────────────────── */
176+
177+
void cbm_toon_table_header(cbm_sb_t *sb, const char *key, int n, const char *const *cols,
178+
int ncols) {
179+
char num[32];
180+
snprintf(num, sizeof(num), "[%d]{", n);
181+
cbm_sb_append(sb, key);
182+
cbm_sb_append(sb, num);
183+
for (int i = 0; i < ncols; i++) {
184+
if (i > 0) {
185+
cbm_sb_append_n(sb, ",", 1);
186+
}
187+
cbm_sb_append(sb, cols[i]);
188+
}
189+
cbm_sb_append_n(sb, "}:\n", 3);
190+
}
191+
192+
void cbm_toon_row_begin(cbm_sb_t *sb) {
193+
cbm_sb_append_n(sb, " ", 2);
194+
}
195+
196+
void cbm_toon_cell_str(cbm_sb_t *sb, const char *val, bool first) {
197+
if (!first) {
198+
cbm_sb_append_n(sb, ",", 1);
199+
}
200+
append_value(sb, val ? val : "");
201+
}
202+
203+
void cbm_toon_cell_int(cbm_sb_t *sb, long long v, bool first) {
204+
char num[32];
205+
snprintf(num, sizeof(num), "%lld", v);
206+
if (!first) {
207+
cbm_sb_append_n(sb, ",", 1);
208+
}
209+
cbm_sb_append(sb, num);
210+
}
211+
212+
void cbm_toon_cell_real(cbm_sb_t *sb, double v, bool first) {
213+
char num[48];
214+
snprintf(num, sizeof(num), "%.4g", v);
215+
if (!first) {
216+
cbm_sb_append_n(sb, ",", 1);
217+
}
218+
cbm_sb_append(sb, num);
219+
}
220+
221+
void cbm_toon_cell_bool(cbm_sb_t *sb, bool v, bool first) {
222+
if (!first) {
223+
cbm_sb_append_n(sb, ",", 1);
224+
}
225+
cbm_sb_append(sb, v ? "true" : "false");
226+
}
227+
228+
void cbm_toon_row_end(cbm_sb_t *sb) {
229+
cbm_sb_append_n(sb, "\n", 1);
230+
}

‎src/mcp/compact_out.h‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
/* compact_out.h — TOON (Token-Oriented Object Notation) emission helpers.
2+
*
3+
* Tool responses are consumed by LLM agents, where every byte is context
4+
* tokens. TOON encodes the same data as JSON but declares tabular fields
5+
* once in a header and streams rows line by line, cutting 40-60% of tokens
6+
* on homogeneous result sets at equal-or-better retrieval accuracy
7+
* (toonformat.dev/guide/benchmarks). Emitters here cover the subset we
8+
* emit: scalar key-value lines and flat tables with explicit [N] lengths.
9+
*
10+
* Quoting: a cell/scalar is double-quoted iff it is empty, has leading or
11+
* trailing whitespace, contains a comma, quote, newline, or CR, or would
12+
* read as a non-string literal (true/false/null/number). Quotes and
13+
* backslashes are escaped JSON-style; newlines become \n.
14+
*/
15+
#ifndef CBM_MCP_COMPACT_OUT_H
16+
#define CBM_MCP_COMPACT_OUT_H
17+
18+
#include <stdbool.h>
19+
#include <stddef.h>
20+
21+
/* Minimal growing string buffer (OOM-safe: sticky flag, finish returns NULL). */
22+
typedef struct {
23+
char *buf;
24+
size_t len;
25+
size_t cap;
26+
bool oom;
27+
} cbm_sb_t;
28+
29+
void cbm_sb_init(cbm_sb_t *sb);
30+
void cbm_sb_append_n(cbm_sb_t *sb, const char *s, size_t n);
31+
void cbm_sb_append(cbm_sb_t *sb, const char *s);
32+
/* Returns the heap buffer (caller frees) and resets sb. NULL on OOM. */
33+
char *cbm_sb_finish(cbm_sb_t *sb);
34+
void cbm_sb_free(cbm_sb_t *sb);
35+
36+
/* `key: value` scalar lines (top-level, no indent). */
37+
void cbm_toon_scalar_str(cbm_sb_t *sb, const char *key, const char *val);
38+
void cbm_toon_scalar_int(cbm_sb_t *sb, const char *key, long long v);
39+
void cbm_toon_scalar_bool(cbm_sb_t *sb, const char *key, bool v);
40+
41+
/* `key[n]{col1,col2,...}:` table header; rows follow at 2-space indent. */
42+
void cbm_toon_table_header(cbm_sb_t *sb, const char *key, int n, const char *const *cols,
43+
int ncols);
44+
45+
/* Row cells: call row_begin, then cell_* per column (first=true for the
46+
* first cell), then row_end. Empty/NULL strings emit as empty cells. */
47+
void cbm_toon_row_begin(cbm_sb_t *sb);
48+
void cbm_toon_cell_str(cbm_sb_t *sb, const char *val, bool first);
49+
void cbm_toon_cell_int(cbm_sb_t *sb, long long v, bool first);
50+
void cbm_toon_cell_real(cbm_sb_t *sb, double v, bool first);
51+
void cbm_toon_cell_bool(cbm_sb_t *sb, bool v, bool first);
52+
void cbm_toon_row_end(cbm_sb_t *sb);
53+
54+
#endif /* CBM_MCP_COMPACT_OUT_H */

0 commit comments

Comments
 (0)