Norq

AI Integration

Norq is designed to work well with AI coding assistants. It provides a Model Context Protocol (MCP) server for programmatic template authoring, machine-readable context files, and an AI-powered playground.

MCP Server

The MCP (Model Context Protocol) server lets AI agents interact with Norq programmatically. Start it with:

norq mcp-server

The server runs on stdin/stdout and exposes tools for:

Available tools

Tool Parameters Description
norq_list none List all notification IDs
norq_resolve notification (required) Get channels, samples, and schema for a notification
norq_compile notification (required), channel, data (object), sample Compile a notification to channel payloads
norq_lint notification Lint templates: structure, syntax, and deliverability checks (all if omitted)
norq_test notification Run assertion tests from tests.yaml (all if omitted)
norq_channel_schema channel (required) Get directive support and compilation targets for a channel
norq_create notification (required), channels (string array) Scaffold a new notification with starter templates
norq_preview notification (required), channel (required), sample Compile and return output for a single channel
norq_doctor none Diagnose project environment, config, and health (Discovery, Environment, Project, Health sections)
norq_brand_inspect none Return the project’s resolved brand as DTCG-2025.10 JSON. Aliases and color pipes are pre-resolved to literal values; Norq-specific fields (styles, defaults, element-typography, fonts, modes, voice, codeTheme) ride under $extensions.norq. Use this to introspect visual identity before authoring templates so you reference token names like {colors.brand} instead of inline hex.
norq_render_preview notification (required), device (desktop/mobile), dark_mode (bool), sample, data Render a quick preview image of a compiled email. device defaults to "desktop", dark_mode defaults to false. Returns base64-encoded image data. Requires a render-capable provider (e.g. SuprSend).
norq_render_screenshot notification (required), client (required), sample, data Render an email as it appears in a specific email client. Common client values: outlook_2021, gmail_web, apple_mail, iphone_15. Returns base64-encoded image data. Both render tools require a render-capable provider (SuprSend).

Example: norq_compile tool call

Request:

{
  "method": "tools/call",
  "params": {
    "name": "norq_compile",
    "arguments": {
      "notification": "transactional/welcome",
      "channel": "email",
      "sample": "New user"
    }
  },
  "id": 1
}

Response:

{
  "result": {
    "content": [{
      "type": "text",
      "text": "{ \"email\": { \"subject\": \"Welcome to Acme\", \"html\": \"<html>...</html>\", \"text\": \"Welcome, Gaurav!\" } }"
    }]
  },
  "id": 1
}

Pass data (a JSON object) instead of sample to supply template variables directly. Omit channel to compile all channels at once.

The norq plugin bundles the MCP server + an agentskills.io skill that teaches the agent the schema-first workflow, template syntax, and best practices.

Claude Code

/plugin marketplace add https://github.com/suprsend/norq
/plugin install norq

Or add the MCP server manually:

claude mcp add norq -- npx -y norq mcp-server

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "norq": {
      "command": "npx",
      "args": ["-y", "norq", "mcp-server"]
    }
  }
}

Codex (OpenAI)

codex plugin install norq

Or add the MCP server manually to your Codex config:

{
  "mcpServers": {
    "norq": {
      "command": "npx",
      "args": ["-y", "norq", "mcp-server"]
    }
  }
}

Cursor

Add to Cursor MCP settings:

{
  "mcpServers": {
    "norq": {
      "command": "npx",
      "args": ["-y", "norq", "mcp-server"]
    }
  }
}

Known limitations

  • The MCP server compile/test flows now use the same hierarchical _shared/ walk-up as the CLI and SDKs (notification → category → type → global). If you find a mismatch, treat it as a bug rather than expected behavior.

Example: AI-authored template

An AI agent with MCP access can:

  1. Call norq_list to see existing templates
  2. Call norq_resolve to understand channels, samples, and data shape
  3. Call norq_create to scaffold a new notification
  4. Call norq_lint to verify templates are correct
  5. Call norq_compile to see the compiled output
  6. Call norq_test to run assertion tests
  7. Call norq_render_preview to see a visual preview of the email
  8. Iterate until the template passes all checks

Best practices for AI template generation

Provide the schema first

When asking an AI to generate templates, provide or reference the data.schema.yaml so it knows the exact variable names and types available.

Use llms-full.txt for complex templates

For multi-channel templates with control flow, fields, and actions, include llms-full.txt in the AI’s context. The directive compilation tables are especially important for understanding what works on each channel.

Validate with lint

Always run norq lint on AI-generated templates. Common AI mistakes:

  • Using variables not in the schema
  • Missing :::if guards for nullable fields
  • Invalid frontmatter fields
  • Using :::raw where a directive would work better

Start with email, expand to other channels

Email is the most complex channel (MJML, subject, preheader). Starting with email and then adapting for SMS/Slack/etc. is usually more efficient than generating all channels simultaneously.

Docs over SSH

Norq documentation is available over SSH at get.norq.sh. AI agents and developers can use standard bash commands to browse, search, and read docs without installing anything.

Quick start

# Guided setup — pipe to your AI agent
ssh get.norq.sh setup | claude
 
# Append agent instructions to your project
ssh get.norq.sh agents >> CLAUDE.md
 
# Install as a skill
mkdir -p .claude/skills/norq-docs
ssh get.norq.sh skill > .claude/skills/norq-docs/SKILL.md

Browsing docs

# Interactive shell
ssh get.norq.sh
 
# Read the overview
ssh get.norq.sh cat /norq/llms.txt
 
# Read the full reference
ssh get.norq.sh cat /norq/llms-full.txt
 
# Browse all doc files
ssh get.norq.sh find /norq/docs -name "*.md"
 
# Search docs for a topic
ssh get.norq.sh grep -r "columns" /norq/docs/
 
# Read a specific doc
ssh get.norq.sh cat /norq/docs/channels/email.md
 
# See example templates
ssh get.norq.sh ls /norq/examples/notifications/

Available content

Path Description
/norq/llms.txt High-level overview — start here
/norq/llms-full.txt Complete reference with examples
/norq/docs/ All documentation (28 files)
/norq/docs/channels/ Per-channel docs (email, sms, slack, push, whatsapp, msteams)
/norq/docs/templates/ Template syntax (directives, expressions, partials, control flow)
/norq/docs/sdk/ SDK guides (Node, Python, Go, Java, Ruby)
/norq/examples/ Example norq project with templates

Custom commands

Command Description
ssh get.norq.sh setup Outputs setup instructions — pipe to claude, codex, or any AI agent
ssh get.norq.sh agents Outputs agent instructions — append to CLAUDE.md, AGENTS.md, or GEMINI.md
ssh get.norq.sh skill Outputs a SKILL.md — write to your agent’s skill directory

Why SSH?

AI coding agents spend most of their time in the shell. They already know grep, find, cat, and ls. Docs-over-SSH gives them the same interface for Norq docs — zero install, zero auth, works everywhere SSH works.

LLM context files

Two files at the project root provide Norq syntax reference for AI assistants:

llms.txt

A concise reference (~230 lines) covering:

  • File structure and naming
  • All 6 channels and their compilation targets
  • Expression syntax and pipes
  • Control flow (:::if, :::each, :::table)
  • All 18 directives with parameters
  • Frontmatter fields
  • CLI commands
  • Data schema format
  • Sample data format
  • Test syntax
  • Native JSON mode

This file follows the llms.txt convention. AI coding assistants can fetch it to understand Norq syntax before generating templates.

llms-full.txt

A comprehensive reference (~600 lines) with everything in llms.txt plus:

  • Complete pipe reference with examples (including variable pipe arguments)
  • Detailed directive compilation tables (what each directive produces in each channel)
  • Full frontmatter reference per channel
  • Detailed assertion test syntax
  • Complete examples (email, SMS, Slack with compiled output)
  • Native JSON payload wrapping rules per channel

Use llms-full.txt when the AI needs to generate complex multi-channel templates or work with channel-specific features.