Nodule

A local MCP (Model Context Protocol) server that provides a bounce_idea tool — an independent second opinion for your coding agent. It sends your current solution to a configurable LLM critic for architectural critique, bug hunting, and alternative approaches.

How It Works

[Your Agent] ──bounce_idea──> [Nodule MCP Server] ──prompt──> [Your LLM]
                                     │                              │
                                     └───── critique ◄──────────────┘

Nodule implements a Double-Layer Reasoning pattern: your primary agent does the implementation, while an independently configured LLM plays the role of a ruthless senior critic. This breaks local optima and catches issues before they reach production.

BYOM / BYOK

Nodule is fully local. You choose the critic model and provide your own API key:

• Gemini (default) — fast, long-context, cheap
• OpenAI — GPT-4.1-mini, GPT-5, etc.
• Ollama / vLLM / LM Studio — any local model with an OpenAI-compatible /v1/chat/completions endpoint

Quick Start

Go Install

go install github.com/redstone-md/nodule/cmd/nodule@latest

npm

npx @redstone-md/nodule

Configuration (Environment Variables)

Variable	Default	Description
NODULE_LLM_PROVIDER	gemini	LLM provider: gemini or openai
NODULE_MODEL_NAME	gemini-2.5-flash	Model identifier
NODULE_API_KEY	—	API key (fallbacks: GEMINI_API_KEY, GOOGLE_API_KEY, OPENAI_API_KEY)
NODULE_LLM_BASE_URL	—	Base URL for OpenAI-compatible servers (e.g. http://localhost:11434/v1)
NODULE_TEMPERATURE	1.2	Critic temperature (higher = more creative)
NODULE_MAX_TOKENS	4096	Maximum output tokens
NODULE_SERVER_NAME	nodule	MCP server name
NODULE_SERVER_VERSION	0.4.1	MCP server version

Examples

Gemini (default):

export NODULE_API_KEY="your-gemini-key"
export NODULE_MODEL_NAME="gemini-2.5-flash"
npx @redstone-md/nodule

OpenAI:

export NODULE_LLM_PROVIDER="openai"
export NODULE_API_KEY="sk-..."
export NODULE_MODEL_NAME="gpt-4.1-mini"
npx @redstone-md/nodule

Local Ollama (no API key needed):

export NODULE_LLM_PROVIDER="openai"
export NODULE_LLM_BASE_URL="http://localhost:11434/v1"
export NODULE_MODEL_NAME="qwen3:8b"
npx @redstone-md/nodule

MCP Tool: bounce_idea

Parameter	Type	Required	Description
context	string	Yes	Current codebase state, function signatures, benchmarks, or error logs
proposed_solution	string	Yes	Draft idea or code the agent plans to apply
focus	string	No	Critique specialization: performance, architecture, security, edge_cases (default: performance)

Focus Modes

• performance — Hidden allocations, O(N^2) paths, cache misses, lock contention
• architecture — Encapsulation leaks, cyclic dependencies, god-objects, SRP violations
• security — Injection vulnerabilities, unsafe operations, input validation gaps
• edge_cases — Race conditions, deadlocks, nil/empty inputs, context cancellation

MCP Client Configuration

For AI agents: a step-by-step, copy-paste install guide written for an LLM to follow lives in docs/INSTALL_FOR_LLM.md.

Claude Code

Fastest — one command (user scope, available in every project):

claude mcp add nodule --scope user \
  -e NODULE_LLM_PROVIDER=gemini \
  -e NODULE_API_KEY=your-key \
  -e NODULE_MODEL_NAME=gemini-2.5-flash \
  -- npx -y @redstone-md/nodule@latest

Verify: claude mcp list should show nodule … ✔ Connected.

Or edit ~/.claude.json (top-level mcpServers) by hand:

{
  "mcpServers": {
    "nodule": {
      "command": "npx",
      "args": ["-y", "@redstone-md/nodule@latest"],
      "env": {
        "NODULE_LLM_PROVIDER": "gemini",
        "NODULE_API_KEY": "your-key",
        "NODULE_MODEL_NAME": "gemini-2.5-flash"
      }
    }
  }
}

OpenCode (~/.config/opencode/opencode.json)

OpenCode uses a single command array, not command + args:

{
  "mcp": {
    "nodule": {
      "type": "local",
      "command": ["npx", "-y", "@redstone-md/nodule@latest"],
      "enabled": true,
      "env": {
        "NODULE_LLM_PROVIDER": "openai",
        "NODULE_LLM_BASE_URL": "https://api.openai.com/v1",
        "NODULE_API_KEY": "sk-...",
        "NODULE_MODEL_NAME": "gpt-4.1-mini"
      }
    }
  }
}

Cursor / VS Code

{
  "mcp.servers": {
    "nodule": {
      "command": "npx",
      "args": ["-y", "@redstone-md/nodule@latest"],
      "env": {
        "NODULE_LLM_PROVIDER": "openai",
        "NODULE_API_KEY": "your-key",
        "NODULE_MODEL_NAME": "gpt-4.1-mini"
      }
    }
  }
}

First-run note (read this if it "doesn't connect")

npx downloads a ~16 MB platform binary on first launch. A cold start can exceed an MCP client's startup timeout, and a stale npx cache from an older version is the most common failure. Pre-warm once in a terminal, then (re)start your client:

npm cache clean --force            # only if a previous version misbehaved
npx -y @redstone-md/nodule@latest  # wait for "nodule: ready", then Ctrl+C

Skill (Claude Code)

A bundled skill teaches the agent when and how to call bounce_idea well. Install:

mkdir -p ~/.claude/skills/nodule
cp skills/nodule/SKILL.md ~/.claude/skills/nodule/SKILL.md

Development

# Build
go build ./cmd/nodule/

# Test
go test ./...

# Vet
go vet ./...

Architecture

cmd/nodule/main.go          # Entry point: config → provider → server
internal/
  config/config.go          # Env-based BYOM/BYOK configuration
  llm/
    client.go               # llm.Client interface (Bring Your Own Model)
    gemini.go               # Gemini provider (google.golang.org/genai)
    openai.go               # OpenAI-compatible provider (Ollama, vLLM, etc.)
    llmmock/mock.go         # Test double for llm.Client
  prompt/builder.go         # System/user prompt assembly by focus mode
  mcpserver/server.go       # MCP server + bounce_idea tool handler

License

MIT