feat(server): expose resource and icon embedder hooks (#519)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

Author: rakshith48

patches/fastmcp@4.3.2.patch

@@ -1,31 +1,61 @@
 diff --git a/dist/FastMCP.d.cts b/dist/FastMCP.d.cts
-index 8eba099cc20f7ae5f70060bebb3871c387cfb2de..c3031da662933c366c7320171db47c246cd3191a 100644
+index 8eba099cc20f7ae5f70060bebb3871c387cfb2de..3bcd654a3f9f1a42d2f92d8a72daf0612fc58d52 100644
 --- a/dist/FastMCP.d.cts
 +++ b/dist/FastMCP.d.cts
-@@ -605,6 +605,8 @@ type Tool<T extends FastMCPSessionAuth, Params extends ToolParameters = ToolPara
+@@ -240,10 +240,12 @@ type Resource<T extends FastMCPSessionAuth> = {
+     uri: string;
+ };
+ type ResourceResult = {
++    _meta?: Record<string, unknown>;
+     blob: string;
+     mimeType?: string;
+     uri?: string;
+ } | {
++    _meta?: Record<string, unknown>;
+     mimeType?: string;
+     text: string;
+     uri?: string;
+@@ -605,7 +607,10 @@ type Tool<T extends FastMCPSessionAuth, Params extends ToolParameters = ToolPara
          streamingHint?: boolean;
      } & ToolAnnotations;
      canAccess?: (auth: T) => boolean;
 +    beforeValidate?: (args: unknown, auth: T) => ContentResult | Promise<ContentResult | undefined> | undefined;
 +    canList?: (auth: T) => boolean;
      description?: string;
++    icons?: { src: string; mimeType?: string; sizes?: string[]; theme?: "light" | "dark" }[];
      execute: (args: StandardSchemaV1.InferOutput<Params>, context: Context<T>) => Promise<AudioContent | ContentResult | ImageContent | ResourceContent | ResourceLink | StandardSchemaV1.InferOutput<OutputParams> | string | TextContent | void>;
      name: string;
+     outputSchema?: OutputParams;
 diff --git a/dist/FastMCP.d.ts b/dist/FastMCP.d.ts
-index 810df0c5b6511f34685a0651e6df83acd0239e7b..5c82680c32900c1ca39679e1be25e64c3408aee9 100644
+index 810df0c5b6511f34685a0651e6df83acd0239e7b..8f688f131ff0b99566a3179f882e95159d7ef9ab 100644
 --- a/dist/FastMCP.d.ts
 +++ b/dist/FastMCP.d.ts
-@@ -605,6 +605,8 @@ type Tool<T extends FastMCPSessionAuth, Params extends ToolParameters = ToolPara
+@@ -240,10 +240,12 @@ type Resource<T extends FastMCPSessionAuth> = {
+     uri: string;
+ };
+ type ResourceResult = {
++    _meta?: Record<string, unknown>;
+     blob: string;
+     mimeType?: string;
+     uri?: string;
+ } | {
++    _meta?: Record<string, unknown>;
+     mimeType?: string;
+     text: string;
+     uri?: string;
+@@ -605,7 +607,10 @@ type Tool<T extends FastMCPSessionAuth, Params extends ToolParameters = ToolPara
          streamingHint?: boolean;
      } & ToolAnnotations;
      canAccess?: (auth: T) => boolean;
 +    beforeValidate?: (args: unknown, auth: T) => ContentResult | Promise<ContentResult | undefined> | undefined;
 +    canList?: (auth: T) => boolean;
      description?: string;
++    icons?: { src: string; mimeType?: string; sizes?: string[]; theme?: "light" | "dark" }[];
      execute: (args: StandardSchemaV1.InferOutput<Params>, context: Context<T>) => Promise<AudioContent | ContentResult | ImageContent | ResourceContent | ResourceLink | StandardSchemaV1.InferOutput<OutputParams> | string | TextContent | void>;
      name: string;
+     outputSchema?: OutputParams;
 diff --git a/dist/chunk-LWU5CQGW.js b/dist/chunk-LWU5CQGW.js
-index 474670585c1fff7d9609d0f900d0743df14a7688..86d120ca21d74d6c335a8c3c9763e2f4ac835d10 100644
+index 474670585c1fff7d9609d0f900d0743df14a7688..74610d15a0a9392cf286e357995847f0ff1e6db7 100644
 --- a/dist/chunk-LWU5CQGW.js
 +++ b/dist/chunk-LWU5CQGW.js
 @@ -986,6 +986,9 @@ ${error instanceof Error ? error.stack : JSON.stringify(error)}`
@@ -38,7 +68,7 @@ index 474670585c1fff7d9609d0f900d0743df14a7688..86d120ca21d74d6c335a8c3c9763e2f4
      let cachedToolsList = null;
      this.#server.setRequestHandler(ListToolsRequestSchema, async () => {
        if (cachedToolsList) {
-@@ -994,9 +997,12 @@ ${error instanceof Error ? error.stack : JSON.stringify(error)}`
+@@ -994,9 +997,13 @@ ${error instanceof Error ? error.stack : JSON.stringify(error)}`
          };
        }
        cachedToolsList = await Promise.all(
@@ -49,10 +79,11 @@ index 474670585c1fff7d9609d0f900d0743df14a7688..86d120ca21d74d6c335a8c3c9763e2f4
 +            // Top-level Tool.title (MCP 2025-06-18). Clients such as Codex index this
 +            // for tool search and do not read annotations.title.
 +            ...tool.annotations?.title && { title: tool.annotations.title },
++            ...tool.icons && { icons: tool.icons },
              description: tool.description,
              inputSchema: tool.parameters ? strictJsonSchema(await toJsonSchema(tool.parameters)) : {
                additionalProperties: false,
-@@ -1026,6 +1032,15 @@ ${error instanceof Error ? error.stack : JSON.stringify(error)}`
+@@ -1026,6 +1033,15 @@ ${error instanceof Error ? error.stack : JSON.stringify(error)}`
            `Unknown tool: ${request.params.name}`
          );
        }
@@ -69,7 +100,7 @@ index 474670585c1fff7d9609d0f900d0743df14a7688..86d120ca21d74d6c335a8c3c9763e2f4
        if (tool.parameters) {
          const parsed = await tool.parameters["~standard"].validate(
 diff --git a/dist/chunk-UYG7NPM6.cjs b/dist/chunk-UYG7NPM6.cjs
-index 3b695bf493c4f54fd970e145cf14fdd8effc9c6d..3e17b1d1f71f3bf41eb5e589fa272e670f27c150 100644
+index 3b695bf493c4f54fd970e145cf14fdd8effc9c6d..1b7ce74a69d3104f23da4e4a5b3218fcd84d71d5 100644
 --- a/dist/chunk-UYG7NPM6.cjs
 +++ b/dist/chunk-UYG7NPM6.cjs
 @@ -986,6 +986,9 @@ ${error instanceof Error ? error.stack : JSON.stringify(error)}`
@@ -82,7 +113,7 @@ index 3b695bf493c4f54fd970e145cf14fdd8effc9c6d..3e17b1d1f71f3bf41eb5e589fa272e67
      let cachedToolsList = null;
      this.#server.setRequestHandler(_typesjs.ListToolsRequestSchema, async () => {
        if (cachedToolsList) {
-@@ -994,9 +997,12 @@ ${error instanceof Error ? error.stack : JSON.stringify(error)}`
+@@ -994,9 +997,13 @@ ${error instanceof Error ? error.stack : JSON.stringify(error)}`
          };
        }
        cachedToolsList = await Promise.all(
@@ -93,10 +124,11 @@ index 3b695bf493c4f54fd970e145cf14fdd8effc9c6d..3e17b1d1f71f3bf41eb5e589fa272e67
 +            // Top-level Tool.title (MCP 2025-06-18). Clients such as Codex index this
 +            // for tool search and do not read annotations.title.
 +            ...tool.annotations?.title && { title: tool.annotations.title },
++            ...tool.icons && { icons: tool.icons },
              description: tool.description,
              inputSchema: tool.parameters ? _xsschema.strictJsonSchema.call(void 0, await _xsschema.toJsonSchema.call(void 0, tool.parameters)) : {
                additionalProperties: false,
-@@ -1026,6 +1032,15 @@ ${error instanceof Error ? error.stack : JSON.stringify(error)}`
+@@ -1026,6 +1033,15 @@ ${error instanceof Error ? error.stack : JSON.stringify(error)}`
            `Unknown tool: ${request.params.name}`
          );
        }

pnpm-lock.yaml

@@ -180,10 +180,18 @@ export type ToolContext = {
   [key: string]: unknown;
 };
 
+export type ToolIcon = {
+  src: string;
+  mimeType?: string;
+  sizes?: string[];
+  theme?: 'light' | 'dark';
+};
+
 /** A tool as registered on the server. */
 export interface ToolDefinition {
   name: string;
   description?: string;
+  icons?: ToolIcon[];
   /** A Standard Schema (for example a zod object) for the arguments. */
   parameters?: unknown;
   /** JSON Schema of the structured result. */
@@ -216,6 +224,24 @@ type RegisteredTool = Parameters<FastMCP<SessionData>['addTool']>[0];
 /** Registers a tool onto an instance. */
 export type ToolRegistrar = { addTool(tool: ToolDefinition): void };
 
+export type ResourceContent = ({ text: string } | { blob: string }) & {
+  uri?: string;
+  mimeType?: string;
+  _meta?: Record<string, unknown>;
+};
+
+export interface ResourceDefinition {
+  uri: string;
+  name: string;
+  description?: string;
+  mimeType?: string;
+  load(session?: Session): Promise<ResourceContent | ResourceContent[]>;
+}
+
+export type ResourceRegistrar = {
+  addResource(resource: ResourceDefinition): void;
+};
+
 /** The HTTP request `authenticate` receives; absent for stdio. */
 export type AuthenticationRequest = {
   headers: IncomingHttpHeaders;
@@ -288,6 +314,7 @@ export interface FirecrawlMcpServerHooks {
     registrar: ToolRegistrar,
     context: ExtraToolsContext
   ) => void;
+  registerResources?: (registrar: ResourceRegistrar) => void;
   /** Credential and headers for each Firecrawl API request of a session. */
   outboundRequest?: (
     session: SessionData | undefined
@@ -2973,6 +3000,10 @@ Set \`redactPII\` to request redaction of personally identifiable information in
     }
   );
 
+  hooks.registerResources?.({
+    addResource: (resource) => server.addResource(resource),
+  });
+
   return {
     start: (args) =>
       server.start(args as Parameters<typeof server.start>[0]),

src/server.ts

@@ -89,11 +89,24 @@ test('the packed package embeds through firecrawl-mcp/server', async (t) => {
   const auth = { authorization: 'Bearer embed-token' };
   const listed = await rpc(port, 'tools/list', {}, auth);
   assert.equal(listed.status, 200);
-  const names = parseSseJson(await listed.text()).result.tools.map(
-    (tool) => tool.name
-  );
+  const tools = parseSseJson(await listed.text()).result.tools;
+  const names = tools.map((tool) => tool.name);
   assert.ok(names.includes('firecrawl_scrape'));
   assert.ok(names.includes('embed_echo'));
+  assert.deepEqual(tools.find(({ name }) => name === 'embed_echo').icons, [
+    { src: 'https://example.com/icon.svg', mimeType: 'image/svg+xml', sizes: ['any'] },
+  ]);
+  const rejectedRead = await rpc(port, 'resources/read', { uri: 'ui://example/app.html' });
+  assert.equal(rejectedRead.status, 401);
+  const read = await rpc(port, 'resources/read', { uri: 'ui://example/app.html' }, auth);
+  assert.equal(read.status, 200);
+  assert.deepEqual(parseSseJson(await read.text()).result.contents, [{
+    uri: 'ui://example/app.html',
+    name: 'Example app',
+    mimeType: 'text/html;profile=mcp-app',
+    text: '<html>acme</html>',
+    _meta: { ui: { csp: { connectDomains: [], resourceDomains: [] } } },
+  }]);
 
   const called = await rpc(
     port,

tests/embed-package.test.mjs

@@ -8,12 +8,41 @@ import {
   UserError,
   type FirecrawlMcpServerHooks,
   type Session,
+  type ResourceContent,
+  type ResourceDefinition,
+  type ResourceRegistrar,
   type ToolDefinition,
+  type ToolIcon,
   type ToolResult,
 } from 'firecrawl-mcp/server';
 
+const icon: ToolIcon = {
+  src: 'https://example.com/icon.svg',
+  mimeType: 'image/svg+xml',
+  sizes: ['any'],
+  theme: 'light',
+};
+
+const resource: ResourceDefinition = {
+  uri: 'ui://example/app.html',
+  name: 'Example app',
+  mimeType: 'text/html;profile=mcp-app',
+  load: async (session): Promise<ResourceContent[]> => [
+    {
+      text: String(session?.tenant),
+      _meta: { ui: { csp: { connectDomains: [] } } },
+    },
+    {
+      blob: 'aGVsbG8=',
+      uri: 'example://binary',
+      mimeType: 'application/octet-stream',
+    },
+  ],
+};
+
 const tool: ToolDefinition = {
   name: 'embed_tenant',
+  icons: [icon],
   description: 'Return the caller tenant.',
   execute: async (_args, { session }) => {
     if (!session?.tenant)
@@ -48,6 +77,9 @@ const hooks: FirecrawlMcpServerHooks = {
     const scrape = builtInTool('firecrawl_scrape');
     if (scrape) registrar.addTool({ ...scrape, name: 'embed_scrape' });
   },
+  registerResources: (registrar: ResourceRegistrar) => {
+    registrar.addResource(resource);
+  },
   outboundRequest: (session) => ({
     headers: { 'x-tenant': String(session?.tenant) },
   }),
@@ -63,3 +95,9 @@ export const stop: () => Promise<void> = server.stop;
 // Content items must match one of the MCP content shapes.
 // @ts-expect-error a text item needs its text
 export const missingText: ToolResult = { content: [{ type: 'text' }] };
+
+// @ts-expect-error a resource needs text or blob
+export const missingResourceContent: ResourceContent = { _meta: {} };
+
+// @ts-expect-error icon themes must match the MCP light/dark variants
+export const invalidIcon: ToolIcon = { src: 'https://example.com/icon.svg', theme: 'other' };

tests/fixtures/embed/embed-types.ts

@@ -21,11 +21,27 @@ export async function startEmbedded(port) {
         registrar.addTool({
           name: 'embed_echo',
           description: 'Echo text with the caller tenant.',
+          icons: [{
+            src: 'https://example.com/icon.svg',
+            mimeType: 'image/svg+xml',
+            sizes: ['any'],
+          }],
           parameters: z.object({ text: z.string() }),
           execute: async ({ text }, { session }) =>
             `${session?.tenant}: ${text}`,
         });
       },
+      registerResources: ({ addResource }) => {
+        addResource({
+          uri: 'ui://example/app.html',
+          name: 'Example app',
+          mimeType: 'text/html;profile=mcp-app',
+          load: async (session) => ({
+            text: `<html>${session.tenant}</html>`,
+            _meta: { ui: { csp: { connectDomains: [], resourceDomains: [] } } },
+          }),
+        });
+      },
     },
   });
   await server.start({