nimctx - Nim Context MCP Server

English | 中文

Nim Context MCP Server provides deep context for Nim projects and standard library for AI programming assistants, including module indexing for dependency packages.

This project nimctx solves the problem of AI programming assistants lacking deep context about Nim projects.

The Problem

When AI assistants (like Claude) help with Nim programming, they face several challenges:

1. No easy access to stdlib docs - Can't look up standard library functions, their signatures, or documentation
2. Dependency blind spot - Don't know what packages a project depends on or what's available in them
3. Import confusion - Can't tell if import json refers to stdlib or a third-party package
4. Version compatibility - Hard to check if code works across different Nim versions
5. Manual context - Users have to manually copy-paste docs or package info into conversations

Features

Standard Library Support

• Standard Library Documentation Query: Search and retrieve symbols, procedure signatures, and documentation from the Nim standard library
• Module Documentation: Get exported symbols and documentation from stdlib modules

Dependency Package Support

• Dependency Listing: Get project dependency information via nimble
• Package Module Indexing: Index modules from installed packages (e.g., jsony, chronos, etc.)
• Cross-Package Search: Search symbols across multiple dependency packages
• Package-Specific Search: Search symbols within a specific package

Development Assistance

• Import Resolution: Resolve the source of import statements (stdlib or dependency packages)
• Procedure Signatures: Get detailed signatures for procedures from stdlib or dependency packages
• Smart Caching: Search result caching for improved response speed
• Project Root Support: All tools support projectRoot parameter to analyze any Nim project

Installation

Build from Source

git clone <repository>
cd nimctx
nimble build

Or using nim command:

nim c -d:release src/nimctx.nim

Usage

Command Line

./nimctx

The server communicates with MCP clients via standard input/output (stdio).

MCP Client Configuration

Claude Desktop (macOS)

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "nimctx": {
      "command": "/path/to/nimctx",
      "args": []
    }
  }
}

RooCode / Cline (VS Code)

Add to VS Code settings:

{
  "mcp.servers": {
    "nimctx": {
      "command": "/path/to/nimctx",
      "args": [],
      "transportType": "stdio",
      "enabled": true
    }
  }
}

Available Tools

Usage Examples

Search Standard Library:

search_stdlib(query: "split", moduleFilter: "strutils")

Search in Dependency Packages:

search_stdlib(query: "parseJson", packageFilter: "jsony")

Get Procedure Signature from Package:

get_proc_signature(procName: "fromJson", packageName: "jsony")

List Dependencies:

list_dependencies(directOnly: true)

Specify Project Root:

# Analyze dependencies of a specific project
list_dependencies(projectRoot: "/path/to/my/project")

# Search symbols in another project
search_stdlib(query: "parseJson", projectRoot: "/path/to/my/project")

Check Version Compatibility:

check_version_compat(filePath: "src/myfile.nim", testAllInstalled: true)

List Nim Versions:

list_nim_versions()

Configuration

// ~/.config/nimctx/config.json or ./nimctx.json
{
  "nim": {
    "nimPath": "/usr/local/bin/nim",
    "nimblePath": "/usr/local/bin/nimble",
    "stdlibPath": "/usr/local/lib/nim/lib"
  },
  "indexing": {
    "enableStdlibIndex": true,
    "cacheDir": "~/.cache/nimctx"
  },
  "limits": {
    "maxSearchResults": 20,
    "maxDocLength": 10000
  }
}

Project Structure

nimctx/
├── src/
│   ├── nimctx.nim              # Main entry + MCP server
│   └── nimctx/
│       ├── config.nim          # Configuration management
│       ├── version_compat.nim  # Nim version compatibility checking
│       ├── stdlib/
│       │   └── indexer.nim     # Standard library indexing
│       ├── packages/
│       │   └── indexer.nim     # Dependency package indexing
│       ├── project/
│       │   └── manager.nim     # Nimble dependency management
│       └── utils/
│           ├── cache.nim       # In-memory cache system
│           ├── logging.nim     # Logging utilities
│           ├── indexing.nim    # Indexing utilities and common types
│           └── sqlite_indexer.nim  # SQLite-based symbol indexing backend
├── tests/                      # Tests
├── examples/                   # Configuration examples
└── notes/                      # Design documents

Technical Features

• SQLite-Based Indexing: Persistent and efficient symbol storage using SQLite backend for fast lookups
• Multi-Level Caching: File index cache + in-memory search cache for optimal performance
• Incremental Indexing: Index dependency packages on demand with automatic discovery
• Version Compatibility Checking: Test code against multiple Nim versions via choosenim integration
• Smart Recognition: Automatically distinguishes between stdlib and package modules

License

MIT