pi-roundtable-mcp 0.1.0

package/src/connectors/connectors-plugin.ts

@@ -0,0 +1,114 @@
+import {
+	ConfigError,
+	definePlugin,
+	type RoundtablePlugin,
+	serviceKey,
+} from "pi-roundtable";
+import { DISCORD } from "pi-roundtable/discord";
+import type { VirtualServer } from "pi-roundtable/kit";
+import { connectorCommands } from "./connector-commands.ts";
+import {
+	type Connector,
+	type ConnectorProfileSource,
+	ConnectorRegistry,
+	DEFAULT_MAX_TOOL_NAME,
+	DEFAULT_SERVER_PREFIX,
+} from "./connector-registry.ts";
+import {
+	ContextForgeAdmin,
+	contextForgeToken,
+	resolveVirtualServer,
+} from "./contextforge.ts";
+import { type ConnectorMessages, connectorMessages } from "./messages.ts";
+
+/** One token per process, valid for a year; every restart mints a fresh one. */
+const TOKEN_TTL_SECONDS = 365 * 24 * 3600;
+
+export interface ContextForgeOptions {
+	/** The gateway's base URL, such as `http://localhost:4444`. */
+	url: string;
+	/** The secret ContextForge signs and verifies its JWTs with. */
+	jwtSecret: string;
+	/** The admin user the plugin acts as, an email address such as `admin@example.com`. */
+	user: string;
+}
+
+export interface McpConnectorsOptions {
+	contextForge: ContextForgeOptions;
+	/** The start of every connector's virtual server name in ContextForge; default `roundtable-conn-`. */
+	serverPrefix?: string;
+	/** Tools whose names are longer are left out of a connector's server; default 45. */
+	maxToolName?: number;
+	/** The Discord text and the registry's refusals, in your wording; English by default. */
+	messages?: Partial<ConnectorMessages>;
+}
+
+/** What a host reads to give its agents the owner's connectors. */
+export interface Connectors {
+	/** Changes on every add, description change, and removal, so a host knows its tool sets are stale. */
+	readonly version: number;
+	list(): Connector[];
+	/** Virtual servers of the connectors whose tools are known. */
+	servers(): VirtualServer[];
+	/** Each connector as the profile source a host builds a per-agent MCP profile from. */
+	profileSources(): ConnectorProfileSource[];
+	/** The bearer token that ContextForge's virtual server URLs expect; one per process. */
+	readonly token: string;
+}
+
+export const CONNECTORS = serviceKey<Connectors>(
+	"pi-roundtable-mcp.connectors",
+);
+
+function checkOptions({ contextForge }: McpConnectorsOptions): string {
+	const base = URL.parse(contextForge.url);
+	if (base?.protocol !== "http:" && base?.protocol !== "https:")
+		throw new ConfigError(
+			"mcp-connectors: contextForge.url must be an http(s) URL",
+		);
+	if (!contextForge.jwtSecret)
+		throw new ConfigError("mcp-connectors: contextForge.jwtSecret is empty");
+	if (!contextForge.user)
+		throw new ConfigError("mcp-connectors: contextForge.user is empty");
+	return contextForge.url.replace(/\/+$/, "");
+}
+
+/**
+ * The owner's MCP connectors: ContextForge holds each upstream server and its token, a table
+ * holds what the host needs to route to it, and `/<root> connector` adds and removes them.
+ * Provides `CONNECTORS`.
+ */
+export function mcpConnectors(options: McpConnectorsOptions): RoundtablePlugin {
+	const url = checkOptions(options);
+	const text = connectorMessages(options.messages);
+	return definePlugin({
+		name: "mcp-connectors",
+		requires: [DISCORD],
+		provides: [CONNECTORS],
+		migrations: [ConnectorRegistry.migration],
+		setup: async ({ database, services, logger }) => {
+			const { jwtSecret, user } = options.contextForge;
+			const token = contextForgeToken(jwtSecret, user, TOKEN_TTL_SECONDS);
+			const registry = await ConnectorRegistry.attach(database(), {
+				admin: new ContextForgeAdmin(url, token),
+				resolve: (name) => resolveVirtualServer(url, token, name),
+				logger,
+				serverPrefix: options.serverPrefix ?? DEFAULT_SERVER_PREFIX,
+				maxToolName: options.maxToolName ?? DEFAULT_MAX_TOOL_NAME,
+				messages: text,
+			});
+			const { commands, guard } = services.get(DISCORD);
+			commands.add(connectorCommands(guard, registry, text));
+			services.provide(CONNECTORS, {
+				get version() {
+					return registry.version;
+				},
+				list: () => registry.list(),
+				servers: () => registry.servers(),
+				profileSources: () => registry.profileSources(),
+				token,
+			});
+			return {};
+		},
+	});
+}

package/src/connectors/contextforge.ts

@@ -0,0 +1,371 @@
+import { createHmac, randomUUID } from "node:crypto";
+import { ConfigError } from "pi-roundtable";
+import type { VirtualServer } from "pi-roundtable/kit";
+
+function base64url(value: string | Buffer): string {
+	return Buffer.from(value).toString("base64url");
+}
+
+/**
+ * An admin token with the claims ContextForge's own `create_jwt_token --admin` issues,
+ * signed HS256 with its JWT secret. `teams: null` gives the admin bypass.
+ */
+export function contextForgeToken(
+	secret: string,
+	user: string,
+	ttlSeconds: number,
+	now = Math.floor(Date.now() / 1000),
+): string {
+	const header = base64url(JSON.stringify({ alg: "HS256", typ: "JWT" }));
+	const payload = base64url(
+		JSON.stringify({
+			username: user,
+			sub: user,
+			iat: now,
+			exp: now + ttlSeconds,
+			iss: "mcpgateway",
+			aud: "mcpgateway-api",
+			jti: randomUUID(),
+			env: "development",
+			user: {
+				email: user,
+				full_name: "pi-roundtable-mcp",
+				is_admin: true,
+				auth_provider: "cli",
+			},
+			teams: null,
+		}),
+	);
+	const signature = createHmac("sha256", secret)
+		.update(`${header}.${payload}`)
+		.digest("base64url");
+	return `${header}.${payload}.${signature}`;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+async function getJson(
+	url: string,
+	token: string,
+	fetchImpl: typeof fetch,
+): Promise<unknown> {
+	const response = await fetchImpl(url, {
+		headers: { authorization: `Bearer ${token}` },
+		signal: AbortSignal.timeout(15_000),
+	});
+	if (!response.ok) {
+		throw new ConfigError(
+			`ContextForge ${url} answered ${response.status}: ${(await response.text()).slice(0, 200)}`,
+		);
+	}
+	return response.json();
+}
+
+/** Finds a virtual server by name and lists the tool names it serves. */
+export async function resolveVirtualServer(
+	baseUrl: string,
+	token: string,
+	name: string,
+	fetchImpl: typeof fetch = fetch,
+): Promise<VirtualServer> {
+	const servers = await getJson(
+		`${baseUrl}/servers?include_pagination=false`,
+		token,
+		fetchImpl,
+	);
+	const server = Array.isArray(servers)
+		? servers.find((entry) => isRecord(entry) && entry.name === name)
+		: undefined;
+	if (!isRecord(server) || typeof server.id !== "string") {
+		throw new ConfigError(`ContextForge has no virtual server named ${name}`);
+	}
+	const tools = await getJson(
+		`${baseUrl}/servers/${server.id}/tools?include_pagination=false`,
+		token,
+		fetchImpl,
+	);
+	const names = Array.isArray(tools)
+		? tools.flatMap((tool) =>
+				isRecord(tool) && typeof tool.name === "string" ? [tool.name] : [],
+			)
+		: [];
+	if (names.length === 0)
+		throw new ConfigError(`virtual server ${name} serves no tools`);
+	return { name, url: `${baseUrl}/servers/${server.id}/mcp`, tools: names };
+}
+
+/** A request ContextForge refused or could not complete; the message is safe to show the owner. */
+export class ContextForgeError extends Error {}
+
+/** How ContextForge authenticates to an upstream MCP server. */
+export type UpstreamAuth =
+	| { type: "none" }
+	| { type: "bearer"; token: string }
+	| { type: "header"; name: string; value: string };
+
+/** The credential as ContextForge's gateway form takes it. */
+function authFields(auth: UpstreamAuth): Record<string, string> {
+	if (auth.type === "bearer")
+		return { auth_type: "bearer", auth_token: auth.token };
+	if (auth.type === "header")
+		return {
+			auth_type: "authheaders",
+			auth_header_key: auth.name,
+			auth_header_value: auth.value,
+		};
+	return {};
+}
+
+/** The parts of the credential that error text must not repeat. */
+function authSecrets(auth: UpstreamAuth): string[] {
+	if (auth.type === "bearer") return [auth.token];
+	if (auth.type === "header") return [auth.value];
+	return [];
+}
+
+export interface GatewayTool {
+	id: string;
+	name: string;
+	gatewaySlug: string;
+}
+
+/** The admin API calls that add and remove owner connectors. */
+export interface GatewayState {
+	name: string;
+	enabled: boolean;
+	reachable: boolean;
+	tools: number;
+}
+
+export class ContextForgeAdmin {
+	readonly #baseUrl: string;
+	readonly #token: string;
+	readonly #fetch: typeof fetch;
+
+	constructor(baseUrl: string, token: string, fetchImpl: typeof fetch = fetch) {
+		this.#baseUrl = baseUrl;
+		this.#token = token;
+		this.#fetch = fetchImpl;
+	}
+
+	/** Registers an upstream server; ContextForge connects and lists its tools before answering. */
+	async createGateway(gateway: {
+		name: string;
+		url: string;
+		description: string;
+		auth: UpstreamAuth;
+	}): Promise<{ id: string; slug: string }> {
+		const { auth } = gateway;
+		const upstream = URL.parse(gateway.url);
+		if (!upstream)
+			throw new ContextForgeError(
+				`Cannot parse the upstream URL: ${gateway.url}`,
+			);
+		const body = {
+			name: gateway.name,
+			url: gateway.url,
+			description: gateway.description,
+			transport: /\/sse\/?$/.test(upstream.pathname) ? "SSE" : "STREAMABLEHTTP",
+			...authFields(auth),
+		};
+		const secrets = [...authSecrets(auth), ...urlSecrets(gateway.url)];
+		const created = await this.#send(
+			"POST",
+			"/gateways",
+			body,
+			90_000,
+			secrets,
+		);
+		if (!isRecord(created) || typeof created.id !== "string")
+			throw new ContextForgeError(
+				"ContextForge did not return the gateway ID.",
+			);
+		return {
+			id: created.id,
+			slug: typeof created.slug === "string" ? created.slug : gateway.name,
+		};
+	}
+
+	async tools(): Promise<GatewayTool[]> {
+		const tools = await this.#send(
+			"GET",
+			"/tools?include_pagination=false&limit=0",
+		);
+		return Array.isArray(tools)
+			? tools.flatMap((tool) =>
+					isRecord(tool) &&
+					typeof tool.id === "string" &&
+					typeof tool.name === "string" &&
+					typeof tool.gatewaySlug === "string"
+						? [{ id: tool.id, name: tool.name, gatewaySlug: tool.gatewaySlug }]
+						: [],
+				)
+			: [];
+	}
+
+	/** Every upstream gateway with its state and tool count; URLs and auth are never read. */
+	async gateways(): Promise<GatewayState[]> {
+		const [gateways, tools] = await Promise.all([
+			this.#send("GET", "/gateways?include_pagination=false"),
+			this.tools(),
+		]);
+		return Array.isArray(gateways)
+			? gateways.flatMap((gateway) =>
+					isRecord(gateway) && typeof gateway.name === "string"
+						? [
+								{
+									name: gateway.name,
+									enabled: gateway.enabled === true,
+									reachable: gateway.reachable === true,
+									tools: tools.filter(
+										(tool) =>
+											tool.gatewaySlug ===
+											(typeof gateway.slug === "string"
+												? gateway.slug
+												: gateway.name),
+									).length,
+								},
+							]
+						: [],
+				)
+			: [];
+	}
+
+	/** Every virtual server with the names of the tools it serves. */
+	async servers(): Promise<{ name: string; tools: string[] }[]> {
+		const servers = await this.#send(
+			"GET",
+			"/servers?include_pagination=false",
+		);
+		const named = Array.isArray(servers)
+			? servers.filter(
+					(server): server is { id: string; name: string } =>
+						isRecord(server) &&
+						typeof server.id === "string" &&
+						typeof server.name === "string",
+				)
+			: [];
+		return Promise.all(
+			named.map(async (server) => {
+				const tools = await this.#send(
+					"GET",
+					`/servers/${encodeURIComponent(server.id)}/tools?include_pagination=false`,
+				);
+				return {
+					name: server.name,
+					tools: Array.isArray(tools)
+						? tools.flatMap((tool) =>
+								isRecord(tool) && typeof tool.name === "string"
+									? [tool.name]
+									: [],
+							)
+						: [],
+				};
+			}),
+		);
+	}
+
+	async createServer(
+		name: string,
+		description: string,
+		toolIds: string[],
+	): Promise<string> {
+		const created = await this.#send("POST", "/servers", {
+			server: { name, description, associated_tools: toolIds },
+		});
+		if (!isRecord(created) || typeof created.id !== "string")
+			throw new ContextForgeError(
+				"ContextForge did not return the virtual server ID.",
+			);
+		return created.id;
+	}
+
+	async deleteServer(id: string): Promise<void> {
+		await this.#send("DELETE", `/servers/${encodeURIComponent(id)}`);
+	}
+
+	async deleteGateway(id: string): Promise<void> {
+		await this.#send("DELETE", `/gateways/${encodeURIComponent(id)}`);
+	}
+
+	async #send(
+		method: string,
+		path: string,
+		body?: unknown,
+		timeoutMs = 30_000,
+		/** Masked in error text, since a validation error may echo the request. */
+		secrets: readonly string[] = [],
+	): Promise<unknown> {
+		const response = await this.#fetch(`${this.#baseUrl}${path}`, {
+			method,
+			headers: {
+				authorization: `Bearer ${this.#token}`,
+				...(body === undefined ? {} : { "content-type": "application/json" }),
+			},
+			...(body === undefined ? {} : { body: JSON.stringify(body) }),
+			signal: AbortSignal.timeout(timeoutMs),
+		});
+		const text = await response.text();
+		if (!response.ok)
+			throw new ContextForgeError(
+				`ContextForge answered ${response.status}: ${detailOf(masked(text, secrets))}`,
+			);
+		if (!text) return undefined;
+		try {
+			return JSON.parse(text);
+		} catch {
+			throw new ContextForgeError(
+				`ContextForge did not answer with JSON: ${detailOf(masked(text, secrets))}`,
+			);
+		}
+	}
+}
+
+/**
+ * The parts of an upstream URL that may carry a credential: the URL itself, what follows
+ * its host, user and password, and query values. Short parts are left, since masking them
+ * would garble the rest of the message.
+ */
+export function urlSecrets(url: string): string[] {
+	const parsed = URL.parse(url);
+	if (!parsed) return [url];
+	const rest = `${parsed.pathname}${parsed.search}${parsed.hash}`;
+	return [
+		url,
+		parsed.href,
+		rest === "/" ? "" : rest,
+		parsed.username,
+		parsed.password,
+		...parsed.searchParams.values(),
+		...[...parsed.searchParams.values()].map(encodeURIComponent),
+	].filter((part) => part.length >= 4);
+}
+
+/** The text with the secrets removed, raw or JSON-escaped once or twice; longest first. */
+function masked(text: string, secrets: readonly string[]): string {
+	const forms = secrets.flatMap((secret) => {
+		const once = JSON.stringify(secret).slice(1, -1);
+		return [secret, once, JSON.stringify(once).slice(1, -1)];
+	});
+	return [...new Set(forms)]
+		.sort((a, b) => b.length - a.length)
+		.reduce((result, form) => result.replaceAll(form, "***"), text);
+}
+
+/** ContextForge's error detail, shortened. */
+function detailOf(text: string): string {
+	try {
+		const parsed: unknown = JSON.parse(text);
+		if (isRecord(parsed)) {
+			const detail = parsed.detail ?? parsed.message;
+			return (
+				typeof detail === "string" ? detail : JSON.stringify(detail)
+			).slice(0, 300);
+		}
+	} catch {
+		// Not JSON: the raw text below is the detail.
+	}
+	return text.slice(0, 300);
+}

package/src/connectors/messages.ts

@@ -0,0 +1,119 @@
+/** The text the connectors plugin shows the owner on Discord, and the refusals the registry raises. */
+export interface ConnectorMessages {
+	nameRule: string;
+	urlRule: string;
+	purposeRequired: string;
+	purposeEmpty: string;
+	nameTaken(name: string): string;
+	noTools: string;
+	toolsTooLong(max: number, names: readonly string[]): string;
+	unknownConnector(name: string): string;
+
+	groupDescription: string;
+	addDescription: string;
+	listDescription: string;
+	describeDescription: string;
+	removeDescription: string;
+	nameOption: string;
+	newPurposeOption: string;
+
+	modalTitle: string;
+	nameLabel: string;
+	nameHelp: string;
+	urlLabel: string;
+	urlHelp: string;
+	purposeLabel: string;
+	purposeHelp: string;
+	headerLabel: string;
+	headerHelp: string;
+	tokenLabel: string;
+	tokenHelp: string;
+
+	headerNeedsToken: string;
+	headerRule: string;
+	urlUnreadable: string;
+
+	/** The tool line of a connector: how many it has, the first few, and how many are left out of the list. */
+	toolCount(total: number, listed: string, hidden: number): string;
+	toolsUnreadable: string;
+	listTitle: string;
+	listEmpty(root: string): string;
+	listFooter(root: string): string;
+	purposeUpdatedTitle: string;
+	purposeUpdatedFooter: string;
+	removedTitle: string;
+	removed(name: string): string;
+	addedTitle: string;
+	addedFooter: string;
+	skippedTools(names: string): string;
+}
+
+export const CONNECTOR_MESSAGES: ConnectorMessages = {
+	nameRule:
+		"Use lowercase letters, digits and `-`, start with a letter, and keep it to 12 characters.",
+	urlRule: "The URL must start with `https://` or `http://`.",
+	purposeRequired:
+		"Describe what this connector is for; the agent uses it to decide when to call it.",
+	purposeEmpty: "The purpose cannot be empty.",
+	nameTaken: (name) => `The name \`${name}\` is already taken. Pick another.`,
+	noTools: "This MCP server offers no tools.",
+	toolsTooLong: (max, names) =>
+		`Every tool name is longer than ${max} characters, which the model cannot use: ${names.join(", ")}`,
+	unknownConnector: (name) => `There is no connector named \`${name}\`.`,
+
+	groupDescription: "External MCP connectors the agent can use",
+	addDescription: "Add an MCP connector that connects with a token",
+	listDescription: "List every connector and its tools",
+	describeDescription:
+		"Change a connector's purpose, which the agent uses to decide when to call it",
+	removeDescription: "Delete a connector and its token",
+	nameOption: "Connector",
+	newPurposeOption: "The new purpose",
+
+	modalTitle: "Add an MCP connector",
+	nameLabel: "Name",
+	nameHelp:
+		"Lowercase letters, digits and -, up to 12; it becomes the prefix of its tool names",
+	urlLabel: "MCP URL",
+	urlHelp:
+		"A Streamable HTTP endpoint; one ending in /sse uses SSE. A credential may be part of the URL",
+	purposeLabel: "Purpose",
+	purposeHelp: "The agent decides from this text when to use the connector",
+	headerLabel: "Header name (optional)",
+	headerHelp: "Leave empty to send Authorization: Bearer <token>",
+	tokenLabel: "Token (optional)",
+	tokenHelp:
+		"Handed to ContextForge to store encrypted; leave empty if the credential is in the URL",
+
+	headerNeedsToken: "A header name needs a token with it.",
+	headerRule: "A header name may use letters, digits and `-` only.",
+	urlUnreadable: "(the URL cannot be parsed)",
+
+	toolCount: (total, listed, hidden) =>
+		`-# ${total} tools: ${listed}${hidden > 0 ? ` and ${hidden} more` : ""}`,
+	toolsUnreadable:
+		"-# The tools cannot be read, so the agent will not use it for now; see the log for the reason.",
+	listTitle: "MCP connectors",
+	listEmpty: (root) =>
+		`No connectors yet. Add one with \`/${root} connector add\`.`,
+	listFooter: (root) =>
+		`\`/${root} connector add\` adds one; \`describe\` changes its purpose; \`remove\` deletes the connector and its token.`,
+	purposeUpdatedTitle: "Purpose updated",
+	purposeUpdatedFooter:
+		"From the next message on, the agent follows the new purpose.",
+	removedTitle: "Connector removed",
+	removed: (name) =>
+		`**${name}** and its token are deleted; from the next message on, the agent no longer uses it.`,
+	addedTitle: "Connector added",
+	addedFooter:
+		"From the next message on, questions that need it go to this connector's tools.",
+	skippedTools: (names) =>
+		`**Skipped tools**  Their names are too long for the model: ${names}`,
+};
+
+/** The English text with the host's own wording laid over it. */
+export function connectorMessages(
+	overrides: Partial<ConnectorMessages> = {},
+): ConnectorMessages {
+	return { ...CONNECTOR_MESSAGES, ...overrides };
+}

package/src/index.ts

@@ -0,0 +1,23 @@
+// The package's one entry: two plugins, their options, and the service the connectors plugin provides.
+
+export type {
+	Connector,
+	ConnectorProfileSource,
+	NewConnector,
+} from "./connectors/connector-registry.ts";
+export type {
+	Connectors,
+	ContextForgeOptions,
+	McpConnectorsOptions,
+} from "./connectors/connectors-plugin.ts";
+export { CONNECTORS, mcpConnectors } from "./connectors/connectors-plugin.ts";
+export type { UpstreamAuth } from "./connectors/contextforge.ts";
+export type { ConnectorMessages } from "./connectors/messages.ts";
+export type { RemoteMcpMessages } from "./remote-mcp/messages.ts";
+export type { RemoteClaimHooks } from "./remote-mcp/remote-claim.ts";
+export type {
+	DefaultConversationOptions,
+	HostConversationOptions,
+	RemoteMcpOptions,
+} from "./remote-mcp/remote-mcp-plugin.ts";
+export { remoteMcp } from "./remote-mcp/remote-mcp-plugin.ts";