Repository avatar
Other Tools
v1.0.0
active

symbols

io.github.p1va/symbols

MCP server to read, inspect and troubleshoot codebase symbols

Repository

Documentation

Symbols MCP

Read, inspect and navigate through codebase symbols by connecting to a Language Server

NPM Version

Introduction

By connecting to a Language Server of choice this MCP server makes it easy and efficient for coding agents to explore and navigate the codebase and its dependencies. The server offers a minimal toolset intended to be simple to use and light on the model's context. Language Server configuration is kept in a dedicated file to keep MCP settings clean.

Available Tools

  • outline: returns a concise outline of code symbols in a given file
    • preview: false keeps it compact with just names and kinds
    • preview: true includes a code snippet with signatures, modifiers, return types...
  • inspect: returns context for a given symbol. Works for both local and third-party ones (e.g. installed from npm, NuGet, ... )
    • any documentation and signature details
    • symbol declaration location with code preview
    • symbol implementation location with code preview
  • search: returns matching symbols across the codebase
  • references: finds all references of a symbol across the codebase
  • rename: renames all references of a symbol across the codebase
  • diagnostics: returns active diagnostics in a given file
  • completion: returns a list of contextual completions at a given location
  • logs: returns Language Server own logs for troubleshooting

Installation

1. Add MCP Server

Add the MCP server to your coding agent of choice

 

Claude Code

To install the MCP server add this to your repository .mcp.json file

{
  "mcpServers": {
    "symbols": {
      "command": "npx",
      "args": ["-y", "@p1va/symbols@latest"]
    }
  }
}

or

claude mcp add symbols -- npx -y @p1va/symbols@latest
 

OpenAI Codex

To install the MCP server add this to your global $HOME/.codex/config.toml file

[mcp_servers.symbols]
command = "npx"
args = ["-y", "@p1va/symbols@latest"]
 

Google Gemini CLI

To install the MCP server add this to your repository .gemini/settings.json file

{
  "mcpServers": {
    "symbols": {
      "command": "npx",
      "args": ["-y", "@p1va/symbols@latest"],
      "env": {},
      "cwd": ".",
      "timeout": 30000,
      "trust": true
    }
  }
}
 

GitHub Copilot

To install the MCP server add this to your repository's .vscode/mcp.json file

{
  "servers": {
    "symbols": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@p1va/symbols@latest"]
    }
  }
}

2. Install Language Servers

Install the Language Servers relevant to your codebases

    Pyright   (pre-installed)

Pyright

Installation

✅ This Language Server is installed as a dependency of the MCP server and does not need installation.

Configuration

✅ A default configuration for this Language Server is created during startup so things should just work.

Troubleshooting

If the logs tool output includes errors or the diagnostics tool only reports module import errors even when none appear in the IDE these might be signs of Pyright not detecting the virtual environment.

You can update your pyproject.toml to correctly point it to the virtual environment location.

[tool.pyright]
venvPath = "."
venv = ".venv"
    TS Language Server   (pre-installed)

TypeScript Language Server for TS and JS

Installation

✅ This Language Server is installed as a dependency of the MCP server and does not need installation.

Configuration

✅ A default configuration for this Language Server is created during startup so things should just work.

    Roslyn via NuGet Feed

Roslyn Language Server

Installation

The official C# Language Server is distributed over the VS IDE NuGet feed as a self-contained executable.

To download it we use the dotnet CLI with a temporary project file named ServerDownload.csproj with the following content:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <PackageNameBase>Microsoft.CodeAnalysis.LanguageServer</PackageNameBase>
    <PackageVersion>5.0.0-1.25353.13</PackageVersion>
    <RestorePackagesPath  Condition=" '$(RestorePackagesPath)' == '' ">/tmp/lsp-download</RestorePackagesPath>
    <ServerPath Condition=" '$(DownloadPath)' == '' ">./LspServer/</ServerPath>
    <TargetFramework>net9.0</TargetFramework>
    <DisableImplicitNuGetFallbackFolder>true</DisableImplicitNuGetFallbackFolder>
    <AutomaticallyUseReferenceAssemblyPackages>false</AutomaticallyUseReferenceAssemblyPackages>
    <RestoreSources>
      https://pkgs.dev.azure.com/azure-public/vside/_packaging/vs-impl/nuget/v3/index.json
    </RestoreSources>
  </PropertyGroup>
  <ItemGroup>
    <PackageDownload Include="$(PackageNameBase).$(Platform)" version="[$(PackageVersion)]" />
  </ItemGroup>
  <Target Name="SimplifyPath" AfterTargets="Restore">
    <PropertyGroup>
      <PackageIdFolderName>$(PackageNameBase.ToLower()).$(Platform.ToLower())</PackageIdFolderName>
      <PackageContentPath>$(RestorePackagesPath)/$(PackageIdFolderName)/$(PackageVersion)/content/LanguageServer/$(Platform)/</PackageContentPath>
    </PropertyGroup>
    <ItemGroup>
      <ServerFiles Include="$(PackageContentPath)**/*" />
    </ItemGroup>
    <Copy SourceFiles="@(ServerFiles)" DestinationFolder="$(ServerPath)%(RecursiveDir)" />
    <RemoveDir Directories="$(RestorePackagesPath)" />
  </Target>
</Project>

We then pick the platform identifier matching the machine from:

  • win-x64
  • win-arm64
  • linux-x64
  • linux-arm64
  • linux-musl-x64
  • linux-musl-arm64
  • osx-x64
  • osx-arm64
  • neutral

And finally restore the temporary project to trigger the download of the Language Server.

Adjust both RestorePackagesPath and ServerPath to your machine and keep track of the latter.

ServerPath=$HOME/.csharp-lsp/

dotnet restore ServerDownload.csproj \
  /p:Platform=your-platform-id \
  /p:RestorePackagesPath=/tmp/your/download/location \
  /p:ServerPath=$ServerPath

Verify Installation

To verify the outcome of the installation we run the command below

$ServerPath/Microsoft.CodeAnalysis.LanguageServer --version

Configuration

Initialize a configuration file for the repository with

npx -y @p1va/symbols@latest template show csharp > lsps.yaml
    Roslyn via C# DevKit for VSCode

Roslyn

x

Installation

x

    Gopls

Gopls

Installation

go install golang.org/x/tools/gopls@latest

Verify Installation

To double-check the outcome of the installation run the command below

gopls version

Configuration

Initialize a config file by running this command and review paths

npx -y @p1va/symbols@latest template show go > lsps.yaml
    Rust-analyzer

Rust-analyzer

Installation

rustup component add rust-analyzer

Verify Installation

To double-check the outcome of the installation run the command below

rust-analyzer --version

Configuration

Initialize a configuration file for the repository by running

npx -y @p1va/symbols@latest template show rust > lsps.yaml
    Jdt.ls

jdt.ls

x

Installation

x

3. Configuration

Configuration is how the MCP server knows which LSPs are available and when to launch them.

  ⚙️   More on config

Global

A global config file is created on first run, it includes TypeScript and Python and can be found at these locations:

  • Linux: ~/.config/symbols-nodejs/symbols.yaml
  • macOS: ~/Library/Preferences/symbols-nodejs/symbols.yaml
  • Windows: %APPDATA%\symbols-nodejs\Config\symbols.yaml

More LSPs can be added there and will be available in all coding agents configured with the MCP server.

Workspace

Config can also be provided at workspace level where LSPs declared in files named either symbols.y(a)ml or lsps.y(a)ml are automatically loaded.

Workspace location defaults to the same location where the Coding Agent was launched.

A workspace can be explicitly set by adding the --workspace path/to/dir flag when launching the MCP server.

Argument

A config flag provided when launching the MCP server allows to force a specific file name

--config path/to/language-servers.yaml

Troubleshooting

Active config can be seen with npx -y @p1va/symbols@latest --show-config.

Language Server Resolution

The MCP server launches the Language Server listing in its workspace_files any file detected in the current working directory. e.g. pyproject.toml launches Pyright, package.json TypeScript

These mappings can be updated or extended by modifying the configuration.

Language Server resolution can be made explicit by providing the exact Language Server to launch with this flag --lsp name-of-ls

Development

  • pnpm lint outputs the lint violations
  • pnpm lint:fix attempts to fix lint violations
  • pnpm format formats the codebase
  • pnpm dev starts in development mode
  • pnpm build runs the linter and build
  • pnpm start starts the built artifacts
  • pnpm test:unit runs the unit tests
  • pnpm test:integration:{language id} runs the integration tests for a given language
NPM
@p1va/symbols
Install Command
npm install @p1va/symbols

Related Servers

ai.gomarble/mcp-api

GoMarble MCP API Server

ai.mcpcap/mcpcap

An MCP server for analyzing PCAP files.

ai.meminal/meminal

Memory for deep conversational context across any platform