Add MCP servers and custom tools for bots
Two new settings pages, MCPs and Tools. Super admins define them; super
admins and admins attach them to bots, to workspaces (every bot there),
or to every bot. Bots get them in chat replies and tasks.
- Custom tools: a JSON-schema of arguments plus an HTTP request, a script
on the bot's computer, or a prompt, templated with {{args.x}} and
{{env.KEY}}, secrets redacted from results.
- MCP servers: remote (URL and headers) or stdio commands run on the host
with a setup command and an isolated env, in a per-process pool. Tools
are listed into a cache and connect on first call.
- Add, edit, access and try open in modals.
- Markdown, JSON and command fields use twui's AceEditor (CodeEditor),
its scripts loaded on demand.
Co-Authored-By: Claude Opus 5.5 <[email protected]>
This commit is contained in:
Claude Opus 5.5
@@ -0,0 +1,70 @@
|
||||
import type { CustomToolRecord } from "@/src/types";
|
||||
import redactSecrets from "@/src/utils/redact-secrets";
|
||||
import type { HarnessTool } from "../../types";
|
||||
import checkRequiredArgs from "./check-required-args";
|
||||
import runHttpTool from "./run-http-tool";
|
||||
import runPromptTool from "./run-prompt-tool";
|
||||
import runScriptTool from "./run-script-tool";
|
||||
|
||||
type Params = {
|
||||
tool: CustomToolRecord;
|
||||
/**
|
||||
* What `{{env.KEY}}` reads (`grabRunEnvs`). Secret values are blanked
|
||||
* out of every result and error.
|
||||
*/
|
||||
envs: { key: string; value: string; secret: boolean }[];
|
||||
/**
|
||||
* Where a script tool runs. Without one, a script tool isn't offered.
|
||||
*/
|
||||
computer_id?: number | string | null;
|
||||
bot_id?: number | string;
|
||||
workspace_id?: number | string | null;
|
||||
};
|
||||
|
||||
/**
|
||||
* A custom tool as a harness tool: its name, description and JSON schema
|
||||
* as the model sees them, and `run` dispatching on its kind (an HTTP
|
||||
* request, a script on the computer, or a prompt). Null for a script tool
|
||||
* when the run has no computer.
|
||||
*/
|
||||
export default function buildCustomTool({
|
||||
tool,
|
||||
envs,
|
||||
computer_id,
|
||||
bot_id,
|
||||
workspace_id,
|
||||
}: Params): HarnessTool<Record<string, unknown>> | null {
|
||||
if (tool.kind == "script" && !computer_id) return null;
|
||||
|
||||
const secrets = envs.filter((env) => env.secret);
|
||||
const redact = (text: string) => redactSecrets({ text, secrets });
|
||||
|
||||
const call = ({ args, signal }: { args: Record<string, unknown>; signal: AbortSignal }) => {
|
||||
switch (tool.kind) {
|
||||
case "http":
|
||||
return runHttpTool({ config: tool.config, args, envs, signal });
|
||||
case "script":
|
||||
return runScriptTool({ config: tool.config, args, computer_id: computer_id!, workspace_id, signal });
|
||||
case "prompt":
|
||||
return runPromptTool({ config: tool.config, args, envs, bot_id, workspace_id, signal });
|
||||
}
|
||||
};
|
||||
|
||||
return {
|
||||
name: tool.name,
|
||||
description:
|
||||
tool.kind == "script"
|
||||
? `${tool.description}\n(Runs on your current computer.)`
|
||||
: tool.description,
|
||||
parameters: tool.parameters,
|
||||
run: async ({ args, signal }) => {
|
||||
try {
|
||||
checkRequiredArgs({ parameters: tool.parameters, args });
|
||||
return redact(await call({ args, signal }));
|
||||
} catch (error: unknown) {
|
||||
if (error instanceof Error) error.message = redact(error.message);
|
||||
throw error;
|
||||
}
|
||||
},
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,21 @@
|
||||
type Params = {
|
||||
/**
|
||||
* The tool's JSON schema.
|
||||
*/
|
||||
parameters: Record<string, unknown>;
|
||||
args: Record<string, unknown>;
|
||||
};
|
||||
|
||||
/**
|
||||
* Throws when the model left out an argument the tool's schema requires.
|
||||
* The rest of the schema is the model's to follow: custom tools fill
|
||||
* templates, so a wrong type does no harm the call wouldn't show.
|
||||
*/
|
||||
export default function checkRequiredArgs({ parameters, args }: Params) {
|
||||
const required = Array.isArray(parameters.required) ? parameters.required.map(String) : [];
|
||||
const missing = required.filter((key) => args[key] === undefined || args[key] === null || args[key] === "");
|
||||
|
||||
if (missing.length) {
|
||||
throw new Error(`Missing required arguments: ${missing.join(", ")}.`);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,58 @@
|
||||
import { AppData } from "@/src/data/app-data";
|
||||
import type { CustomToolHttpConfig } from "@/src/types";
|
||||
import fillTemplate from "@/src/utils/fill-template";
|
||||
|
||||
type Params = {
|
||||
config: CustomToolHttpConfig;
|
||||
args: Record<string, unknown>;
|
||||
envs: { key: string; value: string }[];
|
||||
signal: AbortSignal;
|
||||
};
|
||||
|
||||
/**
|
||||
* Calls the tool's API from the app: URL (arguments URL-encoded), headers
|
||||
* and body filled in from the arguments and envs. With no body template,
|
||||
* anything but GET sends the arguments as JSON. Returns the response (JSON
|
||||
* pretty-printed); a non-2xx answer throws with its status and body.
|
||||
*/
|
||||
export default async function runHttpTool({ config, args, envs, signal }: Params) {
|
||||
const fill = (template: string, encode?: (value: string) => string) =>
|
||||
fillTemplate({ template, args, envs, encode });
|
||||
|
||||
const method = config.method || "GET";
|
||||
const headers = new Headers(
|
||||
Object.entries(config.headers || {}).map(([key, value]) => [key, fill(value)] as [string, string]),
|
||||
);
|
||||
const body =
|
||||
method == "GET" ? undefined : config.body?.trim() ? fill(config.body) : JSON.stringify(args);
|
||||
|
||||
if (body && !headers.has("content-type")) headers.set("content-type", "application/json");
|
||||
|
||||
const res = await fetch(fill(config.url, encodeURIComponent), {
|
||||
method,
|
||||
headers,
|
||||
body,
|
||||
signal: AbortSignal.any([
|
||||
signal,
|
||||
AbortSignal.timeout(
|
||||
Math.min(config.timeout_ms || AppData.CustomToolDefaultTimeoutMs, AppData.CustomToolMaxTimeoutMs),
|
||||
),
|
||||
]),
|
||||
});
|
||||
|
||||
const text = prettify({ text: await res.text() });
|
||||
|
||||
if (!res.ok) {
|
||||
throw new Error(`HTTP ${res.status} ${res.statusText}${text ? `: ${text.slice(0, 4000)}` : ""}`);
|
||||
}
|
||||
|
||||
return text || `HTTP ${res.status}, no body.`;
|
||||
}
|
||||
|
||||
function prettify({ text }: { text: string }) {
|
||||
try {
|
||||
return JSON.stringify(JSON.parse(text), null, 2);
|
||||
} catch {
|
||||
return text.trim();
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,30 @@
|
||||
import type { CustomToolPromptConfig } from "@/src/types";
|
||||
import fillTemplate from "@/src/utils/fill-template";
|
||||
import generateText from "../../text/generate-text";
|
||||
|
||||
type Params = {
|
||||
config: CustomToolPromptConfig;
|
||||
args: Record<string, unknown>;
|
||||
envs: { key: string; value: string }[];
|
||||
/**
|
||||
* Its models are used, like the run's.
|
||||
*/
|
||||
bot_id?: number | string;
|
||||
workspace_id?: number | string | null;
|
||||
signal: AbortSignal;
|
||||
};
|
||||
|
||||
/**
|
||||
* Fills the tool's prompt in and answers it with one text model turn (no
|
||||
* tools). Returns the answer.
|
||||
*/
|
||||
export default async function runPromptTool({ config, args, envs, bot_id, workspace_id, signal }: Params) {
|
||||
const result = await generateText({
|
||||
messages: [{ role: "user", content: fillTemplate({ template: config.prompt || "", args, envs }) }],
|
||||
bot_id,
|
||||
workspace_id,
|
||||
signal,
|
||||
});
|
||||
|
||||
return result.text || "(no answer)";
|
||||
}
|
||||
@@ -0,0 +1,73 @@
|
||||
import { AppData } from "@/src/data/app-data";
|
||||
import { CustomToolScriptLanguages } from "@/src/dict/custom-tool-dict";
|
||||
import grabComputerMcpUrl from "@/src/functions/backend/db/computers/grab-computer-mcp-url";
|
||||
import grabComputerEnvs from "@/src/functions/backend/db/envs/grab-computer-envs";
|
||||
import type { CustomToolScriptConfig } from "@/src/types";
|
||||
import computerNotReadyMessage from "@/src/utils/computer-not-ready-message";
|
||||
import redactSecrets from "@/src/utils/redact-secrets";
|
||||
import runComputerCommand from "../computer/run-computer-command";
|
||||
import writeComputerEnv from "../computer/write-computer-env";
|
||||
|
||||
type Params = {
|
||||
config: CustomToolScriptConfig;
|
||||
args: Record<string, unknown>;
|
||||
computer_id: number | string;
|
||||
/**
|
||||
* The workspace the run is in: its envs apply on the computer.
|
||||
*/
|
||||
workspace_id?: number | string | null;
|
||||
signal: AbortSignal;
|
||||
};
|
||||
|
||||
/**
|
||||
* Runs the tool's code on a computer over the sandbox's REST API, with the
|
||||
* computer's envs set (`writeComputerEnv`) and the arguments as JSON in
|
||||
* `COBBLE_ARGS` and on stdin. Code and arguments travel base64-encoded,
|
||||
* so nothing in them needs quoting. Returns what it printed (stdout and
|
||||
* stderr), secrets redacted; a non-zero exit throws with it.
|
||||
*/
|
||||
export default async function runScriptTool({ config, args, computer_id, workspace_id, signal }: Params) {
|
||||
const target = await grabComputerMcpUrl({ computer_id });
|
||||
|
||||
if (!target) throw new Error(`Computer #${computer_id} has no container to run on.`);
|
||||
if (!target.ready) throw new Error(computerNotReadyMessage(target));
|
||||
|
||||
const envs = await grabComputerEnvs({ computer_id, workspace_id });
|
||||
const { shell_path } = await writeComputerEnv({ base_url: target.base_url, envs, signal });
|
||||
const language =
|
||||
CustomToolScriptLanguages.find((l) => l.value == config.language) || CustomToolScriptLanguages[0];
|
||||
|
||||
const code = Buffer.from(config.code || "").toString("base64");
|
||||
const input = Buffer.from(JSON.stringify(args)).toString("base64");
|
||||
|
||||
const result = await runComputerCommand({
|
||||
base_url: target.base_url,
|
||||
/**
|
||||
* In a subshell: `exit` in the sandbox's own shell would end its
|
||||
* session.
|
||||
*/
|
||||
command: `(${[
|
||||
`f=$(mktemp --suffix=.${language.extension})`,
|
||||
`echo ${code} | base64 -d > "$f"`,
|
||||
`[ -f ${shell_path} ] && . ${shell_path}`,
|
||||
`export COBBLE_ARGS="$(echo ${input} | base64 -d)"`,
|
||||
`printf '%s' "$COBBLE_ARGS" | ${language.interpreter} "$f" 2>&1`,
|
||||
`status=$?`,
|
||||
`rm -f "$f"`,
|
||||
`exit $status`,
|
||||
].join("; ")})`,
|
||||
timeout_ms: Math.min(config.timeout_ms || AppData.CustomToolDefaultTimeoutMs, AppData.CustomToolMaxTimeoutMs),
|
||||
signal,
|
||||
});
|
||||
|
||||
const output = redactSecrets({
|
||||
text: result.output.trim(),
|
||||
secrets: envs.filter((env) => env.secret),
|
||||
});
|
||||
|
||||
if (result.exit_code) {
|
||||
throw new Error(`Exit code ${result.exit_code}${output ? `:\n${output}` : "."}`);
|
||||
}
|
||||
|
||||
return output || "(no output)";
|
||||
}
|
||||
@@ -0,0 +1,108 @@
|
||||
import grabBotExtensions from "@/src/functions/backend/db/extensions/grab-bot-extensions";
|
||||
import grabRunEnvs from "@/src/functions/backend/db/extensions/grab-run-envs";
|
||||
import mcpToolName from "@/src/utils/mcp-tool-name";
|
||||
import redactSecrets from "@/src/utils/redact-secrets";
|
||||
import mcpHarnessTool from "../../mcp/mcp-harness-tool";
|
||||
import openMcpServer from "../../mcp/open-mcp-server";
|
||||
import readImage from "../../media/read-image";
|
||||
import type { HarnessTool } from "../../types";
|
||||
import buildCustomTool from "../custom/build-custom-tool";
|
||||
|
||||
type Params = {
|
||||
bot_id: number | string;
|
||||
workspace_id?: number | string | null;
|
||||
/**
|
||||
* Where script tools run: the task's computer, or in chat the bot's
|
||||
* current one. None leaves script tools out.
|
||||
*/
|
||||
computer_id?: number | string | null;
|
||||
/**
|
||||
* Names the run's built-in tools already use: they win.
|
||||
*/
|
||||
taken?: string[];
|
||||
signal?: AbortSignal;
|
||||
};
|
||||
|
||||
export type OpenBotExtensions = {
|
||||
tools: HarnessTool[];
|
||||
/**
|
||||
* For the system prompt, only when something's wrong (an MCP server
|
||||
* with no tools listed), so the bot can say so. Empty otherwise.
|
||||
*/
|
||||
note: string;
|
||||
close: () => Promise<void>;
|
||||
};
|
||||
|
||||
/**
|
||||
* The MCP servers' and custom tools' tools a bot gets on one run
|
||||
* (`grabBotExtensions`), as harness tools. MCP tools are built from each
|
||||
* server's last listing (`<slug>__<tool>`) and connect on their first call,
|
||||
* so a run that doesn't use them never waits on them. Secret env values are
|
||||
* blanked out of every result. Call `close` when the run ends.
|
||||
*/
|
||||
export default async function openBotExtensions({
|
||||
bot_id,
|
||||
workspace_id,
|
||||
computer_id,
|
||||
taken = [],
|
||||
signal,
|
||||
}: Params): Promise<OpenBotExtensions> {
|
||||
const { servers, tools } = await grabBotExtensions({ bot_id, workspace_id });
|
||||
|
||||
if (!servers.length && !tools.length) return { tools: [], note: "", close: async () => {} };
|
||||
|
||||
const envs = await grabRunEnvs({ workspace_id });
|
||||
const secrets = envs.filter((env) => env.secret);
|
||||
const redact = (text: string) => redactSecrets({ text, secrets });
|
||||
const names = new Set(taken);
|
||||
const result: HarnessTool[] = [];
|
||||
const notes: string[] = [];
|
||||
const opened: ReturnType<typeof openMcpServer>[] = [];
|
||||
|
||||
const add = (tool: HarnessTool | null) => {
|
||||
if (!tool || names.has(tool.name)) return;
|
||||
names.add(tool.name);
|
||||
result.push(tool);
|
||||
};
|
||||
|
||||
for (const tool of tools) {
|
||||
add(buildCustomTool({ tool, envs, computer_id, bot_id, workspace_id }));
|
||||
}
|
||||
|
||||
for (const server of servers) {
|
||||
const listed = server.tools.filter((tool) => !server.excluded_tools.includes(tool.name));
|
||||
|
||||
if (!listed.length) {
|
||||
notes.push(
|
||||
`- ${server.name}: ${server.status == "error" ? `unavailable (${redact(server.last_error).slice(0, 300)})` : "no tools listed yet"}.`,
|
||||
);
|
||||
continue;
|
||||
}
|
||||
|
||||
const open = openMcpServer({ server, envs, signal });
|
||||
opened.push(open);
|
||||
|
||||
for (const tool of listed) {
|
||||
add(
|
||||
mcpHarnessTool({
|
||||
name: mcpToolName({ slug: server.slug, name: tool.name }),
|
||||
tool: { ...tool, description: `${server.name}: ${tool.description}` },
|
||||
client: open.client,
|
||||
redact,
|
||||
describeImage: ({ data, mime_type }) =>
|
||||
readImage({ url: `data:${mime_type};base64,${data}`, signal, bot_id, workspace_id }),
|
||||
}),
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
return {
|
||||
tools: result,
|
||||
note: notes.length
|
||||
? `These MCP servers were set up for you but you can't use them right now; if the user needs them, say so (an admin fixes them in Settings, under MCPs):\n${notes.join("\n")}`
|
||||
: "",
|
||||
close: async () => {
|
||||
await Promise.all(opened.map((open) => open.close()));
|
||||
},
|
||||
};
|
||||
}
|
||||
Reference in New Issue
Block a user