AI tooling: Structural refactoring API for agents (CLI + MCP/ACP + LSP index parity)

[emil14]

Tracking

• Parent AI umbrella: 2026 AI Direction Tracker: Neva for AI Codegen and GenAI Apps #1056
• Parent AI-codegen track: Track A: Make Neva a top-tier target for AI code generation #1057

Context / why this matters

In AI assistants, the most expensive operation is structural refactoring (rename/find usages/go to definition), when the agent is forced to grep through text and read dozens of files.

This causes:

• unnecessary token usage and long iteration cycles,
• false positives (comments/strings/similar names),
• missed real occurrences,
• slower feedback loops.

For Neva this is especially critical, because our Track A goal is to make a language that coding agents can work with quickly, accurately, and with a small context window.

Thesis

We need an official structural tool surface for agents (MCP/ACP-friendly), so navigation and refactoring operations use a semantic index (AST/symbol graph) instead of text search.

Proposed approach (distilled scope)

1) CLI as the canonical backend for agents

Add/standardize machine-readable commands in the neva CLI:

• symbol lookup (by name/qualified path/entity type)
• go to definition
• find usages
• rename (preview + apply)
• diagnostics explain (human- and machine-readable modes)

Requirements:

• stable JSON schema/versioning,
• deterministic output for identical input,
• minimal payloads (signature-first, no unnecessary prose).

2) MCP/ACP integration layer

Build an official protocol adapter on top of the CLI (at least MCP, optionally an ACP-compatible layer), so an agent makes 1 tool call per structural operation instead of N grep/read/edit cycles.

MVP tools:

• search_symbol
• goto_definition
• find_usages
• rename_refactoring
• get_diagnostics

3) LSP synergy

Use the same index/semantic source of truth as LSP navigation (or explicitly define the contract between them) to avoid divergence:

• CLI/LSP/MCP must return consistent results,
• rename/find usages must not diverge between IDE and agent.

4) Agent-oriented UX constraints

• token-cheap responses (concise, structured, no long walls of text),
• local context delivery (agent receives only relevant symbols/ranges),
• fast round-trips for large repositories.

How this maps to current tracks

• Concretizes Workstream 1 and 2 from Track A: Make Neva a top-tier target for AI code generation #1057 (AI-oriented CLI ergonomics + tool integration surface).
• Partially overlaps with Tooling: Markdown Documentation Generation (from Neva Source Code) #973 (docs pipeline), but the focus here is not docs publication; it is operational refactoring/navigation tool calls for agents.

Acceptance criteria (MVP)

• There is an RFC/design doc with CLI API + MCP tool contract.
• There is a working prototype of rename/find usages/goto on a real Neva project.
• Metrics are captured for benchmark scenarios "rename symbol" and "find usages":
  • token budget,
  • wall-clock,
  • precision/recall of occurrences,
  • number of agent iterations.
• Improvement is demonstrated against the baseline (grep-centric workflow).

Non-goals

• We are not building IDE-specific integration for only one editor.
• We are not changing language semantics for AI sugar.
• We are not trying to solve the entire debugger space (see Debugger: Design Space & Direction #977).

Open questions

• Do we need a separate ACP adapter, or is MCP + stable CLI API enough?
• Where should the source-of-truth index live: CLI-only, shared library, or LSP-first?
• What is the minimum safe rename granularity in Neva (package/module/workspace) for apply?

Source idea

• Post about the cost of grep-based refactoring in coding agents and the value of IDE-level structural tooling:
  https://www.linkedin.com/feed/update/urn:li:activity:7448780175267446785/?originTrackingId=eniFHOVHSX0Fn%2FDngO1w5Q%3D%3D