@btravstack/mcp-server

@btravstack/mcp-server

Classes

ToolRefused

Defined in: packages/mcp-server/src/mcp.ts:47

A tool's refusal, as the model reads it. A tool's own triage mints it from its E — an exhaustive mapErrCases — so widening E fails every tool that folds it, and text is the one thing the caller is told.

Extends

TaggedErrorInstance<"ToolRefused", { text: string; }>

Constructors

Constructor

new ToolRefused(args): ToolRefused;

Defined in: node_modules/.pnpm/unthrown@5.12.1/node_modules/unthrown/dist/index.d.mts:2386

Parameters

Parameter	Type
`args`	`object` & `object`

Returns

ToolRefused

Inherited from

TaggedError("ToolRefused")<{ readonly text: string }>.constructor

Properties

Property	Modifier	Type	Inherited from	Defined in
`_tag`	`readonly`	`"ToolRefused"`	`TaggedError("ToolRefused")._tag`	node_modules/.pnpm/unthrown@5.12.1/node_modules/unthrown/dist/index.d.mts:2363
`cause?`	`public`	`unknown`	`TaggedError("ToolRefused").cause`	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es2022.error.d.ts:24
`message`	`public`	`string`	`TaggedError("ToolRefused").message`	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1075
`name`	`public`	`string`	`TaggedError("ToolRefused").name`	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1074
`stack?`	`public`	`string`	`TaggedError("ToolRefused").stack`	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1076
`text`	`readonly`	`string`	`TaggedError("ToolRefused").text`	packages/mcp-server/src/mcp.ts:47

Type Aliases

McpContext

type McpContext<Principal, Unit> = object;

Defined in: packages/mcp-server/src/mcp.ts:58

What server is handed for one request: the caller requires resolved (undefined without requires), the unit record read off the forked kind, the request's abort signal, and toolResult, which turns a tool's Result into the SDK's answer.

Type Parameters

Type Parameter	Default type
`Principal`	`unknown`
`Unit`	`Readonly`<`Record`<`string`, `unknown`>>

Properties

Property	Modifier	Type	Description	Defined in
`principal`	`readonly`	`Principal`	-	packages/mcp-server/src/mcp.ts:59
`signal`	`readonly`	`AbortSignal`	-	packages/mcp-server/src/mcp.ts:61
`toolResult`	`readonly`	<`T`>(`outcome`) => `Promise`<`CallToolResult`>	`Ok` is the tool's answer — text for a string, structured content beside its JSON text when that JSON is an object, its JSON text alone otherwise. `Err` is a tool error carrying the refusal's `text`. A defect — or a value JSON cannot encode — is reported to `Observers` and answered as a tool error saying nothing about its cause. It answers a `Promise`, and that is the boundary: the SDK's tool callback answers a value or a promise, as a GraphQL resolver does for `fieldResult`.	packages/mcp-server/src/mcp.ts:72
`unit`	`readonly`	`Unit`	-	packages/mcp-server/src/mcp.ts:60

McpOptions

type McpOptions<A, Units, R, U> = object;

Defined in: packages/mcp-server/src/mcp.ts:103

Serve an MCP server as one answerer under the existing HTTP runtime.

Type Parameters

Type Parameter
`A` extends `Authenticators`
`Units` extends `UnitsOf`<`A`>
`R` extends `Requirements` & `{ readonly [I in keyof R]: OneScheme<R[I]> }`
`U` extends `Readonly`<`Record`<`string`, `AnyPort`>>

Properties

Property	Modifier	Type	Description	Defined in
`prefix?`	`readonly`	`/${string}`	-	packages/mcp-server/src/mcp.ts:115
`requires?`	`readonly`	`R` & `RequiresGate`<`R`, `{ readonly [K in keyof A]: A[K]["scope"] }`>	-	packages/mcp-server/src/mcp.ts:118
`server`	`readonly`	(`context`) => `McpServer`	The SDK's own server, built for one request — `new McpServer(…)` and its `registerTool` calls. Built per request because the transport is stateless: no session outlives the request, so a replica can answer any of them.	packages/mcp-server/src/mcp.ts:114
`unit?`	`readonly`	`U` & `UnitGate`<`U`, `Units`, `KindOf`<`R`>>	-	packages/mcp-server/src/mcp.ts:117
`units?`	`readonly`	`Units` & `{ readonly [K in Exclude<keyof Units, Kinds<A>>]: never }`	-	packages/mcp-server/src/mcp.ts:116

ToolOutcome

type ToolOutcome<T> = 
  | AsyncResult<T, ToolRefused>
  | Result<T, ToolRefused>;

Defined in: packages/mcp-server/src/mcp.ts:50

What a tool answers from: its value on Ok, a ToolRefused on Err.

Type Parameters

Type Parameter
`T`

Variables

McpModule

const McpModule: <Name>(name) => <A, I, P, X, N>(options) => Module<
  | Extract<readonly ...[number], AnyModule> extends infer T_3 ? T_3 extends Extract<...[number], AnyModule> ? T_3 extends Module<infer X_3, infer E, infer N_1> ? readonly [..., ..., ...] : never : never : never[0]
  | readonly [typeof HttpRuntime, typeof HttpHandler, ...(...), ...(...)][number] extends infer E_1 ? E_1 extends AnyPort ? InstanceType<E_1> : E_1 extends AnyProvider ? InstanceType<E_1["port"]> : never : never, 
  | 
  | A extends Provider<infer P_1, infer E_2, infer N_2> ? readonly [..., ..., ...] : never
  | P[number] extends infer T_4 ? T_4 extends ...[...] ? ... extends ... ? ... : ... : never : never
  | AuthOf<A> extends infer T_5 ? T_5 extends AuthOf<...> ? ... extends ... ? ... : ... : never : never[1]
  | readonly [..., ...][number] extends infer T_6 ? T_6 extends readonly ...[number] ? T_6 extends Module<infer X_3, infer E, infer N_1> ? readonly [..., ..., ...] : never : never : never[1], 
  | Exclude<
  | A extends Provider<..., ..., ...> ? readonly ... : never
  | ...[...] extends ... ? ... extends ... ? ... : ... : never
  | AuthOf<...> extends ... ? ... extends ... ? ... : ... : never[2], 
  | ...[number] extends infer T_9 ? T_9 extends ...[...] ? ... extends ... ? ... : ... : never : never[0]
  | 
  | ... extends ... ? ... : ...
  | ... extends ... ? ... : ...
  | ... extends ... ? ... : ...[0]>
  | Exclude<readonly ...[number] extends infer T_9 ? T_9 extends ...[number] ? T_9 extends Module<..., ..., ...> ? readonly ... : never : never : never[2], 
  | ...[number] extends infer T_9 ? T_9 extends ...[...] ? ... extends ... ? ... : ... : never : never[0]
  | 
  | ... extends ... ? ... : ...
  | ... extends ... ? ... : ...
  | ... extends ... ? ... : ...[0]>>;

Defined in: packages/http-server/dist/internal.d.mts:128

Declare an HTTP application served by one answerer — graphql(), mcp() — without repeating runtime or authenticator wiring: the answerer's authenticators are provided and its declared request modules bound to the runtime. HttpModule is the oRPC and fragments one.

Type Parameters

Type Parameter
`Name` extends `string`

Parameters

Parameter	Type
`name`	`Name`

Returns

<A, I, P, X, N>(options) => Module< | Extract<readonly ...[number], AnyModule> extends infer T_3 ? T_3 extends Extract<...[number], AnyModule> ? T_3 extends Module<infer X_3, infer E, infer N_1> ? readonly [..., ..., ...] : never : never : never[0] | readonly [typeof HttpRuntime, typeof HttpHandler, ...(...), ...(...)][number] extends infer E_1 ? E_1 extends AnyPort ? InstanceType<E_1> : E_1 extends AnyProvider ? InstanceType<E_1["port"]> : never : never, | | A extends Provider<infer P_1, infer E_2, infer N_2> ? readonly [..., ..., ...] : never | P[number] extends infer T_4 ? T_4 extends ...[...] ? ... extends ... ? ... : ... : never : never | AuthOf<A> extends infer T_5 ? T_5 extends AuthOf<...> ? ... extends ... ? ... : ... : never : never[1] | readonly [..., ...][number] extends infer T_6 ? T_6 extends readonly ...[number] ? T_6 extends Module<infer X_3, infer E, infer N_1> ? readonly [..., ..., ...] : never : never : never[1], | Exclude< | A extends Provider<..., ..., ...> ? readonly ... : never | ...[...] extends ... ? ... extends ... ? ... : ... : never | AuthOf<...> extends ... ? ... extends ... ? ... : ... : never[2], | ...[number] extends infer T_9 ? T_9 extends ...[...] ? ... extends ... ? ... : ... : never : never[0] | | ... extends ... ? ... : ... | ... extends ... ? ... : ... | ... extends ... ? ... : ...[0]> | Exclude<readonly ...[number] extends infer T_9 ? T_9 extends ...[number] ? T_9 extends Module<..., ..., ...> ? readonly ... : never : never : never[2], | ...[number] extends infer T_9 ? T_9 extends ...[...] ? ... extends ... ? ... : ... : never : never[0] | | ... extends ... ? ... : ... | ... extends ... ? ... : ... | ... extends ... ? ... : ...[0]>>

Functions

mcp()

function mcp<A, Units, R, U>(api, options): Provider<HttpHandler, never, 
  | HttpConfig
  | HttpUnit
  | Observers
  | UnitsNeedsOf<Units>
  | SchemePortsOf<R>
  | Scope> & object;

Defined in: packages/mcp-server/src/mcp.ts:191

An MCP server as one answerer: Streamable HTTP, stateless, answering JSON, under prefix (default /mcp). The SDK owns the protocol; this owns what the runtime owns for every answerer — authentication through the shared schemes, the request's unit, the body limit — and nothing else.

const answerer = mcp(auth, {
  requires: [{ user: [] }],
  unit: { orders: Orders },
  server: ({ principal, unit, toolResult }) => {
    const server = new McpServer({ name: "orders", version: "1.0.0" });
    server.registerTool("list_orders", { inputSchema: {} }, () =>
      toolResult(unit.orders.list(principal.tenantId)),
    );
    return server;
  },
});

A caller no requirement accepts is answered 401 and an under-scoped one 403, with no body — so protectedResource()'s challenge rides the 401.

Type Parameters

Type Parameter	Default type
`A` extends `Readonly`<`Record`<`string`, `Authenticator`<`unknown`, `string`, `unknown`, `unknown`>>>	-
`Units` extends `Partial`<`Readonly`<`Record`<`Kinds`<`A`>, `AnyUnitModule`>>>	`Record`<`never`, `never`>
`R` extends `Requirements` & { readonly [I in string \| number \| symbol]: OneScheme<R[I]> }	`never`
`U` extends `Readonly`<`Record`<`string`, `AnyPort`>>	`Record`<`never`, `never`>

Parameters

Parameter	Type
`api`	`HttpAuth`<`A`>
`options`	`McpOptions`<`A`, `Units`, `R`, `U`>

Returns

@btravstack/mcp-server ​

Classes ​

ToolRefused ​

Extends ​

Constructors ​

Constructor ​

Parameters ​

Returns ​

Inherited from ​

Properties ​

Type Aliases ​

McpContext ​

Type Parameters ​

Properties ​

McpOptions ​

Type Parameters ​

Properties ​

ToolOutcome ​

Type Parameters ​

Variables ​

McpModule ​

Type Parameters ​

Parameters ​

Returns ​

Functions ​

mcp() ​

Type Parameters ​

Parameters ​

Returns ​

@btravstack/mcp-server

Classes

ToolRefused

Extends

Constructors

Constructor

Parameters

Returns

Inherited from

Properties

Type Aliases

McpContext

Type Parameters

Properties

McpOptions

Type Parameters

Properties

ToolOutcome

Type Parameters

Variables

McpModule

Type Parameters

Parameters

Returns

Functions

mcp()

Type Parameters

Parameters

Returns