gokr/nimgenie

NimGenie v0.2.0

MCP Server for AI assisted Nim Programming

NimGenie is a Model Context Protocol (MCP) server that provides AI assistants with deep understanding of Nim codebases through intelligent code analysis, symbol indexing, and development assistance.

What is NimGenie?

NimGenie bridges the gap between AI assistants and Nim development by providing MCP tools for the LLM to use to:

• Intelligent Symbol Search: Find functions, types, and variables across your entire codebase and dependencies
• Semantic Search with Vector Embeddings: Vector-based similarity search using TiDB native vector support
• Real-time Code Analysis: Perform syntax checking and semantic validation using the Nim compiler
• External Database Integration: Query external TiDB/MySQL databases directly from AI assistants
• Dependency Management: Automatic discovery and indexing of Nimble packages
• Multi-Project Support: Work with multiple Nim projects simultaneously
• Persistent Storage: TiDB-backed symbol database that survives server restarts

Key Features

🔍 Code Indexing

• Search symbols by name, type, or module across your entire codebase
• Automatic indexing of project dependencies and Nimble packages
• Cross-reference functionality to understand code relationships
• Dependency-based incremental indexing that only re-indexes changed files and their dependents

🧠 Semantic Search with Vector Embeddings

• Vector-based semantic search using TiDB native vector support
• Embedding generation via Ollama local LLM
• Find similar symbols based on semantic meaning
• Combined text and vector search capabilities

🛠️ Development Tasks

• Syntax and semantic checking with detailed error reporting
• Project statistics and codebase metrics
• Nimble package management (install, search, upgrade)
• Project creation and build automation
• Dependency-based incremental indexing for efficient re-indexing

📁 Resource Management

• Serve project files and assets as MCP resources
• Screenshot workflow support for game development
• Directory-based resource organization

🗃️ External Database Integration

• Query external TiDB/MySQL databases directly from AI assistants
• Execute SQL queries with safety controls
• Schema exploration and data analysis tools
• Streaming query results with real-time updates

🔧 Advanced Tooling

• 46 specialized MCP tools organized into 8+ functional categories
• Structured Output Schemas: All tools include MCP-compliant output schemas for better LLM understanding
• Streaming versions of tools for real-time progress updates
• Multi-project support for working with multiple codebases simultaneously
• Fine-grained locking for thread-safe concurrent access

Quick Start

1. Prerequisites

• Nim 2.2.4+: Install from nim-lang.org
• TiDB: For persistent storage (see setup below)
• Ollama: For running a local LLM to perform embeddings

2. TiDB Setup

NimGenie uses TiDB for persistent storage. The easiest way to get started running Tidb locally is with TiUP:

# Install TiUP (TiDB cluster management tool)
curl --proto '=https' --tlsv1.2 -sSf https://tiup-mirrors.pingcap.com/install.sh | sh

# Start a persistent TiDB playground for Nimgenie (includes TiDB, TiKV, PD)
tiup playground --tag nimgenie

This starts TiDB on localhost:4000 with default settings (user: root, password: empty).

3. Install NimGenie

# Clone the repository
git clone https://github.com/gokr/nimgenie
cd nimgenie

# Build the MCP server
nimble build

# Run NimGenie
./nimgenie

# Install globally
nimble install

4. Configuration

NimGenie can be configured via environment variables or command-line options.

Command-line options:

Usage: nimgenie [OPTIONS]

Options:
  -h, --help              Show help message
  -v, --version           Show version information
  -p, --port <number>     MCP server port (default: 8080)
      --host <address>    Host address (default: localhost)
      --project <path>    Project directory (default: current directory)
      --verbose           Enable verbose logging
      --database-host     TiDB host (default: localhost)
      --database-port     TiDB port (default: 4000)
      --no-discovery      Disable Nimble package discovery

5. Tutorial

For comprehensive documentation and tutorials, see the .

Architecture

NimGenie is built with Nimcp, a library that makes it easy to build MCP servers. We mostly call out to Nim tools like nimble and the Nim compiler etc to perform indexing and other tasks. The database used is Tidb because it is MySQL compatible, fully Open Source, can run locally or is also available in the cloud and supports vector based searching and more. Embeddings are calculated via Ollama with an embeddings LLM running, typically locally. NimGenie also provides tools for external database integration, allowing AI assistants to query external TiDB/MySQL databases directly.

Dependency Tracking

NimGenie uses the Nim compiler's built-in dependency analysis (nim genDepend) to track file dependencies efficiently. This enables:

• Incremental indexing: Only re-index files that have changed and their dependents
• Accurate dependency tracking: Leverages the compiler's understanding of imports and modules
• Efficient updates: Avoids full re-indexing on every change
• Cascade changes: Automatically identifies all files affected by a dependency change

The dependency information is stored in the TiDB database with tables for:

• file_dependency: Tracks source → target file dependencies
• file_modification: Stores file modification times, sizes, and hashes

This approach is more reliable than manual file hash/modification tracking as it uses the compiler's own dependency analysis, handling complex import scenarios correctly.

Documentation

For comprehensive documentation, see the which covers:

• Quick start guide
• Architecture overview
• Installation & configuration
• Tutorial & examples
• Complete MCP tool reference
• Vector embedding system
• External database integration
• Output Schema Reference - JSON schemas for all 46 MCP tools
• Advanced topics
• Testing guide
• Development guidelines

Output Schema Documentation

NimGenie now includes comprehensive output schemas for all 46 MCP tools, following the MCP specification. These schemas provide LLMs with structured information about tool return values, enabling better tool selection and result handling.

See docs/MANUAL.md#output-schema-reference (Section 9) for detailed documentation covering:

• What output schemas are and their benefits
• Schema format and examples
• All 46 tools with their return value structures
• Implementation details and technical information

Contributing

We welcome contributions! Please see our development documentation in CLAUDE.md for detailed information about the codebase architecture and development guidelines.

License

MIT License - see LICENSE file for details.

Links

• Nimcp: github.com/gokr/nimcp
• MCP Protocol: modelcontextprotocol.io
• Nim Language: nim-lang.org
• TiDB Database: pingcap.com