feat(mcp): adds firebase://docs/{path} resource template to MCP (#9198)

Author: mbleigh

src/mcp/index.ts

@@ -17,9 +17,11 @@ import {
   ListResourcesResult,
   ReadResourceRequest,
   ReadResourceResult,
+  ReadResourceRequestSchema,
+  ListResourceTemplatesRequestSchema,
+  ListResourceTemplatesResult,
   McpError,
   ErrorCode,
-  ReadResourceRequestSchema,
 } from "@modelcontextprotocol/sdk/types.js";
 import { checkFeatureActive, mcpError } from "./util";
 import { ClientConfig, McpContext, SERVER_FEATURES, ServerFeature } from "./types";
@@ -42,7 +44,7 @@ import { existsSync } from "node:fs";
 import { LoggingStdioServerTransport } from "./logging-transport";
 import { isFirebaseStudio } from "../env";
 import { timeoutFallback } from "../timeout";
-import { resources } from "./resources";
+import { resolveResource, resources, resourceTemplates } from "./resources";
 
 const SERVER_VERSION = "0.3.0";
 
@@ -115,9 +117,12 @@ export class FirebaseMcpServer {
     this.server.setRequestHandler(CallToolRequestSchema, this.mcpCallTool.bind(this));
     this.server.setRequestHandler(ListPromptsRequestSchema, this.mcpListPrompts.bind(this));
     this.server.setRequestHandler(GetPromptRequestSchema, this.mcpGetPrompt.bind(this));
+    this.server.setRequestHandler(
+      ListResourceTemplatesRequestSchema,
+      this.mcpListResourceTemplates.bind(this),
+    );
     this.server.setRequestHandler(ListResourcesRequestSchema, this.mcpListResources.bind(this));
     this.server.setRequestHandler(ReadResourceRequestSchema, this.mcpReadResource.bind(this));
-
     const onInitialized = (): void => {
       const clientInfo = this.server.getClientVersion();
       this.clientInfo = clientInfo;
@@ -424,9 +429,13 @@ export class FirebaseMcpServer {
     };
   }
 
-  async mcpReadResource(req: ReadResourceRequest): Promise<ReadResourceResult> {
-    const resource = resources.find((r) => r.mcp.uri === req.params.uri);
+  async mcpListResourceTemplates(): Promise<ListResourceTemplatesResult> {
+    return {
+      resourceTemplates: resourceTemplates.map((rt) => rt.mcp),
+    };
+  }
 
+  async mcpReadResource(req: ReadResourceRequest): Promise<ReadResourceResult> {
     let projectId = await this.getProjectId();
     projectId = projectId || "";
 
@@ -435,13 +444,14 @@ export class FirebaseMcpServer {
 
     const resourceCtx = this._createMcpContext(projectId, accountEmail);
 
-    if (!resource) {
+    const resolved = await resolveResource(req.params.uri, resourceCtx);
+    if (!resolved) {
       throw new McpError(
         ErrorCode.InvalidParams,
         `Resource '${req.params.uri}' could not be found.`,
       );
     }
-    return resource.fn(req.params.uri, resourceCtx);
+    return resolved.result;
   }
 
   async start(): Promise<void> {

src/mcp/resource.ts

@@ -27,3 +27,45 @@ export function resource(
       : fnOrText;
   return { mcp: options, fn };
 }
+
+export interface ServerResourceTemplate {
+  mcp: {
+    uriTemplate: string;
+    /** How to know if a URI matches this template, can be a string (prefix), regex, or function. */
+    name: string;
+    description?: string;
+    title?: string;
+    _meta?: {
+      /** Set this on a resource if it *always* requires a signed-in user to work. */
+      requiresAuth?: boolean;
+      /** Set this on a resource if it uses Gemini in Firebase API in any way. */
+      requiresGemini?: boolean;
+    };
+  };
+  match: (uri: string) => boolean;
+  fn: (uri: string, ctx: McpContext) => Promise<ReadResourceResult>;
+}
+
+export function resourceTemplate(
+  options: ServerResourceTemplate["mcp"] & {
+    match: string | RegExp | ServerResourceTemplate["match"];
+  },
+  fnOrText: ServerResourceTemplate["fn"] | string,
+): ServerResourceTemplate {
+  let matchFn: ServerResourceTemplate["match"];
+  const { match, ...mcp } = options;
+
+  if (match instanceof RegExp) {
+    matchFn = (uri) => match.test(uri);
+  } else if (typeof match === "string") {
+    matchFn = (uri) => uri.startsWith(match);
+  } else {
+    matchFn = match;
+  }
+
+  const fn: ServerResourceTemplate["fn"] =
+    typeof fnOrText === "string"
+      ? async (uri) => ({ contents: [{ uri, text: fnOrText }] })
+      : fnOrText;
+  return { mcp, match: matchFn, fn };
+}

src/mcp/resources/docs.ts

@@ -0,0 +1,47 @@
+import { resourceTemplate } from "../resource";
+
+export const docs = resourceTemplate(
+  {
+    name: "docs",
+    title: "Firebase Docs",
+    description:
+      "loads plain text content from Firebase documentation, e.g. `https://firebase.google.com/docs/functions` becomes `firebase://docs/functions`",
+    uriTemplate: `firebase://docs/{path}`,
+    match: `firebase://docs/`,
+  },
+  async (uri) => {
+    const path = uri.replace("firebase://docs/", "");
+    try {
+      const response = await fetch(`https://firebase.google.com/docs/${path}.md.txt`);
+
+      if (response.status >= 400) {
+        return {
+          contents: [
+            {
+              uri,
+              text: `Received a ${response.status} error while fetching '${uri}':\n\n${await response.text()}`,
+            },
+          ],
+        };
+      }
+
+      return {
+        contents: [
+          {
+            uri,
+            text: await response.text(),
+          },
+        ],
+      };
+    } catch (e) {
+      return {
+        contents: [
+          {
+            uri,
+            text: `ERROR: There was an error fetching content for ${uri}`,
+          },
+        ],
+      };
+    }
+  },
+);

src/mcp/resources/index.ts

@@ -1,10 +1,14 @@
+import { ReadResourceResult } from "@modelcontextprotocol/sdk/types";
+import { McpContext } from "../types";
+import { docs } from "./docs";
 import { init_ai } from "./guides/init_ai";
 import { init_auth } from "./guides/init_auth";
 import { init_backend } from "./guides/init_backend";
 import { init_data_connect } from "./guides/init_data_connect";
 import { init_firestore } from "./guides/init_firestore";
 import { init_hosting } from "./guides/init_hosting";
 import { init_rtdb } from "./guides/init_rtdb";
+import { ServerResource, ServerResourceTemplate } from "../resource";
 
 export const resources = [
   init_backend,
@@ -15,3 +19,34 @@ export const resources = [
   init_auth,
   init_hosting,
 ];
+
+export const resourceTemplates = [docs];
+
+export async function resolveResource(
+  uri: string,
+  ctx: McpContext,
+): Promise<
+  | ({
+      result: ReadResourceResult;
+    } & (
+      | { type: "template"; mcp: ServerResourceTemplate["mcp"] }
+      | { type: "resource"; mcp: ServerResource["mcp"] }
+    ))
+  | null
+> {
+  // check if an exact resource name matches first
+  const resource = resources.find((r) => r.mcp.uri === uri);
+  if (resource) {
+    const result = await resource.fn(uri, ctx);
+    return { type: "resource", mcp: resource.mcp, result };
+  }
+
+  // then check if any templates match
+  const template = resourceTemplates.find((rt) => rt.match(uri));
+  if (template) {
+    const result = await template.fn(uri, ctx);
+    return { type: "template", mcp: template.mcp, result };
+  }
+
+  return null;
+}

src/mcp/tools/core/read_resources.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { tool } from "../../tool";
-import { resources } from "../../resources";
+import { resolveResource, resources } from "../../resources";
 import { toContent } from "../../util";
 
 export const read_resources = tool(
@@ -36,14 +36,13 @@ export const read_resources = tool(
 
     const out: string[] = [];
     for (const uri of uris) {
-      const resource = resources.find((r) => r.mcp.uri === uri);
-      if (!resource) {
+      const resolved = await resolveResource(uri, ctx);
+      if (!resolved) {
         out.push(`<resource uri="${uri}" error>\nRESOURCE NOT FOUND\n</resource>`);
         continue;
       }
-      const result = await resource.fn(uri, ctx);
       out.push(
-        `<resource uri="${uri}" title="${resource?.mcp.title}">\n${result.contents.map((c) => c.text).join("")}\n</resource>`,
+        `<resource uri="${uri}" title="${resolved.mcp.title || resolved.mcp.name}">\n${resolved.result.contents.map((c) => c.text).join("")}\n</resource>`,
       );
     }