ucplint


The definitive Universal Commerce Protocol (UCP) validation tool.

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

``bash
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

`bash


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

$3

`bash


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"
`

$3

`typescript
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

$3


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

$3

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

$3

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)

$3

Validates OAuth 2.0 configuration:
- Authorization server metadata
- Required endpoints
- Supported scopes
- Grant types
- PKCE support

$3

Validates webhook signing configuration:
- JWK signing keys present
- Key format validity
- Algorithm support (ES256, RS256, etc.)
- Key ID uniqueness

$3

Tests actual endpoint functionality:
- MCP endpoint responds
- Service endpoints reachable
- Response times acceptable
- Error responses valid
- CORS preflight works

$3

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

API Reference

$3

Performs full validation and returns detailed results.

`typescript
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;
errors: ValidationIssue[];
warnings: ValidationIssue[];
recommendations: string[];
checks: CheckResult[];
}
`

$3

Returns just pass/fail and score.

`typescript
import { quickCheck } from 'ucplint';

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

$3

Returns all available checks.

`typescript
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

$3

`yaml
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.

`bash


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