[MCP] Flexible directory selection and command line arguments. (#8468)

Author: mbleigh

npm-shrinkwrap.json

@@ -4,8 +4,7 @@
   "description": "Command-Line Interface for Firebase",
   "main": "./lib/index.js",
   "bin": {
-    "firebase": "./lib/bin/firebase.js",
-    "firebase-mcp": "./lib/bin/firebase-mcp.js"
+    "firebase": "./lib/bin/firebase.js"
   },
   "scripts": {
     "build": "tsc && npm run copyfiles",

package.json

@@ -1,19 +1,37 @@
 #!/usr/bin/env node
 
-import { Command } from "../command";
-import { requireAuth } from "../requireAuth";
-
 import { silenceStdout } from "../logger";
 silenceStdout();
 
 import { FirebaseMcpServer } from "../mcp/index";
+import { parseArgs } from "util";
+import { SERVER_FEATURES, ServerFeature } from "../mcp/types";
+
+const STARTUP_MESSAGE = `
+This is a running process of the Firebase MCP server. This command should only be executed by an MCP client. An example MCP client configuration might be:
 
-const cmd = new Command("mcp").before(requireAuth);
+{
+  "mcpServers": {
+    "firebase": {
+      "command": "firebase",
+      "args": ["experimental:mcp", "--dir", "/path/to/firebase/project"]
+    }
+  }
+}
+`;
 
-export async function mcp() {
-  const options: any = {};
-  options.cwd = process.env.PROJECT_ROOT || process.env.CWD;
-  await cmd.prepare(options);
-  const server = new FirebaseMcpServer({ cliOptions: options });
+export async function mcp(): Promise<void> {
+  const { values } = parseArgs({
+    options: {
+      only: { type: "string", default: "" },
+      dir: { type: "string" },
+    },
+    allowPositionals: true,
+  });
+  const activeFeatures = (values.only || "")
+    .split(",")
+    .filter((f) => SERVER_FEATURES.includes(f as ServerFeature)) as ServerFeature[];
+  const server = new FirebaseMcpServer({ activeFeatures, projectRoot: values.dir });
   await server.start();
+  if (process.stdin.isTTY) process.stderr.write(STARTUP_MESSAGE);
 }

src/bin/mcp.ts

@@ -0,0 +1,43 @@
+# Firebase MCP Server
+
+The Firebase MCP Server provides assistive utilities to compatible AI-assistant
+development tools.
+
+## Usage
+
+The Firebase MCP server uses the Firebase CLI for authentication and project
+selection. You will usually want to start the server with a specific directory
+as an argument to operate against the project of your working directory.
+
+For clients that don't operate within a specific workspace, the Firebase MCP
+server makes tools available to read and write a project directory.
+
+### Example: Cursor
+
+In `.cursor/mcp.json` in your workspace directory, add the Firebase MCP server:
+
+```json
+{
+  "mcpServers": {
+    "firebase": {
+      "command": "npx",
+      "args": ["-y", "firebase-tools", "experimental:mcp", "--dir", "<your_absolute_workspace_dir>"]
+    }
+  }
+}
+```
+
+### Command Line Options
+
+- `--dir <absolute_dir_path>`: The absolute path of a directory containing `firebase.json` to set a project context for the MCP server. If unspecified, the `{get|set}_firebase_directory` tools will become available and the default directory will be the working directory where the MCP server was started.
+- `--only <feature1,feature2>`: A comma-separated list of feature groups to activate. Use this to limit the tools exposed to only features you are actively using.
+
+## Tools
+
+| Tool Name                | Feature Group | Description                                                                                                         |
+| ------------------------ | ------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `get_firebase_directory` | `core`        | When running without the `--dir` command, retrieves the current directory (defaults to current working directory).  |
+| `set_firebase_directory` | `core`        | When running without the `--dir` command, sets the current project directory (i.e. one with `firebase.json` in it). |
+| `get_project`            | `project`     | Get basic information about the active project in the current Firebase directory.                                   |
+| `list_apps`              | `project`     | List registered apps for the currently active project.                                                              |
+| `get_sdk_config`         | `project`     | Get an Firebase client SDK config for a specific platform.                                                          |

src/mcp/README.md

@@ -0,0 +1,6 @@
+import { mcpError } from "./util";
+
+export const NO_PROJECT_ERROR = mcpError(
+  "No active project was found. Use the `set_firebase_directory` command to set the project directory (containing firebase.json).",
+  "PRECONDITION_FAILED",
+);

src/mcp/errors.ts

@@ -10,55 +10,104 @@ import {
 import { ServerFeature } from "./types.js";
 import { tools } from "./tools/index.js";
 import { ServerTool } from "./tool.js";
+import { configstore } from "../configstore.js";
+import { coreTools } from "./tools/core/index.js";
+import { Command } from "../command.js";
+import { requireAuth } from "../requireAuth.js";
+import { Options } from "../options.js";
+import { getProjectId } from "../projectUtils.js";
 
 const SERVER_VERSION = "0.0.1";
+const PROJECT_ROOT_KEY = "mcp.projectRoot";
+
+const cmd = new Command("experimental:mcp").before(requireAuth);
 
 export class FirebaseMcpServer {
-  projectId?: string;
+  projectRoot?: string;
   server: Server;
   cliOptions: any;
   activeFeatures?: ServerFeature[];
+  fixedRoot?: boolean;
 
-  constructor(options: { activeFeatures?: ServerFeature[]; cliOptions: any }) {
+  constructor(options: { activeFeatures?: ServerFeature[]; projectRoot?: string }) {
     this.activeFeatures = options.activeFeatures;
-    this.cliOptions = options.cliOptions;
     this.server = new Server({ name: "firebase", version: SERVER_VERSION });
-    this.server.registerCapabilities({ tools: { listChanged: false } });
+    this.server.registerCapabilities({ tools: { listChanged: true } });
     this.server.setRequestHandler(ListToolsRequestSchema, this.mcpListTools.bind(this));
     this.server.setRequestHandler(CallToolRequestSchema, this.mcpCallTool.bind(this));
+    this.projectRoot =
+      options.projectRoot ??
+      (configstore.get(PROJECT_ROOT_KEY) as string) ??
+      process.env.PROJECT_ROOT ??
+      process.cwd();
+    if (options.projectRoot) this.fixedRoot = true;
   }
 
-  get activeTools(): ServerTool[] {
-    const toolDefs: ServerTool[] = [];
-    const activeFeatures = this.activeFeatures || (Object.keys(tools) as ServerFeature[]);
+  get availableTools(): ServerTool[] {
+    const toolDefs: ServerTool[] = this.fixedRoot ? [] : [...coreTools];
+    const activeFeatures = this.activeFeatures?.length
+      ? this.activeFeatures
+      : (Object.keys(tools) as ServerFeature[]);
     for (const key of activeFeatures || []) {
       toolDefs.push(...tools[key]);
     }
     return toolDefs;
   }
 
+  async activeTools(): Promise<ServerTool[]> {
+    const hasActiveProject = !!(await this.getProjectId());
+    return this.availableTools.filter((t) => hasActiveProject || !t.mcp._meta?.requiresProject);
+  }
+
   getTool(name: string): ServerTool | null {
-    return this.activeTools.find((t) => t.mcp.name === name) || null;
+    return this.availableTools.find((t) => t.mcp.name === name) || null;
   }
 
-  mcpListTools(): Promise<ListToolsResult> {
-    return Promise.resolve({
-      tools: this.activeTools.map((t) => t.mcp),
+  async mcpListTools(): Promise<ListToolsResult> {
+    const hasActiveProject = !!(await this.getProjectId());
+    return {
+      tools: (await this.activeTools()).map((t) => t.mcp),
       _meta: {
+        projectRoot: this.projectRoot,
+        projectDetected: hasActiveProject,
         activeFeatures: this.activeFeatures,
       },
-    });
+    };
+  }
+
+  setProjectRoot(newRoot: string | null): void {
+    if (newRoot === null) {
+      configstore.delete(PROJECT_ROOT_KEY);
+      this.projectRoot = process.env.PROJECT_ROOT || process.cwd();
+      void this.server.sendToolListChanged();
+      return;
+    }
+
+    configstore.set(PROJECT_ROOT_KEY, newRoot);
+    this.projectRoot = newRoot;
+    void this.server.sendToolListChanged();
+  }
+
+  async resolveOptions(): Promise<Partial<Options>> {
+    const options: Partial<Options> = { cwd: this.projectRoot };
+    await cmd.prepare(options);
+    return options;
+  }
+
+  async getProjectId(): Promise<string | undefined> {
+    return getProjectId(await this.resolveOptions());
   }
 
   async mcpCallTool(request: CallToolRequest): Promise<CallToolResult> {
     const toolName = request.params.name;
     const toolArgs = request.params.arguments;
     const tool = this.getTool(toolName);
     if (!tool) throw new Error(`Tool '${toolName}' could not be found.`);
-    return tool.fn(toolArgs, { projectId: this.cliOptions.project });
+
+    return tool.fn(toolArgs, { projectId: await this.getProjectId(), host: this });
   }
 
-  async start() {
+  async start(): Promise<void> {
     const transport = new StdioServerTransport();
     await this.server.connect(transport);
   }

src/mcp/index.ts

@@ -1,6 +1,12 @@
 import { CallToolResult } from "@modelcontextprotocol/sdk/types";
 import { z, ZodTypeAny } from "zod";
 import { zodToJsonSchema } from "zod-to-json-schema";
+import type { FirebaseMcpServer } from "./index";
+
+export interface ServerToolContext {
+  projectId?: string;
+  host: FirebaseMcpServer;
+}
 
 export interface ServerTool<InputSchema extends ZodTypeAny = ZodTypeAny> {
   mcp: {
@@ -14,8 +20,11 @@ export interface ServerTool<InputSchema extends ZodTypeAny = ZodTypeAny> {
       idempotentHint?: boolean;
       openWorldHint?: boolean;
     };
+    _meta?: {
+      requiresProject?: boolean;
+    };
   };
-  fn: (input: z.infer<InputSchema>, ctx: { projectId?: string }) => Promise<CallToolResult>;
+  fn: (input: z.infer<InputSchema>, ctx: ServerToolContext) => Promise<CallToolResult>;
 }
 
 export function tool<InputSchema extends ZodTypeAny>(

src/mcp/tool.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+import { tool } from "../../tool.js";
+import { mcpError, toContent } from "../../util.js";
+import { detectProjectRoot } from "../../../detectProjectRoot.js";
+
+export const get_firebase_directory = tool(
+  {
+    name: "get_firebase_directory",
+    description:
+      "Gets the current Firebase project directory. If this has been set using the `set_firebase_directory` tool it will return that, otherwise it will look for a PROJECT_ROOT environment variable or the current working directory of the running Firebase MCP server.",
+    inputSchema: z.object({}),
+    annotations: {
+      title: "Get Firebase Project Directory",
+      readOnlyHint: true,
+    },
+  },
+  (_, { host }) => {
+    if (!detectProjectRoot({ cwd: host.projectRoot }))
+      return Promise.resolve(
+        mcpError(
+          `There is no detected 'firebase.json' in directory '${host.projectRoot}'. Please use the 'set_firebase_directory' tool to activate a Firebase project directory.`,
+        ),
+      );
+    return Promise.resolve(
+      toContent(`The current Firebase project directory is '${host.projectRoot}'.`),
+    );
+  },
+);

src/mcp/tools/core/get_firebase_directory.ts

@@ -0,0 +1,4 @@
+import { get_firebase_directory } from "./get_firebase_directory";
+import { set_firebase_directory } from "./set_firebase_directory";
+
+export const coreTools = [get_firebase_directory, set_firebase_directory];

src/mcp/tools/core/index.ts

@@ -0,0 +1,43 @@
+import { z } from "zod";
+import { tool } from "../../tool.js";
+import { mcpError, toContent } from "../../util.js";
+import { existsSync } from "fs";
+import { join } from "path";
+
+export const set_firebase_directory = tool(
+  {
+    name: "set_firebase_directory",
+    description:
+      "Sets the project directory for the Firebase MCP server to utilize for project detection and authentication. This should be a directory with a `firebase.json` file in it. This information is persisted between sessions.",
+    inputSchema: z.object({
+      dir: z
+        .string()
+        .nullable()
+        .describe(
+          "the absolute path of the directory. set to null to 'unset' the value and fall back to the working directory",
+        ),
+    }),
+    annotations: {
+      title: "Set Firebase Project Directory",
+      idempotentHint: true,
+    },
+  },
+  ({ dir }, { host }) => {
+    if (dir === null) {
+      host.setProjectRoot(null);
+      return Promise.resolve(
+        toContent(
+          `Firebase MCP project directory setting deleted. New project root is: ${host.projectRoot || "unset"}`,
+        ),
+      );
+    }
+
+    if (!existsSync(dir)) return Promise.resolve(mcpError(`Directory '${dir}' does not exist.`));
+    if (!existsSync(join(dir, "firebase.json")))
+      return Promise.resolve(
+        mcpError(`Directory '${dir}' does not contain a 'firebase.json' file.`),
+      );
+    host.setProjectRoot(dir);
+    return Promise.resolve(toContent(`Firebase MCP project directory set to '${dir}'.`));
+  },
+);