Skill: pablomanjarres/nella (version 0.2.7)

--- name: nella description: Use this skill whenever the user is working inside a code repository and needs grounded, codebase-aware answers: locating a symbol or definition, tracing where a function is called, understanding how modules connect, reviewing dependency drift, or maintaining persistent context across a session. Trigger this skill on phrases like "where is X defined", "how is Y used", "what calls this", "search the codebase", "index this repo", or any request that benefits from semantic or hybrid code search rather than blind grep. Also use when an assumption about the codebase should be recorded for later verification, or when a long-running coding session needs continuity of context across turns. Do NOT use this skill for one-off shell commands, simple text edits, or tasks that do not require structural understanding of the repository. --- # Nella MCP Nella is a codebase intelligence layer for AI coding agents. It exposes the repository as a set of searchable, structured tools over the Model Context Protocol, so an agent can ground its reasoning in the actual code rather than guessing from filenames or partial snippets. ## When to reach for Nella Use the Nella tools when any of the following is true: - The repo is non-trivial (more than a handful of files) and a grep would return too many false positives. - The user asks about behavior, call sites, or relationships rather than literal strings. - The session involves multiple turns and context should persist (assumptions, prior searches, prior decisions). - A change is being scoped and dependency drift or impact analysis matters. If the question is purely lexical (find a literal token in one file), plain `grep` or `view` is faster and Nella is overkill. ## Setup The package ships two binaries: `nella` (CLI) and `mcp` (stdio MCP entrypoint). Local stdio config for an MCP client: ```json { "mcpServers": { "nella": { "command": "npx", "args": ["-y", "@getnella/mcp", "--workspace", "/absolute/path/to/project"] } } } ``` Hosted config (recommended for shared or always-on workspaces): ```json { "mcpServers": { "nella": { "url": "https://mcp.getnella.dev/mcp", "headers": { "Authorization": "Bearer nella_your_key_here" } } } } ``` Quick shortcut for Claude Code: `nella setup`. For other clients: `nella connect --client <claude|claude-code|vscode|cursor|windsurf|cline|roo-code>`. ## Available tools | Tool | When to call it | |------|-----------------| | `nella_index` | First contact with a workspace, or after large refactors. Pass `--force` to rebuild from scratch. | | `nella_search` | Default lookup. Supports `hybrid` (best general default), `semantic` (concept-level), and `lexical` (exact tokens). | | `nella_get_context` | Pull the current session memory before answering, so prior assumptions and searches are not lost. | | `nella_add_assumption` | Record any non-trivial assumption ("this function is only called from the worker") so it can be verified later. | | `nella_check_assumptions` | Review recorded assumptions, especially before committing changes that depend on them. | | `nella_check_dependencies` | Detect drift between the index and the working tree, or surface upstream impact of a change. | | `nella_heartbeat` | Verify trust-chain continuity between tool calls in long sessions. | ## Recommended flow 1. Call `nella_get_context` at the start of a non-trivial task to load any prior session state. 2. If the workspace has not been indexed yet, call `nella_index`. Skip this if the index is already current. 3. Use `nella_search` (hybrid by default) to locate the relevant code before reading files. 4. Record any load-bearing assumption with `nella_add_assumption` so it survives across turns. 5. Before finalizing changes, run `nella_check_assumptions` and `nella_check_dependencies`. ## Search mode selection - **hybrid**: Default. Combines lexical and semantic signals. Use when unsure. - **semantic**: Conceptual queries ("where do we handle rate limiting", "auth flow for OAuth"). Tolerates paraphrase. - **lexical**: Exact identifiers, error strings, or known token shapes. Faster, no embedding cost. ## Notes for the agent - Always pass an absolute path to `--workspace`. Relative paths fail silently in some clients. - Hosted mode requires a valid API key. If `nella_search` returns an auth error, surface it to the user rather than retrying blindly. - The index can lag behind the working tree on large repos. If results look stale, call `nella_index` (without `--force`) for an incremental refresh. - Treat `nella_get_context` output as authoritative for prior decisions in the session. Do not override silently.

path: dist/cli.d.ts
content: #!/usr/bin/env node


path: dist/index.d.ts
content: export { AssumptionTracker, AssumptionType, ChangeLedger, Changes, CodeChunk, Constraint, ContextManager, ContextService, DependencyChange, DependencyTracker, FileChange, IndexConfig, IndexManager, McpTool, McpToolCall, McpToolHandler, McpToolResult, NELLA_TOOLS, RawTaskYaml, RunLogger, RunResult, SearchQuery, SearchResponse, SearchResult, SearchService, SessionStore, Task, ToolHandlerConfig, ValidationResult, VerifyCodeRequest, VerifyCodeResult, Workspace, WorkspaceConfig, WorkspaceEntry, WorkspaceOptions, WorkspaceRegistry, WorkspaceService, WorkspaceSwitcher, applyChanges, cleanupTempWorkspace, createCodeVerifier, createHybridSearcher, createIndexManager, createMcpToolHandler, createNellaDir, createTempWorkspace, createWorkspaceRegistry, createWorkspaceSwitcher, generateRunId, getDiff, getModifiedFiles, getWorkspaceRegistry, getWorkspaceSwitcher, validateToolInput, writeArtifacts } from '@usenella/core';
import { ServerContext } from './mcp/server.js';
export { startMcpServer } from './mcp/server.js';
import { Tool } from '@modelcontextprotocol/sdk/types.js';

/**
 * Context Tools
 *
 * MCP tools for stateful context tracking across agent sessions:
 * - Dependency monitoring
 * - Assumption tracking
 * - Change history
 * - Session context
 */

declare function registerContextTools(): Tool[];
interface ToolCallResult {
    content: Array<{
        type: "text";
        text: string;
    }>;
    isError?: boolean;
}
declare function handleContextTool(name: string, args: Record<string, unknown>, context: ServerContext): Promise<ToolCallResult | null>;

export { ServerContext, handleContextTool, registerContextTools };


path: dist/mcp/hosted-server.d.ts
content: /**
 * Hosted MCP Server
 *
 * Exposes Nella's MCP tools over Streamable HTTP transport.
 * Authenticates via API keys stored in Supabase, rate limits via Redis,
 * and logs usage to the usage_events table.
 *
 * Usage:
 *   nella serve --port 3000
 *   NODE_ENV=production node packages/nella/dist/mcp/hosted-server.js
 *
 * Required env vars:
 *   SUPABASE_URL              - Supabase project URL
 *   SUPABASE_SERVICE_ROLE_KEY - Supabase service role key
 *   REDIS_URL                 - Redis connection string (rediss://... for TLS)
 *
 * Optional env vars:
 *   PORT                      - HTTP port (default: 3000)
 *   NELLA_LOG_LEVEL           - Log level (default: info)
 */
interface HostedServerOptions {
    port?: number;
    host?: string;
}
declare function startHostedServer(options?: HostedServerOptions): Promise<void>;

export { type HostedServerOptions, startHostedServer };


path: dist/mcp/server.d.ts
content: #!/usr/bin/env node
import { ContextManager } from '@usenella/core';

/**
 * Challenge-Response Heartbeat
 *
 * Lightweight challenge-response mechanism to verify trust chain continuity
 * between tool calls. If an injection hijacks the agent's behavior, the
 * challenge-response will fail on the next tool call.
 *
 * Flow:
 * 1. nella_get_context issues the first challenge
 * 2. Agent includes the challenge response in its next nella tool call
 * 3. System verifies and issues a new challenge
 * 4. If verification fails → warning (trust chain may be compromised)
 *
 * Part of the prompt injection defense system (Layer 4 upgrade).
 */

interface ChallengeState {
    /** Current active challenge the agent should respond to */
    currentChallenge: string;
    /** Number of successful verifications in this session */
    verifiedCount: number;
    /** Number of failed verifications */
    failedCount: number;
    /** Whether the last verification succeeded */
    lastVerified: boolean;
    /** Timestamp of last verification */
    lastVerifiedAt?: string;
}

/**
 * Nella MCP Server
 *
 * Model Context Protocol server that exposes Nella's codebase intelligence
 * to AI agents like Claude.
 *
 * Usage:
 *   npx -y @getnella/mcp --workspace /path/to/project  # direct stdio entrypoint
 *   nella mcp --workspace /path/to/project            # via CLI subcommand
 */

interface ServerContext {
    workspacePath: string;
    contextManager: ContextManager;
    /** Per-session trust token for prompt injection defense (L4) */
    sessionToken?: string;
    /** HMAC signing key derived from session token (L4+) */
    hmacKey?: Buffer;
    /** Challenge-response state for trust chain verification (L4+) */
    challengeState?: ChallengeState;
}
declare function startMcpServer(args: {
    workspace?: string;
    help?: boolean;
}): Promise<void>;

export { type ServerContext, startMcpServer };


path: dist/mcp/index.d.ts
content: export { ServerContext, startMcpServer } from './server.js';
export { startHostedServer } from './hosted-server.js';
export { handleContextTool, registerContextTools } from '../index.js';
import '@usenella/core';
import '@modelcontextprotocol/sdk/types.js';


path: README.md
content: # @getnella/mcp

CLI and MCP server package for Nella.

## Install

```bash
npm install -g @getnella/mcp
```

The package installs:

- `nella` for the CLI
- `mcp` as the direct stdio MCP entrypoint used by `npx -y @getnella/mcp --workspace /path/to/project`

## Quick Start

```bash
# Show CLI help
nella help

# Configure a supported client
nella connect --client claude

# Claude Code shortcut
nella setup

# Start the local stdio MCP server directly
npx -y @getnella/mcp --workspace /path/to/project
```

If you want to build or refresh the local index yourself:

```bash
nella auth login
nella index --force
```

`nella index` requires either a Nella login or Azure embedding environment variables.

## Commands

| Command | Purpose |
|---------|---------|
| `nella index [--workspace <path>] [--force] [--graph]` | Index a workspace or build a dependency graph from an existing index |
| `nella mcp --workspace <path>` | Start the local stdio MCP server |
| `nella serve [--port <number>] [--host <host>]` | Start the hosted HTTP MCP server |
| `nella connect [--mode <local\|hosted>] [--client <name>]` | Write MCP client config for supported agents |
| `nella auth <login\|logout\|status>` | Manage CLI authentication |
| `nella setup` | Alias for `nella connect --client claude-code --mode local -y` |
| `nella help` | Show top-level help |

Direct stdio/local launches must include `--workspace`, for example `npx -y @getnella/mcp --workspace /path/to/project`.

## MCP Tools

| Tool | Description |
|------|-------------|
| `nella_index` | Index or re-index a workspace |
| `nella_search` | Search indexed code with hybrid, semantic, or lexical mode |
| `nella_get_context` | Read the current session context |
| `nella_add_assumption` | Record an assumption about the codebase |
| `nella_check_assumptions` | Review assumption status |
| `nella_check_dependencies` | Check dependency drift |
| `nella_heartbeat` | Verify trust-chain continuity between tool calls |

## Manual Client Config

Local stdio example:

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

Hosted example:

```json
{
  "mcpServers": {
    "nella": {
      "url": "https://mcp.getnella.dev/mcp",
      "headers": {
        "Authorization": "Bearer nella_your_key_here"
      }
    }
  }
}
```

## Notes

- `nella connect` supports `claude`, `claude-code`, `vscode`, `cursor`, `windsurf`, `cline`, and `roo-code`.
- The local `nella serve` implementation requires `SUPABASE_URL` and `SUPABASE_SERVICE_ROLE_KEY`, and uses `REDIS_URL` when available.

## Docs

- [CLI Reference](../../docs/cli/commands.md)
- [Installation](../../docs/getting-started/installation.md)
- [Quick Start](../../docs/getting-started/quick-start.md)
- [Claude Desktop](../../docs/integrations/claude-desktop.md)
- [Cursor](../../docs/integrations/cursor.md)
- [VS Code](../../docs/integrations/vscode.md)


path: package.json
content: {
  "name": "@getnella/mcp",
  "version": "0.2.7",
  "description": "Nella MCP Server — codebase intelligence for AI coding agents. Grounded search, persistent context, and deep code understanding via the Model Context Protocol.",
  "type": "commonjs",
  "bin": {
    "nella": "dist/cli.js",
    "mcp": "dist/mcp/server.js"
  },
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "require": "./dist/index.js"
    },
    "./mcp": {
      "types": "./dist/mcp/index.d.ts",
      "require": "./dist/mcp/index.js"
    }
  },
  "files": [
    "dist",
    "claude-plugin",
    "README.md"
  ],
  "keywords": [
    "coding-agent",
    "ai",
    "cli",
    "mcp",
    "model-context-protocol",
    "codebase-intelligence",
    "nella"
  ],
  "author": "Nella Labs",
  "license": "SEE LICENSE IN LICENSE",
  "repository": {
    "type": "git",
    "url": "https://github.com/nella-labs/nella.git",
    "directory": "packages/nella"
  },
  "engines": {
    "node": ">=18"
  },
  "publishConfig": {
    "access": "public"
  },
  "dependencies": {
    "@clack/prompts": "^1.1.0",
    "@modelcontextprotocol/sdk": "^1.26.0",
    "@typescript-eslint/typescript-estree": "^7.0.0",
    "chalk": "^4.1.2",
    "cli-table3": "^0.6.5",
    "dotenv": "^16.6.1",
    "figures": "^3.2.0",
    "minimatch": "^10.2.4",
    "natural": "^6.10.0"
  },
  "optionalDependencies": {
    "@google-cloud/storage": "^7.7.0",
    "@msgpack/msgpack": "^3.0.0",
    "@opentelemetry/api": "^1.9.0",
    "@opentelemetry/exporter-trace-otlp-http": "^0.212.0",
    "@opentelemetry/resources": "^1.30.0",
    "@opentelemetry/sdk-node": "^0.212.0",
    "@opentelemetry/sdk-trace-base": "^1.30.0",
    "@supabase/supabase-js": "^2.39.0",
    "better-sqlite3": "^11.0.0",
    "express": "^4.18.0",
    "hnswlib-node": "^3.0.0",
    "ioredis": "^5.9.3",
    "onnxruntime-node": "^1.17.0",
    "pg": "^8.11.0",
    "usearch": "^2.12.0",
    "ws": "^8.16.0"
  },
  "devDependencies": {
    "@types/figures": "^3.0.3",
    "@types/node": "^20.0.0",
    "@types/ws": "^8.5.0",
    "tsup": "^8.5.1",
    "typescript": "^5.3.0",
    "@usenella/core": "0.0.0"
  },
  "scripts": {
    "build": "tsup",
    "build:tsc": "tsc",
    "test": "tsx --test src/mcp/tools/__tests__/*.test.ts src/mcp/utils/__tests__/*.test.ts",
    "test:ci": "tsx --test src/mcp/tools/__tests__/*.test.ts src/mcp/utils/__tests__/*.test.ts",
    "dev": "tsup --watch",
    "start:mcp": "node dist/mcp/server.js"
  }
}

path: claude-plugin/.claude-plugin/plugin.json
content: {
  "name": "nella",
  "description": "Nella — codebase intelligence for AI coding agents. Adds /nella slash command for code search, context tracking, assumptions, and dependency checking.",
  "author": {
    "name": "Nella Labs",
    "url": "https://github.com/usenella"
  }
}


path: claude-plugin/commands/nella.md
content: ---
description: Run nella MCP tools — search code, get context, manage assumptions and dependencies
argument-hint: [context|search|assumptions|deps|index] [args]
allowed-tools: [mcp__nella__nella_index, mcp__nella__nella_search, mcp__nella__nella_get_context, mcp__nella__nella_add_assumption, mcp__nella__nella_check_assumptions, mcp__nella__nella_check_dependencies, Read, Glob, Grep, Bash]
---

# /nella

The user invoked `/nella` with arguments: $ARGUMENTS

## Instructions

Use nella MCP tools based on the arguments:

- **no args** or **context**: Call `nella_get_context` to show session state, recent changes, and assumptions.
- **search `<query>`**: Call `nella_search` with the provided query to find relevant code.
- **assumptions**: Call `nella_check_assumptions` to review all tracked assumptions.
- **deps**: Call `nella_check_dependencies` to check for dependency changes.
- **index**: Call `nella_index` to index or re-index the workspace.

If no arguments are given, default to `nella_get_context`.

Summarize results clearly after running the tool(s).


Security scan verdicts — ClawScan: suspicious | static analysis: suspicious | VirusTotal: clean | SkillSpector:  ()