pi-roundtable-mcp 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -5,6 +5,20 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-10-01
+
+### Added
+
+- `ChannelGrantStore` is exported, with its `migration`, `attach(sql)`, `ensureBundle`, `save` and the rest, for host-side imports and tools. The plugin still owns the tables.
+- `ConnectorMessages`: the ContextForge errors are messages now (`upstreamUrlUnreadable`, `contextForgeNoGatewayId`, `contextForgeNoServerId`, `contextForgeRefused`, `contextForgeNotJson`, `virtualServerRequestFailed`, `virtualServerMissing`, `virtualServerNoTools`), and so are the description of a new connector's virtual server (`serverDescription`) and the separator after a connector's name in the list (`labelSeparator`). The values they receive are masked as before.
+- `RemoteMcpMessages`: the human part of a granted tool's error (`operationFailed`, `outcomeUnrecorded`, and `codeDetail`, which joins it to the fixed code), the label and list separators of the grants list (`labelSeparator`, `listSeparator`), and the wording of an audit entry's status (`auditStatus`).
+- `RemoteMcpMessages.describeAgentNameOption` and `revokeNotInBundle`: the `name` option of `describe` and the refusal of `revoke` have their own wording. They default to the text of `agentNameOption` and `notInBundle`.
+
+### Changed
+
+- `agentNameOption` now words only the `name` option of `authorize`, and `notInBundle` only what `describe` says when the channel is not in the bundle. The English defaults are unchanged, so a host that overrides `messages` keeps working; it sets the new keys where it wants a different wording.
+- `runGrantedTool` takes the messages as its last argument. It is internal and not exported from the package.
+
 ## [0.3.0] - 2026-10-01
 
 ### Added

package/README.md

@@ -186,6 +186,12 @@ The plugin provides the `REMOTE_MCP` service (`RemoteMcpService`) for a host tha
 | `grants` | `bundles()` and `grants(bundleId?)`, read only: every bundle, and the channel grants of one bundle or of all |
 | `describeGrant(client, grant)` | One grant as lines of text for a Discord message: the name the agent sees, where the channel is, its purpose, and the allowed operations, in the plugin's wording |
 
+#### `ChannelGrantStore`
+
+The package also exports the `ChannelGrantStore` class, for host-side imports and tools; the plugin owns the tables.
+`ChannelGrantStore.migration` creates them, `ChannelGrantStore.attach(sql)` opens the store over a migrated pool, and `ensureBundle`, `save` and the other methods read and write bundles and grants, so an offline script can move an existing set of grants into the database.
+The tables belong to the plugin: change them through the plugin on Discord, or through this class, not by hand.
+
 #### The default conversation
 
 Without `answer` and `claim`, a relayed turn runs on the core: `context.turns.run` of kind `remote`, for an owner-tier speaker, in the channel `mcp:<session>`, through the agent server's runtime.
@@ -252,9 +258,11 @@ The host's agents then reach a connector through the connector's virtual server
 
 pi-roundtable's message catalog is closed to plugins, so these plugins keep their text in English and take a `messages` option of their own: a partial object laid over the defaults.
 Entries that take values are functions.
-The types `ConnectorMessages` and `RemoteMcpMessages` are exported and list every key.
+The types `ConnectorMessages` and `RemoteMcpMessages` are exported and list every key, each with a comment that says where it is read.
+Every sentence a Discord user or an outside agent reads is a key, including the errors of the ContextForge client, the description of a connector's virtual server (`serverDescription`), the human part of a granted tool's error (`operationFailed`, `outcomeUnrecorded`, joined to the fixed error code by `codeDetail`), and the separators (`labelSeparator`, `listSeparator`).
+The machine error codes (`CHANNEL_NOT_AUTHORIZED`, `DISCORD_OPERATION_FAILED`, ...) stay fixed, since outside agents match on them.
+`contextForgeRefused` and `contextForgeNotJson` receive ContextForge's answer with the request's token and any credential in the upstream URL already masked, so a wording of your own cannot leak them.
 Operation labels (`read`, `send`, ...) come from pi-roundtable and follow the host's language.
-The errors of the ContextForge client (a refused request) are English only.
 
 ## Database
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-roundtable-mcp",
-	"version": "0.3.0",
+	"version": "0.4.0",
 	"description": "MCP connectors through ContextForge and a remote MCP endpoint for pi-roundtable",
 	"type": "module",
 	"license": "MIT",

package/src/connectors/connector-commands.ts

@@ -171,7 +171,7 @@ function section(connector: Connector, text: ConnectorMessages): string {
 		.map((t) => `\`${t}\``)
 		.join(" ");
 	return [
-		`**${connector.name}**  ${plain(displayUrl(connector.url, text.urlUnreadable))}`,
+		`**${connector.name}**${text.labelSeparator}${plain(displayUrl(connector.url, text.urlUnreadable))}`,
 		plain(connector.description),
 		connector.server
 			? text.toolCount(

package/src/connectors/connector-registry.ts

@@ -258,7 +258,7 @@ export class ConnectorRegistry {
 		const serverId = await this.#contextForge(() =>
 			admin.createServer(
 				this.serverName(name),
-				`Connector ${name}: ${input.description}`,
+				this.#text.serverDescription(name, input.description),
 				usable.map((tool) => tool.id),
 			),
 		);

package/src/connectors/connectors-plugin.ts

@@ -93,8 +93,9 @@ export function mcpConnectors(options: McpConnectorsOptions): RoundtablePlugin {
 		setup: async ({ database, services, logger }) => {
 			const { jwtSecret, user } = options.contextForge;
 			const token = contextForgeToken(jwtSecret, user, TOKEN_TTL_SECONDS);
-			const admin = new ContextForgeAdmin(url, token);
-			const resolve = (name: string) => resolveVirtualServer(url, token, name);
+			const admin = new ContextForgeAdmin(url, token, fetch, text);
+			const resolve = (name: string) =>
+				resolveVirtualServer(url, token, name, fetch, text);
 			const registry = await ConnectorRegistry.attach(database(), {
 				admin,
 				resolve,

package/src/connectors/contextforge.ts

@@ -1,6 +1,7 @@
 import { createHmac, randomUUID } from "node:crypto";
 import { ConfigError } from "pi-roundtable";
 import type { VirtualServer } from "pi-roundtable/kit";
+import { CONNECTOR_MESSAGES, type ConnectorMessages } from "./messages.ts";
 
 function base64url(value: string | Buffer): string {
 	return Buffer.from(value).toString("base64url");
@@ -50,6 +51,7 @@ async function getJson(
 	url: string,
 	token: string,
 	fetchImpl: typeof fetch,
+	text: ConnectorMessages,
 ): Promise<unknown> {
 	const response = await fetchImpl(url, {
 		headers: { authorization: `Bearer ${token}` },
@@ -57,7 +59,11 @@ async function getJson(
 	});
 	if (!response.ok) {
 		throw new ConfigError(
-			`ContextForge ${url} answered ${response.status}: ${(await response.text()).slice(0, 200)}`,
+			text.virtualServerRequestFailed(
+				url,
+				response.status,
+				(await response.text()).slice(0, 200),
+			),
 		);
 	}
 	return response.json();
@@ -69,22 +75,25 @@ export async function resolveVirtualServer(
 	token: string,
 	name: string,
 	fetchImpl: typeof fetch = fetch,
+	text: ConnectorMessages = CONNECTOR_MESSAGES,
 ): Promise<VirtualServer> {
 	const servers = await getJson(
 		`${baseUrl}/servers?include_pagination=false`,
 		token,
 		fetchImpl,
+		text,
 	);
 	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}`);
+		throw new ConfigError(text.virtualServerMissing(name));
 	}
 	const tools = await getJson(
 		`${baseUrl}/servers/${server.id}/tools?include_pagination=false`,
 		token,
 		fetchImpl,
+		text,
 	);
 	const names = Array.isArray(tools)
 		? tools.flatMap((tool) =>
@@ -92,7 +101,7 @@ export async function resolveVirtualServer(
 			)
 		: [];
 	if (names.length === 0)
-		throw new ConfigError(`virtual server ${name} serves no tools`);
+		throw new ConfigError(text.virtualServerNoTools(name));
 	return { name, url: `${baseUrl}/servers/${server.id}/mcp`, tools: names };
 }
 
@@ -143,11 +152,18 @@ export class ContextForgeAdmin {
 	readonly #baseUrl: string;
 	readonly #token: string;
 	readonly #fetch: typeof fetch;
+	readonly #text: ConnectorMessages;
 
-	constructor(baseUrl: string, token: string, fetchImpl: typeof fetch = fetch) {
+	constructor(
+		baseUrl: string,
+		token: string,
+		fetchImpl: typeof fetch = fetch,
+		text: ConnectorMessages = CONNECTOR_MESSAGES,
+	) {
 		this.#baseUrl = baseUrl;
 		this.#token = token;
 		this.#fetch = fetchImpl;
+		this.#text = text;
 	}
 
 	/** Registers an upstream server; ContextForge connects and lists its tools before answering. */
@@ -161,7 +177,7 @@ export class ContextForgeAdmin {
 		const upstream = URL.parse(gateway.url);
 		if (!upstream)
 			throw new ContextForgeError(
-				`Cannot parse the upstream URL: ${gateway.url}`,
+				this.#text.upstreamUrlUnreadable(gateway.url),
 			);
 		const body = {
 			name: gateway.name,
@@ -179,9 +195,7 @@ export class ContextForgeAdmin {
 			secrets,
 		);
 		if (!isRecord(created) || typeof created.id !== "string")
-			throw new ContextForgeError(
-				"ContextForge did not return the gateway ID.",
-			);
+			throw new ContextForgeError(this.#text.contextForgeNoGatewayId);
 		return {
 			id: created.id,
 			slug: typeof created.slug === "string" ? created.slug : gateway.name,
@@ -276,9 +290,7 @@ export class ContextForgeAdmin {
 			server: { name, description, associated_tools: toolIds },
 		});
 		if (!isRecord(created) || typeof created.id !== "string")
-			throw new ContextForgeError(
-				"ContextForge did not return the virtual server ID.",
-			);
+			throw new ContextForgeError(this.#text.contextForgeNoServerId);
 		return created.id;
 	}
 
@@ -310,14 +322,17 @@ export class ContextForgeAdmin {
 		const text = await response.text();
 		if (!response.ok)
 			throw new ContextForgeError(
-				`ContextForge answered ${response.status}: ${detailOf(masked(text, secrets))}`,
+				this.#text.contextForgeRefused(
+					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))}`,
+				this.#text.contextForgeNotJson(detailOf(masked(text, secrets))),
 			);
 		}
 	}

package/src/connectors/messages.ts

@@ -46,6 +46,31 @@ export interface ConnectorMessages {
 	addedTitle: string;
 	addedFooter: string;
 	skippedTools(names: string): string;
+
+	/** Between a connector's name and its address in the list; the English default is two spaces. */
+	labelSeparator: string;
+	/** The description ContextForge shows on a new connector's virtual server. */
+	serverDescription(name: string, description: string): string;
+	/** Refuses an upstream URL that cannot be parsed; `url` is the address as the owner gave it. */
+	upstreamUrlUnreadable(url: string): string;
+	/** ContextForge accepted a new upstream server but returned no gateway ID. */
+	contextForgeNoGatewayId: string;
+	/** ContextForge accepted a new virtual server but returned no ID. */
+	contextForgeNoServerId: string;
+	/** ContextForge refused an admin request; `detail` is its reason, with credentials masked. */
+	contextForgeRefused(status: number, detail: string): string;
+	/** ContextForge answered an admin request with something other than JSON; `detail` is masked. */
+	contextForgeNotJson(detail: string): string;
+	/** Reading a virtual server's endpoint and tools failed with `status`; raised at startup. */
+	virtualServerRequestFailed(
+		url: string,
+		status: number,
+		detail: string,
+	): string;
+	/** ContextForge has no virtual server of this name; raised at startup. */
+	virtualServerMissing(name: string): string;
+	/** The virtual server exists but serves no tools; raised at startup. */
+	virtualServerNoTools(name: string): string;
 }
 
 export const CONNECTOR_MESSAGES: ConnectorMessages = {
@@ -109,6 +134,21 @@ export const CONNECTOR_MESSAGES: ConnectorMessages = {
 		"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}`,
+
+	labelSeparator: "  ",
+	serverDescription: (name, description) => `Connector ${name}: ${description}`,
+	upstreamUrlUnreadable: (url) => `Cannot parse the upstream URL: ${url}`,
+	contextForgeNoGatewayId: "ContextForge did not return the gateway ID.",
+	contextForgeNoServerId: "ContextForge did not return the virtual server ID.",
+	contextForgeRefused: (status, detail) =>
+		`ContextForge answered ${status}: ${detail}`,
+	contextForgeNotJson: (detail) =>
+		`ContextForge did not answer with JSON: ${detail}`,
+	virtualServerRequestFailed: (url, status, detail) =>
+		`ContextForge ${url} answered ${status}: ${detail}`,
+	virtualServerMissing: (name) =>
+		`ContextForge has no virtual server named ${name}`,
+	virtualServerNoTools: (name) => `virtual server ${name} serves no tools`,
 };
 
 /** The English text with the host's own wording laid over it. */

package/src/index.ts

@@ -17,6 +17,7 @@ export type {
 	ChannelBundle,
 	ChannelGrant,
 } from "./remote-mcp/channel-grants.ts";
+export { ChannelGrantStore } from "./remote-mcp/channel-grants.ts";
 export type {
 	RemoteMcpMessages,
 	RemoteToolNames,

package/src/remote-mcp/channel-tools.ts

@@ -4,6 +4,7 @@ import {
 	ChannelToolError,
 } from "pi-roundtable/discord";
 import type { ChannelBundle, ChannelGrantStore } from "./channel-grants.ts";
+import type { RemoteMcpMessages } from "./messages.ts";
 
 /**
  * Runs one tool call for a bundle. The grant and the bundle's token are read after Discord
@@ -15,6 +16,10 @@ export async function runGrantedTool(
 	args: Record<string, unknown>,
 	store: ChannelGrantStore,
 	executor: ChannelExecutor,
+	text: Pick<
+		RemoteMcpMessages,
+		"codeDetail" | "operationFailed" | "outcomeUnrecorded"
+	>,
 ): Promise<unknown> {
 	const spec = CHANNEL_TOOLS[tool];
 	const channelId = args.channelId;
@@ -39,14 +44,20 @@ export async function runGrantedTool(
 	} catch {
 		await store.finishCall(receipt, "failed");
 		throw new ChannelToolError(
-			`DISCORD_OPERATION_FAILED: audit entry ${receipt}`,
+			text.codeDetail(
+				"DISCORD_OPERATION_FAILED",
+				text.operationFailed(receipt),
+			),
 		);
 	}
 	try {
 		await store.finishCall(receipt, "succeeded");
 	} catch {
 		throw new ChannelToolError(
-			`DISCORD_OUTCOME_UNRECORDED: the operation may have completed, so do not retry automatically. Audit entry ${receipt}`,
+			text.codeDetail(
+				"DISCORD_OUTCOME_UNRECORDED",
+				text.outcomeUnrecorded(receipt),
+			),
 		);
 	}
 	return result;

package/src/remote-mcp/mcp-gateway.ts

@@ -243,6 +243,7 @@ export class McpGateway {
 							parseChannelTool(name, args),
 							grants,
 							executor(),
+							this.#text,
 						),
 					),
 			});

package/src/remote-mcp/mcp-grant-commands.ts

@@ -21,11 +21,9 @@ function mcpGroup(text: RemoteMcpMessages) {
 			.setMaxLength(80)
 			.setAutocomplete(true)
 			.setRequired(true);
-	const agentName = (option: SlashCommandStringOption) =>
-		option
-			.setName("name")
-			.setDescription(text.agentNameOption)
-			.setMaxLength(100);
+	const agentName =
+		(description: string) => (option: SlashCommandStringOption) =>
+			option.setName("name").setDescription(description).setMaxLength(100);
 	const purpose = (option: SlashCommandStringOption) =>
 		option
 			.setName("description")
@@ -42,7 +40,7 @@ function mcpGroup(text: RemoteMcpMessages) {
 					.setName("authorize")
 					.setDescription(text.authorizeDescription)
 					.addStringOption(bundle)
-					.addStringOption(agentName)
+					.addStringOption(agentName(text.agentNameOption))
 					.addStringOption(purpose),
 			)
 			.addSubcommand((sub) =>
@@ -60,7 +58,7 @@ function mcpGroup(text: RemoteMcpMessages) {
 					.setName("describe")
 					.setDescription(text.describeDescription)
 					.addStringOption(bundle)
-					.addStringOption(agentName)
+					.addStringOption(agentName(text.describeAgentNameOption))
 					.addStringOption(purpose)
 					.addStringOption(channelId),
 			)

package/src/remote-mcp/mcp-grant-flow.ts

@@ -114,7 +114,7 @@ export class McpGrantFlow {
 				sections: [
 					removed
 						? text.revoked(plain(bundle.name))
-						: text.notInBundle(plain(bundle.name)),
+						: text.revokeNotInBundle(plain(bundle.name)),
 				],
 			}),
 		);
@@ -285,7 +285,7 @@ export class McpGrantFlow {
 					text.granted(
 						plain(channel.name),
 						plain(bundle.name),
-						opLabels(pending.operations),
+						opLabels(pending.operations, text),
 					),
 					created ? text.urlSection(endpoint.url) : text.existingUrl,
 				],
@@ -318,7 +318,7 @@ export class McpGrantFlow {
 					`${text.recentAudit}\n${audit
 						.map(
 							(a) =>
-								`<t:${Math.floor(a.createdAt.getTime() / 1000)}:f> \`${a.tool}\` ${a.status}`,
+								`<t:${Math.floor(a.createdAt.getTime() / 1000)}:f> \`${a.tool}\` ${text.auditStatus(a.status)}`,
 						)
 						.join("\n")}`,
 				);

package/src/remote-mcp/mcp-grant-panels.ts

@@ -43,8 +43,8 @@ export interface Pending {
 }
 
 export const PENDING_MS = 5 * 60_000;
-export const opLabels = (ops: ChannelOperation[]) =>
-	ops.map(operationLabel).join(", ");
+export const opLabels = (ops: ChannelOperation[], text: RemoteMcpMessages) =>
+	ops.map(operationLabel).join(text.listSeparator);
 
 export function authorizePanel(
 	id: string,
@@ -52,7 +52,7 @@ export function authorizePanel(
 	source: "existing" | "defaults" | "chosen",
 	text: RemoteMcpMessages,
 ) {
-	const labels = opLabels(pending.operations);
+	const labels = opLabels(pending.operations, text);
 	const intro = pending.operations.length
 		? {
 				existing: text.keepExisting,
@@ -133,9 +133,9 @@ export async function describeGrant(
 		where += text.invisibleChannel;
 	}
 	return [
-		`- **${plain(grant.displayName)}**  ${where}`,
+		`- **${plain(grant.displayName)}**${text.labelSeparator}${where}`,
 		text.purposeLine(plain(grant.description) || text.notSet),
-		text.allowedLine(opLabels(grant.operations), grant.channelId),
+		text.allowedLine(opLabels(grant.operations, text), grant.channelId),
 	].join("\n");
 }
 

package/src/remote-mcp/messages.ts

@@ -20,6 +20,15 @@ export interface RemoteMcpMessages {
 	runFailed: string;
 	/** Sent for a granted tool call that failed in a way the agent must not retry. */
 	operationUnfinished: string;
+	/**
+	 * A granted tool's error as the outside agent reads it: the fixed machine `code` it matches
+	 * on, then the human `detail`. Keep the code in the text; the default joins them with `: `.
+	 */
+	codeDetail(code: string, detail: string): string;
+	/** The detail after `DISCORD_OPERATION_FAILED`: the call failed, and where to look it up. */
+	operationFailed(audit: string): string;
+	/** The detail after `DISCORD_OUTCOME_UNRECORDED`: the call may have completed but was not recorded. */
+	outcomeUnrecorded(audit: string): string;
 
 	/** The description of the dispatch tool; `tools` holds the names the host chose. */
 	dispatchDescription(tools: RemoteToolNames): string;
@@ -33,7 +42,10 @@ export interface RemoteMcpMessages {
 	groupDescription: string;
 	bundleOption: string;
 	authorizeDescription: string;
+	/** The `name` option of `authorize`. */
 	agentNameOption: string;
+	/** The `name` option of `describe`, which changes a name that already exists. */
+	describeAgentNameOption: string;
 	purposeOption: string;
 	grantsDescription: string;
 	revokeDescription: string;
@@ -48,7 +60,10 @@ export interface RemoteMcpMessages {
 	nameOrDescription: string;
 	describeTitle: string;
 	described: string;
+	/** Said by `describe` when the channel is not in the bundle. */
 	notInBundle(bundle: string): string;
+	/** Said by `revoke` when the channel was not in the bundle to begin with. */
+	revokeNotInBundle(bundle: string): string;
 	revokedTitle: string;
 	revoked(bundle: string): string;
 	expiredTitle: string;
@@ -91,6 +106,13 @@ export interface RemoteMcpMessages {
 	needManageChannels: string;
 	youLackPermission(operation: string): string;
 	botLacksPermission(operation: string): string;
+
+	/** Between a grant's name and where its channel is, in the grants list; two spaces by default. */
+	labelSeparator: string;
+	/** Between the operations of a grant; `, ` by default. */
+	listSeparator: string;
+	/** How an audit entry's status reads in the grants list; `started`, `succeeded` or `failed`. */
+	auditStatus(status: string): string;
 }
 
 export const REMOTE_MCP_MESSAGES: RemoteMcpMessages = {
@@ -99,6 +121,10 @@ export const REMOTE_MCP_MESSAGES: RemoteMcpMessages = {
 	runFailed: "This run did not complete. Try again later.",
 	operationUnfinished:
 		"The operation did not complete. Check the audit log of the grants on Discord; do not retry automatically.",
+	codeDetail: (code, detail) => `${code}: ${detail}`,
+	operationFailed: (audit) => `audit entry ${audit}`,
+	outcomeUnrecorded: (audit) =>
+		`the operation may have completed, so do not retry automatically. Audit entry ${audit}`,
 
 	dispatchDescription: (tools) =>
 		"Start or continue a conversation turn with the owner's personal agent, on the owner's behalf. " +
@@ -119,6 +145,8 @@ export const REMOTE_MCP_MESSAGES: RemoteMcpMessages = {
 		"Add this channel to a bundle and choose the allowed operations",
 	agentNameOption:
 		"The channel name the agent sees; Discord's name is unchanged",
+	describeAgentNameOption:
+		"The channel name the agent sees; Discord's name is unchanged",
 	purposeOption: "What this channel is for",
 	grantsDescription: "List every grant and this channel's audit log",
 	revokeDescription: "Remove a channel from a bundle",
@@ -138,6 +166,7 @@ export const REMOTE_MCP_MESSAGES: RemoteMcpMessages = {
 	described:
 		"Updated the name and purpose the agent sees; the name and topic on Discord are unchanged.",
 	notInBundle: (bundle) => `This channel is not in bundle **${bundle}**.`,
+	revokeNotInBundle: (bundle) => `This channel is not in bundle **${bundle}**.`,
 	revokedTitle: "Channel removed",
 	revoked: (bundle) =>
 		`Removed the channel from bundle **${bundle}**; its other channels and its URL keep working. Operations already sent are not undone.`,
@@ -198,6 +227,10 @@ export const REMOTE_MCP_MESSAGES: RemoteMcpMessages = {
 		`You lack the Discord permission behind "${operation}".`,
 	botLacksPermission: (operation) =>
 		`The bot lacks the Discord permission behind "${operation}"; grant it in the server settings first.`,
+
+	labelSeparator: "  ",
+	listSeparator: ", ",
+	auditStatus: (status) => status,
 };
 
 /** The English text with the host's own wording laid over it. */