trueline-mcp 2.5.8 → 2.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +16 -36
- package/dist/server.js +39 -39
- package/hooks/core/formatters.js +6 -1
- package/hooks/core/instructions.js +51 -57
- package/hooks/core/routing.js +90 -24
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
# trueline-mcp
|
|
2
2
|
|
|
3
|
-
[](https://github.com/rjkaes/trueline-mcp/actions/workflows/ci.yml)
|
|
3
|
+
[](https://github.com/rjkaes/trueline-mcp/actions/workflows/ci.yml)
|
|
4
4
|
|
|
5
|
-
A [Model Context Protocol](https://modelcontextprotocol.io/) plugin that
|
|
6
|
-
context usage and catches editing mistakes. Works with Claude
|
|
7
|
-
VS Code Copilot, OpenCode, and Codex CLI.
|
|
5
|
+
A [Model Context Protocol](https://modelcontextprotocol.io/) plugin that reduces
|
|
6
|
+
context usage on large files and catches editing mistakes. Works with Claude
|
|
7
|
+
Code, Gemini CLI, VS Code Copilot, OpenCode, and Codex CLI.
|
|
8
8
|
|
|
9
9
|
## Installation
|
|
10
10
|
|
|
@@ -20,7 +20,7 @@ See [INSTALL.md](INSTALL.md) for platform-specific setup instructions.
|
|
|
20
20
|
|
|
21
21
|
## The problem
|
|
22
22
|
|
|
23
|
-
AI agents waste tokens in two ways:
|
|
23
|
+
AI agents waste tokens on large files in two ways:
|
|
24
24
|
|
|
25
25
|
1. **Reading too much.** To find a function in a 500-line file, the agent
|
|
26
26
|
reads all 500 lines, most of which it doesn't need.
|
|
@@ -29,16 +29,19 @@ AI agents waste tokens in two ways:
|
|
|
29
29
|
output the old text being replaced (`old_string`) plus the new text.
|
|
30
30
|
The old text is pure overhead.
|
|
31
31
|
|
|
32
|
-
Both problems compound. A typical editing session reads
|
|
33
|
-
and makes multiple edits, burning through context on
|
|
32
|
+
Both problems compound on larger files. A typical editing session reads
|
|
33
|
+
dozens of files and makes multiple edits, burning through context on
|
|
34
|
+
redundant content.
|
|
34
35
|
|
|
35
36
|
And when things go wrong (stale reads, hallucinated anchors, ambiguous
|
|
36
37
|
matches) the agent silently corrupts your code.
|
|
37
38
|
|
|
38
39
|
## How trueline fixes this
|
|
39
40
|
|
|
40
|
-
trueline
|
|
41
|
-
|
|
41
|
+
trueline provides six MCP tools that are smaller, faster, and verified.
|
|
42
|
+
For small files, the built-in tools work fine. For larger files, the
|
|
43
|
+
savings from targeted reads and compact edits outweigh the token
|
|
44
|
+
overhead of crossing the MCP protocol barrier.
|
|
42
45
|
|
|
43
46
|
### Read less: `trueline_outline` + `trueline_read`
|
|
44
47
|
|
|
@@ -60,6 +63,10 @@ classes, and declarations with their line ranges:
|
|
|
60
63
|
12 lines instead of 139. The agent sees the full structure, then reads
|
|
61
64
|
only the ranges it needs, skipping hundreds of irrelevant lines.
|
|
62
65
|
|
|
66
|
+
The savings scale with file size. MCP tool calls have per-call framing
|
|
67
|
+
overhead, so the break-even point is roughly 15KB; below that, a plain
|
|
68
|
+
`Read` is cheaper. Above it, the gap widens quickly:
|
|
69
|
+
|
|
63
70
|
| File size | Full read | Outline | Savings |
|
|
64
71
|
|-------------|-----------|---------|--------|
|
|
65
72
|
| 140 lines | 140 tokens | 12 tokens | 91% |
|
|
@@ -114,33 +121,6 @@ No more silent corruption. No more ambiguous string matches.
|
|
|
114
121
|
valid without re-reading the file. When the file hasn't changed (the
|
|
115
122
|
common case), the response is a single line — near-zero tokens.
|
|
116
123
|
|
|
117
|
-
### Benchmarks
|
|
118
|
-
|
|
119
|
-
Measured on real project files (`src/streaming-edit.ts`, 529 lines),
|
|
120
|
-
comparing total bytes through the context window (call + result, ÷4 ≈
|
|
121
|
-
tokens):
|
|
122
|
-
|
|
123
|
-
| Workflow | Built-in | Trueline | Saved |
|
|
124
|
-
|-------------------------|----------|-----------|-------|
|
|
125
|
-
| Navigate & understand | 22 094 | 3 609 | 84% |
|
|
126
|
-
| Explore then edit | 22 729 | 8 515 | 63% |
|
|
127
|
-
| Search & fix | 22 731 | 812 | 96% |
|
|
128
|
-
| Multi-region read | 22 094 | 2 720 | 88% |
|
|
129
|
-
| Multi-file exploration | 39 296 | 1 761 | 96% |
|
|
130
|
-
| Verify before edit | 44 823 | 3 608 | 92% |
|
|
131
|
-
| **Total** |**173 767**| **21 025**| **88%** |
|
|
132
|
-
|
|
133
|
-
The search-and-fix workflow saves the most: a single `trueline_search`
|
|
134
|
-
call replaces grep + full-file read + old-string echo, cutting **96%**
|
|
135
|
-
of token usage. The verify-before-edit workflow shows how
|
|
136
|
-
`trueline_verify` avoids a full re-read when checking whether held
|
|
137
|
-
checksums are still valid — **92%** savings over re-reading the entire
|
|
138
|
-
file. Even the explore-then-edit workflow — which includes an
|
|
139
|
-
exploratory read, a targeted re-read, and an edit — still saves **63%**
|
|
140
|
-
over the built-in equivalent.
|
|
141
|
-
|
|
142
|
-
Run the benchmark yourself: `bun run benchmarks/token-benchmark.ts`
|
|
143
|
-
|
|
144
124
|
## Design
|
|
145
125
|
|
|
146
126
|
See [DESIGN.md](DESIGN.md) for the protocol specification, hash
|