@viyv/mcp-spec

Language-neutral wire contracts for the Viyv MCP Gateway: the announce protocol, the JWT claim shape, and per-tool security metadata — as zod schemas plus inferred TypeScript types.

This package is the TypeScript mirror of viyv_mcp's Pydantic single source of truth (viyv_mcp/app/ws_bridge_protocol.py and the security models). The JSON Schema under schema/ and the golden conformance vectors are generated from those Python models (make spec), and BOTH a pytest suite and this package's vitest suite validate against the same vectors — so the Python and TypeScript sides cannot silently drift.

Install

npm i @viyv/mcp-spec        # depends on: zod ^3.25

Use

import {
  AnnounceMessage, ToolCallMessage, ToolResultMessage, ToolDef,
  AuthMessage, AuthResult, JwtClaims, ToolSecurityMeta,
  clearanceAllows, computeTrustedNamespaces, namespaceVisible,
} from '@viyv/mcp-spec'

const msg = ToolCallMessage.parse(JSON.parse(raw)) // validated, typed

// Reference authorization helpers (ADVISORY — the Gateway is authoritative):
clearanceAllows(/* agent */ 1, /* tool level */ 1) // true  (lower = higher privilege)

Most consumers get these types transitively via @viyv/mcp-connect; import this package directly when you want to type or validate the wire yourself.

Exports

• Messages: AuthMessage, AuthResult, AnnounceMessage, AnnounceAck, ToolDef, ToolCallMessage, ToolResultMessage, PingMessage, PongMessage, ContentBlock (+ TextBlock / ImageBlock), AnyMessage.
• Claims & metadata: JwtClaims, ToolSecurityMeta.
• Reference policy: clearanceAllows, computeTrustedNamespaces, namespaceVisible.
• Raw JSON Schema: @viyv/mcp-spec/schema/<Model>.schema.json.

MIT.