ucplint

ucplint

The definitive Universal Commerce Protocol (UCP) validation tool.

Validate any UCP implementation with 58 checks across 7 categories. CLI + Library.

npx ucplint https://forever21.com

Features

• 58 validation checks across 7 categories
• Real endpoint testing - not just schema validation
• Detailed recommendations for fixing issues
• Scoring system with A-F grades
• JSON output for CI/CD integration
• Library API for programmatic use
• Authenticated testing with --auth-token for MCP endpoints

Installation

# Run directly with npx (no install needed)
npx ucplint https://example.com

# Or install globally
npm install -g ucplint

# Or add to your project
npm install ucplint

Quick Start

CLI Usage

# Basic validation
ucplint https://merchant.example.com

# JSON output (for CI/CD)
ucplint https://merchant.example.com --format json

# Save report to file
ucplint https://merchant.example.com --output report.json

# Skip specific categories
ucplint https://merchant.example.com --skip oauth,webhook

# Strict mode (warnings become errors)
ucplint https://merchant.example.com --strict

# Custom timeout (seconds)
ucplint https://merchant.example.com --timeout 60

# Authenticated MCP testing (with OAuth token)
ucplint https://merchant.example.com --auth-token "your-bearer-token"

Library Usage

import { validate, quickCheck } from 'ucplint';

// Full validation
const result = await validate('https://merchant.example.com');
console.log(result.score);  // 0-100
console.log(result.grade);  // A, B, C, D, or F
console.log(result.valid);  // true/false

// Quick check (just pass/fail)
const quick = await quickCheck('https://merchant.example.com');
console.log(quick.valid);   // true/false
console.log(quick.score);   // 0-100

Validation Categories

Discovery (10 checks)

Validates the /.well-known/ucp discovery document:

• Endpoint accessibility
• Valid JSON structure
• UCP version format and support
• Services and capabilities defined
• Signing keys present
• robots.txt AI agent access

Transport (8 checks)

Validates transport layer security:

• HTTPS enforcement
• TLS 1.2+ requirement
• Content-Type headers
• Security headers (HSTS, X-Content-Type-Options)
• CORS configuration
• Request ID and idempotency support

Schema (8 checks)

Validates data formats:

• JSON Schema compliance
• Email format (RFC 5322)
• Phone format (E.164)
• Country codes (ISO 3166-1)
• Currency codes (ISO 4217)
• Date format (RFC 3339)
• Amount format (integer minor units)

OAuth (8 checks)

Validates OAuth 2.0 configuration:

• Authorization server metadata
• Required endpoints
• Supported scopes
• Grant types
• PKCE support

Webhook (8 checks)

Validates webhook signing configuration:

• JWK signing keys present
• Key format validity
• Algorithm support (ES256, RS256, etc.)
• Key ID uniqueness

Operations (8 checks)

Tests actual endpoint functionality:

• MCP endpoint responds
• Service endpoints reachable
• Response times acceptable
• Error responses valid
• CORS preflight works

Conformance (8 checks)

Read-only protocol conformance validation:

• Version negotiation
• Spec/Schema URLs accessible
• Content-Type headers
• CORS preflight
• JSON-RPC format
• Error response format
• Idempotency key support

Note: Many conformance checks require authentication. Use --auth-token to enable full testing.

Output Example

UCP Validation Report
──────────────────────────────────────────────────

Target: https://forever21.com
UCP Version: 2026-01-11

──────────────────────────────────────────────────

  Score: 87/100  Grade: B  Valid: No

──────────────────────────────────────────────────
Category Scores

   Category      Score    Passed    Total
   discovery     96%      9         10
   transport     80%      7         8
   schema        75%      6         8
   oauth         100%     8         8
   webhook       90%      7         8
   operations    77%      6         8
   conformance   75%      1         2

──────────────────────────────────────────────────

CLI Options

Option	Description	Default
-f, --format <format>	Output format: text, json, sarif	text
-o, --output <file>	Write output to file	stdout
--no-color	Disable colored output	-
-s, --strict	Treat warnings as errors	false
--skip <categories>	Skip categories (comma-separated)	-
-t, --timeout <seconds>	Request timeout	30
--verbose	Include verbose details	false
--auth-token <token>	Bearer token for authenticated MCP testing	-
-v, --version	Show version	-

API Reference

validate(url, options?)

Performs full validation and returns detailed results.

import { validate } from 'ucplint';

const result = await validate('https://example.com', {
  timeout: 30000,        // Request timeout in ms
  strict: false,         // Treat warnings as errors
  skipCategories: [],    // Categories to skip
  authToken: '',         // Bearer token for MCP endpoints
});

// Result structure
interface ValidationResult {
  version: string;           // Tool version
  timestamp: string;         // ISO 8601 timestamp
  duration: number;          // Total time in ms
  target: {
    url: string;
    ucpVersion?: string;
  };
  valid: boolean;            // Passes all critical checks
  score: number;             // 0-100
  grade: 'A' | 'B' | 'C' | 'D' | 'F';
  categories: Record<string, CategoryResult>;
  errors: ValidationIssue[];
  warnings: ValidationIssue[];
  recommendations: string[];
  checks: CheckResult[];
}

quickCheck(url, options?)

Returns just pass/fail and score.

import { quickCheck } from 'ucplint';

const result = await quickCheck('https://example.com');
// { valid: boolean, score: number, grade: string }

listChecks()

Returns all available checks.

import { listChecks } from 'ucplint';

const checks = listChecks();
// Array of check definitions

Scoring

Grade	Score	Meaning
A	90-100	Excellent - fully compliant
B	80-89	Good - minor issues
C	70-79	Fair - some issues to address
D	60-69	Poor - significant issues
F	0-59	Failing - critical issues

Critical checks (auto-fail if missing):

• discovery.wellknown-accessible
• discovery.version-present
• transport.https-only
• operations.endpoints-use-https

Exit Codes

Code	Meaning
0	Valid (all critical checks pass)
1	Invalid (critical checks failed)
2	Error (crash/exception)

CI/CD Integration

GitHub Actions

name: UCP Validation
on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npx ucplint https://your-site.com --format json --output ucp-report.json
      - uses: actions/upload-artifact@v4
        with:
          name: ucp-report
          path: ucp-report.json

What is UCP?

The Universal Commerce Protocol (UCP) enables AI agents to make purchases on behalf of users safely and securely. It defines standards for:

• Discovery - How merchants advertise their capabilities
• Authentication - OAuth-based identity linking
• Checkout - Standardized checkout flows
• Payments - Secure payment handling
• Webhooks - Signed event notifications

Contributing

Contributions are welcome! Please read our Contributing Guide first.

# Clone the repo
git clone https://github.com/saitejar/ucplint.git
cd ucplint

# Install dependencies
npm install

# Run in development
npm run dev -- check https://example.com

# Run tests
npm test

# Build
npm run build

License

Apache-2.0

Related

• UCP Specification - Official protocol documentation
• awesome-ucp - Curated list of UCP resources