@getnella/mcp

Unified CLI and MCP Server for AI agent validation

Nella is a complete validation toolkit for AI coding agents. It provides both a CLI for direct use and an MCP (Model Context Protocol) server for integration with AI assistants like Claude.

Installation

# Global installation
npm install -g @getnella/mcp

# Or use with npx
npx @getnella/mcp --help

# As a dev dependency
npm install -D @getnella/mcp

Quick Start

CLI Usage

# Pre-flight check before running an agent
nella check -t ./tasks/my-task -r ./project

# Validate agent changes
nella validate -t ./tasks/my-task -r ./project -c changes.json

# Full validation run with metrics
nella run -t ./tasks/my-task -r ./project -c changes.json

MCP Server (for Claude Desktop)

# Start MCP server
nella mcp --workspace /path/to/project

Playground Server

# Start playground with real-time dashboard
nella playground --workspace /path/to/project

# With custom port
nella playground --workspace /path/to/project --port 4000

Open http://localhost:3847 to view the dashboard with:

• Real-time tool call monitoring
• Chain of thought visualization
• Cost tracking (tokens + estimated $)
• Session management

Commands

nella check

Pre-flight check to determine if a task can proceed.

nella check --task <path> --repo <path> [options]

Detects:

• Risk patterns (dangerous requests like logging passwords)
• Missing prerequisites (package.json, node_modules)
• Invalid task structure

nella validate

Validate agent changes against task constraints.

nella validate --task <path> --repo <path> --changes <path> [options]

Validates:

• Constraint violations (forbidden files, patterns)
• Scope creep (unexpected file modifications)
• Test/lint/compile commands (unless --skip-validation)

nella run

Full validation run combining check + validate + metrics.

nella run --task <path> --repo <path> [--changes <path>] [options]

Includes:

• All checks from check and validate
• Metrics calculation
• Artifact generation in .nella/runs/

nella mcp

Start an MCP server for AI agent integration.

nella mcp [--workspace <path>]

nella playground

Start the playground server with a real-time dashboard.

nella playground [--workspace <path>] [--port <number>] [--host <host>]

Features:

• Dashboard UI — Visual interface for monitoring agent sessions
• WebSocket updates — Real-time tool calls, chain of thought, cost tracking
• HTTP API — /health, /api/status, /api/session/:id endpoints

MCP Integration

Claude Desktop Setup

Add to your Claude Desktop config:

Windows (%APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "nella": {
      "command": "npx",
      "args": ["@getnella/mcp", "--workspace", "C:/path/to/project"]
    }
  }
}

macOS/Linux (~/.config/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "nella": {
      "command": "npx",
      "args": ["@getnella/mcp", "--workspace", "/path/to/project"]
    }
  }
}

Available MCP Tools

CLI Options

Programmatic Usage

// Core validation functions
import {
  runTask,
  check,
  validate,
  checkConstraints,
  detectRiskPatterns,
} from '@getnella/mcp';

// MCP server
import { startMcpServer } from '@getnella/mcp/mcp';

// Example: Run validation programmatically
const result = await runTask(repoPath, task, changes);
console.log(result.passed ? 'Validation passed!' : 'Validation failed');

Core Modules (Re-exported)

@getnella/mcp re-exports everything from @usenella/core, including advanced modules:

• Indexing & search (RAG)
• Workspace management
• Auth + rate limiting
• Context sharing
• Cloud sync (GCS)
• Playground server

See the Core Modules guide for examples.

Task YAML Format

id: my-task
name: "Task description"
prompt: |
  Your task prompt here...
category: feature  # feature | bug-fix | refactor | edge-case | refusal
difficulty: easy   # easy | medium | hard
fixture: my-project

constraints:
  - id: no-auth-changes
    description: "Do not modify authentication"
    files_not_to_modify:
      - "src/auth/**"
    forbidden_patterns:
      - "console\\.log"

validation:
  test: "npm run test"
  lint: "npm run lint"
  compile: "npm run check:types"

expected:
  files_to_modify:
    - "src/routes/users.ts"

Changes JSON Format

{
  "files": [
    {
      "path": "src/users.ts",
      "operation": "modify",
      "content": "// Full file content..."
    }
  ]
}

Exit Codes

Related Packages

• @usenella/core - Core validation library
• @usenella/benchmark - Benchmarking tools

Documentation

Full documentation available at:

• CLI Commands
• MCP Integration
• Core API Reference
• Core Modules
• Examples

License

MIT © Nella Labs