@gtkx/mcp 1.4.0 → 1.6.0

package/src/app-router.ts

@@ -1,19 +1,18 @@
+import { type JSONRPCRequest, McpError, type Result } from "@modelcontextprotocol/sdk/types.js";
+import type { AppConnections, ConnectionEvent, ProtocolConnection, RequestParams } from "./transport.js";
 import {
     appNotFoundError,
+    CONNECTION_CLOSED_CODE,
     connectionWriteFailedError,
     invalidRequestError,
     methodNotFoundError,
     noAppConnectedError,
     type ProtocolError,
+    protocolErrorFrom,
+    REQUEST_TIMEOUT_CODE,
+    requestTimeoutError,
 } from "./protocol/errors.js";
-import { type AppInfo, RegisterParamsSchema, type Request, type Response } from "./protocol/schemas.js";
-import {
-    type AppConnections,
-    ConnectionClosedError,
-    type ConnectionEvent,
-    type ConnectionRequestEvent,
-    type ProtocolConnection,
-} from "./transport.js";
+import { type AppInfo, RegisterParamsSchema } from "./protocol/schemas.js";
 
 type AppRegisteredEvent = CustomEvent<AppInfo>;
 type AppUnregisteredEvent = CustomEvent<string>;
@@ -48,11 +47,7 @@ class AppRouter extends EventTarget {
         super();
         this.connections = connections;
         this.requestTimeout = options.requestTimeout ?? DEFAULT_REQUEST_TIMEOUT_MS;
-
-        this.connections.addEventListener("request", (event) => {
-            const { connection, request } = (event as ConnectionRequestEvent).detail;
-            this.handleRequest(connection, request);
-        });
+        this.connections.onRequest = (connection, request) => this.handleRequest(connection, request);
 
         this.connections.addEventListener("disconnection", (event) => {
             this.removeApp((event as ConnectionEvent).detail);
@@ -73,23 +68,25 @@ class AppRouter extends EventTarget {
         throw noAppConnectedError();
     }
 
-    private handleRequest(connection: ProtocolConnection, request: Request): void {
+    private handleRequest(connection: ProtocolConnection, request: JSONRPCRequest): Promise<Result> {
         if (request.method === "app.register") {
-            this.handleRegister(connection, request);
-        } else if (request.method === "app.unregister") {
-            this.handleUnregister(connection, request);
-        } else {
-            this.sendError(connection, request, methodNotFoundError(request.method));
+            return Promise.resolve(this.handleRegister(connection, request));
+        }
+
+        if (request.method === "app.unregister") {
+            this.removeApp(connection);
+
+            return Promise.resolve({ success: true });
         }
+
+        return Promise.reject(methodNotFoundError(request.method));
     }
 
-    private handleRegister(connection: ProtocolConnection, request: Request): void {
+    private handleRegister(connection: ProtocolConnection, request: JSONRPCRequest): Result {
         const parseResult = RegisterParamsSchema.safeParse(request.params);
 
         if (!parseResult.success) {
-            this.sendError(connection, request, invalidRequestError(parseResult.error.message));
-
-            return;
+            throw invalidRequestError(parseResult.error.message);
         }
 
         const params = parseResult.data;
@@ -102,29 +99,23 @@ class AppRouter extends EventTarget {
 
         this.apps.set(params.applicationId, { info: appInfo, connection });
         this.connectionToApp.set(connection.id, params.applicationId);
-        this.acknowledge(connection, request);
         this.dispatchEvent(appRegisteredEvent(appInfo));
-    }
 
-    private handleUnregister(connection: ProtocolConnection, request: Request): void {
-        this.removeApp(connection);
-        this.acknowledge(connection, request);
+        return { success: true };
     }
 
-    private acknowledge(connection: ProtocolConnection, request: Request): void {
-        const response: Response = {
-            id: request.id,
-            result: { success: true },
-        };
+    private toAppError(app: RegisteredApp, error: McpError): ProtocolError {
+        if (error.code === CONNECTION_CLOSED_CODE) {
+            this.removeApp(app.connection);
 
-        this.connections.send(connection.id, response);
-    }
+            return connectionWriteFailedError(app.info.applicationId);
+        }
 
-    private sendError(connection: ProtocolConnection, request: Request, error: ProtocolError): void {
-        this.connections.send(connection.id, {
-            id: request.id,
-            error: error.toErrorObject(),
-        });
+        if (error.code === REQUEST_TIMEOUT_CODE) {
+            return requestTimeoutError(this.requestTimeout);
+        }
+
+        return protocolErrorFrom(error);
     }
 
     private removeApp(connection: ProtocolConnection): void {
@@ -190,15 +181,14 @@ class AppRouter extends EventTarget {
         });
     }
 
-    async sendToApp<T>(applicationId: string | undefined, method: string, params?: unknown): Promise<T> {
+    async sendToApp<T>(applicationId: string | undefined, method: string, params?: RequestParams): Promise<T> {
         const app = this.resolveTargetApp(applicationId);
 
         try {
             return await app.connection.send<T>(method, params, this.requestTimeout);
         } catch (error) {
-            if (error instanceof ConnectionClosedError) {
-                this.removeApp(app.connection);
-                throw connectionWriteFailedError(app.info.applicationId);
+            if (error instanceof McpError) {
+                throw this.toAppError(app, error);
             }
 
             throw error;

package/src/connection-registry.ts

@@ -1,10 +1,10 @@
 import type { Socket } from "node:net";
-import type { Message } from "./protocol/schemas.js";
+import { methodNotFoundError } from "./protocol/errors.js";
 import {
     type AppConnections,
     connectionDisconnectionEvent,
     connectionErrorEvent,
-    connectionRequestEvent,
+    type ConnectionRequestHandler,
     ProtocolConnection,
 } from "./transport.js";
 
@@ -12,6 +12,8 @@ class ConnectionRegistry extends EventTarget implements AppConnections {
     private connections: Map<string, ProtocolConnection> = new Map();
     private sockets: Map<string, Socket> = new Map();
 
+    onRequest: ConnectionRequestHandler = (_connection, request) => Promise.reject(methodNotFoundError(request.method));
+
     register(socket: Socket): ProtocolConnection {
         const connection = ProtocolConnection.fromSocket(socket, {
             onClose: () => {
@@ -24,30 +26,12 @@ class ConnectionRegistry extends EventTarget implements AppConnections {
 
         this.connections.set(connection.id, connection);
         this.sockets.set(connection.id, socket);
-        connection.on("request", (request) => this.dispatchEvent(connectionRequestEvent(connection, request)));
-
-        connection.on("invalid", ({ id: badId, error }) => {
-            connection.write({ id: badId, error: error.toErrorObject() });
-        });
+        connection.fallbackRequestHandler = (request) => this.onRequest(connection, request);
 
         return connection;
     }
 
-    send(connectionId: string, message: Message): void {
-        const connection = this.connections.get(connectionId);
-
-        if (!connection) {
-            return;
-        }
-
-        connection.write(message);
-    }
-
-    dispose(reason: string): void {
-        for (const connection of this.connections.values()) {
-            connection.rejectPending(new Error(reason));
-        }
-
+    dispose(): void {
         for (const socket of this.sockets.values()) {
             socket.destroy();
         }

package/src/internal.ts

@@ -1,8 +1,7 @@
 export {
-    ErrorCode,
     invalidRequestError,
+    isConnectionClosedError,
     methodNotFoundError,
-    ProtocolError,
     propertyNotFoundError,
     widgetNotFoundError,
 } from "./protocol/errors.js";
@@ -11,7 +10,6 @@ export {
     DEFAULT_SUBTREE_DEPTH,
     MAX_SUBTREE_WIDGETS,
     type ParamsSchema,
-    type Request,
     type SerializedProperty,
     type SerializedWidget,
     type ServerInitiatedMethod,
@@ -19,3 +17,4 @@ export {
     ServerRequestParamsSchemas,
 } from "./protocol/schemas.js";
 export { ProtocolConnection } from "./transport.js";
+export type { JSONRPCRequest, Result } from "@modelcontextprotocol/sdk/types.js";

package/src/protocol/errors.ts

@@ -1,3 +1,5 @@
+import { McpError, ErrorCode as SdkErrorCode } from "@modelcontextprotocol/sdk/types.js";
+
 type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
 
 const ErrorCode = {
@@ -12,6 +14,9 @@ const ErrorCode = {
     PROPERTY_NOT_FOUND: 1008,
 } as const;
 
+const CONNECTION_CLOSED_CODE: number = SdkErrorCode.ConnectionClosed;
+const REQUEST_TIMEOUT_CODE: number = SdkErrorCode.RequestTimeout;
+
 function isErrorCode(code: number): code is ErrorCode {
     return (Object.values(ErrorCode) as number[]).includes(code);
 }
@@ -64,6 +69,17 @@ function methodNotFoundError(method: string): ProtocolError {
     return new ProtocolError(ErrorCode.METHOD_NOT_FOUND, `Method '${method}' not found`, { method });
 }
 
+function isConnectionClosedError(value: unknown): boolean {
+    return value instanceof McpError && value.code === CONNECTION_CLOSED_CODE;
+}
+
+function protocolErrorFrom(error: McpError): ProtocolError {
+    const prefix = `MCP error ${String(error.code)}: `;
+    const message = error.message.startsWith(prefix) ? error.message.slice(prefix.length) : error.message;
+
+    return new ProtocolError(isErrorCode(error.code) ? error.code : ErrorCode.INTERNAL_ERROR, message, error.data);
+}
+
 class ProtocolError extends Error {
     code: ErrorCode;
     data?: unknown;
@@ -74,19 +90,12 @@ class ProtocolError extends Error {
         this.data = data;
         this.name = "ProtocolError";
     }
-
-    toErrorObject(): { code: number; message: string; data?: unknown } {
-        return {
-            code: this.code,
-            message: this.message,
-            ...(this.data !== undefined && { data: this.data }),
-        };
-    }
 }
 
 export {
-    ErrorCode,
-    isErrorCode,
+    CONNECTION_CLOSED_CODE,
+    isConnectionClosedError,
+    REQUEST_TIMEOUT_CODE,
     noAppConnectedError,
     appNotFoundError,
     connectionWriteFailedError,
@@ -96,4 +105,5 @@ export {
     invalidRequestError,
     methodNotFoundError,
     ProtocolError,
+    protocolErrorFrom,
 };

package/src/protocol/schemas.ts

@@ -2,9 +2,6 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { z } from "zod";
 
-type Request = z.infer<typeof RequestSchema>;
-type Response = z.infer<typeof ResponseSchema>;
-
 type SerializedWidget = {
     id: string;
     type: string;
@@ -37,39 +34,6 @@ type ServerRequestParams<Method extends keyof typeof ServerRequestParamsSchemas>
 
 type ParamsSchema<Output> = z.ZodType<Output>;
 type ServerInitiatedMethod = keyof typeof ServerRequestParamsSchemas;
-type Message = Request | Response;
-
-const RequestSchema: z.ZodObject<
-    {
-        id: z.ZodString;
-        method: z.ZodString;
-        params: z.ZodOptional<z.ZodUnknown>;
-    }
-> = z.object({
-    id: z.string(),
-    method: z.string(),
-    params: z.unknown().optional(),
-});
-
-const ErrorSchema: z.ZodObject<
-    { code: z.ZodNumber; message: z.ZodString; data: z.ZodOptional<z.ZodUnknown> }
-> = z.object({
-    code: z.number(),
-    message: z.string(),
-    data: z.unknown().optional(),
-});
-
-const ResponseSchema: z.ZodObject<
-    {
-        id: z.ZodString;
-        result: z.ZodOptional<z.ZodUnknown>;
-        error: z.ZodOptional<typeof ErrorSchema>;
-    }
-> = z.object({
-    id: z.string(),
-    result: z.unknown().optional(),
-    error: ErrorSchema.optional(),
-});
 
 const RegisterParamsSchema: z.ZodObject<
     {
@@ -175,8 +139,6 @@ function getRuntimeDir(): string {
 export {
     DEFAULT_SUBTREE_DEPTH,
     MAX_SUBTREE_WIDGETS,
-    RequestSchema,
-    ResponseSchema,
     RegisterParamsSchema,
     widgetIdParams,
     widgetPropsParams,
@@ -187,13 +149,10 @@ export {
     screenshotParams,
     ServerRequestParamsSchemas,
     DEFAULT_SOCKET_PATH,
-    type Request,
-    type Response,
     type SerializedWidget,
     type SerializedProperty,
     type AppInfo,
     type ServerRequestParams,
     type ParamsSchema,
     type ServerInitiatedMethod,
-    type Message,
 };

package/src/reference.ts

@@ -1,5 +1,6 @@
 import { type ApiReference, type ApiSymbol, loadApiReference, resolveGirPath, resolveLibraries } from "@gtkx/codegen";
 import { loadConfig } from "@gtkx/config";
+import { resolveFuture } from "@gtkx/config/internal";
 import { type McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { type CallToolResult, ErrorCode, McpError, type ReadResourceResult } from "@modelcontextprotocol/sdk/types.js";
 import { existsSync, statSync } from "node:fs";
@@ -192,15 +193,17 @@ const loadReference = async (requestedRoot: string): Promise<LoadedReference> =>
         );
     }
 
-    const libraries = resolveLibraries(config.libraries, girPath);
+    const future = resolveFuture(config.future);
+    const libraries = resolveLibraries(config.libraries, girPath, future.isAdwaitaDefault);
 
     const reference = loadApiReference({
         libraries,
         girPath,
-        isByteArrayTyped: config.future?.v2ByteArrays === true,
-        isValueUnwrapped: config.future?.v2ValueReturns === true,
-        isFinishTrimmed: config.future?.v2FinishResults === true,
-        isInoutInPlace: config.future?.v2InoutReturns === true,
+        isByteArrayTyped: future.isByteArrayTyped,
+        isValueUnwrapped: future.isValueUnwrapped,
+        isFinishTrimmed: future.isFinishTrimmed,
+        isInoutInPlace: future.isInoutInPlace,
+        isTreeShaken: future.isTreeShaken,
     });
 
     const watched = [watchFile(resolve(root, configFile)), ...reference.girFiles.map((file) => watchFile(file))];

package/src/server.ts

@@ -1,6 +1,10 @@
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { loadConfig } from "@gtkx/config";
+import { type McpSettings, resolveMcpSettings } from "@gtkx/config/internal";
 import { createLogger, installGracefulShutdown, type Logger } from "@gtkx/utils";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { parseArgs } from "node:util";
 import { z } from "zod";
 import type { ConnectionErrorEvent } from "./transport.js";
 import packageManifest from "../package.json" with { type: "json" };
@@ -26,11 +30,19 @@ import {
     registerReferenceResources,
 } from "./reference.js";
 import { SocketServer } from "./socket-server.js";
-import { defineTool, imageContent, registerTool, textContent, type Tool } from "./tool.js";
+import { selectTools } from "./tool-filter.js";
+import { defineTool, imageContent, registerTool, textContent, textError, type Tool } from "./tool.js";
 
 type CreateMcpServerOptions = {
     socketPath?: string;
     version: string;
+    settings?: McpSettings;
+};
+
+type ServerOptions = {
+    cwd?: string;
+    tools?: string[];
+    isReadOnly?: boolean;
 };
 
 type McpServerHandle = {
@@ -51,6 +63,18 @@ type AppWithWindows = AppInfo & { windows?: AppWindow[] };
 
 const { version } = packageManifest;
 const log: Logger = createLogger("mcp");
+const DEFAULT_SETTINGS: McpSettings = { tools: [], isReadOnly: false };
+
+const INSTRUCTIONS =
+    "The widget tools drive a GTKX app running under `gtkx dev`: they read " +
+    "its live widget tree, query it by accessible role and name, click and type, and capture screenshots. " +
+    "They fail until an app is running, so start `gtkx dev` first. The reference tools answer from the " +
+    "bindings generated for a specific project, so they describe that project's GIR libraries rather than " +
+    "GTK in general; prefer them over recalled GTK knowledge, which is usually C, PyGObject or GJS and " +
+    "does not apply here.\n\n" +
+    "Widget IDs are valid only while the widget is mounted. After a dialog closes, a list re-renders, or " +
+    "fast refresh patches a component, re-read the tree or re-run the query instead of reusing an ID.";
+
 const APPLICATION_ID_DESCRIPTION = "Application ID to query. If not specified, uses the first connected app.";
 
 const WIDGET_ID_DESCRIPTION =
@@ -137,6 +161,14 @@ const screenshotShape = {
             "Absolute path to write the PNG to on the app's machine. If set, the screenshot is saved there " +
             "in addition to being returned.",
     }),
+    returnImage: z
+        .boolean()
+        .optional()
+        .describe(
+            "Whether to return the PNG as image content, true by default. Pass false together with `path` " +
+            "to save the screenshot and get back only where it landed, which keeps the image out of the " +
+            "conversation until something actually needs to look at it.",
+        ),
 };
 
 function describeParams<Shape extends Record<string, z.ZodType>>(
@@ -202,6 +234,28 @@ const listAppsTool = (appRouter: AppRouter): Tool =>
         },
     });
 
+const screenshotResult = (
+    result: { data: string; mimeType: string; savedPath?: string },
+    shouldReturnImage: boolean,
+): CallToolResult => {
+    if (result.savedPath === undefined) {
+        return shouldReturnImage
+            ? imageContent(result.data, result.mimeType)
+            : textError(
+                    "Nothing to return: `returnImage` was false and no `path` was given, so the screenshot was " +
+                    "neither saved nor returned. Pass `path` to save it, or leave `returnImage` unset.",
+                );
+    }
+
+    const saved = { type: "text", text: `Screenshot saved to ${result.savedPath}` } as const;
+
+    if (!shouldReturnImage) {
+        return { content: [saved] };
+    }
+
+    return { content: [saved, { type: "image", data: result.data, mimeType: result.mimeType }] };
+};
+
 const screenshotTool = (appRouter: AppRouter): Tool =>
     defineTool({
         name: "gtkx_take_screenshot",
@@ -212,23 +266,14 @@ const screenshotTool = (appRouter: AppRouter): Tool =>
             "the PNG to `path` on the app's machine. You can't target widgets from a screenshot; use " +
             "`gtkx_get_widget_tree` to find widget IDs for interaction.",
         inputSchema: screenshotShape,
-        handler: async ({ applicationId, ...params }) => {
+        handler: async ({ applicationId, returnImage, ...params }) => {
             const result = await appRouter.sendToApp<{ data: string; mimeType: string; savedPath?: string }>(
                 applicationId,
                 "widget.screenshot",
                 params,
             );
 
-            if (result.savedPath) {
-                return {
-                    content: [
-                        { type: "text", text: `Screenshot saved to ${result.savedPath}` },
-                        { type: "image", data: result.data, mimeType: result.mimeType },
-                    ],
-                };
-            }
-
-            return imageContent(result.data, result.mimeType);
+            return screenshotResult(result, returnImage !== false);
         },
     });
 
@@ -348,8 +393,19 @@ function buildTools(appRouter: AppRouter): Tool[] {
     return [...buildInspectionTools(appRouter), ...buildInteractionTools(appRouter)];
 }
 
-const registerTools = (mcpServer: McpServer, appRouter: AppRouter, provider: ReferenceProvider): void => {
-    for (const tool of [...buildTools(appRouter), ...buildReferenceTools(provider)]) {
+const registerTools = (
+    mcpServer: McpServer,
+    appRouter: AppRouter,
+    provider: ReferenceProvider,
+    settings: McpSettings,
+): void => {
+    const tools = selectTools([...buildTools(appRouter), ...buildReferenceTools(provider)], settings);
+
+    if (tools.length === 0) {
+        log.warn("no tools matched the configured filter; the server is registering none");
+    }
+
+    for (const tool of tools) {
         registerTool(mcpServer, tool);
     }
 };
@@ -402,16 +458,57 @@ const createMcpServer = (options: CreateMcpServerOptions): McpServerHandle => {
         log.info(`app unregistered: ${(event as AppUnregisteredEvent).detail}`);
     });
 
-    const mcpServer = new McpServer({ name: "gtkx-mcp", version: options.version });
+    const mcpServer = new McpServer({ name: "gtkx-mcp", version: options.version }, { instructions: INSTRUCTIONS });
     const referenceProvider = createReferenceProvider({ getAppRoot: () => appRouter.getProjectRoot() });
-    registerTools(mcpServer, appRouter, referenceProvider);
+    registerTools(mcpServer, appRouter, referenceProvider, options.settings ?? DEFAULT_SETTINGS);
     registerReferenceResources(mcpServer, referenceProvider);
 
     return createServerHandle(socketServer, mcpServer, socketPath);
 };
 
-async function main(): Promise<void> {
-    const server = createMcpServer({ version });
+const configuredSettings = async (cwd: string): Promise<McpSettings> => {
+    try {
+        const { config } = await loadConfig(cwd);
+
+        return resolveMcpSettings(config);
+    } catch {
+        return DEFAULT_SETTINGS;
+    }
+};
+
+const resolveSettings = async (options: ServerOptions): Promise<McpSettings> => {
+    const configured = await configuredSettings(options.cwd ?? process.cwd());
+
+    return {
+        tools: options.tools ?? configured.tools,
+        isReadOnly: options.isReadOnly ?? configured.isReadOnly,
+    };
+};
+
+const splitPatterns = (values: string[]): string[] =>
+    values.flatMap((value) => value.split(",")).map((value) => value.trim()).filter((value) => value.length > 0);
+
+const parseServerArgs = (argv: string[]): ServerOptions => {
+    const { values } = parseArgs({
+        args: argv,
+        options: {
+            tools: { type: "string", multiple: true },
+            "read-only": { type: "boolean" },
+        },
+        allowPositionals: false,
+    });
+
+    const tools = values.tools === undefined ? undefined : splitPatterns(values.tools);
+
+    return {
+        ...(tools !== undefined && { tools }),
+        ...(values["read-only"] !== undefined && { isReadOnly: values["read-only"] }),
+    };
+};
+
+async function main(options: ServerOptions = {}): Promise<void> {
+    const settings = await resolveSettings(options);
+    const server = createMcpServer({ version, settings });
 
     installGracefulShutdown({
         onSignal: () => server.stop(),
@@ -420,4 +517,4 @@ async function main(): Promise<void> {
     await server.start();
 }
 
-export { log, main };
+export { log, main, main as runMcpServer, parseServerArgs };

package/src/socket-server.ts

@@ -353,7 +353,7 @@ class SocketServer {
         }
 
         this.server = null;
-        this.registry.dispose("Server stopping");
+        this.registry.dispose();
         await closeServer(server);
         await this.release();
     }

package/src/tool-filter.ts

@@ -0,0 +1,54 @@
+import type { McpSettings } from "@gtkx/config/internal";
+import type { Tool } from "./tool.js";
+
+const NEGATION_PREFIX = "!";
+const SPECIAL_CHARACTERS = /[.+?^${}()|[\]\\]/g;
+
+const escapeLiteral = (value: string): string => value.replaceAll(SPECIAL_CHARACTERS, String.raw`\$&`);
+
+const patternToRegExp = (pattern: string): RegExp =>
+    new RegExp(`^${pattern.split("*").map((part) => escapeLiteral(part)).join(".*")}$`);
+
+const matchingNames = (tools: Tool[], pattern: string): string[] => {
+    const expression = patternToRegExp(pattern);
+
+    return tools.filter((tool) => expression.test(tool.name)).map((tool) => tool.name);
+};
+
+const applyPattern = (selected: Set<string>, tools: Tool[], pattern: string): void => {
+    const isNegated = pattern.startsWith(NEGATION_PREFIX);
+    const names = matchingNames(tools, isNegated ? pattern.slice(NEGATION_PREFIX.length) : pattern);
+
+    for (const name of names) {
+        if (isNegated) {
+            selected.delete(name);
+        } else {
+            selected.add(name);
+        }
+    }
+};
+
+const selectNames = (tools: Tool[], patterns: string[]): Set<string> => {
+    const isSubtractive = patterns.every((pattern) => pattern.startsWith(NEGATION_PREFIX));
+    const selected: Set<string> = new Set(isSubtractive ? tools.map((tool) => tool.name) : []);
+
+    for (const pattern of patterns) {
+        applyPattern(selected, tools, pattern);
+    }
+
+    return selected;
+};
+
+const selectTools = (tools: Tool[], settings: McpSettings): Tool[] => {
+    const allowed = settings.isReadOnly ? tools.filter((tool) => tool.kind === "readOnly") : tools;
+
+    if (settings.tools.length === 0) {
+        return allowed;
+    }
+
+    const selected = selectNames(allowed, settings.tools);
+
+    return allowed.filter((tool) => selected.has(tool.name));
+};
+
+export { selectTools };

package/src/tool.ts

@@ -12,6 +12,7 @@ type Tool<Shape extends Record<string, z.ZodType> = Record<string, z.ZodType>> =
     kind: ToolKind;
     description: string;
     inputSchema: Shape;
+    isOpenWorld?: boolean;
     handler: (args: ToolArgs<Shape>) => Promise<CallToolResult>;
 };
 
@@ -63,7 +64,7 @@ const registerTool = (server: McpServer, tool: Tool): void => {
                 title: tool.title,
                 readOnlyHint: tool.kind === "readOnly",
                 destructiveHint: tool.kind === "action",
-                openWorldHint: true,
+                openWorldHint: tool.isOpenWorld === true,
             },
         },
         callback,