ADR-017: MCP-LSP Integration Architecture

Status: Accepted Version: 1.0 Date: 2025-12-21 Supersedes: N/A Related ADRs: ADR-016 Related PRDs: N/A

[!NOTE] Implementation Details: The technical specification for this architecture is in SDS-052: Semantic Tooling & IDE Integration. This ADR remains the authoritative architectural decision; SDS-052 provides implementation details.

Context

SEA-Forge™ includes language intelligence capabilities via the DomainForge™ DSL language server. To enable AI agents to leverage this semantic intelligence, we need a standardized way to expose LSP capabilities.

LSP (Language Server Protocol) provides authoritative, semantic code intelligence (hover, go-to-definition, diagnostics, code actions).

MCP (Model Context Protocol) provides LLM applications a standardized way to call tools and access resources, enabling models to request context rather than guessing.

When integrated:

LLM (via MCP) asks: “What’s the type of this symbol? What errors exist?”
Language server (via LSP) answers with ground-truth analysis
The LLM generates outputs that are far more correct than pure text-only reasoning

Decision

Expose DomainForge™ LSP capabilities via MCP as a semantic probe for AI agents, treating hover, diagnostics, and code actions as safe, authoritative tools.

Integration Architecture

VS Code Extension (Node/TS) ↔ Rust LSP Server ↔ MCP Server (optional)
                                    ↓
                            Standard LSP Clients
                                    ↓
                            AI Agents via MCP

Approach Selection

Option	Description	Verdict
FastMCP (Python)	Quick MVP, minimal code	❌ Problematic for VS Code (Python dependency)
Node MCP Server	Runs in extension host	✅ Best for VS Code packaging
Rust MCP Server	Single binary with LSP	✅ Best for long-term infra
No MCP	Direct LSP from VS Code	✅ Simplest for VS Code-only

Recommendation: For VS Code extension, prefer No MCP (use VS Code’s existing LSP integration) or Node MCP Server. Use Rust MCP Server if shared service is needed across multiple clients.

LSP Tools to Expose via MCP

Expose a small, safe subset of LSP requests:

Tool	LSP Method	MCP Exposure
Hover	`textDocument/hover`	✅ Primary — fast, safe, authoritative
Diagnostics	`textDocument/publishDiagnostics`	✅ Read-only error/warning info
Definition	`textDocument/definition`	✅ Navigation context
References	`textDocument/references`	✅ Usage discovery
Code Actions	`textDocument/codeAction`	⚠️ Preview only, no auto-apply
Rename	`textDocument/rename`	⚠️ Preview only, human approval required

Security and Permissions

Default stance: least privilege

Path allowlists (only expose specific workspaces)
Rate limits on tool calls
Human-in-the-loop for any mutations (edits, renames)
No auto-apply of code actions

Trust boundary rules:

MCP-style tool access expands attack surface
Strict permissions and allowlists required
Avoid prompt injection → tool misuse scenarios

Value Proposition

What you gain:

Less hallucination, more grounding — Model uses compiler-grade truth
Reuse the ecosystem — Existing LSP servers for many languages
Better agent workflows — LSP becomes “just another tool”
Protocol fit — Both are JSON-RPC flavored

When it’s not worth it:

Lightweight autocomplete only (overkill)
Can’t tolerate tool-call risk (needs hardening first)

Rationale

Hover is the highest ROI tool to expose first because:

Cheap: Localized computation
Fast: Cached, bounded
Safe: Read-only
Authoritative: Compiler-grade truth

This gives AI agents a “semantic microscope” without mutation risks.

Alternatives Considered

Direct Code Analysis by AI

Rejected — LLMs cannot reliably analyze code semantics; leads to hallucination.

Separate AI Parser

Rejected — Duplicates work; diverges from language server truth.

Full LSP Exposure

Rejected — Too dangerous; mutations without validation.

Constraints

MUST expose only a small, safe subset of LSP requests via MCP
MUST apply path allowlists and rate limits
MUST require human-in-the-loop for any mutations
MUST NOT auto-apply code actions
MUST NOT expose full LSP mutation capabilities without validation workflow

Quality Attributes

AI agents grounded in semantic truth
Reliable code understanding
Consistent with VS Code’s existing LSP integration
Future-friendly (MCP standardization growing)
Compiler-grade truth for code analysis

Bounded Contexts Impacted

DomainForge™ LSP Server
DomainForge™ VS Code Extension
AI Agent Runtime
Developer Tooling

Consequences

Positive

AI agents grounded in semantic truth
Reliable code understanding
Consistent with VS Code’s existing LSP integration
Future-friendly (MCP standardization growing)

Negative

Latency and state management complexity
Security hardening required
Edit application needs validation workflow

Additional Notes

SDS-052: Ultimate LSP Hover Specification
DomainForge™ VSC Extension

⏳ Post-MVP (requires stable LSP server)