nimcp: Instructions file for Claude Code

CLAUDE.md

NimCP - Nim library for MCP servers using macro-based APIs. Implements JSON-RPC 2.0 over stdio/websockets/SSE for LLM integration.

Commands

nimble test          # Run all tests
nim r tests/test_*.nim  # Run specific test
nim c examples/      # Build examples  
nimble docs         # Generate docs
nim c -r examples/basic_calculator.nim  # Compile and run example

Architecture

Core: types.nim (MCP types), server.nim (server separate from transports), mcpmacros.nim (macro API), protocol.nim (JSON-RPC)

Macro API (recommended) can be seen in @examples/macro_calculator.nim The macro API automatically extracts:

• Tool names from proc names
• Descriptions from doc comments (first line)
• JSON schemas from parameter types (int, float, string, bool, seq)
• Parameter documentation from doc comment parameter lists
• Type-safe wrappers for JSON parameter conversion

Key types: McpServer, McpTool, McpResource, McpPrompt, McpRequestContext

Transports: Stdio (CLI), HTTP (REST), WebSocket (realtime), SSE (deprecated) Examples: See examples/ - calculator variants for each transport Dependencies: nim >= 2.2.4, mummy, taskpools

MCP specification

• https://modelcontextprotocol.io/specification/2025-06-18

Streamable HTTP

• https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http
• https://www.claudemcp.com/blog/mcp-streamable-http
• https://mcp-framework.com/docs/Transports/http-stream-transport

Coding Guidelines

• Do not shadow the local result variable (Nim built-in)
• Doc comments: ## below proc signature
• Prefer generics or object variants over methods
• Use return expression for early exits
• Prefer direct field access over getters/setters
• JSON: Use %*{} syntax
• NO asyncdispatch - use taskpools for concurrency or normal threading
• Remove old code during refactoring
• Import full modules, not select symbols
• Use * to export fields that should be publicly accessible
• If something is not exported, export it instead of doing workarounds
• Do not be afraid to break backwards compatibility
• Do not add comments talking about how good something is, it is just noise. Be brief.
• Do not add comments that reflect what has changed, we use git for change tracking, only describe current code
• Do not add unnecessary commentary or explain code that is self-explanatory
• Single-line functions: Use direct expression without result = assignment or return statement
• Multi-line functions: Use result = assignment and return statement for clarity
• Early exits: Use return value instead of result = value; return
• Exception handlers: Use return expression for error cases
• JSON Object Construction: Prefer the %*{} syntax for clean, readable JSON creation
• Content Serialization: Use centralized utilities for consistent formatting
• Error Response Creation: Use standardized error utilities across all transport layers