Open-source AI coworkers that each get a computer of their own: a browser, files and tools, with every action decided before it happens and recorded after. Bring any AG-UI agent.
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
import type { ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
import { cutAtCodeUnits } from "../channels/text";
/**
* The only place in this deployment that speaks MCP to somebody else's server.
*
* One door. Every call out is a credential leaving the building and a result coming back
* that a model will read, so both directions want a single place to be careful in. A second client
* somewhere else would be a second place to forget the timeout, the credential handling or the size
* cap, and nothing about the second one would look wrong in review.
*
* No connection is kept. A client is built, used and closed for every listing and every call.
* Streamable HTTP makes that cheap, and a pooled session would mean one Bot's request could arrive
* on a session another Bot's credential opened, which is a whole class of bug we simply decline to
* have.
*/
/** How long a server gets before we give up on it, for a listing and for a call. */
const LIST_TIMEOUT_MS = 15_000;
const CALL_TIMEOUT_MS = 60_000;
/**
* The most result text a call may return.
*
* A tool result goes straight into a model's context, so an unbounded one is somebody else's server
* deciding how much of our context window to spend, and a truncation the model can see is far better
* than a run that fails or a bill nobody expected. Truncated visibly, never silently.
*/
export const MAX_RESULT_CHARS = 20_000;
/**
* What a vendor said, as the string a model will read.
*
* Its own function, and exported, because this is a decision rather than plumbing: it settles what a
* model is told when a vendor answers with nothing, with something enormous, or with a part we
* cannot render. Keeping it out of {@link callTool} means it can be asserted without a server to
* talk to.
*
* The empty case is the one that earns the separation. A tool that matched nothing used to produce
* an empty string, and an empty string is the worst thing to put in front of a model: it reads as
* "the tool had nothing to say" rather than "there is nothing there", and the model closes the gap
* from memory. For a knowledge connector that is precisely the failure the whole slice exists to
* prevent — an answer with nothing behind it. So nothing is stated, in words.
*/
/**
* How much of a resource link's title, name or description a model is shown.
*
* Long enough for a heading and a sentence, short enough that a link's own metadata cannot spend
* the result cap its pointer has to fit in.
*/
const LINK_FIELD_CHARS = 400;
/**
* A resource_link as the lines a model reads: the pointer first, then bounded metadata.
*
* The URI is the link's identity; the title or name and the description are metadata. The URI
* therefore leads, whole, and the other two are cut, so that a server's long name cannot push its
* own pointer past {@link MAX_RESULT_CHARS} below and leave the model holding a link with nowhere
* to go. Truncation may lose what a resource was called, never where it is. Each line is labelled,
* so the fields are told apart by name rather than by position.
*
* The spec's `title` is the name meant for people, `name` the one meant for programs; the title is
* shown when a server gives one. Null when the link names nothing, so the caller names its type.
*/
function resourceLinkText(item: {
uri?: unknown;
name?: unknown;
title?: unknown;
description?: unknown;
}): string | null {
const field = (value: unknown) =>
typeof value === "string" && value.trim() !== "" ? value : null;
const bounded = (value: string) =>
value.length > LINK_FIELD_CHARS
? `${value.slice(0, LINK_FIELD_CHARS)}…`
: value;
const lines: string[] = [];
const uri = field(item.uri);
if (uri !== null) lines.push(`uri: ${uri}`);
const title = field(item.title);
const name = field(item.name);
if (title !== null) lines.push(`title: ${bounded(title)}`);
else if (name !== null) lines.push(`name: ${bounded(name)}`);
const description = field(item.description);
if (description !== null) {
lines.push(`description: ${bounded(description)}`);
}
return lines.length > 0 ? lines.join("\n") : null;
}
export function resultText(
content: unknown,
structuredContent?: unknown,
): {
text: string;
truncated: boolean;
} {
const parts = Array.isArray(content) ? content : [];
let joined = parts
.map((part) => {
if (!part || typeof part !== "object") return "[unknown]";
const item = part as {
type?: string;
text?: string;
uri?: unknown;
name?: unknown;
title?: unknown;
description?: unknown;
resource?: { text?: unknown } | null;
};
if (item.type === "text" && typeof item.text === "string") {
return item.text;
}
// An embedded resource with text in it is text, and often the answer itself: GitHub's MCP
// server returns a file it read as one, beside a line saying the download worked. A resource
// carrying bytes (`blob`) has no text to read and is named below like any other part.
if (item.type === "resource" && typeof item.resource?.text === "string") {
return item.resource.text;
}
// A resource_link is a pointer, not the file: a URI, a name, sometimes a title, and often a
// sentence of what it is. Named as "[resource_link]", the model was told a link arrived and
// never shown where it went, so a search that answered with pages produced no page it could
// open.
if (item.type === "resource_link") {
const shown = resourceLinkText(item);
if (shown !== null) return shown;
}
// A non-text part is named rather than dropped. A model told "[image]" can say the tool
// returned an image; a model handed nothing concludes the tool returned nothing.
return `[${item.type ?? "unknown"}]`;
})
.join("\n");
// Trimmed only to decide emptiness, never to alter a result that has something in it. A vendor
// that sent one newline has said nothing, and which shape of nothing arrived should not change
// what the model is told.
if (joined.trim() === "") {
/*
* MCP tools with an output schema often put the answer in `structuredContent` and leave
* `content` empty. Treating that as "nothing was found" is the same lie an empty string was:
* the tool answered, and the model fills the gap from memory. Read only when `content` had
* nothing; a text part already present is the representation the server chose to show.
*/
const structured =
structuredContent !== null &&
structuredContent !== undefined &&
typeof structuredContent === "object"
? JSON.stringify(structuredContent)
: "";
if (structured === "") {
return {
text: "The tool returned no content. Nothing was found, so there is nothing here to answer from.",
truncated: false,
};
}
joined = structured;
}
if (joined.length <= MAX_RESULT_CHARS) {
return { text: joined, truncated: false };
}
return {
text: `${cutAtCodeUnits(joined, MAX_RESULT_CHARS)}\n\n[truncated: the tool returned ${joined.length} characters]`,
truncated: true,
};
}
export type McpTool = {
name: string;
description: string;
inputSchema: Record<string, unknown>;
};
/**
* A tool as a transport listed it, including anything that transport happens to know about it.
*
* Three optional fields rather than a separate type per transport, so `refreshTools` reads
* `tool.effect` with no cast and no `"effect" in tool` sniffing. Optional because a transport may
* know none of it for a given tool, and a field always left undefined would be an invitation to
* read it as meaning something.
*
* AN MCP SERVER CAN PUBLISH AN EFFECT, and this docblock used to say it could not. That sentence
* was not a stale comment, it was load bearing: the argument that surfacing a recorded effect could
* not disturb any existing curated read rested on MCP listings never carrying one, which was true
* only because {@link listTools} was discarding `annotations`. The specification defines
* `annotations.destructiveHint`, servers publish it, and a tool a vendor declared destructive was
* classifying as a read for any curated entry whose hand-written `writeTools` happened to omit the
* name. Version is the field MCP genuinely has no concept of; effect and destructive are not.
*
* `McpTool` stays exactly what a `tools/list` answer contains, because that is what it is for.
*/
export type ListedTool = McpTool & {
/**
* The vendor's own spelling, when it differs from the name this deployment records.
*
* ABSENT MEANS THEY ARE THE SAME STRING, which is the honest answer for every transport but
* Arcade: Composio's `GMAIL_FETCH_EMAILS`, an MCP server's names and the Drive REST names are all
* offerable to a model exactly as the vendor spells them, so there is nothing to keep apart.
*
* THE TRANSPORT DECIDES, because only it knows the vendor's naming convention. Arcade's listing
* answers `Toolkit.Action` and the dot is illegal in a model tool name, so its transport splits
* the two: `name` is the action, this is the qualified name the vendor is called by. Deriving it
* here instead would make a rule out of the shape of one vendor's listing. See
* {@link mcpTools.vendorName}.
*/
vendorName?: string;
/** What the vendor said this action does, when it said anything. */
effect?: "read" | "write";
/** Whether the vendor marked it as destroying something. */
destructive?: boolean;
/** The vendor's version string, when calling the action requires one. */
version?: string;
};
export class McpServerError extends Error {
constructor(message: string) {
super(message);
this.name = "McpServerError";
}
}
type Connection = {
url: string;
/** The bearer token for this server, already decrypted. Absent for a server that needs none. */
token?: string;
/** The header the token goes in, sent as stored, when the vendor does not read `Authorization`. */
tokenHeader?: string;
};
/**
* The vendor's own sentence out of a failure, when there is one worth reading.
*
* The transport puts the response body in the message, after a fixed prefix. Two shapes turn up: a
* plain error object, and — from Google's Workspace servers — a JSON-RPC result whose `content` holds
* the explanation as text under `isError`. Both are worth surfacing; the tool list, which arrives in
* the same position under a 403, is not.
*/
function reasonFrom(error: unknown): string | null {
const message = error instanceof Error ? error.message : String(error);
const body = message.slice(message.indexOf("{"));
if (!body.startsWith("{")) return null;
let parsed: unknown;
try {
parsed = JSON.parse(body);
} catch {
return null;
}
const asRecord = (value: unknown) =>
value && typeof value === "object"
? (value as Record<string, unknown>)
: {};
// `{"error": {"message": "..."}}` — how Google's REST APIs refuse.
const restMessage = asRecord(asRecord(parsed).error).message;
if (typeof restMessage === "string" && restMessage) {
return trimmed(restMessage);
}
// `{"result": {"content": [{"text": "..."}], "isError": true}}` — how its MCP servers refuse.
const result = asRecord(asRecord(parsed).result);
if (result.isError === true && Array.isArray(result.content)) {
const text = result.content
.map((part) => asRecord(part).text)
.find((value): value is string => typeof value === "string" && !!value);
if (text) return trimmed(text);
}
return null;
}
/** Long enough for a sentence and a URL, short enough not to be the wall of JSON this replaced. */
const trimmed = (value: string) =>
value.length > 400 ? `${value.slice(0, 400)}…` : value;
/**
* A vendor's failure, as one sentence an operator can act on.
*
* WHAT THIS REPLACES. The transport throws `Error POSTing to endpoint: <the whole response body>`,
* and the status lives on the error object rather than in the message — so rewrapping by `.message`
* alone threw away the only part that says what went wrong and kept the part that does not.
*
* Google's Workspace MCP servers make that worse than it sounds. Asked for a tool list with a token
* they will not accept, they answer **401, or 403, with a complete and valid tool list in the body** —
* verified against the live endpoint. So the message was a wall of successful-looking JSON attached
* to a failure, which reads as a parsing bug here rather than as a refusal there.
*
* The status leads, and the well-known ones are named. A 403 also keeps the vendor's own sentence
* where there is one, because that is where Google says which API is not enabled — and each Workspace
* product is two APIs, so nothing else can tell "I enabled it" from "it is enabled".
*/
function vendorFailure(error: unknown): string {
const status =
typeof error === "object" && error !== null && "code" in error
? (error as { code?: unknown }).code
: undefined;
if (status === 401) {
return "The app turned down this account (401). Reconnect the account and try again. If it keeps happening, the account may not have access to this app.";
}
if (status === 403) {
/*
* A 403 keeps its reason, unlike a 401.
*
* This cost a diagnosis. Google refuses a Workspace MCP server with 403 when the API behind it is
* not enabled for the project — and the sentence saying so, with the console URL to fix it, is in
* the response body. Dropping the body left "the account may lack access, or the API may not be
* enabled", which is a guess between two very different problems when the vendor had already
* answered the question.
*
* Worse, each Workspace product is TWO APIs: enabling `drive.googleapis.com` does not enable
* `drivemcp.googleapis.com`, so "I enabled it" and "it is enabled" are not the same claim and
* only the body can tell them apart.
*
* Trimmed, because the body may instead be the tool list — the same server answers `tools/list`
* with a full, valid list under a 403 — and a wall of JSON is what made the original error
* unreadable.
*/
const detail = reasonFrom(error);
return detail
? `The app refused the request (403). It said: ${detail}`
: "The app refused the request (403). The account may not have access, or the API may not be turned on for this project.";
}
if (typeof status === "number") {
return `The vendor answered ${status}.`;
}
return error instanceof Error ? error.message : String(error);
}
/**
* The Authorization header a stored token becomes.
*
* Bearer by default, which is what an MCP server's own token usually is. A token that already
* names its scheme is sent as written, because some vendors forward the header straight to an API
* that only speaks Basic: DataForSEO's hosted server answers the handshake and the tool listing to
* anything, then returns 401 on every real call made with Bearer, so a deployment that could only
* say Bearer looked connected and never worked. The scheme travels with the credential rather than
* as a setting on the server row, so rotating a token can change how it is presented and nothing
* else has to know.
*/
export function authorizationHeader(token: string): string {
const trimmed = token.trim();
return /^(basic|bearer)\s+\S/i.test(trimmed) ? trimmed : `Bearer ${trimmed}`;
}
/**
* Build, use and close a client.
*
* The `finally` closes the transport whatever happened, because a thrown error is the case where a
* leaked connection is most likely and least noticed.
*/
async function withClient<T>(
connection: Connection,
use: (client: Client) => Promise<T>,
): Promise<T> {
const transport = new StreamableHTTPClientTransport(new URL(connection.url), {
requestInit: connection.token
? {
headers: connection.tokenHeader
? { [connection.tokenHeader]: connection.token.trim() }
: { Authorization: authorizationHeader(connection.token) },
}
: undefined,
});
const client = new Client({ name: "openbot", version: "1.0.0" });
try {
await client.connect(transport);
return await use(client);
} catch (error) {
// Rewrapped so a caller never has to care whether the failure came from the transport, the
// handshake or the call, and so the message that reaches an audit row and an admin page is one
// sentence rather than a stack.
throw new McpServerError(vendorFailure(error));
} finally {
await client.close().catch(() => {
// A server that will not say goodbye is not a failure of the work that just succeeded.
});
}
}
/**
* A remote server will not list its tools to nobody, so a credential is required to ask.
*
* Declared rather than assumed, because the other transport in this deployment answers differently
* and the difference is the whole shape of an administrator's setup flow. See {@link ./transport}.
*/
export const listNeedsCredential = true;
/**
* ONLY THE HINT THAT NARROWS IS BELIEVED, and the omission of the other one is the decision here.
*
* The SDK declares four hints on `annotations` — `readOnlyHint`, `destructiveHint`,
* `idempotentHint`, `openWorldHint` — and warns in the same place that a client should never make
* tool use decisions from annotations a server it does not trust supplied. That warning is the
* whole design of this function. `destructiveHint` can only ever move an action from read to write,
* so a server that lies with it can restrict itself and nothing else. `readOnlyHint` moves an
* action the other way, and `classifyTool` exists to make sure nothing but review can do that.
*
* WHAT HONOURING `readOnlyHint` WOULD ACTUALLY BUY, which is the reason withholding it costs
* nothing. For a curated vendor it changes no answer: an advertised name absent from the reviewed
* `writeTools` already classifies as a read, so recording `read` for it lands on the same result by
* a worse route. For a name the reviewed list DOES hold, `classifyTool` consults review first and
* ignores the column, so the hint would be discarded anyway. The single case where it would change
* an answer is a server an administrator added by URL, which has no reviewed list behind it and
* whose every tool is a write for exactly that reason — and there, believing it means letting an
* arbitrary server declare its own tools harmless and be believed. Zero accuracy gained, one
* fail-open introduced, so it is not read at all.
*
* `destructiveHint` is taken on presence of `true` only, never inverted. The specification gives it
* a default of true when a tool is not read-only, and applying that default would reclassify every
* unannotated action of every MCP vendor as a write — correct by the letter and a mass revocation
* of grants people already hold. An absent hint stays absent, which leaves the reviewed list
* deciding exactly as it did before, and only an explicit declaration narrows anything.
*
* A server that sets both hints is contradicting itself, and is read as destructive. The
* specification says `destructiveHint` is meaningless while `readOnlyHint` is true, but resolving
* an incoherent listing towards the permissive reading is the one direction that could hurt.
*/
function declaredEffect(annotations: ToolAnnotations | undefined) {
if (annotations?.destructiveHint !== true) return {};
return { effect: "write", destructive: true } as const;
}
/** What this server says it offers, right now. */
export async function listTools(connection: Connection): Promise<ListedTool[]> {
return withClient(connection, async (client) => {
const result = await client.listTools(undefined, {
timeout: LIST_TIMEOUT_MS,
});
return result.tools.map((tool) => ({
name: tool.name,
description: tool.description ?? "",
inputSchema: (tool.inputSchema ?? {}) as Record<string, unknown>,
...declaredEffect(tool.annotations),
}));
});
}
export type McpCallResult = {
/** The result as text, which is what a model reads. Truncated visibly if it was enormous. */
text: string;
/** True when the server itself reported the call as an error rather than failing to answer. */
isError: boolean;
truncated: boolean;
/**
* The vendor no longer holds the account this call was made in, though this deployment still has
* a row for it. Only the Composio transport sets it, and only on an `isError` result; the store
* turns it into a refusal that offers Reconnect. Absent everywhere else.
*/
accountGone?: true;
};
/**
* Call one tool.
*
* Whether the call was permitted is not decided here. This function's only job is to speak the
* protocol; the grant and the policy are settled before anything reaches it. Keeping the two apart
* means the permission check cannot be accidentally satisfied by a code path that also happens to
* make the call.
*/
export async function callTool(
connection: Connection,
toolName: string,
args: Record<string, unknown>,
): Promise<McpCallResult> {
return withClient(connection, async (client) => {
const result = await client.callTool(
{ name: toolName, arguments: args },
undefined,
{ timeout: CALL_TIMEOUT_MS },
);
const { text, truncated } = resultText(
result.content,
"structuredContent" in result ? result.structuredContent : undefined,
);
return { text, isError: result.isError === true, truncated };
});
}