Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions packages/pivotkit-mcp/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,12 @@ All notable changes to `pivotkit-mcp` are documented in this file. The format is

## [Unreleased]

### Changed

- The HTTP handler runs its requests through pivotkit-server's route handler (`createRouteHandler`
of `pivotkit-server/internal`), so it needs the pivotkit-server of the same release. The answers and
log lines stay the same.

## [0.4.0] - 2026-11-22

### Added
Expand Down
64 changes: 16 additions & 48 deletions packages/pivotkit-mcp/src/http.js
Original file line number Diff line number Diff line change
Expand Up @@ -18,8 +18,8 @@
*/

import { createMcpHandler, hostHeaderValidationResponse, originValidationResponse } from "@modelcontextprotocol/server";
import { BODY_BYTES, ConfigError, DEFAULT_PORT, callerOf, requestScopeFor, serveFetch } from "pivotkit-server";
import { DOWNLOAD_BODY_BYTES, DOWNLOADS_PATH, publicOriginOf, SIGNED_IN, allowedHosts, brandingAnswer, brandingOfContext, pageRedirect, hostProblem, hostRefusal, hostRefusedLine, clientAddress, connectionLimitsOf, createDownloadHandler, createLimits, isLoopback, limitKeyOf, logNotes, logUnanswered, noteProtocolRefusal, openAddressRefusal, prepareHttpServe, refusalReason, refusedText, startFields, takeSignIn, withRequestIdHeader, withRequestScope } from "pivotkit-server/internal";
import { BODY_BYTES, ConfigError, DEFAULT_PORT, callerOf, serveFetch } from "pivotkit-server";
import { DOWNLOAD_BODY_BYTES, publicOriginOf, SIGNED_IN, allowedHosts, brandingAnswer, brandingOfContext, pageRedirect, hostProblem, hostRefusal, hostRefusedLine, clientAddress, connectionLimitsOf, createDownloadHandler, createLimits, createRouteHandler, isLoopback, limitKeyOf, logNotes, noteProtocolRefusal, openAddressRefusal, prepareHttpServe, refusalReason, refusedText, startFields, takeSignIn } from "pivotkit-server/internal";
import { MCP_TOKEN_ENV, createMcpContext } from "./context.js";
import { createAuth, refusedClientOf } from "./auth.js";
import { pageCsp, quickStartPage } from "./page.js";
Expand All @@ -29,9 +29,6 @@ export const ENDPOINT = "/mcp";

export { BODY_BYTES, DEFAULT_PORT, isLoopback };

/** The route family of the download links: a link nobody has (404) is logged at info, since a person asks the operator about it. */
const DOWNLOAD_FAMILY = Object.freeze({ path: DOWNLOADS_PATH, notFound: /** @type {const} */ ("info") });

/** The headers every answer of this server carries. */
const SAFE_HEADERS = { "x-content-type-options": "nosniff", "referrer-policy": "no-referrer" };

Expand Down Expand Up @@ -119,7 +116,7 @@ function protocolRefusal(log, error) {
* The fetch handler of a context.
* @param {any} context createMcpContext's
* @param {{ env?: Record<string, string | undefined>, loopback?: boolean, notFound?: () => Response }} [runtime] notFound: the answer to a path nobody serves (pivotkit-server's, which names its REST service); else a plain "not found"
* @returns {Promise<{ fetch(request: Request): Promise<Response>, precheck(request: Request): Promise<Response | null>, problem(status: number): Response, close(): Promise<void>, auth: any, downloads: any }>}
* @returns {Promise<{ fetch(request: Request, info?: Record<string | symbol, any>): Promise<Response>, precheck(request: Request, info?: Record<string | symbol, any>): Promise<Response | null>, problem(status: 400 | 413, path: string, info?: Record<string | symbol, any>): Response, close(): Promise<void>, auth: any, downloads: any }>}
*/
export async function createHttpHandler(context, runtime = {}) {
const notFound = runtime.notFound ?? (() => new Response("not found", { status: 404 }));
Expand Down Expand Up @@ -201,7 +198,7 @@ export async function createHttpHandler(context, runtime = {}) {
async function route(request, info) {
const url = new URL(request.url);
if (downloads.handles(url.pathname)) {
return downloads.fetch(request);
return downloads.fetch(request, info);
}
const refused = hostOrOrigin(request);
if (refused) {
Expand Down Expand Up @@ -268,36 +265,16 @@ export async function createHttpHandler(context, runtime = {}) {
return {
auth,
downloads,
/** The answer for a body that cannot be read, as JSON-RPC, with its refused line. */
problem(status, _path, info = {}) {
const scope = requestScopeFor(null, info, { trustProxy });
withRequestScope(scope, () => context.log.refused({ status, path: ENDPOINT, reason: refusalReason(status === 413 ? "BODY_TOO_LARGE" : "INVALID_INPUT"), ...(status === 413 ? { limit: BODY_BYTES } : {}) }));
return withRequestIdHeader(bodyProblem(status), scope.id);
},
/**
* The checks a request's headers allow, before its body is read: Host, Origin, the declared
* size, and the token for /mcp (kept in `info` for fetch, so it is checked once). A Response
* to send, or null to go on.
* @param {Request} request without its body
* @param {{ address?: string, [SIGNED_IN]?: any }} [info] the client's address; serveFetch hands the same object to fetch
*/
async precheck(request, info = {}) {
// the request's scope: serveFetch's, or made here for a host that serves the handler itself
const scope = requestScopeFor(request, info, { trustProxy });
const answer = await logUnanswered(context.log, scope, await withRequestScope(scope, () => check(request, info)), routeFamily(request));
return answer && withRequestIdHeader(answer, scope.id);
},
/**
* @param {Request} request
* @param {{ address?: string, [SIGNED_IN]?: any }} [info]
*/
async fetch(request, info = {}) {
const scope = requestScopeFor(request, info, { trustProxy });
// a 4xx without a line of its own (the SDK answers a body that is not JSON or an
// unsupported protocol version without reporting it) gets a refused line
const response = await logUnanswered(context.log, scope, await withRequestScope(scope, () => answer(request, info)), routeFamily(request));
return withRequestIdHeader(/** @type {Response} */ (response), scope.id);
},
// pivotkit-server's route handler: the request's scope, the refused line of an unlogged error
// (a 4xx the SDK answered without reporting it: a body that is not JSON, an unsupported
// protocol version), the id on every answer
...createRouteHandler(context, {
check,
answer,
familyOf: (request) => (new URL(request.url).pathname === ENDPOINT ? { path: ENDPOINT } : {}),
// a body that cannot be read is answered as JSON-RPC
unreadable: { path: ENDPOINT, limitOf: () => BODY_BYTES, answer: (status) => bodyProblem(status) }
}),
async close() {
downloads.close();
limits.close();
Expand All @@ -306,23 +283,14 @@ export async function createHttpHandler(context, runtime = {}) {
}
};

/**
* The route family of a request, for a refused line written by logUnanswered: /mcp or /downloads.
* @param {Request} request
*/
function routeFamily(request) {
const path = new URL(request.url).pathname;
return path === ENDPOINT ? { path: ENDPOINT } : downloads.handles(path) ? DOWNLOAD_FAMILY : {};
}

/**
* The checks before the body is read (precheck's work).
* @param {Request} request
* @param {{ address?: string, [SIGNED_IN]?: any }} info
*/
async function check(request, info) {
if (downloads.handles(new URL(request.url).pathname)) {
return downloads.precheck(request);
return downloads.precheck(request, info);
}
const refused = hostOrOrigin(request);
if (refused) {
Expand Down Expand Up @@ -400,7 +368,7 @@ export async function listen(given, runtime) {
handler = await createHttpHandler(context, { env: runtime.env, loopback: isLoopback(host) });
const downloads = handler.downloads;
const isDownload = (path) => downloads.handles(path.split("?")[0]);
listening = await serveFetch({ precheck: (request, info) => handler.precheck(request, info), fetch: (request, info) => handler.fetch(request, info), problem: (status, path, info) => (isDownload(path) ? downloads.problem(status) : handler.problem(status, path, info)) }, { host, port, bodyBytes: (request) => (isDownload(new URL(request.url).pathname) ? DOWNLOAD_BODY_BYTES : BODY_BYTES), graceMs: options.http?.graceMs, limits: connectionLimitsOf(options), trustProxy: options.http?.trustProxy ?? false, onClientError: (entry) => context.log.refused({ ...entry, reason: refusalReason("INVALID_INPUT") }), onInternalError: () => context.log.refused({ status: 500, reason: refusalReason("INTERNAL") }), onRefused: (entry) => context.log.warn(refusedText(entry), entry) });
listening = await serveFetch({ precheck: (request, info) => handler.precheck(request, info), fetch: (request, info) => handler.fetch(request, info), problem: (status, path, info) => (isDownload(path) ? downloads.problem(status, path, info) : handler.problem(status, path, info)) }, { host, port, bodyBytes: (request) => (isDownload(new URL(request.url).pathname) ? DOWNLOAD_BODY_BYTES : BODY_BYTES), graceMs: options.http?.graceMs, limits: connectionLimitsOf(options), trustProxy: options.http?.trustProxy ?? false, onClientError: (entry) => context.log.refused({ ...entry, reason: refusalReason("INVALID_INPUT") }), onInternalError: () => context.log.refused({ status: 500, reason: refusalReason("INTERNAL") }), onRefused: (entry) => context.log.warn(refusedText(entry), entry) });
} catch (e) {
await handler?.close();
await context.close();
Expand Down
4 changes: 4 additions & 0 deletions packages/pivotkit-server/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -153,6 +153,10 @@ node scripts/openapi.js # write docs/openapi.json after a route or operat
- Connections are bounded in all and per address. Slots stay free for loopback (`connectionGate`).
- A stranger's body cap is `BODY_BYTES`. A signed-in caller's cap is at most `MAX_BODY_BYTES`.
- A refused Host is answered and logged with `HOST_HINT` (`hostProblem`, `hostRefusedLine`).
- `createRouteHandler` in `src/route-handler.js` runs every route family: REST, MCP, download links
and `serve`, which hosts them. It owns the request's scope, the refused line of an unlogged error
and `X-Request-Id`. A family supplies only its check, its answer and its answer to an unreadable body.
- A host passes its `info` on to the family it routes to, so both name one request id.

## Untrusted documents

Expand Down
3 changes: 3 additions & 0 deletions packages/pivotkit-server/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,9 @@ All notable changes to `pivotkit-server` are documented in this file. The format

### Changed

- REST, MCP, the download links and `serve` run their requests through one route handler
(`createRouteHandler`): request id, scope, the refused line and `X-Request-Id`. Every request
through `serve`, pivotkit-mcp or REST gets the same answers and log lines as before.
- Depends on `pivotkit-node` `^0.1.0` for the file handling and the REST contract, which it took from
`pivotkit-cli` before. pivotkit-cli stays a dependency for `pivotkit-server cli`.
- Reads IP addresses, loopback, Retry-After and the code of a failed connection through
Expand Down
69 changes: 37 additions & 32 deletions packages/pivotkit-server/src/downloads.js
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,8 @@ import { discover, ISSUER_LIMITS, issuerFetch, issuerHint, issuerRulesOf, jwksUr
import { allowedHosts, hostRefusal, hostRefusedLine } from "./checks.js";
import { isLoopback } from "./listen.js";
import { OUTPUT_MARK, outputDir } from "./output.js";
import { newRequestId, requestId, requestScope, withRequestId } from "./request-id.js";
import { newRequestId, requestId, requestScope } from "./request-id.js";
import { createRouteHandler } from "./route-handler.js";
import { createLimits } from "./limits.js";
import { readSecret } from "./secrets.js";
import { typeOf } from "./rest/problem.js";
Expand All @@ -46,6 +47,9 @@ export const CALLBACK_PATH = `${DOWNLOADS_PATH}/callback`;
/** The largest body a download request may carry (the one-time link's form sends none). */
export const DOWNLOAD_BODY_BYTES = 1024;

/** The route family's refused lines: a link nobody has (404) is logged at info, since a person asks the operator about it. */
const DOWNLOAD_FAMILY = Object.freeze({ path: DOWNLOADS_PATH, notFound: /** @type {const} */ ("info") });

/** The least length of output.downloads.key, in bytes. */
export const KEY_MIN_BYTES = 32;

Expand Down Expand Up @@ -549,7 +553,7 @@ function answerOf(brand, request, code, headers = {}) {
* so the REST service and the MCP endpoint on one port share it).
* @param {any} context
* @param {{ env?: Record<string, string | undefined>, loopback?: boolean, sweepEveryMs?: number }} [runtime] sweepEveryMs: how often expired one-time markers are swept (tests)
* @returns {{ handles(path: string): boolean, precheck(request: Request): Promise<Response | null>, fetch(request: Request): Promise<Response>, problem(status: number): Response, listening(url: string): void, close(): void }}
* @returns {{ handles(path: string): boolean, precheck(request: Request, info?: Record<string | symbol, any>): Promise<Response | null>, fetch(request: Request, info?: Record<string | symbol, any>): Promise<Response>, problem(status: 400 | 413, path: string, info?: Record<string | symbol, any>): Response, listening(url: string): void, close(): void }}
*/
export function createDownloadHandler(context, runtime = {}) {
const existing = states.get(context);
Expand Down Expand Up @@ -1008,7 +1012,7 @@ export function createDownloadHandler(context, runtime = {}) {
return fileAnswer(found.report, "GET", { headers: { "set-cookie": cookie } });
}

/** A request of the route after its precheck, inside its request id. */
/** A request of the route after its precheck, inside its request's scope. */
async function route(request, path) {
try {
if (!active || !state.base) {
Expand All @@ -1029,40 +1033,41 @@ export function createDownloadHandler(context, runtime = {}) {
}
}

/**
* The checks before the body is read: Host, and a body of at most DOWNLOAD_BODY_BYTES.
* @param {Request} request
*/
async function check(request) {
const refused = hostRefusal(request, hosts);
if (refused) {
context.log.refused(hostRefusedLine(request, refused, { path: DOWNLOADS_PATH }));
return answer(request, "FORBIDDEN_HOST");
}
if (Number(request.headers.get("content-length") ?? 0) > DOWNLOAD_BODY_BYTES) {
context.log.refused({ status: 413, path: DOWNLOADS_PATH, reason: "body_too_large", limit: DOWNLOAD_BODY_BYTES, size: Number(request.headers.get("content-length")) });
return answer(request, "BODY_TOO_LARGE");
}
return null;
}

const handler = {
/** Whether a path is the route's (anything under /downloads; what is not a link answers 404). */
handles: (path) => path === DOWNLOADS_PATH || path.startsWith(`${DOWNLOADS_PATH}/`),

/** The checks before the body is read: Host, and a body of at most DOWNLOAD_BODY_BYTES. */
async precheck(request) {
const refused = hostRefusal(request, hosts);
if (refused) {
context.log.refused(hostRefusedLine(request, refused, { path: DOWNLOADS_PATH }));
return answer(request, "FORBIDDEN_HOST");
// the request's scope, the refused line of an unlogged error, the id on every answer
// (route-handler.js); a host passes its `info`, so the route names the host's request id
...createRouteHandler(context, {
check,
// the precheck again: a host that serves the route without one still checks Host and size
answer: async (request) => (await check(request)) ?? route(request, new URL(request.url).pathname),
// a link nobody has (404) is logged at info, since a person asks the operator about it
familyOf: () => DOWNLOAD_FAMILY,
unreadable: {
path: DOWNLOADS_PATH,
limitOf: () => DOWNLOAD_BODY_BYTES,
answer: (status, _limit, id) => new Response(JSON.stringify({ code: status === 413 ? "BODY_TOO_LARGE" : "INVALID_INPUT", requestId: id }), { status, headers: { ...BASE_HEADERS, "content-type": "application/problem+json", connection: "close" } })
}
if (Number(request.headers.get("content-length") ?? 0) > DOWNLOAD_BODY_BYTES) {
context.log.refused({ status: 413, path: DOWNLOADS_PATH, reason: "body_too_large", limit: DOWNLOAD_BODY_BYTES, size: Number(request.headers.get("content-length")) });
return answer(request, "BODY_TOO_LARGE");
}
return null;
},

/** A request of the route. */
async fetch(request) {
const early = await handler.precheck(request);
if (early) {
return early;
}
const path = new URL(request.url).pathname;
// one id per request: its log lines, its problem document and its page name the same one
return withRequestId(requestId() ?? newRequestId(), () => route(request, path));
},

/** The answer for a body that cannot be read (too large, cut off), with its refused line. */
problem: (status) => {
context.log.refused({ status, path: DOWNLOADS_PATH, reason: status === 413 ? "body_too_large" : "bad_request", ...(status === 413 ? { limit: DOWNLOAD_BODY_BYTES } : {}) });
return new Response(JSON.stringify({ code: status === 413 ? "BODY_TOO_LARGE" : "INVALID_INPUT", requestId: requestId() ?? newRequestId() }), { status, headers: { ...BASE_HEADERS, "content-type": "application/problem+json", connection: "close" } });
},
}),

/**
* The address the server listens on, once it does: the links' base on loopback without
Expand Down
1 change: 1 addition & 0 deletions packages/pivotkit-server/src/internal.js
Original file line number Diff line number Diff line change
Expand Up @@ -22,5 +22,6 @@ export { secretFileWarning } from "./secrets.js";
export { CREATABLE_SECRET_REF } from "./options/shared.js";
export { prepareHttpServe, logNotes, openAddressRefusal, planState, stateDirOf, configFrom, builtInConfig, tokenShowHint, IMAGE_PATHS, STATE_ENV, DEFAULT_TOKEN_NAME } from "./state.js";
export { createDownloadHandler, linksOf, DOWNLOADS_PATH, CALLBACK_PATH, DOWNLOAD_BODY_BYTES } from "./downloads.js";
export { createRouteHandler } from "./route-handler.js";
export { optionsFrom, flagLines, httpFlags, startFormatOf, SERVER_FLAGS, SHARED_FLAGS } from "./flags.js";
export { AUTO_VALUES_DEFAULT, AUTO_VALUES_DENY, AUTO_VALUES_WHOLE_WORDS, CLOSED_DATE_GROUPING, DESCRIBE_HINT, NAME_TEXT, UNNAMED_WHY, autoValuesOf, autoValuesOption, denyEntries, draftingOf, fieldKey, hiddenColumns, mayList } from "./policy.js";
5 changes: 1 addition & 4 deletions packages/pivotkit-server/src/listen.js
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
import { createServer } from "node:http";
import { isLoopback } from "pivotkit-node/rest";
import { HOST_SYNTAX } from "./checks.js";
import { newRequestId, requestScopeFor, withRequestIdHeader, withRequestScope } from "./request-id.js";
import { newRequestId, plainAddress, requestScopeFor, withRequestIdHeader, withRequestScope } from "./request-id.js";

/** Whether an address is loopback (pivotkit-node/rest's: the CLI decides with it where http is allowed). */
export { isLoopback } from "pivotkit-node/rest";
Expand Down Expand Up @@ -86,9 +86,6 @@ export function refusedText(entry) {
return `connections refused since the last report: ${entry.limits.map((l) => why[l]).join("; ")}`;
}

/** A socket's address as a loopback check reads it ("::ffff:127.0.0.1" is 127.0.0.1). */
const plainAddress = (address) => String(address ?? "").replace(/^::ffff:/i, "");

/**
* Who may open a connection: a count in all and per address. A connection from loopback may use
* every slot; one from another address only those not kept for loopback, and with `perAddress` at
Expand Down
Loading
Loading