Integrations

One contract pack for HTTP, MCP, webhooks, CI, and SDK automation.

Nerviq now publishes a compact integration surface so external dashboards, bots, pipelines, and internal developer tooling can bind to explicit contracts instead of scraping terminal output.

OpenAPI 3.1MCP stdioWebhook schemaSDK examples

What the Pack Includes

The goal is simple: if another system needs Nerviq data, it should have a stable place to look and a clear contract to follow.

Published surfaces

Serve, MCP, webhook, CI patterns, output formats (markdown/junit/csv), and SDK are documented together as one integration pack.

GET

HTTP method

The current local REST surface stays intentionally small and read-only.

1.0

Webhook schema

Generic audit webhook events now advertise an explicit schema version.

Local

Deployment mode

Serve and SDK usage stay local-first; no hosted control plane is required.

Surface	Entry point	Why it exists
OpenAPI	`/api/openapi.json`	Use the live local serve contract for generated clients, Swagger import, and internal tools.
MCP transport	`nerviq-mcp`	Register the separate stdio JSON-RPC server when an MCP host expects tools over stdin/stdout.
Webhook event	`contracts/audit-webhook-event.schema.json`	Bind generic webhook consumers to a stable JSON event instead of scraping CLI text.
CI patterns	`docs/ci-integration.md`	Use threshold gates, PR drift gates, and fleet rollup artifacts across CI providers.
CI output formats	`--format=markdown\|junit\|csv`	Emit PR-comment markdown, Jenkins-compatible JUnit XML, or RFC 4180 CSV for any CI surface or reporting consumer.
SDK examples	`sdk/README.md`	Use stable programmatic surfaces when the CLI is not enough for your workflow.

HTTP API vs MCP Transport

Nerviq exposes two machine-facing transports. The important thing is to choose the one your integration runtime actually expects.

REST

Serve = local HTTP + OpenAPI

bash

nerviq serve --port 3000

Use nerviq serve for dashboards, wrappers, scripts, and non-Node or language-neutral consumers that want a small local JSON API.

MCP

nerviq-mcp = stdio JSON-RPC 2.0

json

{
  "mcpServers": {
    "nerviq": {
      "command": "npx",
      "args": ["-y", "-p", "@nerviq/cli", "nerviq-mcp"]
    }
  }
}

Use nerviq-mcp when the host expects Model Context Protocol over stdin/stdout. MCP hosts should register this binary, not the HTTP endpoint.

Local REST Contract

Use the local HTTP surface when you want dashboards, wrappers, or internal tools to query the Nerviq engine without spawning and parsing the CLI.

CLI

Start the server

bash

nerviq serve --port 3000

bash

curl http://127.0.0.1:3000/api/openapi.json

OpenAPI

Current endpoints

/api/openapi.json for the live contract.

/api/health for local readiness checks.

/api/audit for single-repo audit runs.

/api/harmony for cross-platform drift analysis.

/api/catalog for the merged check dictionary.

Canonical source

The live OpenAPI document is the machine-readable source of truth for a running Nerviq serve instance. The docs mirror it, but generated clients should bind to the JSON contract directly.

Not the MCP transport

nerviq serve is the local HTTP API surface. If an MCP host expects stdio JSON-RPC, register nerviq-mcp instead.

Generic Webhook Event

When audit results are sent to a generic HTTP webhook, Nerviq now emits a stable event envelope with backward-compatible summary fields plus explicit integration metadata.

Webhook

CLI invocation

bash

npx @nerviq/cli audit \
  --webhook https://ops.example.com/nerviq/audit \
  --webhook-header "Authorization: Bearer $NERVIQ_WEBHOOK_TOKEN" \
  --webhook-retries 4

Schema

Contract notes

The event name is nerviq.audit.completed.

schemaVersion lets new consumers pin contract expectations.

Older consumers still receive top-level platform, score, passed, failed, and results.

New consumers should prefer the nested data and meta blocks.

json

{
  "event": "nerviq.audit.completed",
  "schemaVersion": "1.0",
  "generatedAt": "2026-04-09T12:00:00.000Z",
  "platform": "claude",
  "score": 84,
  "passed": 196,
  "failed": 34,
  "results": [],
  "data": {
    "platform": "claude",
    "score": 84,
    "scoreType": "live-audit-score",
    "checkCount": 258,
    "topNextActions": [],
    "quickWins": [],
    "scoreCoaching": {
      "currentScore": 84,
      "nextMilestone": 90
    }
  },
  "meta": {
    "cliVersion": "1.30.0",
    "source": "nerviq-cli",
    "webhookFormat": "generic-audit-event"
  }
}

CI Reference Patterns

Nerviq's CI story now has three clear patterns: whole-repo score gates, PR drift gates, and multi-repo fleet artifacts.

Baseline

Score gate

bash

npx @nerviq/cli audit --threshold 60

Use this when the whole repository score is your release bar.

Continuous mode

PR drift gate

bash

npx @nerviq/cli audit --diff-only --drift-mode ci --threshold 60

Use this when you want PRs to compare against a managed baseline instead of only checking the full repo state.

Org

Fleet artifact

bash

npx @nerviq/cli org scan ./app ./api ./infra --json --out nerviq-fleet.json

Use this when one pipeline needs an org-wide rollup with fleet semantics and policy coverage.

CI Output Formats

Nerviq audit now emits three machine-readable formats so the CLI plugs straight into the standard CI surfaces without text-scraping.

PR comment

Markdown

bash

npx @nerviq/cli audit --format=markdown --out audit.md

GitHub-flavoured markdown with score badge, top-5 next-actions checklist, and a collapsible all-failed-checks table. Post as a PR comment from any GitHub Action.

Test reporter

JUnit XML

bash

npx @nerviq/cli audit --format=junit --out junit.xml

Jenkins-compatible JUnit XML. Works out of the box with GitHub Actions test reporter, GitLab JUnit reporter, and Jenkins JUnit plugin. One <testsuite> per check category.

Reporting

CSV

bash

npx @nerviq/cli audit --format=csv --out audit.csv

RFC 4180 CSV, one row per check with key,id,name,category,rating,severity,passed,file,line,sourceUrl,fix. Ingest into any spreadsheet, data warehouse, or dashboard.

Stable consumer API

Each format has an explicit contract in docs/integration-contracts.md §7. Downstream wrappers should bind to these shapes rather than scraping the text output.

SDK and HTTP Together

Use the SDK when you are already inside a Node toolchain. Use serve when you need a process boundary or a language-neutral integration surface.

Node.js

SDK use cases

audit, harmonyAudit, detectPlatforms, and getCatalog are the stable programmatic surfaces.

If your integration already lives inside a Node service or CLI, the SDK is usually the shortest path.

Language-neutral

Serve use cases

Use nerviq serve when you want local dashboards, wrapper services, or non-Node consumers to speak to Nerviq over a small JSON surface.

The current HTTP layer is intentionally compact so the contract stays legible and stable.

Why some integrations stay gated

Nerviq does not unblock every marketplace or IDE surface the moment a prototype exists. First-tier distribution should amplify trust, not create it artificially.

First-tier rule

GitHub Marketplace, JetBrains, and similar surfaces move forward only after the contract layer, public proof, operational reliability, ownership, and category fit are strong enough to carry them. See the first-tier integration gate for the explicit bar.