Semctx

Semantic code context for AI agents, via LSP and LSIF.

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/[email protected]"],
      "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.

claude mcp add semctx --scope user go run go.dw1.io/semctx/cmd/[email protected]

codex mcp add semctx -- go run go.dw1.io/semctx/cmd/[email protected]

cmd mcp add semctx --scope user go run go.dw1.io/semctx/cmd/[email protected]

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

droid mcp add semctx "go run go.dw1.io/semctx/cmd/[email protected]"

gemini mcp add semctx go run go.dw1.io/semctx/cmd/[email protected]
gemini mcp add -s user semctx go run go.dw1.io/semctx/cmd/[email protected]

mcp-proxy --transport streamablehttp --port 8080 -- go run go.dw1.io/semctx/cmd/[email protected]

[[mcp_servers]]
name = "semctx"
transport = "stdio"
command = "go"
args = ["run", "go.dw1.io/semctx/cmd/[email protected]"]

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

qodercli mcp add semctx -- go run go.dw1.io/semctx/cmd/[email protected]
qodercli mcp add -s user semctx -- go run go.dw1.io/semctx/cmd/[email protected]

By default, semctx looks for ./.semctx.yaml in the current workspace. You can also point it at a custom config path with -config or SEMCTX_CONFIG.

Internal logging is off by default so MCP stdio sessions stay quiet unless you're debugging. Enable it with -log-level or SEMCTX_LOG_LEVEL using one of debug, info, warn, error, or off. When logging is enabled, semctx always writes to stderr and will also append to -log-file or SEMCTX_LOG_FILE when you want a persistent log.

Example:

{
  "mcpServers": {
    "semctx": {
      "command": "/path/to/semctx",
      "env": {
        "SEMCTX_CONFIG": "./.semctx.yaml",
        "SEMCTX_LOG_LEVEL": "debug",
        "SEMCTX_LOG_FILE": "./.semctx/semctx.log"
      }
    }
  }
}

[!NOTE] If no semctx config is provided, it looks for ./.semctx.yaml in the current workspace. If that file is not present, semctx still starts, but LSP tools need configured sessions before they can do useful work.

Configuration

Config is YAML. Basics:

• servers for LSP server connections.
• defaults for shared rules across bindings.
• languages to map languages to servers.
• transport.kind as stdio, tcp, or unix.
• Relative config paths resolve from the current workspace root.
• LSP server launch directories default to the current workspace root.
• Bindings active unless disabled is true.
• Files in .yaml or .yml.
• Auto-finds ./.semctx.yaml in the current workspace when no path is provided.
• LSP client info from semctx name and version, not customizable.

Example:

defaults:
  diagnosticsMode: auto
  connectionTimeout: 10s

servers:
  gopls:
    transport:
      kind: stdio
    stdio:
      command: gopls
      args:
        - serve
    env:
      GOFLAGS: -tags=integration

languages:
  go:
    server: gopls
    initializationOptions:
      gofumpt: true

Transport needs:

• stdio: stdio.command; args optional.
• tcp: tcp.address.
• unix: unix.path.

Startup validates: rejects bad keys, missing refs, incomplete transports, invalid modes.

MCP Tool Surface

These tools are the key: agents use them directly instead of rebuilding language logic from searches.

Request Conventions

For document tools:

• source may be lsp or online for live workspace queries, lsif or offline for local-dump queries, or omitted to auto-select LSIF when indexPath is present and LSP otherwise.
• language is your configured language id for live LSP requests.
• path can be absolute or relative to the current workspace root; uri works too.
• indexPath points at the primary LSIF JSONL dump for offline requests, and relatedIndexPaths adds extra dumps for cross-dump links.
• Positions stay zero-based.
• Big tools like references and implementations take limit and offset for paging.

For LSP-only planning and workspace tools:

• Rename sends newName, returns LSP WorkspaceEdit.
• Formatting sends FormattingOptions, returns TextEdit array.
• Workspace diagnostics take identifier and previousResultIds, return report.

For the LSIF-only project tool:

• indexPath points at the primary LSIF JSONL dump.
• relatedIndexPaths adds extra dumps for cross-dump links.
• uri is preferred for docs; path resolves from the current workspace root.

One live binding? Skip language where allowed. Multiple? Send it.

Behavior Notes

semctx checks LSP capabilities at init, runs tools only if supported. Handles server requests for config and folders. Acknowledges refreshes for codeLens, semanticTokens, etc. Rejects applyEdit (it's read-only). No vendor extensions.

License

semctx is released with ♡ by @dwisiswant0 under the Apache License 2.0. See the LICENSE file for details.