nablr 4.0.0

nablr — AI-powered SDLC governance. 19 expert personas enforcing quality gates via Model Context Protocol (MCP).

nablr

AI-Powered Guidance for the nablr

nablr provides agent-based AI guidance, codebase mapping, and quality enforcement for the nablr.

Built on Anthropic's Model Context Protocol (MCP) for universal AI assistant compatibility.

---

Table of Contents

• What This Does
• Features
• Security
• Installation
• Configuration
• Local Development
• Quick Start
• Contributing
• About
• License

---

What This Does

nablr is an MCP server that connects to your AI assistant (Cursor, Claude Desktop, Windsurf). Once connected, it provides:

1. Agent-based prompts — Specialized guidance for 13 agents (10 SDLC + 3 utility)
2. Quality enforcement tools — Scan code for compliance, debt, security
3. Workflow orchestration — Track story state, dependencies, handoffs

Important: This is not a standalone app. It requires an MCP-compatible AI assistant.

---

Features

Agent-Based Guidance (13 Agents)

SDLC Workflow Agents (10)

Agent	Function
discovery	Brownfield codebase scanning, CODE_MAP generation
product_manager	Requirements, acceptance criteria
qa_lead	Validates AC before development begins
architect	System design, boundaries, integration points
developer	Elite Code Quality Protocol enforcement
tester	Test standards, real-execution tests
pr_reviewer	PR review, AI anti-pattern detection
scrum_master	Process orchestration, handoff tracking
security_owner	Security audit, vulnerability scanning
test_designer	Conceptual test design, BDD architecture

Utility Agents (3) — On-Demand

Agent	Function
forensic_engineer	Incident investigation, 5 Whys, post-mortems
strategist	Solution brainstorming, trade-off analysis
platform_engineer	DevEx, health scanning, code quality enforcement

Quality Tools

Tool	What It Does
generate_codemap	Auto-document directory structure
validate_compliance	Check code against REF standards
detect_ai_patterns	Find AI-generated code smells
scan_debt	Detect technical debt (TODOs, bare exceptions, etc.)
scan_external_dependencies	Find env vars, API clients, external URLs
scan_code_quality	AST-based pe_rules enforcement (bare except, types, logging)
scan_health	Unified health report across all quality dimensions

Workflow Tools

Tool	What It Does
init_workflow	Start tracking a story
get_workflow_state	See current phase, blockers, artifacts
suggest_next_agent	Auto-suggest agent transitions
generate_story_dependency_graph	Visualize story dependencies
detect_flow_gaps	Find broken E2E flows

---

Security

nablr is designed with security as a core principle:

• ✅ No Network Calls: Contains no HTTP clients, sockets, or external communication
• ✅ No Data Exfiltration: All operations are local-only
• ✅ No Hardcoded Secrets: Scanned for credentials and API keys
• ✅ Audited Dependencies: All dependencies use permissive OSS licenses
• ✅ Stdio Transport Only: Communication via standard input/output streams

Run Security Audit

Enterprise customers can verify these claims:

# Run full security audit
uv run python -m nablr.security_scan

# Output JSON for CI/CD
uv run python -m nablr.security_scan --format json

See SECURITY.md for full security policy and architecture details.

---

Installation

Prerequisites

• uv or uvx (Install uv)
• Python 3.12+ (Windows users: see WINDOWS_TROUBLESHOOTING.md if encountering installation issues)

Client Compatibility

nablr uses stdio transport (Standard Input/Output). It works with:

• Claude Desktop
• Cursor
• Windsurf
• Any MCP-compatible client supporting stdio

Note: Gemini and GitHub Copilot do not currently support MCP.

---

Configuration

Simple installation — works like Playwright MCP. No cloning required.

Cursor (Recommended)

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project-local):

{
  "mcpServers": {
    "nablr": {
      "command": "uvx",
      "args": ["nablr"]
    }
  }
}

Via UI:

1. Settings → MCP → + Add New MCP Server
2. Name: nablr
3. Type: command
4. Command: uvx nablr

Claude Desktop

Add to claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "nablr": {
      "command": "uvx",
      "args": ["nablr"]
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "nablr": {
      "command": "uvx",
      "args": ["nablr"]
    }
  }
}

How uvx Resolves the Package

uvx nablr requires no prior installation. Here's what happens:

1. uvx receives the package name nablr
2. Queries PyPI (https://pypi.org/simple/) — the default registry, same as pip
3. Downloads the latest wheel into an isolated temporary environment
4. Runs the nablr entry point
5. Nothing persists in your global Python environment

You only need uv installed. The package is fetched on demand.

To pin a specific version:

{
  "mcpServers": {
    "nablr": {
      "command": "uvx",
      "args": ["nablr==3.15.0"]
    }
  }
}

Install from GitHub (Development/Unpublished)

If not yet published to PyPI, use GitHub:

{
  "mcpServers": {
    "nablr": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/Mishtert/nablr",
        "nablr"
      ]
    }
  }
}

Note for Windows users: If you encounter pywin32 access denied errors, see WINDOWS_TROUBLESHOOTING.md for solutions. Prefer using PyPI version (uvx nablr) when available.

---

Local Development

For contributors or local testing:

git clone https://github.com/Mishtert/nablr.git
cd nablr
uv sync
uv run nablr

---

Quick Start

1. Verify Connection

After adding the config, restart your AI assistant. In Cursor:

• Open Settings → MCP
• Look for nablr with a green status indicator

2. Try These Commands

Type these in your AI assistant to verify it's working:

"What nablr agents are available?"

Expected: List of 13 agents with descriptions.

"Set my agent to developer"

Expected: Elite Code Quality Protocol injected. AI now enforces coding standards.

"Generate a codemap for this directory"

Expected: CODE_MAP.md structure with files, purposes, dependencies.

"Scan this directory for technical debt"

Expected: Report of TODOs, bare exceptions, missing types, long functions.

3. Full Workflow Example

1. "Set agent to discovery" → Scans codebase, generates documentation
2. "Set agent to product_manager" → Write requirements with testable AC
3. "Set agent to qa_lead" → Validate AC before development
4. "Set agent to developer" → Implement with quality enforcement
5. "Set agent to pr_reviewer" → Review for compliance + AI patterns

Troubleshooting

Issue	Solution
MCP not connecting	Restart AI assistant after config change
uvx not found	Install uv: curl -LsSf https://astral.sh/uv/install.sh | sh
Tools not appearing	Check MCP status in settings; verify JSON syntax
Agent not activating	Use exact agent name: developer

---

Contributing

We welcome contributions! Please see CONTRIBUTING.md for:

• Code of conduct
• Development setup
• PR submission guidelines
• Testing requirements

Version History: See GitHub Releases for changelog.

---

About

nablr implements the Model Context Protocol (MCP), an open standard developed by Anthropic for connecting AI assistants to external tools and data sources. This ensures compatibility with a wide ecosystem of AI development tools.

nablr is part of the nablr — a methodology for collapsing the software delivery lifecycle through intelligent parallelism and agent orchestration.

---

License

Proprietary. All rights reserved.