Skip to content

Commit f2adf20

Browse files
HopsonOHopsonO
authored
Merge pull request #3 from O-Labz/token-reduction-v0.2
v0.2.0: cut MCP token usage 45.5% on day-to-day workflows
2 parents 5a5652b + 3879003 commit f2adf20

30 files changed

Lines changed: 1771 additions & 150 deletions

‎.cursor/rules/context-simplo-usage.mdc‎

Lines changed: 37 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -1,66 +1,53 @@
11
---
2-
description: Use Context-Simplo MCP for code intelligence and analysis
3-
alwaysApply: true
2+
description: Route code queries through Context-Simplo MCP
3+
alwaysApply: false
44
---
55

6-
# Context-Simplo MCP
6+
# Context-Simplo Routing
77

8-
MCP server: `user-context-simplo`. Use it **instead of** grep/ripgrep/Glob/SemanticSearch when the codebase is indexed.
8+
**MCP server:** `user-context-simplo`
9+
**Repository ID (pre-cached):** `f00acc4e11a3eac5`
910

10-
## Startup: call `list_repositories` first. If empty, call `index_repository` with path `/workspace`.
11+
## When to use
1112

12-
## Tool selection
13+
Use Context-Simplo **instead of** Grep/Glob/SemanticSearch/Read chains when:
1314

14-
- **Symbol by name** → `find_symbol` (with optional `kind` filter)
15-
- **Who calls X / what does X call** → `find_callers` / `find_callees`
16-
- **Execution path A→B** → `find_path`
17-
- **Conceptual search** ("how do we handle auth?") → `semantic_search`
18-
- **Literal search** (exact name/string) → `exact_search`
19-
- **Unsure** → `hybrid_search`
20-
- **Before any refactor** → `get_impact_radius` (check blast radius first)
21-
- **Code quality** → `find_dead_code`, `find_complex_functions`, `calculate_complexity`
22-
- **Architecture overview** → `explain_architecture`
23-
- **Validate proposed code** → `lint_context`
15+
- Searching for symbols by name, kind, or pattern
16+
- Finding callers/callees of a function
17+
- Tracing execution paths
18+
- Semantic/conceptual code queries
19+
- Impact analysis before refactoring
20+
- Architecture overviews
21+
- Code quality scans (dead code, complexity)
2422

25-
## Cost-saving rules
23+
**Skip Context-Simplo** for single-file edits where the file is already open.
2624

27-
- Prefer Context-Simplo over multi-file Read/Grep chains — one MCP call replaces many tool calls
28-
- Use `limit` parameter to cap results (default 10, increase only if needed)
29-
- Pass `repositoryId` to scope queries and avoid full-index scans
30-
- Use `incremental: true` when re-indexing after changes
31-
- Skip Context-Simplo for single-file edits where the file is already open/known
32-
33-
## Compact mode (token savings)
34-
35-
Set `CONTEXT_SIMPLO_RESPONSE_MODE=compact` in the server environment to enable ~60% input token savings.
25+
## Tool routing
3626

37-
In compact mode, response keys are abbreviated:
27+
| Query type | Tool |
28+
|------------|------|
29+
| Symbol by name | `find_symbol` (pass `kind` to filter) |
30+
| Who calls X / what does X call | `find_callers` / `find_callees` |
31+
| Path from A to B | `find_path` |
32+
| Conceptual ("how do we handle auth?") | `semantic_search` |
33+
| Exact name/string | `exact_search` |
34+
| Unsure | `hybrid_search` |
35+
| Pre-refactor check | `get_impact_radius` |
36+
| Code quality | `find_dead_code`, `find_complex_functions`, `calculate_complexity` |
37+
| Architecture | `explain_architecture` |
38+
| Validate code | `lint_context` |
3839

39-
| Full key | Compact | Full key | Compact |
40-
|----------|---------|----------|---------|
41-
| `results` / `callers` / `callees` | `r` | `repositoryId` | `rid` |
42-
| `name` | `n` | `language` | `lang` |
43-
| `qualifiedName` | `qn` | `nodeId` | `nid` |
44-
| `kind` | `k` | `score` | `s` |
45-
| `filePath` | `fp` | `isExported` | `x` |
46-
| `lineStart` | `ls` | `complexity` | `cx` |
47-
| `lineEnd` | `le` | `total` | `t` |
48-
| `symbol` | `sym` | `hasMore` | `m` |
49-
| `affectedNodes` | `nodes` | `searchType` | `st` |
50-
| `affectedFiles` | `files` | `entryPoints` | `entry` |
51-
| `modules` | `mods` | `keyAbstractions` | `abs` |
40+
## Token optimization
5241

53-
Compact mode also removes `null` values, `id` hash fields, `visibility`, `limit`, and `offset` from responses, and minifies JSON (no indentation). `repositoryId` and `language` are hoisted to the envelope when all results share the same value.
54-
55-
## Response style
56-
57-
Be direct and concise in all responses. Drop articles (a/an/the), filler (just/really/basically/simply), pleasantries (sure/certainly/of course), and hedging. Fragments OK. Use short synonyms: "fix" not "implement a solution for", "use" not "utilize". Technical terms, code blocks, and error messages stay exact.
42+
- Pass `repositoryId: "f00acc4e11a3eac5"` to all tools (avoids full-index scan)
43+
- Default `limit: 10` is sufficient; increase only if results are incomplete
44+
- Set `includeSnippets: true` only when code context is required for the answer
45+
- Use `incremental: true` when re-indexing after changes
5846

59-
Pattern: `[thing] [action] [reason]. [next step].`
47+
## Response format
6048

61-
Example — not: "Sure! I'd be happy to help. The issue you're experiencing is likely caused by..."
62-
Example — yes: "Bug in auth middleware. Token expiry uses `<` not `<=`. Fix:"
49+
Server runs in **compact mode** (60% token savings). Response keys abbreviated:
6350

64-
Exception: use full sentences for security warnings, irreversible operations, and multi-step sequences where brevity risks misreading.
51+
`r`=results/callers/callees, `n`=name, `qn`=qualifiedName, `k`=kind, `fp`=filePath, `ls`=lineStart, `le`=lineEnd, `rid`=repositoryId, `lang`=language, `s`=score, `t`=total, `m`=hasMore, `nid`=nodeId, `x`=isExported, `cx`=complexity, `st`=searchType, `sym`=symbol, `nodes`=affectedNodes, `files`=affectedFiles, `entry`=entryPoints, `mods`=modules, `abs`=keyAbstractions
6552

66-
Never create or edit `.md` files unless explicitly asked.
53+
Null values, `id` hash fields, `visibility`, `limit`, `offset` stripped. JSON minified.

‎.env.example‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -66,10 +66,10 @@ CONTEXT_SIMPLO_WATCH=true
6666
CONTEXT_SIMPLO_LOG_LEVEL=info
6767

6868
# Response mode for MCP tools: full or compact
69-
# - full: Complete responses with all metadata
70-
# - compact: ~60% smaller responses (abbreviated keys, no nulls)
71-
# Default: full
72-
CONTEXT_SIMPLO_RESPONSE_MODE=full
69+
# - full: Complete responses with all metadata (use for compatibility with parsers expecting original key names)
70+
# - compact: ~60% smaller responses (abbreviated keys, no nulls, minified JSON)
71+
# Default: compact (recommended for token savings)
72+
CONTEXT_SIMPLO_RESPONSE_MODE=compact
7373

7474
# =============================================================================
7575
# Performance Tuning

‎AGENTS.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# Agent Guidance: Context-Simplo
2+
3+
**MCP server:** `user-context-simplo`
4+
**Repository ID:** `f00acc4e11a3eac5`
5+
6+
## Routing Rules
7+
8+
Use Context-Simplo MCP **instead of** Grep, Glob, SemanticSearch, or multi-file Read chains when searching code, analyzing structure, or answering conceptual questions.
9+
10+
**Always pass** `repositoryId: "f00acc4e11a3eac5"` to avoid full-index scans.
11+
12+
### Tool Selection
13+
14+
| Task | Tool | Key Parameters |
15+
|------|------|----------------|
16+
| Find symbol by name | `find_symbol` | `name`, optional `kind` filter |
17+
| Who calls function X | `find_callers` | `symbolName` |
18+
| What does function X call | `find_callees` | `symbolName` |
19+
| Trace execution path A→B | `find_path` | `fromSymbol`, `toSymbol` |
20+
| Conceptual query ("how does auth work?") | `semantic_search` | `query`, `repositoryId` |
21+
| Exact string/symbol match | `exact_search` | `query` |
22+
| Mixed semantic + exact | `hybrid_search` | `query`, `repositoryId` |
23+
| Pre-refactor impact check | `get_impact_radius` | `symbolName` |
24+
| Find unused exports | `find_dead_code` | `repositoryId` |
25+
| Find complex functions | `find_complex_functions` | `repositoryId` |
26+
| Calculate cyclomatic complexity | `calculate_complexity` | `symbolName` |
27+
| Architecture summary | `explain_architecture` | `repositoryId`, `detailLevel: 1-3` |
28+
| Validate code snippet | `lint_context` | `language`, `code` |
29+
30+
### Token Optimization
31+
32+
- Default `limit: 10` is sufficient; increase only if results are truncated
33+
- Set `includeSnippets: true` only when code excerpts are required to answer the query
34+
- Use `incremental: true` when re-indexing after edits
35+
36+
### Response Format
37+
38+
Server runs in **compact mode** (abbreviated keys, minified JSON, no nulls). Key mappings:
39+
40+
- `r` = results/callers/callees
41+
- `n` = name
42+
- `qn` = qualifiedName
43+
- `k` = kind
44+
- `fp` = filePath
45+
- `ls` = lineStart
46+
- `le` = lineEnd
47+
- `rid` = repositoryId
48+
- `lang` = language
49+
- `s` = score
50+
- `t` = total
51+
- `m` = hasMore
52+
- `nid` = nodeId
53+
- `x` = isExported
54+
- `cx` = complexity
55+
- `st` = searchType
56+
- `sym` = symbol
57+
- `nodes` = affectedNodes
58+
- `files` = affectedFiles
59+
- `entry` = entryPoints
60+
- `mods` = modules
61+
- `abs` = keyAbstractions
62+
63+
Null values, hash `id`, `visibility`, `limit`, and `offset` fields are stripped.
64+
65+
### Skip Conditions
66+
67+
Do **not** use Context-Simplo for single-file edits where the file is already open or when the user has explicitly provided the file path.

‎CHANGELOG.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,67 @@ All notable changes to Context-Simplo will be documented in this file.
55
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
66
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
77

8+
## [0.2.0] - 2026-05-04
9+
10+
### BREAKING CHANGES
11+
12+
#### Response Mode Default
13+
- **Compact mode is now the default** (`CONTEXT_SIMPLO_RESPONSE_MODE=compact`)
14+
- Response keys abbreviated (e.g., `n`=name, `fp`=filePath, `r`=results)
15+
- JSON minified (no whitespace)
16+
- Null values, hash IDs, and metadata fields stripped
17+
- **Migration:** To preserve v0.1.0 behavior, set `CONTEXT_SIMPLO_RESPONSE_MODE=full` in your environment or `.env` file
18+
- **Impact:** ~60% token savings for AI assistants; existing parsers expecting full key names must be updated or use `full` mode
19+
20+
#### Search Tool Defaults
21+
- Default result `limit` reduced from `20` to `10` across all search/query tools
22+
- **Migration:** Explicitly pass `limit: 20` if you need more results, or paginate with `offset`
23+
- **Impact:** Reduced token cost per query; most workflows work well with 10 results
24+
25+
#### Code Snippets Opt-In
26+
- `exact_search`, `semantic_search`, and `hybrid_search` no longer include code snippets by default
27+
- **Migration:** Pass `includeSnippets: true` when you need source code context (up to 10 lines / 500 chars per result)
28+
- **Impact:** Significant token savings for symbol-only queries; snippets cost ~100-500 tokens per result
29+
30+
### Added
31+
32+
- **Startup Logging:** Active `responseMode` is now logged at server startup for operator visibility
33+
- **`includeSnippets` Parameter:** New boolean flag for search tools to opt-in to code snippet extraction
34+
- **Benchmark Harness:** Production benchmark suite (`scripts/benchmark.ts`, `scripts/benchmark-compare.ts`) with 10 day-to-day engineer workflow scenarios
35+
- **AGENTS.md:** Project-level AI agent guidance with pre-cached `repositoryId` and imperative routing rules
36+
37+
### Changed
38+
39+
- **Default Response Mode:** Changed from `full` to `compact` in `src/core/config.ts`
40+
- **Docker Compose:** Added `CONTEXT_SIMPLO_RESPONSE_MODE=compact` to default environment
41+
- **`.env.example`:** Updated to recommend `compact` mode with migration notes
42+
- **Tool Descriptions:** Removed 400+ token preamble from `TOOL_DEFINITIONS_COMPACT[0]`; updated default limit descriptions; removed false token cost estimates from `explain_architecture`
43+
- **Cursor Rule:** Rewritten `.cursor/rules/context-simplo-usage.mdc` with `alwaysApply: false`, tighter descriptions, imperative routing language, and pre-cached `repositoryId` (was adding ~800 tokens per turn)
44+
45+
### Fixed
46+
47+
- **Snippet Extraction Gating:** Search handlers now respect `includeSnippets` flag; snippets no longer extracted unconditionally (saving ~3-10KB per search call)
48+
49+
### Performance
50+
51+
- **Token Savings:** Typical engineer workflow shows 50-70% reduction in MCP response tokens compared to v0.1.0
52+
- **Rule Overhead:** Cursor rule token cost reduced from ~800/turn to 0 (opt-in via `@context-simplo`)
53+
- **Search Efficiency:** Default `limit=10` + snippet opt-in reduces average query cost by 40-60%
54+
55+
### Migration Guide
56+
57+
#### For Existing Deployments
58+
59+
1. **Test Compatibility:** If you have custom MCP clients or parsers, verify they handle abbreviated keys
60+
2. **Opt-Out (if needed):** Add `CONTEXT_SIMPLO_RESPONSE_MODE=full` to your environment to preserve v0.1.0 format
61+
3. **Update Queries:** Review queries that relied on default `limit=20` or automatic snippets; add explicit `limit` or `includeSnippets: true` where needed
62+
4. **Restart Server:** v0.2.0 requires a server restart to pick up new defaults
63+
64+
#### For AI Assistants (Cursor, VS Code, Claude Desktop)
65+
66+
- No changes required if using the MCP SDK (it handles both `full` and `compact` formats)
67+
- If parsing responses manually, update your parser to handle abbreviated keys or set `CONTEXT_SIMPLO_RESPONSE_MODE=full`
68+
869
## [0.1.0] - 2026-04-13
970

1071
### Added
@@ -126,4 +187,5 @@ Visit http://localhost:3001 for the dashboard.
126187

127188
---
128189

190+
[0.2.0]: https://github.com/ohopson/context-simplo/releases/tag/v0.2.0
129191
[0.1.0]: https://github.com/ohopson/context-simplo/releases/tag/v0.1.0

‎README.md‎

Lines changed: 39 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -257,73 +257,62 @@ Context-Simplo tools are most effective when your AI agent uses them automatical
257257

258258
```markdown
259259
---
260-
description: Use Context-Simplo MCP for code intelligence and analysis
261-
alwaysApply: true
260+
description: Route code queries through Context-Simplo MCP
261+
alwaysApply: false
262262
---
263263

264-
# Context-Simplo MCP
264+
# Context-Simplo Routing
265265

266-
MCP server: `user-context-simplo`. Use it **instead of** grep/ripgrep/Glob/SemanticSearch when the codebase is indexed.
266+
**MCP server:** `user-context-simplo`
267+
**Repository ID (pre-cached):** `<YOUR_REPO_ID>`
267268

268-
## Startup: call `list_repositories` first. If empty, call `index_repository` with path `/workspace`.
269+
## When to use
269270

270-
## Tool selection
271+
Use Context-Simplo **instead of** Grep/Glob/SemanticSearch/Read chains when:
271272

272-
- **Symbol by name** → `find_symbol` (with optional `kind` filter)
273-
- **Who calls X / what does X call** → `find_callers` / `find_callees`
274-
- **Execution path A→B** → `find_path`
275-
- **Conceptual search** ("how do we handle auth?") → `semantic_search`
276-
- **Literal search** (exact name/string) → `exact_search`
277-
- **Unsure** → `hybrid_search`
278-
- **Before any refactor** → `get_impact_radius` (check blast radius first)
279-
- **Code quality** → `find_dead_code`, `find_complex_functions`, `calculate_complexity`
280-
- **Architecture overview** → `explain_architecture`
281-
- **Validate proposed code** → `lint_context`
273+
- Searching for symbols by name, kind, or pattern
274+
- Finding callers/callees of a function
275+
- Tracing execution paths
276+
- Semantic/conceptual code queries
277+
- Impact analysis before refactoring
278+
- Architecture overviews
279+
- Code quality scans (dead code, complexity)
282280

283-
## Cost-saving rules
281+
**Skip Context-Simplo** for single-file edits where the file is already open.
284282

285-
- Prefer Context-Simplo over multi-file Read/Grep chains — one MCP call replaces many tool calls
286-
- Use `limit` parameter to cap results (default 10, increase only if needed)
287-
- Pass `repositoryId` to scope queries and avoid full-index scans
288-
- Use `incremental: true` when re-indexing after changes
289-
- Skip Context-Simplo for single-file edits where the file is already open/known
290-
291-
## Compact mode (token savings)
292-
293-
Set `CONTEXT_SIMPLO_RESPONSE_MODE=compact` in the server environment to enable ~60% input token savings.
294-
295-
In compact mode, response keys are abbreviated:
283+
## Tool routing
296284

297-
| Full key | Compact | Full key | Compact |
298-
|----------|---------|----------|---------|
299-
| `results` / `callers` / `callees` | `r` | `repositoryId` | `rid` |
300-
| `name` | `n` | `language` | `lang` |
301-
| `qualifiedName` | `qn` | `nodeId` | `nid` |
302-
| `kind` | `k` | `score` | `s` |
303-
| `filePath` | `fp` | `isExported` | `x` |
304-
| `lineStart` | `ls` | `complexity` | `cx` |
305-
| `lineEnd` | `le` | `total` | `t` |
306-
| `symbol` | `sym` | `hasMore` | `m` |
307-
| `affectedNodes` | `nodes` | `searchType` | `st` |
308-
| `affectedFiles` | `files` | `entryPoints` | `entry` |
309-
| `modules` | `mods` | `keyAbstractions` | `abs` |
285+
| Query type | Tool |
286+
|------------|------|
287+
| Symbol by name | `find_symbol` (pass `kind` to filter) |
288+
| Who calls X / what does X call | `find_callers` / `find_callees` |
289+
| Path from A to B | `find_path` |
290+
| Conceptual ("how do we handle auth?") | `semantic_search` |
291+
| Exact name/string | `exact_search` |
292+
| Unsure | `hybrid_search` |
293+
| Pre-refactor check | `get_impact_radius` |
294+
| Code quality | `find_dead_code`, `find_complex_functions`, `calculate_complexity` |
295+
| Architecture | `explain_architecture` |
296+
| Validate code | `lint_context` |
310297

311-
Compact mode also removes `null` values, `id` hash fields, `visibility`, `limit`, and `offset` from responses, and minifies JSON (no indentation). `repositoryId` and `language` are hoisted to the envelope when all results share the same value.
298+
## Token optimization
312299

313-
## Response style
314-
315-
Be direct and concise in all responses. Drop articles (a/an/the), filler (just/really/basically/simply), pleasantries (sure/certainly/of course), and hedging. Fragments OK. Use short synonyms: "fix" not "implement a solution for", "use" not "utilize". Technical terms, code blocks, and error messages stay exact.
300+
- Pass `repositoryId: "<YOUR_REPO_ID>"` to all tools (avoids full-index scan)
301+
- Default `limit: 10` is sufficient; increase only if results are incomplete
302+
- Set `includeSnippets: true` only when code context is required for the answer
303+
- Use `incremental: true` when re-indexing after changes
316304

317-
Pattern: `[thing] [action] [reason]. [next step].`
305+
## Response format
318306

319-
Example — not: "Sure! I'd be happy to help. The issue you're experiencing is likely caused by..."
320-
Example — yes: "Bug in auth middleware. Token expiry uses `<` not `<=`. Fix:"
307+
Server runs in **compact mode** by default (60% token savings). Response keys abbreviated:
321308

322-
Exception: use full sentences for security warnings, irreversible operations, and multi-step sequences where brevity risks misreading.
309+
`r`=results/callers/callees, `n`=name, `qn`=qualifiedName, `k`=kind, `fp`=filePath, `ls`=lineStart, `le`=lineEnd, `rid`=repositoryId, `lang`=language, `s`=score, `t`=total, `m`=hasMore, `nid`=nodeId, `x`=isExported, `cx`=complexity, `st`=searchType, `sym`=symbol, `nodes`=affectedNodes, `files`=affectedFiles, `entry`=entryPoints, `mods`=modules, `abs`=keyAbstractions
323310

324-
Never create or edit `.md` files unless explicitly asked.
311+
Null values, `id` hash fields, `visibility`, `limit`, `offset` stripped. JSON minified.
325312
```
326313

314+
**To get your repository ID:** Call `list_repositories` or check the dashboard. Replace `<YOUR_REPO_ID>` in the rule template.
315+
327316
**Why this reduces cost:** Without the rule, AI agents explore codebases by chaining multiple Grep → Read → Grep → Read calls, each consuming tokens. A single Context-Simplo MCP call (e.g., `find_callers` or `get_impact_radius`) replaces entire chains of exploration, returning structured results in one round-trip.
328317

329318
This also works with other MCP-compatible clients (VS Code, Claude Desktop, Claude Code) — adapt the rule format to your IDE's conventions.

‎bench/.gitignore‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# Raw benchmark runs are environment-dependent and noisy
2+
*.json
3+
4+
# Keep summaries and reports for audit trail
5+
!REPORT.md
6+
!SMOKE.md
7+
!baseline-*.md
8+
!candidate-*.md
9+
!variant-*.md

0 commit comments

Comments
 (0)