Next Level Builders Directory Toolkits

Monorepo containing the official TypeScript Contracts, CLI (nlb), Model Context Protocol (MCP) Server, and AgentSkill for Next Level Builders Directory.

---

📦 Packages & Architecture

nlb-directory-toolkits/
├── packages/
│   ├── contracts/       # @nextlevelbuilder/contracts: Zod schemas, 17 block types, 5 templates, SHA-256 hasher, wire APIs
│   ├── cli/             # @nextlevelbuilder/cli: `nlb` binary (validate, preview, submit, list, get, rankings, stats, traffic, doctor, vote, keys, upload, checkout)
│   └── mcp/             # @nextlevelbuilder/mcp: Model Context Protocol server (stdio & Cloudflare Workers, 16 tools)
├── skills/
│   └── nlb-submit/      # SKILL.md: Standard AgentSkill for Claude Code, Cursor, Codex, OpenCode, skills.sh
└── docs/                # Detailed guides for CLI, MCP, Contracts, and Architecture

Package	Description	Status
@nextlevelbuilder/contracts	Canonical server-synchronized schemas for 17 block types, 5 layout templates, deterministic canonical SHA-256 hasher, and API wire contracts.
@nextlevelbuilder/cli	Developer & agent CLI binary nlb with validation, terminal preview, submissions with Polar payments, rankings, stats, doctor, voting, and uploads.
@nextlevelbuilder/mcp	Model Context Protocol server exposing 16 tools for local AI IDEs and Cloudflare Workers edge runtime.
skills/nlb-submit	Cross-marketplace AgentSkill for autonomous repository scanning, block formatting, and directory submission.

---

⚡ Quickstart

1. Using the CLI (nlb)

# Validate schema and compute SHA-256 canonical hash:
npx @nextlevelbuilder/cli validate product.json

# Render terminal ASCII box preview:
npx @nextlevelbuilder/cli preview product.json

# Generate a starter template:
npx @nextlevelbuilder/cli template dev-tool --out product.json

# Submit revision to directory review queue (supports Polar checkout if slot needed):
npx @nextlevelbuilder/cli submit product.json --org <YOUR_ORG_UUID> --api-key <YOUR_API_KEY>

# View organic community rankings / leaderboard:
npx @nextlevelbuilder/cli rankings weekly

# Check live platform metrics and statistics:
npx @nextlevelbuilder/cli stats

# Query your product's NLB page traffic using the configured API key:
npx @nextlevelbuilder/cli traffic my-awesome-tool --json

# Export raw LLM-optimized Markdown for any product:
npx @nextlevelbuilder/cli get my-awesome-tool --markdown

# Check database and endpoint connectivity:
npx @nextlevelbuilder/cli doctor

2. Setting up the MCP Server

For Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "nlb-directory": {
      "command": "npx",
      "args": ["-y", "@nextlevelbuilder/mcp"]
    }
  }
}

For Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "nlb-directory": {
      "command": "npx",
      "args": ["-y", "@nextlevelbuilder/mcp"],
      "env": {
        "NLB_API_KEY": "nlb_live_your_key_here"
      }
    }
  }
}

---

🧩 17 Supported Block Types

Every listing in Next Level Builders is composed of modular, strongly-typed blocks with id and props:

1. hero: Main showcase with headline, subheadline, CTA, and badge.
2. carousel: Multi-slide image rotation with titles and image URLs.
3. mediaGallery: Responsive multi-column screenshot and video gallery.
4. quote: Testimonials, verified reviews, and author credentials.
5. grid: Multi-column feature highlights and capability cards (1-3 cols).
6. changelog: Version histories, release dates, and categorized change notes.
7. roadmap: Planned, in-progress, and completed development milestones.
8. pricing: Tiers with billing periods, feature lists, and popular badges.
9. faq: Accordion Q&A items.
10. techStack: Categorized technology and runtime badges.
11. liveDemo: Embedded interactive sandbox (iframe, height, sandboxTokens).
12. cta: High-conversion call-to-action banner.
13. founder: Founder profiles, bios, and verified social links.
14. verification: Metric and platform provenance proofs.
15. milestones: Key historical achievements with metrics.
16. caseStudy: In-depth customer story with problem, solution, and quantifiable results.
17. analytics: Real NLB product page traffic with configurable title and 7/30/90-day period. Publishing opts into public aggregate totals and daily series; detailed traffic remains organization-authorized. See Analytics block and traffic contracts.

---

🛠️ Development & Monorepo Workflow

Prerequisites

• Node.js >= 18.0.0
• pnpm >= 9.0.0

Commands

# Install dependencies
pnpm install

# Build all packages in topological order
pnpm build

# Run comprehensive test suite across all packages (Vitest)
pnpm test

# Typecheck with TypeScript strict mode
pnpm type-check

---

📖 Documentation

• CLI Reference — Comprehensive command and flag documentation
• MCP Reference — Tool specifications and Cloudflare Workers deployment
• Contracts Reference — Zod schemas and layout templates
• System Architecture — Core/adapter boundary and cryptographic design

---

📄 License

MIT © Next Level Builders

Publishing packages

Release workflow publishes all three packages on a v<version> tag whose commit belongs to main. The tag must match every package version. Merge a reviewed version change first, then create the matching tag. Manual workflow runs build, test, type-check and upload npm-packages tarballs without publishing. Release builds use Node 24 and npm 11.19.0. pnpm packs the workspace dependencies into registry-compatible versions; npm publishes those archives using GitHub OIDC and automatically attaches provenance.

Configure each package's npm Trusted Publisher with:

• Provider: GitHub Actions
• Repository: nextlevelbuilder/nlb-directory-toolkits
• Workflow filename: release.yml
• Environment: leave empty
• Allowed action: direct npm publish

No NPM_TOKEN or NODE_AUTH_TOKEN repository secret is required. npm requires a package to exist before trust can be configured. For the first release only, run the workflow manually, download and inspect its three tarballs, and publish them with an authenticated maintainer account (contracts first). Then register each package using npm 11.15.0 or later with account 2FA enabled:

npm trust github @nextlevelbuilder/contracts --repo nextlevelbuilder/nlb-directory-toolkits --file release.yml --allow-publish --yes
npm trust github @nextlevelbuilder/cli --repo nextlevelbuilder/nlb-directory-toolkits --file release.yml --allow-publish --yes
npm trust github @nextlevelbuilder/mcp --repo nextlevelbuilder/nlb-directory-toolkits --file release.yml --allow-publish --yes

Publish subsequent versions through tags and verify the workflow, registry versions and provenance before calling the release complete. If a release partly publishes, inspect the registry before retrying: npm versions are immutable. See npm trusted publishing and npm trust for account setup.