apollovm_mcp library

MCP (Model Context Protocol) server for ApolloVM.

Exposes ApolloVM's parse / execute / translate / compile capabilities to AI agents as MCP tools (apollovm.parse, apollovm.execute, apollovm.translate, apollovm.ast, apollovm.symbols, apollovm.types, apollovm.wasm), plus a set of apollovm.lsp.* tools that let an agent inspect code the way an editor does (diagnostics, outline, hover, definition, references, completion and workspace-wide symbol search).

This library is web-safe: it imports no dart:io and no dart:isolate, so a browser IDE or an embedded agent can run the server and all tools in-process. Construct an ApolloMcpServer on any StreamChannel<String>. On native, tools flagged by McpLimits.isolateTools run in a killable isolate for a hard timeout; on the web they run in-process with a cooperative timeout (see isolate_executor.dart).

The native-only transports and CLI (stdio, HTTP/SSE, the mcp command) live in package:apollovm/apollovm_mcp_io.dart, which requires dart:io.

Classes

ApolloMcpServer
An MCP server exposing ApolloVM as agent tools over a StreamChannel.
GitBlameLine
One line of git blame.
GitCommit
One commit from git log.
GitResult
The result of a mutating git command.
GitStatusEntry
One entry of git status (porcelain).
InMemoryRepositoryAdapter
A web-safe, in-memory RepositoryAdapter backing tests and browser demos.
LineRange
A 1-based, inclusive line range for partial file reads.
LspRuntime
In-process façade over the ApolloVM Language Server (LspService) used by the MCP apollovm.lsp.* tools, so an AI agent can inspect code the way an editor does: diagnostics, outline, hover, go-to-definition, references, completion and workspace-wide symbol search.
McpLimits
Resource limits enforced by the ApolloVM MCP server.
Op
The op names shared by RepositoryRpc (server) and RemoteRepositoryAdapter (client) — one source of truth for the wire contract.
PermissionGuard
A RepositoryAdapter decorator that enforces a RepoConfig over any inner adapter, so the security policy holds regardless of the backend.
RemoteRepositoryAdapter
A RepositoryAdapter that talks to a remote repository server over HTTP.
RepoCapabilities
What a concrete RepositoryAdapter (as configured) is able and permitted to do. Tools consult this to fail cleanly ("not supported / not permitted") instead of throwing when an operation is unavailable.
RepoConfig
Policy for the repository surface (the RepositoryAdapter operations and the apollovm.fs.*/search.*/code.*/git.* MCP tools built on it).
RepoEdit
The outcome of an RepositoryAdapter.edit (or write).
RepoEntry
A directory entry produced by RepositoryAdapter.list.
RepoFile
The content of a file (or a line slice of it).
RepoRuntime
The MCP JSON layer over a RepositoryService: it maps the apollovm.fs.* / apollovm.search.* / apollovm.code.* / apollovm.git.* tool calls to typed service methods and serializes the results to JSON.
RepositoryAdapter
A pluggable backend for the workspace/repository MCP tools.
RepositoryRpc
A tiny, transport-agnostic JSON layer over a RepositoryService.
RepositoryService
A high-level, typed façade over a RepositoryAdapter — the entry point for using ApolloVM's repository features from any Dart host (a web IDE, a desktop editor, an agent, a test), independently of MCP.
RepoStat
File/directory metadata produced by RepositoryAdapter.stat.
TextMatch
A content-search hit produced by RepositoryAdapter.searchText.

Constants

allToolNames → const List<String>
The names of all tools this server exposes, in registration order: the core VM tools followed by the apollovm.lsp.* code-inspection tools.
lspToolNames → const List<String>
The LSP inspection tools this server exposes, in registration order.
repoToolNames → const List<String>
All workspace/repository tool names (fs + search + code + git), in registration order.

Functions

buildLspTools() → List<Tool>
The Tool definitions for the LSP inspection tools. These are the single source of truth advertised via tools/list.
buildRepoTools() → List<Tool>
The Tool definitions for every workspace/repository tool.
computeLspTool(String name, Map<String, Object?> args, McpLimits limits) → Future<Map<String, Object?>>
Runs the LSP tool named name with args and returns its JSON result map (always including an isError flag). Pure with respect to the host, so it runs identically in-process or inside a spawned isolate.
computeTool(String name, Map<String, Object?> args, McpLimits limits) → Future<Map<String, Object?>>
Runs the tool named name with args and returns its JSON result map.
computeToolIsolated(String toolName, Map<String, Object?> args, McpLimits limits) → Future<Map<String, Object?>>
Runs the tool named toolName with the configured timeout. Convenience wrapper over runToolInIsolate, mirroring the native executor's API.
isLspTool(String name) → bool
Whether name is one of the LSP tools handled by computeLspTool.
isRepoTool(String name) → bool
Whether name is one of the workspace/repository tools handled by RepoRuntime.
runToolInIsolate(String toolName, Map<String, Object?> args, McpLimits limits, Duration timeout) → Future<Map<String, Object?>>
Runs computeTool for toolName in-process, bounding it with a cooperative timeout (Future.timeout).

Exceptions / Errors

RepoException
Raised by a RepositoryAdapter for an expected, reportable failure — a missing file, a path that escapes the workspace root, a rejected line anchor, or a git error. RepoRuntime turns these into {isError: true} tool results rather than letting them crash the server.
RepoPermissionException
Raised when an operation is not permitted by the adapter's capabilities / RepoConfig (e.g. a write while read-only). A subtype of RepoException so callers can distinguish "forbidden" from "failed".