semctx

<p align="center"> <img width="420" alt="semctx - Semantic code context for AI agents" src="https://github.com/user-attachments/assets/aafca8a1-ca9f-4569-973e-d9eeddc44231" /> <p align="center"><b>Semantic code context</b> for AI agents, via LSP and LSIF.</p> </p>

Imagine you're working on an AI agent that has to make sense of tangled codebases. Every time it needs to figure out a symbol or follow a reference, it burns through tokens on endless searches and wild guesses. That's where semctx comes in - a way to hook AI agents straight into the semantic side of code via LSP servers and LSIF dumps. Instead of telling your agent to rummage through repos, guess relationships, or fake editor behavior, it just asks the language server or LSIF index for the right answer, turning hover, definition, references, diagnostics, symbols, and code actions into clean tool calls and ditching the heavy prompts for raw repo digging.

The idea is simple: expose official LSP through MCP, no made-up stuff. You pick your LSP servers, tie languages to the current workspace, and semctx handles sessions, transports, capability talks, document syncing, and routing. Result? A better workflow for AI, with clearer context, less junk, and fewer errors, all from the same protocols editors use.

Table of contents:

• What It Does
• Why (AI Agents Care)
• For Agent Builders
  • AGENTS.md Template
• Requirements
• Usage
  • MCP Client configuration
• Configuration
• MCP Tool Surface
• Request Conventions
• Behavior Notes
• License

[!WARNING] semctx is still pre-v1. Expect breaking changes while the tool surface, config schema, and payload shapes settle. If you're wiring it into an MCP host or agent workflow, pin a specific version and review changes before upgrading.

What It Does

semctx links MCP to LSP servers over stdio, tcp, or unix. It supports multiple languages in one workspace, letting agents tap into semantic editor features without endless text searches. It pulls key LSP language and workspace features into MCP tools that focus on reading and planning edits (like rename and format) which give you the changes but don't run them.

For offline stuff, it works with LSIF dumps, grabbing hover info, navigation, documents, diagnostics, semantic tokens, and project views from local JSONL files. If you add related dumps, it handles cross-dump links and references. Results are structured and to the point, with excerpts for ranges, paging for big queries, context for position requests, and previews for code actions, hence you can spot-check code without pulling in whole files.

It checks server capabilities and fails cleanly if something's not supported. It's read-only on purpose: plans renames and formats but doesn't apply edits, run commands, or mess with files. It also has helpers for binding resolution alongside the LSP and LSIF tools.

Why (AI Agents Care)

It's annoying to make an agent scrape a repo for info the language server already has. semctx helps you get precise context for definitions, references, symbols, diagnostics, and fixes, without stuffing prompts with full files. It saves tokens by giving focused protocol answers instead of messy search noise, cuts hallucination risk with spec-backed LSP or LSIF replies, and lets you flip between live LSP for active editing and LSIF for offline, pre-built indexes.

For Agent Builders

No more "search the repo to crack this symbol". With semctx, you run a tight semantic loop:

1. Call resolve_language_binding to set the session for your language.
2. Use go_to_definition for the symbol you want. Add source: "lsif" or indexPath when you want the offline LSIF path.
3. Grab the next bit of detail with hover, find_all_references, document_symbols, or diagnostics.
4. Read files only when you need the deep implementation.
5. Use code_actions, rename_symbol, format_document, and format_range to inspect suggested changes without giving the agent edit rights.

semctx wraps LSP and LSIF results in a small metadata layer, with excerpts for range outputs when it can. Agents see the raw protocol under result, but the context usually lets you skip extra reads. Big queries add paging and groups; code actions have previews; hover calls give request context.

This keeps prompts short, saves compute for actual thinking (token-efficient), and relies on protocol facts over guesses.

AGENTS.md Template

If you're adding semctx instructions to other repos for agents, start with AGENTS.template.md. It's the source template: put it in the repo root as AGENTS.md, add your project's commands and notes, and stick to the semctx-first flow so agents check semantic facts before searching files.

Requirements

You need:

1. Go 1.26.1 or later (optional; only if installing/building from source)
2. An LSP server reachable via stdio, tcp, or unix
3. An MCP host for stdio servers

Usage

semctx is an MCP stdio server, launched by an MCP host. Add the following config to your MCP client:

{
  "mcpServers": {
    "semctx": {
      "command": "go",
      "args": ["run", "go.dw1.io/semctx/cmd/semctx@v0.1.0"],
      "env": {
        "SEMCTX_CONFIG": "./.semctx.yaml"
      }
    }
  }
}

If you self-host semctx from a release or local build, point your MCP client at the binary instead:

{
  "mcpServers": {
    "semctx": {
      "command": "/path/to/semctx",
      "env": {
        "SEMCTX_CONFIG": "./.semctx.yaml"
      }
    }
  }
}

MCP Client configuration

Use the standard config above in any MCP host that supports local stdio MCP servers.

<details> <summary>Amp</summary>

Follow the Amp MCP docs and use the standard config above.

If you prefer the CLI, add semctx first and then adjust the saved server config if you want an explicit SEMCTX_CONFIG path instead of the default ./.semctx.yaml.

</details> <details> <summary>Antigravity</summary>

Follow the Antigravity MCP docs to add a custom MCP server, then paste in the standard config above.

</details> <details> <summary>Claude Code</summary>

Follow the Claude Code MCP guide and use the standard config above.

You can also add it from the CLI when ./.semctx.yaml is present in the current workspace:

claude mcp add semctx --scope user go run go.dw1.io/semctx/cmd/semctx@v0.1.0

If you prefer a local build, change command to /path/to/semctx and keep SEMCTX_CONFIG pointed at your config file.

</details> <details> <summary>Cline</summary>

Follow the Cline MCP docs and use the standard config above.

</details> <details> <summary>Codex</summary>

Follow the Codex MCP guide and use the standard config above.

You can also add it from the CLI when you are using the default workspace config path:

codex mcp add semctx -- go run go.dw1.io/semctx/cmd/semctx@v0.1.0

If you keep Codex config in .codex/config.toml, translate the same command, args, and env values into that file.

</details> <details> <summary>Command Code</summary>

Follow the Command Code MCP docs or add it from the CLI:

cmd mcp add semctx --scope user go run go.dw1.io/semctx/cmd/semctx@v0.1.0

</details> <details> <summary>Copilot CLI</summary>

Start Copilot CLI, run /mcp add, choose a local MCP server, and use the standard config above.

If the prompt only accepts a command string, use go run go.dw1.io/semctx/cmd/semctx@v0.1.0 and rely on ./.semctx.yaml in the current workspace.

</details> <details> <summary>Copilot / VS Code</summary>

Follow the VS Code MCP configuration guide and use the standard config above.

For macOS and Linux, you can also add it from the CLI:

code --add-mcp '{"name":"semctx","command":"go","args":["run","go.dw1.io/semctx/cmd/semctx@v0.1.0"],"env":{"SEMCTX_CONFIG":"./.semctx.yaml"}}'

</details> <details> <summary>Cursor</summary>

Go to Cursor Settings -> MCP -> New MCP Server and use the standard config above.

If you self-host semctx, replace the go run ... command with /path/to/semctx.

</details> <details> <summary>Factory CLI</summary>

Follow the Factory CLI MCP docs or add it directly:

droid mcp add semctx "go run go.dw1.io/semctx/cmd/semctx@v0.1.0"

</details> <details> <summary>Gemini CLI</summary>

Follow the Gemini CLI MCP guide and use the standard config above.

Project-scoped and user-scoped installs work well when you keep .semctx.yaml in the current workspace:

gemini mcp add semctx go run go.dw1.io/semctx/cmd/semctx@v0.1.0
gemini mcp add -s user semctx go run go.dw1.io/semctx/cmd/semctx@v0.1.0

</details> <details> <summary>Gemini Code Assist</summary>

Follow the Gemini Code Assist MCP guide and use the standard config above.

</details> <details> <summary>JetBrains AI Assistant & Junie</summary>

Go to Settings | Tools | AI Assistant | Model Context Protocol (MCP) -> Add and use the standard config above.

The same setup works for Junie in Settings | Tools | Junie | MCP Settings -> Add.

</details> <details> <summary>Kiro</summary>

In Kiro Settings, go to Configure MCP and open the workspace or user MCP config, then paste in the standard config above.

You can also open MCP config from the Kiro activity bar and use the same server definition there.

</details> <details> <summary>Katalon Studio</summary>

Katalon StudioAssist expects an MCP proxy for stdio servers. Start a proxy in front of semctx:

mcp-proxy --transport streamablehttp --port 8080 -- go run go.dw1.io/semctx/cmd/semctx@v0.1.0

Then add http://127.0.0.1:8080/mcp in StudioAssist as an HTTP MCP server.

</details> <details> <summary>Mistral Vibe</summary>

Add this to ~/.vibe/config.toml:

[[mcp_servers]]
name = "semctx"
transport = "stdio"
command = "go"
args = ["run", "go.dw1.io/semctx/cmd/semctx@v0.1.0"]

</details> <details> <summary>OpenCode</summary>

Add this to ~/.config/opencode/opencode.json or your existing OpenCode config:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "semctx": {
      "type": "local",
      "command": ["go", "run", "go.dw1.io/semctx/cmd/semctx@v0.1.0"]
    }
  }
}

</details> <details> <summary>Qoder</summary>

In Qoder Settings, go to MCP Server -> + Add and use the standard config above.

You can also follow the Qoder MCP guide.

</details> <details> <summary>Qoder CLI</summary>

Add semctx with the Qoder CLI:

qodercli mcp add semctx -- go run go.dw1.io/semctx/cmd/semctx@v0.1.0
qodercli mcp add -s user semctx -- go run go.dw1.io/semctx/cmd/semctx@v0.1.0

</details> <details> <summary>Visual Studio</summary>

Use Visual Studio MCP server settings and paste in the standard config above.

If you prefer a proxy or wrapper executable, point Visual Studio at that command instead.

</details> <details> <summary>Warp</summary>

Go to `Settings | AI | M