Initial commit

2026-04-23 23:58:59 -05:00
commit 47b9e3c159
257 changed files with 18913 additions and 0 deletions
@@ -0,0 +1,16 @@
+# Exploring Commands
+
+The Firebase CLI documents itself. Use help commands to discover functionality.
+
+- **Global Help**: List all available commands and categories.
+  ```bash
+  npx -y firebase-tools@latest --help
+  ```
+
+- **Command Help**: Get detailed usage for a specific command.
+  ```bash
+  npx -y firebase-tools@latest [command] --help
+  # Example:
+  npx -y firebase-tools@latest deploy --help
+  npx -y firebase-tools@latest firestore:indexes --help
+  ```
@@ -0,0 +1,11 @@
+# Creating a Project
+
+To create a new Firebase project from the CLI:
+
+```bash
+npx -y firebase-tools@latest projects:create
+```
+
+You will be prompted to:
+1. Enter a **Project ID** (must be 6-30 chars, lowercase, digits, and hyphens; must be unique globally).
+2. Enter a **display name**.
@@ -0,0 +1,18 @@
+# Initialization
+
+Before initializing, check if you are already in a Firebase project directory by looking for `firebase.json`.
+
+1. **Project Directory:**
+   Navigate to the root directory of the codebase. 
+   *(Only if starting a completely new project from scratch without an existing codebase, create a directory first: `mkdir my-project && cd my-project`)*
+
+2. **Initialize Services:**
+   Run the initialization command:
+   ```bash
+   npx -y firebase-tools@latest init
+   ```
+
+The CLI will guide you through:
+- Selecting features (Firestore, Functions, Hosting, etc.).
+- Associating with an existing project or creating a new one.
+- Configuring files (e.g. `firebase.json`, `.firebaserc`).
@@ -0,0 +1,65 @@
+# Firebase Local Environment Setup
+
+This skill documents the bare minimum setup required for a full Firebase experience for the agent. Before starting to use any Firebase features, you MUST verify that each of the following steps has been completed.
+
+## 1. Verify Node.js
+- **Action**: Run `node --version`.
+- **Handling**: Ensure Node.js is installed and the version is `>= 20`. If Node.js is missing or `< v20`, install it based on the operating system:
+
+  **Recommended: Use a Node Version Manager**
+  This avoids permission issues when installing global packages.
+
+  **For macOS or Linux:**
+  1. Guide the user to the [official nvm repository](https://github.com/nvm-sh/nvm#installing-and-updating).
+  2. Request the user to manually install `nvm` and reply when finished. **Stop and wait** for the user's confirmation.
+  3. Make `nvm` available in the current terminal session by sourcing the appropriate profile:
+     ```bash
+     # For Bash
+     source ~/.bash_profile
+     source ~/.bashrc
+
+     # For Zsh
+     source ~/.zprofile
+     source ~/.zshrc
+     ```
+  4. Install Node.js:
+     ```bash
+     nvm install 24
+     nvm use 24
+     ```
+
+  **For Windows:**
+  1. Guide the user to download and install [nvm-windows](https://github.com/coreybutler/nvm-windows/releases).
+  2. Request the user to manually install `nvm-windows` and Node.js, and reply when finished. **Stop and wait** for the user's confirmation.
+  3. After the user confirms, verify Node.js is available:
+     ```bash
+     node --version
+     ```
+
+  **Alternative: Official Installer**
+  1. Guide the user to download and install the LTS version from [nodejs.org](https://nodejs.org/en/download).
+  2. Request the user to manually install Node.js and reply when finished. **Stop and wait** for the user's confirmation.
+
+## 2. Verify Firebase CLI
+The Firebase CLI is the primary tool for interacting with Firebase services.
+- **Action**: Run `npx -y firebase-tools@latest --version`.
+- **Handling**: Ensure this command runs successfully and outputs a version number.
+
+## 3. Verify Firebase Authentication
+You must be authenticated to manage Firebase projects.
+- **Action**: Run `npx -y firebase-tools@latest login`.
+- **Handling**: If the environment is remote or restricted (no browser access), run `npx -y firebase-tools@latest login --no-localhost` instead.
+
+## 4. Install Agent Skills and MCP Server
+To fully manage Firebase, the agent needs specific skills and the Firebase MCP server installed. Identify the agent environment you are currently running in and follow the corresponding setup document strictly.
+
+**Read the setup document for your current agent:**
+- **Gemini CLI**: Review [setup-gemini_cli.md](setup-gemini_cli.md)
+- **Antigravity**: Review [setup-antigravity.md](setup-antigravity.md)
+- **Claude Code**: Review [setup-claude_code.md](setup-claude_code.md)
+- **Cursor**: Review [setup-cursor.md](setup-cursor.md)
+- **GitHub Copilot**: Review [setup-github_copilot.md](setup-github_copilot.md)
+- **Other Agents** (Windsurf, Cline, etc.): Review [setup-other_agents.md](setup-other_agents.md)
+
+---
+**CRITICAL AGENT RULE:** Do NOT proceed with any other Firebase tasks until EVERY step above has been successfully verified and completed.
@@ -0,0 +1,46 @@
+# Refresh Antigravity Local Environment
+
+Follow these steps to refresh Antigravity's local environment, ensuring that their agent skills and plugins are fully up-to-date.
+
+Antigravity relies on `npx skills`. Updates should prioritize the global level; if skills are installed at the project level, omit the `--global` flag.
+
+1. **List Available Skills:** Identify all Firebase skills available in the repository:
+   ```bash
+   npx -y skills add firebase/agent-skills --list
+   ```
+
+2. **Check Currently Installed Skills:** Determine which skills are already installed and linked at both project and global levels:
+   ```bash
+   # Check project-level skills
+   npx -y skills list --agent antigravity
+
+   # Check global-level skills
+   npx -y skills list --agent antigravity --global
+   ```
+   *Note: If a skill shows `Agents: not linked` in the output, it is installed but not currently available to Antigravity.*
+
+3. **Add Missing or Unlinked Skills:** Compare the results from Step 1 and Step 2. For each missing or unlinked skill, follow the appropriate conditional instruction below:
+
+   - **IF any Firebase skills were found at the PROJECT level in Step 2:** Add the missing skill to the project level:
+     ```bash
+     npx -y skills add firebase/agent-skills --agent antigravity --skill "<SKILL_NAME>" --yes
+     ```
+
+   - **IF any Firebase skills were found at the GLOBAL level in Step 2:** Add the missing skill to the global level:
+     ```bash
+     npx -y skills add firebase/agent-skills --agent antigravity --skill "<SKILL_NAME>" --global --yes
+     ```
+
+   - **IF NO Firebase skills were found in Step 2:** Add each missing skill to the global level:
+     ```bash
+     npx -y skills add firebase/agent-skills --agent antigravity --skill "<SKILL_NAME>" --global --yes
+     ```
+
+4. **Update Existing Skills:** Update all currently installed skills to their latest versions:
+   ```bash
+   # Update project-level skills
+   npx -y skills update --agent antigravity --yes
+
+   # Update global-level skills
+   npx -y skills update --agent antigravity --global --yes
+   ```
@@ -0,0 +1,10 @@
+# Refresh Claude Code Local Environment
+
+Follow these steps to refresh Claude Code's local environment, ensuring that their agent skills and plugins are fully up-to-date.
+
+Use Claude Code's native plugin manager instead of `npx`.
+
+1. **Update the Plugin:** Run the specific CLI command to update the Firebase plugin:
+   ```bash
+   claude plugin update firebase@firebase
+   ```
@@ -0,0 +1,11 @@
+# Refresh Gemini CLI Local Environment
+
+Follow these steps to refresh Gemini CLI's local environment, ensuring that their agent skills and plugins are fully up-to-date.
+
+Use the native Gemini CLI extension manager instead of `npx`.
+
+1. **Update the Extension:** Run the specific CLI command to update:
+   ```bash
+   gemini extensions update firebase
+   ```
+   *Note: If the extension is named differently, replace `firebase` with the correct name from `gemini extensions list`.*
@@ -0,0 +1,48 @@
+# Refresh Other Local Environment
+
+Follow these steps to refresh the local environment of other agents, ensuring that their agent skills and plugins are fully up-to-date.
+
+Other agents rely on `npx skills`. Updates should prioritize the global level; if skills are installed at the project level, omit the `--global` flag.
+
+Replace `<AGENT_NAME>` with the actual agent name, which can be found in the [skills repository README](https://github.com/vercel-labs/skills/blob/main/README.md).
+
+1. **List Available Skills:** Identify all Firebase skills available in the repository:
+   ```bash
+   npx -y skills add firebase/agent-skills --list
+   ```
+
+2. **Check Currently Installed Skills:** Determine which skills are already installed and linked for the agent at both project and global levels:
+   ```bash
+   # Check project-level skills
+   npx -y skills list --agent <AGENT_NAME>
+
+   # Check global-level skills
+   npx -y skills list --agent <AGENT_NAME> --global
+   ```
+   *Note: If a skill shows `Agents: not linked` in the output, it is installed but not currently available to the agent.*
+
+3. **Add Missing or Unlinked Skills:** Compare the results from Step 1 and Step 2. For each missing or unlinked skill, follow the appropriate conditional instruction below:
+
+   - **IF any Firebase skills were found at the PROJECT level in Step 2:** Add the missing skill to the project level:
+     ```bash
+     npx -y skills add firebase/agent-skills --agent <AGENT_NAME> --skill "<SKILL_NAME>" --yes
+     ```
+
+   - **IF any Firebase skills were found at the GLOBAL level in Step 2:** Add the missing skill to the global level:
+     ```bash
+     npx -y skills add firebase/agent-skills --agent <AGENT_NAME> --skill "<SKILL_NAME>" --global --yes
+     ```
+
+   - **IF NO Firebase skills were found in Step 2:** Add each missing skill to the global level:
+     ```bash
+     npx -y skills add firebase/agent-skills --agent <AGENT_NAME> --skill "<SKILL_NAME>" --global --yes
+     ```
+
+4. **Update Existing Skills:** Update all currently installed skills to their latest versions:
+   ```bash
+   # Update project-level skills
+   npx -y skills update --agent <AGENT_NAME> --yes
+
+   # Update global-level skills
+   npx -y skills update --agent <AGENT_NAME> --global --yes
+   ```
@@ -0,0 +1,63 @@
+# Antigravity Setup
+
+To get the most out of Firebase in Antigravity, follow these steps to install the agent skills and the MCP server.
+
+### 1. Install and Verify Firebase Skills
+Check if the skills are already installed before proceeding:
+
+1. **Check Local skills**: Run `ls -d .agent/skills/firebase-basics` or `ls -d .agents/skills/firebase-basics`. If the directory exists, the skills are already installed locally.
+2. **Check Global skills**: If not found locally, check the global installation by running:
+   ```bash
+   npx skills list --global --agent antigravity
+   ```
+   If the output includes `firebase-basics`, the skills are already installed globally.
+3. **Install Skills**: If both checks fail, run the following command to install the Firebase agent skills:
+   ```bash
+   npx skills add firebase/agent-skills --agent antigravity --skill "*"
+   ```
+   *Note: Omit `--yes` and `--global` to choose the installation location manually. If prompted interactively in the terminal, ensure you send the appropriate user choices via standard input to complete the installation.*
+4. **Verify Installation**: Re-run the checks in steps 1 or 2 to confirm that `firebase-basics` is now available.
+
+### 2. Configure and Verify Firebase MCP Server
+The MCP server allows Antigravity to interact directly with Firebase projects.
+
+1. **Locate `mcp_config.json`**: Find the configuration file for your operating system:
+   - macOS / Linux: `~/.gemini/antigravity/mcp_config.json`
+   - Windows: `%USERPROFILE%\\.gemini\\antigravity\\mcp_config.json`
+   
+   *Note: If the `.gemini/antigravity/` directory or `mcp_config.json` file does not exist, create them and initialize the file with `{ "mcpServers": {} }` before proceeding.*
+2. **Check Existing Configuration**: Open `mcp_config.json` and check the `mcpServers` section for a `firebase` entry.
+   - It is already configured if the `command` is `"firebase"` OR if the `command` is `"npx"` with `"firebase-tools"` and `"mcp"` in the `args`.
+   - **Important**: If a valid `firebase` entry is found, the MCP server is already configured. **Skip step 3** and proceed directly to step 4.
+   
+   **Example valid configurations**:
+   ```json
+   "firebase": {
+     "command": "npx",
+     "args": ["-y", "firebase-tools@latest", "mcp"]
+   }
+   ```
+   OR
+   ```json
+   "firebase": {
+     "command": "firebase",
+     "args": ["mcp"]
+   }
+   ```
+3. **Add or Update Configuration**: If the `firebase` block is missing or incorrect, add it to the `mcpServers` object:
+   ```json
+   "firebase": {
+     "command": "npx",
+     "args": [
+       "-y",
+       "firebase-tools@latest",
+       "mcp"
+     ]
+   }
+   ```
+   *CRITICAL: Merge this configuration into the existing `mcp_config.json` file. You MUST preserve any other existing servers inside the `mcpServers` object.*
+4. **Verify Configuration**: Save the file and confirm the `firebase` block is present and properly formatted JSON.
+
+### 3. Restart and Verify Connection
+1. **Restart Antigravity**: Instruct the user to restart the Antigravity application. **Stop and wait** for their confirmation before proceeding.
+2. **Confirm Connection**: Check the MCP server list in the Antigravity UI to confirm that the Firebase MCP server is connected.
@@ -0,0 +1,30 @@
+# Claude Code Setup
+
+To get the most out of Firebase in Claude Code, follow these steps to install the agent skills and the MCP server.
+
+## Recommended Method: Using Plugins
+
+The recommended method is using the plugin marketplace to install both the agent skills and the MCP functionality.
+
+### 1. Install and Verify Plugins
+
+Check if the plugins are already installed before proceeding:
+
+1. **Check Existing Skills**: Run `npx skills list --agent claude-code` to check for local skills. Run `npx skills list --global --agent claude-code` to check for global skills. Note whether the output includes `firebase-basics`.
+2. **Check Existing MCP Configuration**: Run `claude mcp list -s user` and `claude mcp list -s project`. Note whether the output of either command includes `firebase`.
+3. **Determine Installation Path**:
+   - If **both** skills and MCP configuration are found, the plugin is fully installed. **Stop here and skip all remaining setup steps in this document.**
+   - If **neither** are found, proceed to step 4.
+   - If **only one** is found (e.g., skills are installed but MCP is missing, or vice versa), **stop and prompt the user**. Explain the mixed state and ask if they want to proceed with installing the Firebase plugin before continuing to step 4.
+4. **Add Marketplace**: Run the following command to add the marketplace (this uses the default User scope):
+   ```bash
+   claude plugin marketplace add firebase/agent-skills
+   ```
+5. **Install Plugins**: Run the following command to install the plugin:
+   ```bash
+   claude plugin install firebase@firebase
+   ```
+6. **Verify Installation**: Re-run the checks in steps 1 and 2 to confirm the skills and the MCP server are now available.
+
+### 2. Restart and Verify Connection
+1. **Restart Claude Code**: Instruct the user to restart Claude Code. **Stop and wait** for their confirmation before proceeding.
@@ -0,0 +1,63 @@
+# Cursor Setup
+
+To get the most out of Firebase in Cursor, follow these steps to install the agent skills and the MCP server.
+
+### 1. Install and Verify Firebase Skills
+Check if the skills are already installed before proceeding:
+
+1. **Check Local skills**: Run `npx skills list --agent cursor`. If the output includes `firebase-basics`, the skills are already installed locally.
+2. **Check Global skills**: If not found locally, check the global installation by running:
+   ```bash
+   npx skills list --global --agent cursor
+   ```
+   If the output includes `firebase-basics`, the skills are already installed globally.
+3. **Install Skills**: If both checks fail, run the following command to install the Firebase agent skills:
+   ```bash
+   npx skills add firebase/agent-skills --agent cursor --skill "*"
+   ```
+   *Note: Omit `--yes` and `--global` to choose the installation location manually. If prompted interactively in the terminal, ensure you send the appropriate user choices via standard input to complete the installation.*
+4. **Verify Installation**: Re-run the checks in steps 1 or 2 to confirm that `firebase-basics` is now available.
+
+### 2. Configure and Verify Firebase MCP Server
+The MCP server allows Cursor to interact directly with Firebase projects.
+
+1. **Locate `mcp.json`**: Find the configuration file for your operating system:
+   - Global: `~/.cursor/mcp.json`
+   - Project: `.cursor/mcp.json`
+   
+   *Note: If the directory or `mcp.json` file does not exist, create them and initialize the file with `{ "mcpServers": {} }` before proceeding.*
+2. **Check Existing Configuration**: Open `mcp.json` and check the `mcpServers` section for a `firebase` entry.
+   - It is already configured if the `command` is `"firebase"` OR if the `command` is `"npx"` with `"firebase-tools"` and `"mcp"` in the `args`.
+   - **Important**: If a valid `firebase` entry is found, the MCP server is already configured. **Skip step 3** and proceed directly to step 4.
+   
+   **Example valid configurations**:
+   ```json
+   "firebase": {
+     "command": "npx",
+     "args": ["-y", "firebase-tools@latest", "mcp"]
+   }
+   ```
+   OR
+   ```json
+   "firebase": {
+     "command": "firebase",
+     "args": ["mcp"]
+   }
+   ```
+3. **Add or Update Configuration**: If the `firebase` block is missing or incorrect, add it to the `mcpServers` object:
+   ```json
+   "firebase": {
+     "command": "npx",
+     "args": [
+       "-y",
+       "firebase-tools@latest",
+       "mcp"
+     ]
+   }
+   ```
+   *CRITICAL: Merge this configuration into the existing `mcp.json` file. You MUST preserve any other existing servers inside the `mcpServers` object.*
+4. **Verify Configuration**: Save the file and confirm the `firebase` block is present and properly formatted JSON.
+
+### 3. Restart and Verify Connection
+1. **Restart Cursor**: Instruct the user to restart the Cursor application. **Stop and wait** for their confirmation before proceeding.
+2. **Confirm Connection**: Check the MCP server list in the Cursor UI to confirm that the Firebase MCP server is connected.
@@ -0,0 +1,39 @@
+# Gemini CLI Setup
+
+To get the most out of Firebase in the Gemini CLI, follow these steps to install the agent extension and the MCP server.
+
+## Recommended: Installing Extensions
+
+The best way to get both the agent skills and the MCP server is via the Gemini extension.
+
+### 1. Install and Verify Firebase Extension
+Check if the extension is already installed before proceeding:
+
+1. **Check Existing Extensions**: Run `gemini extensions list`. If the output includes `firebase`, the extension is already installed.
+2. **Install Extension**: If not found, run the following command to install the Firebase agent skills and MCP server:
+   ```bash
+   gemini extensions install https://github.com/firebase/agent-skills
+   ```
+3. **Verify Installation**: Run the following checks to confirm installation:
+   - `gemini mcp list` -> Output should include `firebase-tools`.
+   - `gemini skills list` -> Output should include `firebase-basic`.
+
+### 2. Restart and Verify Connection
+1. **Restart Gemini CLI**: Instruct the user to restart the Gemini CLI if any new installation occurred. **Stop and wait** for their confirmation before proceeding.
+
+---
+
+## Alternative: Manual MCP Configuration (Project Scope)
+
+If the user only wants to use the MCP server for the current project:
+
+### 1. Configure and Verify Firebase MCP Server
+1. **Check Existing Configuration**: Run `gemini mcp list`. If the output includes `firebase-tools`, the MCP server is already configured.
+2. **Add the MCP Server**: If not found, run the following command to configure the Firebase MCP Server:
+   ```bash
+   gemini mcp add -e IS_GEMINI_CLI_EXTENSION=true firebase npx -y firebase-tools@latest mcp
+   ```
+3. **Verify Configuration**: Re-run `gemini mcp list` to confirm `firebase-tools` is connected.
+
+### 2. Restart and Verify Connection
+1. **Restart Gemini CLI**: Instruct the user to restart the Gemini CLI. **Stop and wait** for their confirmation before proceeding.
@@ -0,0 +1,70 @@
+# GitHub Copilot Setup
+
+To get the most out of Firebase with GitHub Copilot in VS Code, follow these steps to install the agent skills and the MCP server.
+
+## Recommended: Global Setup
+
+The agent skills and MCP server should be installed globally for consistent access across projects.
+
+### 1. Install and Verify Firebase Skills
+Check if the skills are already installed before proceeding:
+
+1. **Check Local skills**: Run `npx skills list --agent github-copilot`. If the output includes `firebase-basics`, the skills are already installed locally.
+2. **Check Global skills**: If not found locally, check the global installation by running:
+   ```bash
+   npx skills list --global --agent github-copilot
+   ```
+   If the output includes `firebase-basics`, the skills are already installed globally.
+3. **Install Skills**: If both checks fail, run the following command to install the Firebase agent skills:
+   ```bash
+   npx skills add firebase/agent-skills --agent github-copilot --skill "*"
+   ```
+   *Note: Omit `--yes` and `--global` to choose the installation location manually. If prompted interactively in the terminal, ensure you send the appropriate user choices via standard input to complete the installation.*
+4. **Verify Installation**: Re-run the checks in steps 1 or 2 to confirm that `firebase-basics` is now available.
+
+### 2. Configure and Verify Firebase MCP Server
+The MCP server allows GitHub Copilot to interact directly with Firebase projects.
+
+1. **Locate `mcp.json`**: Find the configuration file for your environment:
+   - Workspace: `.vscode/mcp.json`
+   - Global: User Settings `mcp.json` file.
+   
+   *Note: If the `.vscode/` directory or `mcp.json` file does not exist, create them and initialize the file with `{ "mcp": { "servers": {} } }` before proceeding.*
+2. **Check Existing Configuration**: Open the `mcp.json` file and check the `mcp.servers` object for a `firebase` entry.
+   - It is already configured if the `command` is `"firebase"` OR if the `command` is `"npx"` with `"firebase-tools"` and `"mcp"` in the `args`.
+   - **Important**: If a valid `firebase` entry is found, the MCP server is already configured. **Skip step 3** and proceed directly to step 4.
+   
+   **Example valid configurations**:
+   ```json
+   "firebase": {
+     "type": "stdio",
+     "command": "npx",
+     "args": ["-y", "firebase-tools@latest", "mcp"]
+   }
+   ```
+   OR
+   ```json
+   "firebase": {
+     "type": "stdio",
+     "command": "firebase",
+     "args": ["mcp"]
+   }
+   ```
+3. **Add or Update Configuration**: If the `firebase` block is missing or incorrect, add it to the `mcp.servers` object:
+   ```json
+   "firebase": {
+     "type": "stdio",
+     "command": "npx",
+     "args": [
+       "-y",
+       "firebase-tools@latest",
+       "mcp"
+     ]
+   }
+   ```
+   *CRITICAL: Merge this configuration into the existing `mcp.json` file under the `mcp.servers` object. You MUST preserve any other existing servers inside `mcp.servers`.*
+4. **Verify Configuration**: Save the file and confirm the `firebase` block is present and properly formatted JSON.
+
+### 3. Restart and Verify Connection
+1. **Restart VS Code**: Instruct the user to restart VS Code. **Stop and wait** for their confirmation before proceeding.
+2. **Confirm Connection**: Check the MCP server list in the VS Code Copilot UI to confirm that the Firebase MCP server is connected.
@@ -0,0 +1,65 @@
+# Other Agents Setup
+
+If you use another agent (like Windsurf, Cline, or Claude Desktop), follow these steps to install the agent skills and the MCP server.
+
+## Recommended: Global Setup
+
+The agent skills and MCP server should be installed globally for consistent access across projects.
+
+### 1. Install and Verify Firebase Skills
+Check if the skills are already installed before proceeding:
+
+1. **Check Local skills**: Run `npx skills list --agent <agent-name>`. If the output includes `firebase-basics`, the skills are already installed locally. Replace `<agent-name>` with the actual agent name, which can be found [here](https://github.com/vercel-labs/skills/blob/main/README.md).
+2. **Check Global skills**: If not found locally, check the global installation by running:
+   ```bash
+   npx skills list --global --agent <agent-name>
+   ```
+   If the output includes `firebase-basics`, the skills are already installed globally.
+3. **Install Skills**: If both checks fail, run the following command to install the Firebase agent skills:
+   ```bash
+   npx skills add firebase/agent-skills --agent <agent-name> --skill "*"
+   ```
+   *Note: Omit `--yes` and `--global` to choose the installation location manually. If prompted interactively in the terminal, ensure you send the appropriate user choices via standard input to complete the installation.*
+4. **Verify Installation**: Re-run the checks in steps 1 or 2 to confirm that `firebase-basics` is now available.
+
+### 2. Configure and Verify Firebase MCP Server
+The MCP server allows the agent to interact directly with Firebase projects.
+
+1. **Locate MCP Configuration**: Find the configuration file for your agent (e.g., `~/.codeium/windsurf/mcp_config.json`, `cline_mcp_settings.json`, or `claude_desktop_config.json`).
+   
+   *Note: If the document or its containing directory does not exist, create them and initialize the file with `{ "mcpServers": {} }` before proceeding.*
+2. **Check Existing Configuration**: Open the configuration file and check the `mcpServers` section for a `firebase` entry.
+   - It is already configured if the `command` is `"firebase"` OR if the `command` is `"npx"` with `"firebase-tools"` and `"mcp"` in the `args`.
+   - **Important**: If a valid `firebase` entry is found, the MCP server is already configured. **Skip step 3** and proceed directly to step 4.
+   
+   **Example valid configurations**:
+   ```json
+   "firebase": {
+     "command": "npx",
+     "args": ["-y", "firebase-tools@latest", "mcp"]
+   }
+   ```
+   OR
+   ```json
+   "firebase": {
+     "command": "firebase",
+     "args": ["mcp"]
+   }
+   ```
+3. **Add or Update Configuration**: If the `firebase` block is missing or incorrect, add it to the `mcpServers` object:
+   ```json
+   "firebase": {
+     "command": "npx",
+     "args": [
+       "-y",
+       "firebase-tools@latest",
+       "mcp"
+     ]
+   }
+   ```
+   *CRITICAL: Merge this configuration into the existing file. You MUST preserve any other existing servers inside the `mcpServers` object.*
+4. **Verify Configuration**: Save the file and confirm the `firebase` block is present and properly formatted JSON.
+
+### 3. Restart and Verify Connection
+1. **Restart Agent**: Instruct the user to restart the agent application. **Stop and wait** for their confirmation before proceeding.
+2. **Confirm Connection**: Check the MCP server list in the agent's UI to confirm that the Firebase MCP server is connected.
@@ -0,0 +1,69 @@
+# Firebase Web Setup Guide
+
+## 1. Create a Firebase Project and App
+If you haven't already created a project:
+
+```bash
+npx -y firebase-tools@latest projects:create
+```
+
+Register your web app:
+```bash
+npx -y firebase-tools@latest apps:create web my-web-app
+```
+(Note the **App ID** returned by this command).
+
+## 2. Installation
+Install the Firebase SDK via npm:
+
+```bash
+npm install firebase
+```
+
+## 3. Initialization
+Create a `firebase.js` (or `firebase.ts`) file. You can fetch your config object using the CLI:
+
+```bash
+npx -y firebase-tools@latest apps:sdkconfig <APP_ID>
+```
+
+Copy the output config object into your initialization file:
+
+```javascript
+import { initializeApp } from "firebase/app";
+import { getAuth } from "firebase/auth";
+
+// Your web app's Firebase configuration
+const firebaseConfig = {
+  apiKey: "API_KEY",
+  authDomain: "PROJECT_ID.firebaseapp.com",
+  projectId: "PROJECT_ID",
+  storageBucket: "PROJECT_ID.firebasestorage.app",
+  messagingSenderId: "SENDER_ID",
+  appId: "APP_ID",
+  measurementId: "G-MEASUREMENT_ID"
+};
+
+// Initialize Firebase
+const app = initializeApp(firebaseConfig);
+const auth = getAuth(app);
+
+export { app };
+```
+
+## 4. Using Services
+Import specific services as needed (Modular API):
+
+```javascript
+import { getFirestore, collection, getDocs } from "firebase/firestore";
+import { app } from "./firebase"; // Import the initialized app
+
+const db = getFirestore(app);
+
+async function getUsers() {
+  const querySnapshot = await getDocs(collection(db, "users"));
+  querySnapshot.forEach((doc) => {
+    console.log(`${doc.id} => ${doc.data()}`);
+  });
+}
+```