@pleri/pylon

@pleri/pylon

Runtime SDK for MCP servers that enrol into Pylon — token verification, capability resolution, schema push, request-guard middleware.

This is the library half of the Pylon product. It's what an MCP runtime imports to verify the JWTs its users carry.

• Admins / operators: you want @pleri/pylon-cli, not this package. The CLI is for logging in, enrolling apps, granting roles, approving schema migrations.
• MCP authors: this is the right package. Install it, point it at your Pylon org, and your requests gain a verified Actor with capabilities.

Install

pnpm add @pleri/pylon

Requires Node ≥ 22 (or any runtime with WHATWG fetch + Web Crypto — Cloudflare Workers supported).

Quick start

// Workers and Node ≥ 22: import the slim verify-only entry to keep
// your bundle under ~8 KB gz.
import { pylonClient, pylonGuard } from '@pleri/pylon/verify';

const client = pylonClient({
  orgUrl:        process.env.PYLON_ORG_URL!,
  appId:         'olam',
  expectedOrgId: process.env.PYLON_ORG_ID!,
  // sessionToken omitted → reads Authorization: Bearer <jwt>
  // from the Request passed to resolve().
});

const guard = pylonGuard(client, { requiredCapability: 'olam:world.read' });

export default {
  async fetch(request: Request): Promise<Response> {
    const { actor, errorResponse } = await guard(request);
    if (errorResponse) {
      return new Response(JSON.stringify(errorResponse.body), {
        status: errorResponse.status,
        headers: { 'content-type': 'application/json' },
      });
    }
    // actor.email / actor.capabilities / actor.capabilities.has(cap)
    return handle(request, actor);
  },
};

Need schema push? Import from @pleri/pylon/schema:

import { pylonSchemaClient } from '@pleri/pylon/schema';

const schema = pylonSchemaClient({
  orgUrl:        process.env.PYLON_ORG_URL!,
  appId:         'olam',
  appToken:      process.env.PYLON_APP_TOKEN!,
  expectedOrgId: process.env.PYLON_ORG_ID!,
});

const result = await schema.push(/* your SchemaDeclaration */);

Full contract

See docs/PYLON_SDK_CONTRACT.md in the repo for the complete public API, HTTP contract, schema model, error shapes, and integration recipes.

Versioning

Pre-1.0 minor bumps (0.1 → 0.2) may be breaking; changelog in CHANGELOG.md. The package version tracks the service's token + schema shapes — the SDK and service ship in lockstep for those surfaces.

License

MIT — see LICENSE.