Trueline Mcp

An MCP plugin that gives AI coding agents hash-verified file editing and targeted reads. Works with Claude Code, Gemini CLI, VS Code Copilot, OpenCode, and Codex CLI.

Installation

Claude Code (recommended; hooks are automatic):

/plugin marketplace add rjkaes/trueline-mcp
/plugin install trueline-mcp@trueline-mcp

Other platforms (Gemini CLI, VS Code Copilot, OpenCode, Codex CLI): See INSTALL.md for platform-specific setup.

CLI (no MCP): For agents that use shell commands instead of MCP, install globally with npm i -g trueline-mcp and add configs/cli/instructions.md to your agent's system prompt. See INSTALL.md.

Why

AI coding agents read entire files to find one function, then echo back everything they're replacing. Both waste context on content the agent already knows or doesn't need. That context costs money, eats into the conversation window, and limits how much real work fits in a session.

Worse, the built-in edit tools match by string content. If the agent hallucinates a line, works from stale context, or hits an ambiguous match, your code gets silently corrupted.

trueline fixes both problems: it reads less, writes less, and rejects every edit that doesn't match the file's actual content.

How it works

trueline provides six MCP tools organized around three workflows.

Explore: understand before you read

trueline_outline returns an AST-based structural outline of any file: functions, classes, declarations, and their line ranges. For a typical source file, that's 10-20 lines instead of hundreds.

1-3: (3 imports)
5-5: const PACKAGE_NAME = "trueline-mcp";
6-6: const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000; // 24 hours
7-7: const CACHE_FILE = join(tmpdir(), "trueline-mcp-update-check.json");
8-8: const REGISTRY_TIMEOUT_MS = 3000;
10-13: interface CachedCheck {
15-22: async function readCache(): Promise<CachedCheck | null> {
24-26: async function writeCache(entry: CachedCheck): Promise<void> {
28-42: async function fetchLatestVersion(): Promise<string | null> {
51-76: export function scheduleUpdateCheck(currentVersion: string, onUpdate: (info: { current: string; latest: string }) => void,
79-87: function compareVersions(a: string, b: string): number {

(11 symbols, 88 source lines)

The agent sees the full structure, then uses trueline_read to fetch only the ranges it needs. Ranges are specified inline on each path:

file_paths: ["src/update-check.ts:28-42", "src/tools/verify.ts:1-20,35-60"]

A 500-line file where the agent needs one 20-line function? It reads 20 lines, not 500. Multiple files with different ranges in a single call.

trueline_search finds lines by literal string or regex and returns them with edit-ready refs, no outline or read step needed. For targeted edits where the agent knows what it's looking for, this is the fastest path.

Edit: compact and verified

The built-in edit tool requires the agent to echo back the old text being replaced. trueline_edit replaces that with a compact line-range reference and a content hash. The agent outputs only the new content.

The savings scale with the size of the replaced block. A one-line change saves little; replacing 30 lines of old code saves the agent from outputting all 30 of those lines again.

Multiple edits can be batched in a single call and applied atomically.

All MCP trueline tools require an absolute file_path/file_paths; relative paths are rejected to avoid silently operating on the wrong file when the agent is working in a git worktree. The CLI (trueline edit, trueline read, etc.) still accepts relative paths, since its working directory is unambiguous.

Review: semantic diffs