Asteria
MCP server for symbolic (LSP) code search
Ask AI about Asteria
Powered by Claude · Grounded in docs
I know everything about Asteria. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
✦ Asteria MCP
An MCP server for symbolic code search over multiple language servers.
Asteria was created as a lightweight alternative to Serena. It only borrows the idea of exposing three symbolic search tools - get_symbols_overview, find_symbol, and find_referencing_symbols - and does not try to replicate Serena's broader MCP toolkit.
The server exposes a small, stable tool surface for agents that need to inspect code with minimal file reads.
WARNING: ⚠️ LSP servers are required. Asteria does not install or manage LSP servers for you. If the required language server is not found in
PATH, the corresponding adapter fails on the first request. See Language server installation for installation commands.
Project status
- Project is in early development and should be considered alpha software.
- Server has been tested on macOS and Linux (Ubuntu).
- Windows is not supported because many LSP servers work poorly on it.
Symbolic search tools
get_symbols_overview: returns a compact overview of symbols in one file, grouped by LSP symbol kindfind_symbol: finds symbols by path-like query across a workspace, file, or directoryfind_referencing_symbols: finds usages of a symbol and groups them by file and logical container
No special prompts are required. In most cases, LLM will prefer symbolic searches in accordance with its own asteria prompt.
The following languages are currently supported
| Language | File extensions | Required executable |
|---|---|---|
| Go | .go | gopls |
| TypeScript / JavaScript | .ts, .tsx, .js, .jsx, .mts, .cts, .mjs, .cjs | typescript-language-server |
| Markdown | .md, .markdown | marksman |
| Python | .py, .pyi | basedpyright-langserver |
| C / C++ | .c, .cc, .cpp, .cxx, .h, .hpp, .cppm, ... | clangd |
| PHP | .php | phpactor |
| Rust | .rs | rust-analyzer |
Adding a new LSP server: see Adding a new LSP server.
LSP runtime requirements.
- Install the language servers you need.
- See Language server installation for installation commands.
- Make sure they are available in
PATHfor the MCP client process.
Asteria Installation
Binary Releases
Prebuilt archives are produced for:
- macOS
amd64 - macOS
arm64 - Linux
amd64 - Linux
arm64
Download the appropriate archive from GitHub Releases.
Homebrew
brew install --cask n-r-w/homebrew-tap/asteria-mcp
Build from Source
Requirements:
- Go
1.26
go build -o asteria-mcp ./cmd/asteria-mcp
or use Task:
task build
task build produces bin/asteria-mcp.
Language server installation
Use the commands that match the languages you want to analyze.
Go
- Executable:
gopls - macOS / Linux:
go install golang.org/x/tools/gopls@latest
Source: https://go.dev/gopls/
TypeScript and JavaScript
- Executable:
typescript-language-server - macOS / Linux:
npm install -g typescript-language-server typescript
Source: https://github.com/typescript-language-server/typescript-language-server
Markdown
- Executable:
marksman - macOS:
brew install marksman
- Linux:
- If you use Homebrew, the same command as on macOS works.
- Otherwise use the official binary release and place
marksmaninPATH.
Source: https://github.com/artempyanykh/marksman/blob/main/docs/install.md
Python
- Executable:
basedpyright-langserver - macOS / Linux:
uv tool install basedpyright
- Alternative:
pip install basedpyright
Use this alternative on macOS and Linux if you prefer pip over uv.
Both commands install the basedpyright CLI and the basedpyright-langserver script.
Source: https://docs.basedpyright.com/dev/installation/command-line-and-language-server/
C and C++
- Executable:
clangd - macOS:
brew install llvm
Homebrew installs llvm as a keg-only formula. If command -v clangd still returns nothing after installation, add $(brew --prefix llvm)/bin to your PATH.
- Linux:
sudo apt-get install clangd-12
sudo update-alternatives --install /usr/bin/clangd clangd /usr/bin/clangd-12 100
On non-Debian distributions, use the package manager or the official release binaries.
Source: https://clangd.llvm.org/installation.html
PHP
- Executable:
phpactor - Requirements: PHP
8.1+ - macOS / Linux:
curl -Lo phpactor.phar https://github.com/phpactor/phpactor/releases/latest/download/phpactor.phar
chmod a+x phpactor.phar
mv phpactor.phar ~/.local/bin/phpactor
Make sure ~/.local/bin is in PATH.
Source: https://phpactor.readthedocs.io/en/master/usage/standalone.html
Rust
- Executable:
rust-analyzer - macOS / Linux:
rustup component add rust-analyzer
rustup component add rust-src
Alternative on macOS:
brew install rust-analyzer
Source: https://rust-analyzer.github.io/book/installation.html
Adding a new LSP server
Add each adapter under internal/adapters/lsp/servers/<server-name>/.
In most cases, the adapter should stay thin and reuse shared packages:
internal/adapters/lsp/runtimelsp- LSP process lifecycle, session reuse, and workspace isolationinternal/adapters/lsp/stdlsp- shared implementation for overview, symbol search, and reference searchinternal/adapters/lsp/helpers- common document and workspace utilities
There are two supported approaches:
- Standard adapter - use this when the language server follows standard LSP behavior closely enough for
stdlsp - Custom adapter - use this when the server needs its own symbol or reference workflow
High-level flow:
- Create the adapter package.
- Implement
router.ILSPandserver.ILSP. - Register the adapter in
internal/appinit/lsp.go. - Add unit and integration tests with fixtures in
testdata/. - Run
task lint,task test, andtask itest.
For the full implementation rules, package layout, multi-workspace behavior, cache requirements, and testing checklist, read LSP Server Implementation Guide.
Environment variables
-
ASTERIAMCP_CACHE_ROOT(optional, default:<os-user-cache-dir>/asteria/cache)- Absolute path for managed adapter artifacts.
-
ASTERIAMCP_SYSTEM_PROMPT(optional, default: built-in server instructions)- Overrides MCP server instructions.
-
ASTERIAMCP_GET_SYMBOLS_OVERVIEW_DESC(optional, default: built-inget_symbols_overviewdescription)- Overrides the MCP tool description.
-
ASTERIAMCP_FIND_SYMBOL_DESC(optional, default: built-infind_symboldescription)- Overrides the MCP tool description.
-
ASTERIAMCP_FIND_REFERENCES_DESC(optional, default: built-infind_referencing_symbolsdescription)- Overrides the MCP tool description.
-
ASTERIAMCP_TOOL_TIMEOUT(optional, default:360s)- Global timeout for one MCP tool call.
- Must be greater than
0.
-
ASTERIAMCP_TOOL_OUTPUT_MAX_BYTES(optional, default:32768)- Maximum serialized JSON size for one tool response.
- Must be greater than
0.
-
ASTERIAMCP_GOPLS_BUILD_FLAGS(optional)goplsbuild flags separated by;.- Example:
-tags=featurex;-tags=integration
-
ASTERIAMCP_GOPLS_ENV(optional)goplsenvironment entries separated by;.- Example:
GOFLAGS=-tags=featurex;GOOS=linux
-
ASTERIAMCP_RUST_ANALYZER_WORKSPACE_SYMBOL_SEARCH_LIMIT(optional, default:128)- rust-analyzer workspace symbol search limit.
-
ASTERIAMCP_RUST_ANALYZER_STARTUP_READY_TIMEOUT(optional, default:30s)- How long Asteria waits for rust-analyzer startup readiness.
You can start from .env.example if you want to keep local configuration in an env file.
Client configuration examples
Claude Code
claude mcp add -s user --transport stdio asteria /path/to/asteria-mcp
VS Code, RooCode, and similar clients
"asteria": {
"command": "/path/to/asteria-mcp"
}
Notes:
- The
commandmust point to the built executable. - Asteria uses stdio transport.
- Language server binaries must be visible in the environment of the MCP client process.
Operational notes
- Asteria creates one LSP session per normalized
workspace_root. - Different workspace roots are isolated from each other.
- Managed adapter artifacts are kept under the configured cache root, not inside the analyzed repository.
- The server communicates over stdio and starts language servers lazily on the first request.
