@mcp-ts/sdk 2.5.0 → 2.5.2

package/src/server/mcp/tool-policy-gateway.ts

@@ -4,12 +4,27 @@ import { sessions } from '../storage/index.js';
 import type { Session } from '../storage/types.js';
 import { assertToolAllowed, filterToolsByPolicy } from '../storage/tool-policy.js';
 
+/**
+ * Internal shape expected from the underlying MCP client.
+ * Extends `ToolClient` with the raw `fetchTools` / `listTools` / `callTool`
+ * methods so the gateway can fetch unfiltered results and apply policy on top.
+ */
 type RawToolClient = ToolClient & {
     fetchTools(): Promise<{ tools: Tool[] }>;
     listTools(): Promise<{ tools: Tool[] }>;
     callTool(name: string, args: Record<string, unknown>): Promise<CallToolResult>;
 };
 
+/**
+ * A thin policy-enforcement layer that wraps a raw `MCPClient`.
+ *
+ * Every public method on this class loads the current session's `toolPolicy`
+ * from the session store and uses it to filter or guard tool access before
+ * delegating to the underlying client.
+ *
+ * This keeps security logic in one place and prevents agents from calling
+ * tools that a user has explicitly blocked via the management UI.
+ */
 export class ToolPolicyGateway implements ToolClient {
     constructor(
         private readonly userId: string,
@@ -17,26 +32,52 @@ export class ToolPolicyGateway implements ToolClient {
         private readonly client: RawToolClient
     ) {}
 
+    /**
+     * Returns whether the underlying MCP client transport is currently connected.
+     */
     isConnected(): boolean {
         return this.client.isConnected();
     }
 
+    /**
+     * Returns the server ID from the underlying client, if available.
+     */
     getServerId(): string | undefined {
         return this.client.getServerId?.();
     }
 
+    /**
+     * Returns the human-readable server name from the underlying client, if available.
+     */
     getServerName(): string | undefined {
         return this.client.getServerName?.();
     }
 
+    /**
+     * Returns the server URL from the underlying client, if available.
+     */
     getServerUrl(): string | undefined {
         return this.client.getServerUrl?.();
     }
 
+    /**
+     * Returns the session ID — prefers the value reported by the underlying
+     * client, falling back to the one injected at construction time.
+     */
     getSessionId(): string {
         return this.client.getSessionId?.() ?? this.sessionId;
     }
 
+    /**
+     * Returns the **policy-filtered** list of tools that the current session
+     * is allowed to call.
+     *
+     * Internally calls `client.fetchTools()` (which is cache-backed) so no
+     * extra network round-trip is incurred when called after `fetchTools()`.
+     *
+     * @returns A `ListToolsResult` containing only the permitted tools.
+     * @throws {Error} When the session does not exist in the store.
+     */
     async listTools(): Promise<ListToolsResult> {
         const session = await this.getSession();
         const result = await this.client.fetchTools();
@@ -48,24 +89,65 @@ export class ToolPolicyGateway implements ToolClient {
         } as ListToolsResult;
     }
 
+    /**
+     * Returns the **complete, unfiltered** list of tools from the remote server,
+     * bypassing any tool-access policy.
+     *
+     * Used by the management UI to show all available tools (including blocked
+     * ones) so users can toggle individual tool access in the dialog.
+     *
+     * @returns The raw `ListToolsResult` from the remote server.
+     */
     async listAllTools(): Promise<ListToolsResult> {
         return await this.client.fetchTools() as ListToolsResult;
     }
 
+    /**
+     * Executes a tool call on the remote server after verifying that the tool
+     * is permitted by the current session's policy.
+     *
+     * @param name - The exact tool name to invoke.
+     * @param args - Key/value arguments to pass to the tool.
+     * @returns The tool's `CallToolResult`.
+     * @throws {Error} When the tool is blocked by the session's policy.
+     * @throws {Error} When the session does not exist in the store.
+     */
     async callTool(name: string, args: Record<string, unknown>): Promise<CallToolResult> {
         const session = await this.getSession();
         this.assertAllowed(session, name);
         return await this.client.callTool(name, args);
     }
 
+    /**
+     * Filters a raw tools array down to only those permitted by the session's
+     * `toolPolicy`.
+     *
+     * @param session - The session whose policy should be applied.
+     * @param tools   - The unfiltered list of tools from the remote server.
+     * @returns A subset of `tools` that the policy allows.
+     */
     filterTools(session: Session, tools: Tool[]): Tool[] {
         return filterToolsByPolicy(tools, session.toolPolicy, this.getPolicyServerId(session));
     }
 
+    /**
+     * Throws if `toolName` is blocked by the session's policy.
+     * Call this before proxying a `callTool` request to the remote server.
+     *
+     * @param session  - The session whose policy should be enforced.
+     * @param toolName - The tool being invoked.
+     * @throws {Error} When the tool is not permitted.
+     */
     assertAllowed(session: Session, toolName: string): void {
         assertToolAllowed(session.toolPolicy, toolName, this.getPolicyServerId(session));
     }
 
+    /**
+     * Loads the session from the store and throws if it does not exist.
+     *
+     * @returns The fully-hydrated `Session` record.
+     * @throws {Error} When the session cannot be found.
+     */
     private async getSession(): Promise<Session> {
         const session = await sessions.get(this.userId, this.sessionId);
         if (!session) {
@@ -74,11 +156,27 @@ export class ToolPolicyGateway implements ToolClient {
         return session;
     }
 
+    /**
+     * Resolves the server ID to use when evaluating tool policy.
+     * Prefers the value from the live client (most accurate) and falls back
+     * to the server ID stored on the session record.
+     */
     private getPolicyServerId(session: Session): string | undefined {
         return this.client.getServerId?.() ?? session.serverId;
     }
 }
 
+/**
+ * Factory function that creates a `ToolPolicyGateway` for a specific session.
+ *
+ * Prefer this over constructing `ToolPolicyGateway` directly — it keeps call
+ * sites concise and makes it easier to swap the implementation in tests.
+ *
+ * @param userId    - The owner of the session (used for storage lookups).
+ * @param sessionId - The session to enforce policy for.
+ * @param client    - The raw MCP client that the gateway wraps.
+ * @returns A fully configured `ToolPolicyGateway` instance.
+ */
 export function createToolPolicyGateway(
     userId: string,
     sessionId: string,
@@ -86,5 +184,3 @@ export function createToolPolicyGateway(
 ): ToolPolicyGateway {
     return new ToolPolicyGateway(userId, sessionId, client);
 }
-
-

package/src/server/storage/tool-policy.ts

@@ -1,16 +1,42 @@
 import type { Tool } from '@modelcontextprotocol/sdk/types.js';
 import type { ToolPolicy } from './types.js';
 
+/**
+ * Raw, unvalidated shape of a tool policy as it may arrive from an external
+ * source (HTTP request body, database read, etc.). All fields are typed as
+ * `unknown` so callers are forced to pass through one of the `normalize*`
+ * helpers before using the value as a `ToolPolicy`.
+ */
 export type ToolPolicyInput = {
     mode?: unknown;
     toolIds?: unknown;
     updatedAt?: unknown;
 } | null | undefined;
 
+/**
+ * Constructs the canonical tool ID string used throughout the policy system.
+ *
+ * Tool IDs combine the server ID and the tool name with a `::` separator so
+ * they are globally unique across all connected MCP servers:
+ * ```
+ * "mn0v3pfwwbxv::delete_mcp_server"
+ * ```
+ *
+ * @param serverId  - The short server identifier (e.g. `"mn0v3pfwwbxv"`).
+ * @param toolName  - The exact tool name as reported by the remote server.
+ * @returns A namespaced tool ID string.
+ */
 export function createToolId(serverId: string, toolName: string): string {
     return `${serverId}::${toolName}`;
 }
 
+/**
+ * Coerces an arbitrary value into a deduplicated array of trimmed, non-empty
+ * strings. Returns an empty array for any non-array or invalid input.
+ *
+ * @param input - Raw value to normalise (typically from user input or a DB read).
+ * @returns A clean `string[]` with duplicates and blank entries removed.
+ */
 function normalizeToolIds(input?: unknown): string[] {
     if (!Array.isArray(input)) return [];
 
@@ -22,6 +48,18 @@ function normalizeToolIds(input?: unknown): string[] {
     ));
 }
 
+/**
+ * Converts a raw, potentially untrusted `ToolPolicyInput` into a validated
+ * `ToolPolicy` object, or `undefined` if the input is absent / malformed.
+ *
+ * - Invalid `mode` values fall back to `"all"` (no restrictions).
+ * - Invalid `updatedAt` values fall back to `now`.
+ * - `"all"` mode always produces an empty `toolIds` array regardless of input.
+ *
+ * @param input - Raw policy data to normalise (from request body, DB, etc.).
+ * @param now   - Unix timestamp used as the fallback for `updatedAt`. Defaults to `Date.now()`.
+ * @returns A well-formed `ToolPolicy`, or `undefined` if `input` is absent.
+ */
 export function normalizeToolPolicy(input?: ToolPolicyInput, now = Date.now()): ToolPolicy | undefined {
     if (!input || typeof input !== 'object') {
         return undefined;
@@ -41,10 +79,39 @@ export function normalizeToolPolicy(input?: ToolPolicyInput, now = Date.now()):
     return { mode, toolIds: normalizeToolIds(input.toolIds), updatedAt };
 }
 
+/**
+ * Same as `normalizeToolPolicy` but guaranteed to return a `ToolPolicy`.
+ * Falls back to an unrestricted `{ mode: "all" }` policy when the input is
+ * absent or invalid.
+ *
+ * Use this variant when a policy is required (e.g. when persisting an update)
+ * rather than when reading an optional policy from the session store.
+ *
+ * @param input - Raw policy data to normalise.
+ * @param now   - Unix timestamp used as the fallback for `updatedAt`. Defaults to `Date.now()`.
+ * @returns A well-formed `ToolPolicy`, never `undefined`.
+ */
 export function normalizeToolPolicyForUpdate(input: ToolPolicyInput, now = Date.now()): ToolPolicy {
     return normalizeToolPolicy(input, now) ?? { mode: 'all', toolIds: [], updatedAt: now };
 }
 
+/**
+ * Determines whether a specific tool is permitted under the given policy.
+ *
+ * | Policy mode  | Allowed when…                                    |
+ * |--------------|--------------------------------------------------|
+ * | `"all"`      | Always (no restrictions).                        |
+ * | `"allowlist"`| The tool's ID is present in `policy.toolIds`.    |
+ * | `"denylist"` | The tool's ID is **not** in `policy.toolIds`.    |
+ *
+ * Returns `false` when the policy requires a `serverId` for ID construction
+ * but none is provided (fail-safe / deny by default).
+ *
+ * @param policy   - The active tool policy, or `undefined` for unrestricted access.
+ * @param toolName - The tool name to check (as reported by the remote server).
+ * @param serverId - The server that owns the tool (required for `allowlist`/`denylist`).
+ * @returns `true` if the tool is allowed, `false` otherwise.
+ */
 export function isToolAllowed(policy: ToolPolicy | undefined, toolName: string, serverId?: string): boolean {
     if (!policy || policy.mode === 'all') return true;
     if (!serverId) return false;
@@ -57,11 +124,33 @@ export function isToolAllowed(policy: ToolPolicy | undefined, toolName: string,
     return !policy.toolIds.includes(toolId);
 }
 
+/**
+ * Asserts that a tool call is permitted under the current session policy.
+ * Throws a descriptive error if the tool is blocked — call this inside
+ * `ToolPolicyGateway.callTool` before proxying the request to the remote server.
+ *
+ * @param policy   - The active tool policy, or `undefined` for unrestricted access.
+ * @param toolName - The tool being invoked.
+ * @param serverId - The server that owns the tool.
+ * @throws {Error} When the tool is not permitted by the policy.
+ */
 export function assertToolAllowed(policy: ToolPolicy | undefined, toolName: string, serverId?: string): void {
     if (isToolAllowed(policy, toolName, serverId)) return;
     throw new Error(`Tool "${toolName}" is not allowed for this MCP session`);
 }
 
+/**
+ * Returns the subset of `tools` that are permitted under the given policy.
+ *
+ * When no policy is set (or mode is `"all"`), the original array is returned
+ * unchanged (no copy is made). Otherwise each tool is tested with
+ * `isToolAllowed` and only the passing tools are included.
+ *
+ * @param tools    - The full, unfiltered list of tools from the remote server.
+ * @param policy   - The active tool policy, or `undefined` for unrestricted access.
+ * @param serverId - The server that owns the tools (required for `allowlist`/`denylist`).
+ * @returns A filtered array containing only the permitted tools.
+ */
 export function filterToolsByPolicy<T extends Pick<Tool, 'name'>>(
     tools: T[],
     policy: ToolPolicy | undefined,
@@ -71,6 +160,19 @@ export function filterToolsByPolicy<T extends Pick<Tool, 'name'>>(
     return tools.filter((tool) => isToolAllowed(policy, tool.name, serverId));
 }
 
+/**
+ * Validates that every tool ID referenced in a policy actually exists on the
+ * connected MCP server. Throws if any ID is unknown.
+ *
+ * This prevents silent misconfigurations where a user accidentally saves a
+ * policy referencing a tool that no longer exists (e.g. after a server update).
+ *
+ * @param policy   - The policy to validate (skipped for `"all"` mode).
+ * @param tools    - The authoritative list of tools from the remote server.
+ * @param serverId - Required to construct tool IDs for comparison.
+ * @throws {Error} When `serverId` is missing and the policy is not `"all"`.
+ * @throws {Error} When the policy contains tool IDs not present in `tools`.
+ */
 export function validateToolPolicyAgainstTools(
     policy: ToolPolicy,
     tools: Array<Pick<Tool, 'name'>>,

package/src/shared/events.ts

@@ -98,6 +98,7 @@ export type McpConnectionEvent =
     serverId: string;
     toolCount: number;
     tools: any[];
+    allTools?: any[];
     timestamp: number;
   }
   | {

package/src/shared/types.ts

@@ -182,6 +182,7 @@ export interface ToolPolicy {
 export type McpRpcMethod =
   | 'connect'
   | 'disconnect'
+  | 'reconnect'
   | 'listTools'
   | 'callTool'
   | 'listSessions'
@@ -223,6 +224,8 @@ export interface DisconnectParams {
   sessionId: string;
 }
 
+export type ReconnectParams = ConnectParams;
+
 export interface SessionParams {
   sessionId: string;
 }
@@ -264,6 +267,7 @@ export interface GetToolPolicyParams {
 export type McpRpcParams =
   | ConnectParams
   | DisconnectParams
+  | ReconnectParams
   | SessionParams
   | CallToolParams
   | GetPromptParams