pi-roundtable-mcp 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -5,6 +5,24 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-10-01
+
+### Added
+
+- `Connectors.resolve(serverName)` reads a virtual server by name, and `Connectors.admin` (`gateways()`, `servers()`) shows what ContextForge holds, for a host that manages some servers itself or shows their state.
+- The `REMOTE_MCP` service of `remoteMcp`: the owner's bundles and grants, read only, and `describeGrant(client, grant)`, so a host can show them in its own status view.
+- The types `GatewayState`, `ChannelBundle`, `ChannelGrant`, and `RemoteMcpService`.
+
+## [0.2.0] - 2026-10-01
+
+### Added
+
+- `remoteMcp({ toolNames })`: the names of the two tools at `/mcp/personal`, for agents that are already set up with other names. The default descriptions name each other with the chosen names. A name that is not letters, digits, `_` or `-` (up to 64), or two equal names, is refused when the plugin is created.
+
+### Changed
+
+- `RemoteMcpMessages.dispatchDescription` and `resultDescription` are now functions that receive the tool names, so a description can refer to the other tool by its real name. A host that set either as a string gives `() => "..."` instead.
+
 ## [0.1.0] - 2026-10-01
 
 First release: two plugins for pi-roundtable 0.4, extracted from a private host.

package/README.md

@@ -90,6 +90,8 @@ It provides the `CONNECTORS` service (`Connectors`):
 | `servers()` | The virtual servers (name, URL, tool names) of the connectors that could be read |
 | `profileSources()` | One `{ name, description, serverName }` per connector, the shape a host builds a per-agent MCP profile from |
 | `token` | The bearer token that the virtual servers' URLs expect; one per process, valid for a year |
+| `resolve(serverName)` | Reads one virtual server's URL and tools by name, for servers the host manages itself rather than as connectors |
+| `admin` | `gateways()` and `servers()`: what ContextForge holds, upstream gateways with their state and every virtual server with its tool names, for a host's status view |
 
 The plugin does not decide which agent uses which connector.
 The host reads the service, builds its own profiles, and compares `version` with the one it built at.
@@ -153,7 +155,8 @@ The owner manages connectors on Discord with `/<root> connector`, where `<root>`
 | `publicUrl` | `string` | required | The HTTPS address that reaches the host's `public` listener. Granted-channel URLs are built on its origin |
 | `persona` | `string` | a short neutral prompt | The system prompt of the default `remote` conversations |
 | `answer`, `claim` | see [below](#when-the-host-runs-the-conversations-itself) | the core's runtime | Give both, or neither |
-| `messages` | `Partial<RemoteMcpMessages>` | English | The relay note, the tool descriptions, and the Discord text, in your wording |
+| `messages` | `Partial<RemoteMcpMessages>` | English | The relay note, the tool descriptions, and the Discord text, in your wording. `dispatchDescription` and `resultDescription` are functions that receive the tool names |
+| `toolNames` | `{ dispatch?: string; result?: string }` | `agent_dispatch`, `agent_result` | The names of the two tools at `/mcp/personal`, for agents that are already set up with other names. The default descriptions follow them |
 
 The plugin serves two endpoints on the host's `public` listener:
 
@@ -176,6 +179,13 @@ The owner grants channels on Discord with `/<root> mcp`:
 | `describe` | Changes the channel name and purpose that the agent sees (Discord's own name and topic stay) |
 | `token` | Replaces a bundle's MCP URL; the old one stops working at once and the channel settings stay |
 
+The plugin provides the `REMOTE_MCP` service (`RemoteMcpService`) for a host that shows the owner what outside agents may reach:
+
+| Member | What it is |
+| --- | --- |
+| `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 |
+
 #### 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.

package/package.json

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

package/src/connectors/connectors-plugin.ts

@@ -54,6 +54,10 @@ export interface Connectors {
 	profileSources(): ConnectorProfileSource[];
 	/** The bearer token that ContextForge's virtual server URLs expect; one per process. */
 	readonly token: string;
+	/** Reads a virtual server's endpoint and tools by name, for the servers a host manages itself. */
+	resolve(serverName: string): Promise<VirtualServer>;
+	/** What ContextForge holds, upstream gateways and virtual servers, for a host's status view. */
+	readonly admin: Pick<ContextForgeAdmin, "gateways" | "servers">;
 }
 
 export const CONNECTORS = serviceKey<Connectors>(
@@ -89,9 +93,11 @@ 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 registry = await ConnectorRegistry.attach(database(), {
-				admin: new ContextForgeAdmin(url, token),
-				resolve: (name) => resolveVirtualServer(url, token, name),
+				admin,
+				resolve,
 				logger,
 				serverPrefix: options.serverPrefix ?? DEFAULT_SERVER_PREFIX,
 				maxToolName: options.maxToolName ?? DEFAULT_MAX_TOOL_NAME,
@@ -107,6 +113,11 @@ export function mcpConnectors(options: McpConnectorsOptions): RoundtablePlugin {
 				servers: () => registry.servers(),
 				profileSources: () => registry.profileSources(),
 				token,
+				resolve,
+				admin: {
+					gateways: () => admin.gateways(),
+					servers: () => admin.servers(),
+				},
 			});
 			return {};
 		},

package/src/index.ts

@@ -11,9 +11,16 @@ export type {
 	McpConnectorsOptions,
 } from "./connectors/connectors-plugin.ts";
 export { CONNECTORS, mcpConnectors } from "./connectors/connectors-plugin.ts";
-export type { UpstreamAuth } from "./connectors/contextforge.ts";
+export type { GatewayState, UpstreamAuth } from "./connectors/contextforge.ts";
 export type { ConnectorMessages } from "./connectors/messages.ts";
-export type { RemoteMcpMessages } from "./remote-mcp/messages.ts";
+export type {
+	ChannelBundle,
+	ChannelGrant,
+} from "./remote-mcp/channel-grants.ts";
+export type {
+	RemoteMcpMessages,
+	RemoteToolNames,
+} from "./remote-mcp/messages.ts";
 export type { RemoteClaimHooks } from "./remote-mcp/remote-claim.ts";
 export type {
 	DefaultConversationOptions,
@@ -21,3 +28,5 @@ export type {
 	RemoteMcpOptions,
 } from "./remote-mcp/remote-mcp-plugin.ts";
 export { remoteMcp } from "./remote-mcp/remote-mcp-plugin.ts";
+export type { RemoteMcpService } from "./remote-mcp/remote-mcp-service.ts";
+export { REMOTE_MCP } from "./remote-mcp/remote-mcp-service.ts";

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

@@ -23,14 +23,17 @@ import {
 	hashChannelToken,
 } from "./channel-grants.ts";
 import { runGrantedTool } from "./channel-tools.ts";
-import { REMOTE_MCP_MESSAGES, type RemoteMcpMessages } from "./messages.ts";
+import {
+	DEFAULT_TOOL_NAMES,
+	REMOTE_MCP_MESSAGES,
+	type RemoteMcpMessages,
+	type RemoteToolNames,
+} from "./messages.ts";
 import { type RemoteAgent, RemoteAgentError } from "./remote-agent.ts";
 
 /** Requests may carry uploads; anything larger is refused before it is parsed. */
 const MAX_BODY_BYTES = 12 * 1024 * 1024;
 
-export const DISPATCH_TOOL = "agent_dispatch";
-export const RESULT_TOOL = "agent_result";
 const LIST_CHANNELS_TOOL = "discord_list_authorized_channels";
 
 export interface McpGatewayOptions {
@@ -42,6 +45,8 @@ export interface McpGatewayOptions {
 	executor(): ChannelExecutor | undefined;
 	logger: Logger;
 	messages?: RemoteMcpMessages;
+	/** The names of the dispatch and result tools; `agent_dispatch` and `agent_result` by default. */
+	toolNames?: RemoteToolNames;
 }
 
 interface ToolSpec {
@@ -73,11 +78,13 @@ const ResultInput = Type.Object(
 export class McpGateway {
 	readonly #options: McpGatewayOptions;
 	readonly #text: RemoteMcpMessages;
+	readonly #tools: RemoteToolNames;
 	readonly #dispatchInput: TSchema;
 
 	constructor(options: McpGatewayOptions) {
 		this.#options = options;
 		this.#text = options.messages ?? REMOTE_MCP_MESSAGES;
+		this.#tools = options.toolNames ?? DEFAULT_TOOL_NAMES;
 		this.#dispatchInput = Type.Object(
 			{
 				message: Type.String({ minLength: 1 }),
@@ -172,8 +179,8 @@ export class McpGateway {
 		return [
 			{
 				tool: {
-					name: DISPATCH_TOOL,
-					description: this.#text.dispatchDescription,
+					name: this.#tools.dispatch,
+					description: this.#text.dispatchDescription(this.#tools),
 					inputSchema: jsonSchema(this.#dispatchInput),
 				},
 				call: async (args) => {
@@ -187,8 +194,8 @@ export class McpGateway {
 			},
 			{
 				tool: {
-					name: RESULT_TOOL,
-					description: this.#text.resultDescription,
+					name: this.#tools.result,
+					description: this.#text.resultDescription(this.#tools),
 					inputSchema: jsonSchema(ResultInput),
 					annotations: { readOnlyHint: true, idempotentHint: true },
 				},

package/src/remote-mcp/messages.ts

@@ -1,3 +1,14 @@
+/** The names of the two tools `/mcp/personal` offers. */
+export interface RemoteToolNames {
+	dispatch: string;
+	result: string;
+}
+
+export const DEFAULT_TOOL_NAMES: RemoteToolNames = {
+	dispatch: "agent_dispatch",
+	result: "agent_result",
+};
+
 /**
  * The text of the remote MCP plugin: what outside agents read in tool descriptions and errors,
  * and what the owner reads in the Discord commands.
@@ -10,8 +21,10 @@ export interface RemoteMcpMessages {
 	/** Sent for a granted tool call that failed in a way the agent must not retry. */
 	operationUnfinished: string;
 
-	dispatchDescription: string;
-	resultDescription: string;
+	/** The description of the dispatch tool; `tools` holds the names the host chose. */
+	dispatchDescription(tools: RemoteToolNames): string;
+	/** The description of the result tool. */
+	resultDescription(tools: RemoteToolNames): string;
 	sessionIdDescription: string;
 	listChannelsDescription: string;
 	/** Appended to every granted channel tool's description. */
@@ -87,12 +100,12 @@ export const REMOTE_MCP_MESSAGES: RemoteMcpMessages = {
 	operationUnfinished:
 		"The operation did not complete. Check the audit log of the grants on Discord; do not retry automatically.",
 
-	dispatchDescription:
+	dispatchDescription: (tools) =>
 		"Start or continue a conversation turn with the owner's personal agent, on the owner's behalf. " +
-		"Returns { runId, sessionId } at once without waiting for the agent to finish; poll agent_result with the runId. " +
+		`Returns { runId, sessionId } at once without waiting for the agent to finish; poll ${tools.result} with the runId. ` +
 		"Omit sessionId to start a new conversation; pass a returned sessionId to continue it.",
-	resultDescription:
-		"Poll a run started by agent_dispatch. Returns { status: 'working' | 'completed' | 'failed', text?, error? }.",
+	resultDescription: (tools) =>
+		`Poll a run started by ${tools.dispatch}. Returns { status: 'working' | 'completed' | 'failed', text?, error? }.`,
 	sessionIdDescription:
 		"A sessionId returned earlier; omit it to start a new conversation",
 	listChannelsDescription:

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

@@ -18,9 +18,15 @@ import {
 } from "./default-conversation.ts";
 import { McpGateway } from "./mcp-gateway.ts";
 import { mcpGrantCommands } from "./mcp-grant-commands.ts";
-import { type RemoteMcpMessages, remoteMcpMessages } from "./messages.ts";
+import {
+	DEFAULT_TOOL_NAMES,
+	type RemoteMcpMessages,
+	type RemoteToolNames,
+	remoteMcpMessages,
+} from "./messages.ts";
 import { RemoteAgent } from "./remote-agent.ts";
 import { type RemoteClaimHooks, remoteClaim } from "./remote-claim.ts";
+import { REMOTE_MCP, remoteMcpService } from "./remote-mcp-service.ts";
 import { RemoteSessionStore } from "./remote-session-store.ts";
 import { RemoteSessionSweeper } from "./session-sweeper.ts";
 
@@ -37,6 +43,11 @@ interface RemoteMcpBaseOptions {
 	publicUrl: string;
 	/** The Discord text, the relay note, and the tool descriptions in your wording; English by default. */
 	messages?: Partial<RemoteMcpMessages>;
+	/**
+	 * The names of the two tools at `/mcp/personal`, for agents already set up with other names;
+	 * `agent_dispatch` and `agent_result` by default. The default descriptions follow the names.
+	 */
+	toolNames?: Partial<RemoteToolNames>;
 }
 
 /** Remote turns run on the core's runtime: nothing more to give. */
@@ -63,6 +74,21 @@ export interface HostConversationOptions {
 export type RemoteMcpOptions = RemoteMcpBaseOptions &
 	(DefaultConversationOptions | HostConversationOptions);
 
+const TOOL_NAME = /^[A-Za-z0-9_-]{1,64}$/;
+
+/** The tool names with the host's overrides laid over the defaults; refuses names a client cannot use. */
+function toolNamesOf(options: RemoteMcpOptions): RemoteToolNames {
+	const names = { ...DEFAULT_TOOL_NAMES, ...options.toolNames };
+	for (const name of Object.values(names))
+		if (!TOOL_NAME.test(name))
+			throw new ConfigError(
+				`remote-mcp: toolNames: "${name}" is not a tool name (letters, digits, _ and -, up to 64)`,
+			);
+	if (names.dispatch === names.result)
+		throw new ConfigError("remote-mcp: toolNames: the two names must differ");
+	return names;
+}
+
 function checkOptions(options: RemoteMcpOptions): void {
 	if (!options.dispatchToken)
 		throw new ConfigError("remote-mcp: dispatchToken is empty");
@@ -79,13 +105,16 @@ function checkOptions(options: RemoteMcpOptions): void {
  * An MCP server over HTTP for outside agents: `/mcp/personal` relays turns to the owner's agent
  * and returns the result when polled, and `/mcp/discord/<token>` offers the Discord channel
  * tools granted to one bundle. Grants are approved on Discord with `/<root> mcp`.
+ * Provides `REMOTE_MCP`.
  */
 export function remoteMcp(options: RemoteMcpOptions): RoundtablePlugin {
 	checkOptions(options);
 	const text = remoteMcpMessages(options.messages);
+	const toolNames = toolNamesOf(options);
 	return definePlugin({
 		name: "remote-mcp",
 		requires: [DISCORD],
+		provides: [REMOTE_MCP],
 		migrations: [ChannelGrantStore.migration, RemoteSessionStore.migration],
 		setup: async (context) => {
 			const { services, logger, conversations, database } = context;
@@ -105,6 +134,7 @@ export function remoteMcp(options: RemoteMcpOptions): RoundtablePlugin {
 				executor: () => discord.connection.channelExecutor(),
 				logger,
 				messages: text,
+				toolNames,
 			});
 			const sweeper = new RemoteSessionSweeper({
 				sessions,
@@ -115,6 +145,7 @@ export function remoteMcp(options: RemoteMcpOptions): RoundtablePlugin {
 			discord.commands.add(
 				mcpGrantCommands(discord.guard, grants, options.publicUrl, text),
 			);
+			services.provide(REMOTE_MCP, remoteMcpService(grants, text));
 			return {
 				services: [
 					{

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

@@ -0,0 +1,31 @@
+import type { Client } from "discord.js";
+import { serviceKey } from "pi-roundtable";
+import type { ChannelGrant, ChannelGrantStore } from "./channel-grants.ts";
+import { describeGrant } from "./mcp-grant-panels.ts";
+import type { RemoteMcpMessages } from "./messages.ts";
+
+/** What a host reads to show the owner which channels outside agents may use. */
+export interface RemoteMcpService {
+	/** The owner's bundles and their channel grants, read only. */
+	grants: Pick<ChannelGrantStore, "bundles" | "grants">;
+	/** One grant as lines of text: the agent's name for the channel, where it is, its purpose, and the allowed operations. */
+	describeGrant(client: Client, grant: ChannelGrant): Promise<string>;
+}
+
+export const REMOTE_MCP = serviceKey<RemoteMcpService>(
+	"pi-roundtable-mcp.remote-mcp",
+);
+
+/** The service over the plugin's grant store and its wording. */
+export function remoteMcpService(
+	grants: ChannelGrantStore,
+	text: RemoteMcpMessages,
+): RemoteMcpService {
+	return {
+		grants: {
+			bundles: () => grants.bundles(),
+			grants: (...args) => grants.grants(...args),
+		},
+		describeGrant: (client, grant) => describeGrant(client, grant, text),
+	};
+}