CodeOutline MCP server

CodeOutline

English | 简体中文

CodeOutline is a code exploration tool and LSP server, powered by Lua.

• Code exploration (code_explore) for coding agents: the MCP tool codeoutline_explore returns symbols, line-numbered source, call paths and callers/callees. Use codeoutline explore for the same exploration from a terminal.
• LSP server for editors: codeoutline lsp --stdio provides symbols, definitions, references, hover, call hierarchy, completion and signature help. Install the bundled clients for VS Code, Cursor or Zed to use it in an editor.

CodeOutline answers symbol queries with line-numbered source, call paths, and callers/callees, refreshes incrementally, and caches the index on disk. Editors get symbols, definitions, references, call hierarchy, and completion from the same index through LSP. The MCP protocol with both transports (stdio and Streamable HTTP) and the language server are implemented in Lua, so neither depends on Node; in the npm package, Node only locates and starts the runtime for your platform.

Installation and setup

Requires Node.js 20 or newer. npm downloads the runtime for your platform automatically; no compiler or Lua installation is needed. Install it globally rather than configuring clients with npx -y: npx keeps a full npm process running beside every server it starts.

npm install -g codeoutline
codeoutline --version
codeoutline --help

To choose each detected AI tool and Zed, VS Code or Cursor editor during global installation, use npm's foreground mode. Each prompt defaults to installation. The shared service then starts automatically, without another install command:

npm install -g codeoutline --foreground-scripts

Installation offers two stages in order, confirming each detected application:

1. Detect AI tools and ask whether to install code exploration (codeoutline_explore over MCP) for each tool, such as Install code_explore (MCP) for Codex (codex)? [Y/n].
2. Detect Zed, VS Code and Cursor and ask whether to install their LSP clients. Each editor gets its own confirmation, such as Install CodeOutline LSP for Zed (zed)? [Y/n].

Every installation prompt defaults to yes: press Enter (or enter y/yes) to install it, or n/no to skip just that application. Press Enter for every item to install all detected integrations. EOF skips remaining applications instead of accepting their defaults. Explicit --target/--editors lists and environment selections bypass the per-application prompts. Interactive removal defaults to no. The installer then starts/registers the shared service. After restarting the selected applications, no additional codeoutline install command is required. npm runs lifecycle scripts in the background by default. The launcher only prompts when it inherits terminal input and output; it does not reopen the controlling console while npm owns it. Without --foreground-scripts, in CI or when no terminal is available, it uses noninteractive setup and installs detected integrations automatically unless explicitly overridden. Ordinary project-local npm install codeoutline does not configure global integrations; use the global installation command above for this setup flow. You can also choose or install clients later:

codeoutline editors                             # detect and choose interactively
codeoutline editors --list                      # only show detected editors
codeoutline editors --editors all               # install for all detected editors
codeoutline editors --editors vscode            # install for VS Code only
codeoutline editors --editors cursor            # install for Cursor only
codeoutline editors --editors zed               # install for Zed only
codeoutline editors --editors vscode,cursor      # install for selected editors

Set CODEOUTLINE_EDITORS to the same selection for unattended global npm installs; none skips clients. Without a terminal, installation never waits for a choice. Local npm installs do not change editor installations. Clients are bundled in release packages; no Rust toolchain or marketplace download is needed. Reload VS Code/Cursor or restart Zed afterward. Detection uses PATH and common installation locations; for a custom location, add the editor CLI to PATH. Zed uses its default user-data directory. Existing editor settings are preserved. The VS Code/Cursor client starts with full navigation enabled; set codeoutline.mode to auxiliary for workspace symbols only. See LSP.md for server capabilities.

Recommended: one shared HTTP service

A stdio server is a child process of its client, so every agent session (each Claude Code session, each Cursor window) starts its own copy and builds its own in-memory index. One HTTP service serves all sessions from a single process and a single index.

A global npm installation starts that service in the background and registers it to start at login: a Run registry value on Windows, a LaunchAgent on macOS, and a systemd user unit on Linux; without a systemd user manager (WSL, containers), start codeoutline daemon at login yourself. The service installs updates and restarts itself into them. Register agents once:

codeoutline install --yes                         # detect agents, configure MCP, start service
codeoutline install --target cursor,claude,codex   # select agents explicitly
codeoutline agents                               # choose interactively, without restarting service
codeoutline agents --list                         # inspect detection and config paths
codeoutline agents --target all                   # configure all detected agents
codeoutline agents --print codex                  # preview one agent's config, no writes
codeoutline agents --target cursor --remove       # remove only CodeOutline's MCP entry

Supported target IDs: claude, cursor, codex, gemini, opencode, hermes, kiro, antigravity, copilot-vscode, copilot-cli, copilot-jetbrains. Detection uses existing profile directories/configs and CLI commands on PATH; explicit IDs work even when detection misses an application. all and auto select detected targets. none skips registration. install --yes does not install LSP clients unless --editors is also specified.

Configuration defaults to user scope. Use --location local --project PATH for project scope; Hermes, Antigravity and Copilot CLI/JetBrains support user scope only. --port selects the shared service port for both registration and startup. agents edits configs only; use install to start/register the service too. Restart the agents after setup so they discover codeoutline_explore and the other MCP tools. Agent approval controls still apply; no prompt hooks or auto-approval policies are changed.

For Claude, Codex, Gemini and OpenCode, setup also adds a short CODEOUTLINE_START/END block to their scoped CLAUDE.md, AGENTS.md or GEMINI.md. If a complete CODEGRAPH_START/END block exists there, it is saved verbatim as codegraph.md in the same directory and removed from active instructions. An unrelated/different existing backup or malformed markers stop setup before config writes. Repeated setup is idempotent; unrelated instructions are preserved. Uninstall removes our block and restores the saved CodeGraph block only to a file that originally supplied it, when the codegraph CLI is still on PATH and no CodeGraph block is already present. The backup remains available for manual recovery, including when CodeGraph is gone. Project instructions are changed only with explicit project-scoped setup/cleanup. codegraph.md is not a default instruction filename, but explicit imports or manual reads can still load it.

The installer preserves unrelated settings and JSONC comments and stores the original nonempty file in <config>.codeoutline.bak before its first change. Repeating the same installation leaves configs unchanged. A different existing codeoutline entry is kept unless --force is passed. Complex TOML/YAML layouts that cannot be edited safely require manual setup using agents --print ID. For unattended global npm installation, set CODEOUTLINE_AGENTS=auto, all, none, or comma-separated IDs. Without a terminal or an explicit selection, global npm setup selects all detected agents and editors. Set both CODEOUTLINE_AGENTS=none and CODEOUTLINE_EDITORS=none to skip integration installation, or --ignore-scripts to skip the entire npm setup lifecycle. Local npm installs skip registration.

For manual setup instead:

Claude Code (added globally, available in every project):

claude mcp add --transport http codeoutline --scope user http://127.0.0.1:19876/mcp

Cursor (~/.cursor/mcp.json):

{ "mcpServers": { "codeoutline": { "url": "http://127.0.0.1:19876/mcp" } } }

codeoutline install does the same for a native installation, or after installing with --ignore-scripts; --port selects a port other than 19876. Set CODEOUTLINE_AUTOSTART=0 when installing to skip the login entry. The service logs to ~/.codeoutline/logs.

For a global npm installation, run codeoutline remove to clean integrations, purge the default user data and then uninstall the npm package. It waits for the runtime to exit before invoking npm; cleanup failure preserves the package for retry. Use codeoutline remove --project PATH to also remove a project's MCP registrations.

For separate cleanup and package removal, first run codeoutline uninstall, then npm uninstall -g codeoutline. The first command stops the service, removes its login entry, user-level Agent MCP entries and the VS Code/Cursor/Zed clients. Use --purge to also remove ~/.codeoutline caches, updates and logs, or --service-only to keep integrations. Cleanup also removes codeoutline.* settings from VS Code/Cursor user settings and named profiles, including language overrides, preserving other settings and comments. Use --project PATH to also remove MCP registrations in a specific project. Close/reload editors to release running LSP processes before deleting package files. Workspace settings, custom editor data directories, remote installations and original configuration backups require separate cleanup. npm 7+ has no uninstall hooks; running only npm uninstall cannot clean integrations or stop the service. The package includes a best-effort preuninstall compatibility hook for package managers that invoke it. It only cleans global uninstall integrations, preserves user data, and skips upgrade/local-install lifecycles. Use codeoutline remove for reliable full cleanup on current npm.

The service listens on 127.0.0.1:19876 and serves projects anywhere on the machine, so switching between projects on different drives needs no configuration. Only local processes can reach it, and they already have your file access. A shared service has no project of its own: it uses the client's roots when the client provides them, and otherwise the agent passes projectPath, which the tools ask for when it is missing.

To run an HTTP service yourself instead, for example restricted to some directories, start codeoutline serve --http and repeat --allow-root for each directory tree to allow; a tree that is unavailable at startup, such as an unmounted drive, is reported and becomes usable once it appears. Such a service installs updates but keeps running the old version until restarted; on Windows, supervise the native launcher rather than the npm one; see DISTRIBUTION.md.

Alternative: stdio, one process per session

Use stdio when you do not want a resident service. Each session then starts and stops its own server.

claude mcp add codeoutline --scope user -- codeoutline serve --stdio

On Windows, Claude Code cannot start the codeoutline.cmd shim directly; use -- cmd /c codeoutline serve --stdio. For Cursor, set "command": "codeoutline", "args": ["serve", "--stdio"]. A client that starts codeoutline with no arguments, as 0.1.7 recommended, gets the same stdio server.

When no project is specified, the service uses, in order: the projectPath argument of the call, the --project option, the client's roots (the first directory returned by roots/list), and the directory the service was started in. Clients usually start a stdio service in the project directory, so a global configuration needs no project path. Access defaults to --project or the start directory; repeat --allow-root to allow more.

Seven tools are provided:

Tool	Purpose
codeoutline_explore	Query source, call paths, and callers/callees by symbol or file name (query; optional projectPath, budget)
codeoutline_callers	Find recursive callers and affected files for an exact symbol/qualified name (query; optional projectPath, depth default 3, max_nodes default 200, budget)
codeoutline_affected	Analyze changed files with shared reverse traversal, shortest paths and test candidates (files; optional projectPath, depth, max_nodes, budget)
codeoutline_type_hierarchy	Find declared ancestors and descendants of a C#/Java/Kotlin/TS/C++ type (query; optional projectPath, direction, depth default 8, max_nodes default 200, budget)
codeoutline_type_references	Find explicit type uses with identity resolution in C/C++, C#, Java, Kotlin, TS/ArkTS, Go and Rust (query; optional projectPath, max_nodes default 200, budget)
codeoutline_status	Refresh and report index, cache, scanner, and parser statistics
codeoutline_rebuild	Rebuild fully, bypassing the cache

Without Node, download the native archive for your platform from GitHub Releases, extract it, and run codeoutline (codeoutline.cmd on Windows).

Editor integration (LSP)

codeoutline lsp --stdio is a language server over the same indexer. Each editor window starts its own server process with its own index; it does not connect to the shared MCP service, and the MCP URL is not an LSP endpoint.

Feature	Scope
Document and workspace symbols	Workspace symbols match substrings, case-insensitively
Definition, hover, signature help	Definition also goes from import lines (require, #include, module imports) to the files they load
References	Functions, methods, constructors, macros and supported explicit type positions
Call hierarchy	Functions, methods, constructors and macros; incoming and outgoing calls
Method implementations	C#, Java, Kotlin and TypeScript interface/abstract methods and C++ virtual overrides; textDocument/implementation
Completion	Locals, the file's definitions and imports, declarations from included C/C++ headers, and members after ., ->, ::, ?., or Lua :

Resolution is name-based, the same as codeoutline_explore; it is not a type checker. Rename, diagnostics, and formatting are not provided, so CodeOutline works best beside a language's own server or where none is available. Unsaved edits are included in every request. A .codeoutline.json file in the workspace root can map Lua call arguments to registration sites for Go to Definition. Behavior, limits, and options are described in LSP.md.

Thin clients are in this repository: one VSIX for VS Code and Cursor, and a Zed extension. They are not published to an extension marketplace yet; install them as described in their READMEs. Other editors can start the same command through their generic LSP support; only VS Code, Cursor, and Zed have been tested.

Clients start the server directly, without a shell:

• Linux and macOS: the npm installation puts an executable codeoutline on PATH, so the client defaults (codeoutline with lsp --stdio) work. An editor started from the desktop may not inherit PATH entries added by your shell profile (nvm, for example); then configure the absolute path printed by command -v codeoutline.
• Windows: npm installs codeoutline.cmd, a batch file. The VS Code/Cursor client finds the npm installation itself, and Zed starts codeoutline.cmd from PATH through cmd.exe, so neither needs settings. For clients that cannot start a batch file, configure node as the command, with the arguments <global npm folder>/codeoutline/launcher/codeoutline.cjs, lsp, --stdio; npm root -g prints the global folder, usually C:\Users\<you>\AppData\Roaming\npm\node_modules. For the native archive, run its bin/xnet.exe with <archive>/scripts/codeoutline/command.lua, LOG_STDERR=1, LOG_FILE=0, lsp, --stdio.

The server uses the newest installed version when it starts and does not install updates itself; an update installed by the background service takes effect the next time the editor starts the server. Started directly from the native archive, the server always runs that archive's version.

System requirements

Platform	Requirements
Windows	x64, Windows 10 / Server 2016 or newer (Windows 8 for the native archive); Windows 11 on ARM64 runs it under x64 emulation. No Visual C++ redistributable needed
Linux	x64, glibc 2.28 or newer: RHEL / Rocky / Alma 8 and 9, CentOS Stream 9, Debian 10+, Ubuntu 20.04+. Alpine/musl is not supported
macOS	macOS 11 or newer; one universal binary for Apple Silicon and Intel

On Linux, decoding GBK sources needs the GBK module of the system iconv. Minimal EL8/EL9 installs and container images lack it: dnf install glibc-gconv-extra. UTF-8 projects work without it, and codeoutline doctor reports when it is missing.