Nim Language Server

The nimlangserver is a versatile tool that supports two primary modes of operation:

1. LSP Server: Use it as a Language Server Protocol (LSP) provider for standard code editors and IDEs to enable features like autocompletion, go-to-definition, and diagnostics.
2. MCP Server: Use it as a Model Context Protocol (MCP) server to provide Nim language intelligence to AI coding agents such as GitHub Copilot, Claude Code, and Gemini.

nimlangserver is a language server for Nim that supports two distinct operational modes depending on your use case:

1. LSP server: The default mode. It provides Nim language intelligence (autocompletion, diagnostics, etc.) to editors and IDEs like VSCode, Neovim, Helix, and Emacs. Running nimlangserver without flags is equivalent to nimlangserver --lsp.
2. MCP server: Exposes Nim-aware tools to AI coding agents such as GitHub Copilot, Claude Code, and Gemini.

To use the LSP mode, follow the LSP server setup instructions. To use the MCP mode, follow the MCP server setup instructions.

Nim's identifier resolution is semantic rather than purely textual. Symbols can be accessed via different spellings (e.g., printThing, printthing, print_thing) or through templates and macros.

Standard text search (like grep) often misses these indirect or case-variant usages. Using nimlangserver as an MCP server ensures that tools like nimFindSymbols and nimFindReferences use the same semantic analysis as the Nim compiler, guaranteeing correct results for all identifier resolutions.

proc printThing(thing: string) =
  echo thing

template doActionWithThing(action: untyped, thing: string): untyped =
  `action Thing`(thing)

when isMainModule:
  printThing("Hello")
  printthing("World")
  print_thing("Nim is awesome")
  doActionWithThing(print, "No really, Nim is so cool")

When using Nim MCP tools, follow these rules for error handling and fallback to general-purpose tools (like grep or ripgrep):

1. On Technical Error: If an MCP tool crashes, times out, or has a connection issue, you MUST fall back to grep_search or other general-purpose tools. State clearly that the MCP tool failed.
2. On Empty Results: If an MCP tool returns an empty list, DO NOT automatically fall back to grep. You MUST prompt the user first, asking if they would like a plain text search.
3. On Unavailability: If MCP tools are unavailable, use general-purpose tools but inform the user.

Note: Fallback results should not be presented as being equivalent in precision to MCP tool results.

You can choose between two transport mechanisms:

• stdio: The default. Best for clients that launch nimlangserver as a subprocess (standard for editors and AI agents).
• socket: Useful when the server and client run in separate environments (e.g., a Windows editor connecting to a server in WSL) or when multiple clients need to connect to a single running server instance.

# LSP over socket, auto port
nimlangserver --lsp --socket

# LSP over socket, specific port
nimlangserver --lsp --socket --port=6000

Inlay hints provide visual context in the editor. nimlangserver supports:

• Type hints: Shows inferred variable types.
• Exception hints: Highlights functions that raise exceptions.
• Parameter hints: (Not yet implemented) Shows parameter names at call sites.

To enable them in Neovim (lspconfig):

require('lspconfig').nim_langserver.setup({
  settings = {
    nim = {
      inlayHints = {
        typeHints = true,
        exceptionHints = true,
        parameterHints = true,
      }
    }
  },
  on_attach = function(client, bufnr) 
    if client.server_capabilities.inlayHintProvider then
       vim.lsp.inlay_hint.enable(true, { bufnr = bufnr })
    end
  end
})

To enable them in Helix (add to languages.toml):

[language-server.nimlangserver.config.nim]
inlayHints = { typeHints = true, exceptionHints = true, parameterHints = true }

The nimlangserver can be run in two primary modes: LSP (Language Server Protocol) or MCP (Model Context Protocol).

• LSP mode is the default and is used by most editors and AI tools for language intelligence.
• MCP mode is used for Model Context Protocol integrations.

By default, both modes use stdio as the transport mechanism, which is ideal when the client launches the server as a subprocess.

# LSP over stdio (default)
nimlangserver

# MCP over stdio (default)
nimlangserver --mcp

Use the most granular diagnostic tool available to conserve tokens and context:

• Use nimCheckFile when the user asks to check a specific Nim file. Do not substitute this with manual inspection, ad-hoc compiler invocations, or nimCheckProject.
• Use nimCheckProject when the user asks for project, workspace, repository, or package-wide diagnostics. Do not substitute this with shelling out to ad-hoc Nim commands or manual log scans.

You can install the Nim Language Server globally using nimble.

Prerequisites:

• nimble >= 0.16.1
• A version of nimsuggest that supports the --v3 flag (Nim 1.6 or devel).

nimble install -g nimlangserver

Before using the tools, you must load the skill using the /nim-mcp-tools slash command in your AI tool.

Once loaded, the AI agent will automatically prefer these semantic tools over general-purpose text search tools (like grep). You can also invoke them directly via natural language commands, for example: "Call nimCheckFile on @myfile.nim."