playerthree/mcp#

playerthree/mcp: the remote MCP binding (Streamable HTTP endpoint), its tool surface, observation paging and the OAuth 2.1 authorization server.

Interfaces#

AuthorizationServer#

Defined in: packages/playerthree/src/mcp/oauth/server.ts:156

The authorization server: its metadata URLs, request handling and the owner-side connection and consent operations.

Properties#

Methods#

allConnections()#

allConnections(): OwnedConnectionStatus[];

Defined in: packages/playerthree/src/mcp/oauth/server.ts:174

Every owner's connections, oldest first. For operator tooling (the operator console); never show it to players.

Returns#

OwnedConnectionStatus[]

challenge()#

challenge(invalid, request?): string;

Defined in: packages/playerthree/src/mcp/oauth/server.ts:186

WWW-Authenticate value for a 401 (invalid: a token was presented but is not valid), for the request's origin.

Parameters#

Returns#

string

close()#

close(): void;

Defined in: packages/playerthree/src/mcp/oauth/server.ts:187

Returns#

void

connections()#

connections(owner): ConnectionStatus[];

Defined in: packages/playerthree/src/mcp/oauth/server.ts:172

Parameters#

Returns#

ConnectionStatus[]

consentRequest()#

consentRequest(id): ConsentRequest | undefined;

Defined in: packages/playerthree/src/mcp/oauth/server.ts:169

Parameters#

Returns#

ConsentRequest | undefined

fetch()#

fetch(request): Promise<Response | undefined>;

Defined in: packages/playerthree/src/mcp/oauth/server.ts:168

Web-standard face: a Response for authorization server paths, else undefined.

Parameters#

Returns#

Promise<Response | undefined>

handle()#

handle(req, res): Promise<boolean>;

Defined in: packages/playerthree/src/mcp/oauth/server.ts:166

node:http face: answers and returns true for authorization server paths, else returns false untouched.

Parameters#

Returns#

Promise<boolean>

handles()#

handles(pathname): boolean;

Defined in: packages/playerthree/src/mcp/oauth/server.ts:164

Whether a pathname belongs to the authorization server (/.well-known/oauth-*, /oauth/*).

Parameters#

Returns#

boolean

onChange()#

onChange(listener): () => void;

Defined in: packages/playerthree/src/mcp/oauth/server.ts:184

Connection credential or role changes. Listeners receive identifiers only, never tokens.

Parameters#

Returns#

() => void

removeOwner()#

removeOwner(owner): void;

Defined in: packages/playerthree/src/mcp/oauth/server.ts:180

Revokes every connection of an owner.

Parameters#

Returns#

void

resolveConsent()#

resolveConsent(id, answer): object;

Defined in: packages/playerthree/src/mcp/oauth/server.ts:171

Answers a pending request (single use). Throws PlayerThreeError('invalid') for unknown/expired ids, owners or roles.

Parameters#

Returns#

object

revokeConnection()#

revokeConnection(owner, id): void;

Defined in: packages/playerthree/src/mcp/oauth/server.ts:178

Revokes a connection and every token of it at once. Throws PlayerThreeError('invalid') for unknown ids.

Parameters#

Returns#

void

updateConnection()#

updateConnection(
   owner, 
   id, 
   patch
): ConnectionStatus;

Defined in: packages/playerthree/src/mcp/oauth/server.ts:176

Sets this exact commander's granted compatible roles without modifying other connections.

Parameters#

Returns#

ConnectionStatus

verify()#

verify(token): OAuthGrant | undefined;

Defined in: packages/playerthree/src/mcp/oauth/server.ts:182

Resource-server side: an access token issued for this endpoint (under any of its origins), or undefined.

Parameters#

Returns#

OAuthGrant | undefined

AuthorizationServerOptions#

Defined in: packages/playerthree/src/mcp/oauth/server.ts:72

Options of createAuthorizationServer.

Properties#

Methods#

consentUrl()#

consentUrl(requestId): string;

Defined in: packages/playerthree/src/mcp/oauth/server.ts:85

The game's consent page for a pending request (absolute URL, or a path on the issuer).

Parameters#

Returns#

string

CimdOptions#

Defined in: packages/playerthree/src/mcp/oauth/cimd.ts:44

Properties#

ConnectionStatus#

Defined in: packages/playerthree/src/mcp/oauth/server.ts:101

A connection as the game shows it to its owner.

Extended by#

• OwnedConnectionStatus

Properties#

ConnectionStore#

Defined in: packages/playerthree/src/mcp/oauth/store.ts:72

Every method may be sync or async; writes are issued in order.

Methods#

deleteClient()#

deleteClient(id): void | Promise<void>;

Defined in: packages/playerthree/src/mcp/oauth/store.ts:77

Parameters#

Returns#

void | Promise<void>

deleteConnection()#

deleteConnection(id): void | Promise<void>;

Defined in: packages/playerthree/src/mcp/oauth/store.ts:75

Parameters#

Returns#

void | Promise<void>

load()#

load(): 
  | ConnectionStoreData
| Promise<ConnectionStoreData>;

Defined in: packages/playerthree/src/mcp/oauth/store.ts:73

Returns#

| ConnectionStoreData | Promise<ConnectionStoreData>

saveClient()#

saveClient(client): void | Promise<void>;

Defined in: packages/playerthree/src/mcp/oauth/store.ts:76

Parameters#

Returns#

void | Promise<void>

saveConnection()#

saveConnection(connection): void | Promise<void>;

Defined in: packages/playerthree/src/mcp/oauth/store.ts:74

Parameters#

Returns#

void | Promise<void>

ConnectionStoreData#

Defined in: packages/playerthree/src/mcp/oauth/store.ts:66

Properties#

ConsentDecision#

Defined in: packages/playerthree/src/mcp/oauth/server.ts:132

Properties#

ConsentEvent#

Defined in: packages/playerthree/src/mcp/server.ts:42

playerthree/mcp: the remote MCP binding (Streamable HTTP endpoint), its tool surface, observation paging and the OAuth 2.1 authorization server.

Properties#

ConsentRequest#

Defined in: packages/playerthree/src/mcp/oauth/server.ts:120

What the game's consent page shows.

Properties#

McpOptions#

Defined in: packages/playerthree/src/mcp/server.ts:56

Options of the MCP endpoint.

Extended by#

• MountMcpOptions

Properties#

McpRequestHandler()#

Defined in: packages/playerthree/src/mcp/server.ts:75

The MCP endpoint as a request handler with a node:http face and a web-standard fetch face.

McpRequestHandler(req, res): Promise<void>;

Defined in: packages/playerthree/src/mcp/server.ts:77

node:http face: fully handles the response. Does not check the path — route before calling.

Parameters#

Returns#

Promise<void>

Properties#

Methods#

close()#

close(): Promise<void>;

Defined in: packages/playerthree/src/mcp/server.ts:81

Aborts in-flight exchanges.

Returns#

Promise<void>

fetch()#

fetch(request): Promise<Response>;

Defined in: packages/playerthree/src/mcp/server.ts:79

Web-standard face.

Parameters#

Returns#

Promise<Response>

MountMcpOptions#

Defined in: packages/playerthree/src/mcp/server.ts:1006

playerthree/mcp: the remote MCP binding (Streamable HTTP endpoint), its tool surface, observation paging and the OAuth 2.1 authorization server.

Extends#

• McpOptions

Properties#

OAuthClientInfo#

Defined in: packages/playerthree/src/mcp/oauth/store.ts:13

Client metadata as the authorization server validated it. Self-asserted for dcr; cimd is served by id's host.

Extended by#

• StoredClient

Properties#

OAuthGrant#

Defined in: packages/playerthree/src/mcp/oauth/server.ts:143

An authenticated OAuth access token, as the MCP binding uses it. Everything is read live.

Properties#

Methods#

activity()#

activity(delta): void;

Defined in: packages/playerthree/src/mcp/oauth/server.ts:152

Marks activity; +1/-1 around calls in flight.

Parameters#

Returns#

void

holds()#

holds(role): boolean;

Defined in: packages/playerthree/src/mcp/oauth/server.ts:150

The connection still exists and holds role.

Parameters#

Returns#

boolean

roles()#

roles(): readonly string[];

Defined in: packages/playerthree/src/mcp/oauth/server.ts:148

Current roles (edits apply to the next call).

Returns#

readonly string[]

ObservationPage#

Defined in: packages/playerthree/src/mcp/paging.ts:10

One page: a partial observation, plus [from, to) item ranges (of of) of the lists it holds only part of.

Properties#

OwnedConnectionStatus#

Defined in: packages/playerthree/src/mcp/oauth/server.ts:115

A connection with its owner, as the operator console lists them across owners.

Extends#

• ConnectionStatus

Properties#

StoredClient#

Defined in: packages/playerthree/src/mcp/oauth/store.ts:58

A client registered through POST /oauth/register (RFC 7591).

Extends#

• OAuthClientInfo

Properties#

StoredConnection#

Defined in: packages/playerthree/src/mcp/oauth/store.ts:32

Properties#

StoredTokenDigest#

Defined in: packages/playerthree/src/mcp/oauth/store.ts:25

Properties#

ToolAnnotationsSpec#

Defined in: packages/playerthree/src/mcp/surface.ts:15

Properties#

ToolSpec#

Defined in: packages/playerthree/src/mcp/surface.ts:22

Properties#

Type Aliases#

CimdErrorCode#

type CimdErrorCode = 
  | "invalid_client_id"
  | "blocked_address"
  | "redirect"
  | "status"
  | "bad_content_type"
  | "too_large"
  | "timeout"
  | "network"
  | "bad_document";

Defined in: packages/playerthree/src/mcp/oauth/cimd.ts:26

CimdResult#

type CimdResult = 
  | {
  document: ClientDocument;
  maxAgeMs: number;
  ok: true;
}
  | {
  code: CimdErrorCode;
  ok: false;
};

Defined in: packages/playerthree/src/mcp/oauth/cimd.ts:42

ClientRegistration#

type ClientRegistration = "cimd" | "dcr";

Defined in: packages/playerthree/src/mcp/oauth/store.ts:10

How the client identified itself: a Client ID Metadata Document URL, or Dynamic Client Registration.

ToolErrorCode#

type ToolErrorCode = ServerErrorCode | "consent_declined";

Defined in: packages/playerthree/src/mcp/meta.ts:8

Closed set of tool-level error codes ({"error": code} in an isError result).

Variables#

LIMITS#

const LIMITS: object;

Defined in: packages/playerthree/src/mcp/surface.ts:51

Limits shared with the host's own argument validation.

Type Declaration#

OAUTH_SCOPE#

const OAUTH_SCOPE: "play" = 'play';

Defined in: packages/playerthree/src/mcp/oauth/server.ts:41

The one scope this server grants: play the roles the owner picked on the consent page.

SURFACE_HASH_META#

const SURFACE_HASH_META: "dev.playerthree/surfaceHash" = 'dev.playerthree/surfaceHash';

Defined in: packages/playerthree/src/mcp/meta.ts:5

_meta key carrying the surfaceHash on tools/list and every tools/call result (clients pin it).

TOOL_ORDER#

const TOOL_ORDER: readonly ControlMethod[];

Defined in: packages/playerthree/src/mcp/surface.ts:34

Deterministic tool order.

Functions#

addressAllowed()#

function addressAllowed(address, allowLoopback?): boolean;

Defined in: packages/playerthree/src/mcp/oauth/cimd.ts:107

A resolved address the server may connect to.

Parameters#

Returns#

boolean

createAuthorizationServer()#

function createAuthorizationServer<M>(typedHost, opts): AuthorizationServer;

Defined in: packages/playerthree/src/mcp/oauth/server.ts:273

The OAuth 2.1 authorization server for typedHost's MCP endpoint (see the module comment for its routes).

Type Parameters#

Parameters#

Returns#

AuthorizationServer

createMcpRequestHandler()#

function createMcpRequestHandler<M>(typedHost, opts?): McpRequestHandler;

Defined in: packages/playerthree/src/mcp/server.ts:329

The remote MCP endpoint for typedHost, unmounted; mountMcp wires it (and the authorization server) into a node:http server.

Type Parameters#

Parameters#

Returns#

McpRequestHandler

fetchClientDocument()#

function fetchClientDocument(clientId, opts?): Promise<CimdResult>;

Defined in: packages/playerthree/src/mcp/oauth/cimd.ts:249

Fetches and validates the metadata document a URL-formatted client_id points to.

Parameters#

Returns#

Promise<CimdResult>

jsonConnectionStore()#

function jsonConnectionStore(dir): ConnectionStore;

Defined in: packages/playerthree/src/mcp/oauth/store.ts:102

<dir>/connections.json, written atomically (temp file + rename) with mode 0600.

Parameters#

Returns#

ConnectionStore

memoryConnectionStore()#

function memoryConnectionStore(): ConnectionStore;

Defined in: packages/playerthree/src/mcp/oauth/store.ts:81

In-memory connection store (the default): connections and registered clients are lost on restart.

Returns#

ConnectionStore

mergeObservationPages()#

function mergeObservationPages(pages): Record<string, unknown>;

Defined in: packages/playerthree/src/mcp/paging.ts:102

Reassemble a full observation from all its pages, in page order (inverse of pageObservation).

Parameters#

Returns#

Record<string, unknown>

methodEnabled()#

function methodEnabled(manifest, method): boolean;

Defined in: packages/playerthree/src/mcp/surface.ts:98

Whether the manifest enables the mode that gates a control method.

Parameters#

Returns#

boolean

mountMcp()#

function mountMcp<M>(
   httpServer, 
   host, 
   opts?
): object;

Defined in: packages/playerthree/src/mcp/server.ts:1016

Serve MCP on an existing node:http server: requests whose pathname equals path — and, with auth, the authorization server's paths (/.well-known/oauth-*, /oauth/*) — are handled here and never reach the server's other request listeners (regardless of registration order); everything else passes through.

Type Parameters#

Parameters#

Returns#

object

pageObservation()#

function pageObservation(
   observation, 
   schema, 
   budget
): ObservationPage[];

Defined in: packages/playerthree/src/mcp/paging.ts:71

Pages of observation whose JSON each fits budget code units (except an indivisible item larger than the budget). One page when it already fits.

Parameters#

Returns#

ObservationPage[]

redirectMatches()#

function redirectMatches(registered, given): boolean;

Defined in: packages/playerthree/src/mcp/oauth/cimd.ts:165

Exact string match, except that a registered plain-http loopback redirect URI matches any port on the same loopback host with the same path and query (RFC 8252 §7.3: native apps listen on an ephemeral port).

Parameters#

Returns#

boolean

serverInstructions()#

function serverInstructions(manifest, hash): string;

Defined in: packages/playerthree/src/mcp/server.ts:215

Static server instructions. Only PlayerThree text and developer-declared manifest data.

Parameters#

Returns#

string

toolSurface()#

function toolSurface(manifest, skills): ToolSpec[];

Defined in: packages/playerthree/src/mcp/surface.ts:298

The tool surface for a game. skills must be every skill the server serves (developer skills, generated reference and SDK defaults) — game_skill's name enum comes from it.

Parameters#

Returns#

ToolSpec[]