# Django Firebase MCP

A comprehensive Django app that implements Firebase Model Context Protocol (MCP) server, enabling AI agents to interact with Firebase services through a standardized protocol.

## 🚀 Quick Start

Get up and running in under 5 minutes with the standalone Firebase agent for testing.

### Prerequisites

- Python 3.11+
- Firebase project with Admin SDK
- Git (optional)
- Redis (optional, for persistent state management)

### 1. Clone & Setup

```bash
git clone https://github.com/your-repo/django-firebase-mcp.git
cd django-firebase-mcp
```

### 2. Install Dependencies

```bash
pip install -r requirements.txt
```

### 3. Firebase Setup

#### Get Firebase Credentials

1. Go to [Firebase Console](https://console.firebase.google.com/)
2. Select your project (or create a new one)
3. Navigate to **Project Settings** → **Service Accounts**
4. Click **"Generate new private key"**
5. Download the JSON file and save it as `credentials.json` in the project root

#### Enable Firebase Services

Make sure these services are enabled in your Firebase project:

- **Authentication** (for user management)
- **Firestore Database** (for document storage)
- **Cloud Storage** (for file uploads)

### 4. Environment Configuration

Create a `.env` file in the project root:

```env
# Firebase Configuration
SERVICE_ACCOUNT_KEY_PATH=credentials.json
FIREBASE_STORAGE_BUCKET=your-project-id.appspot.com

# MCP Configuration
MCP_TRANSPORT=http
MCP_HOST=127.0.0.1
MCP_PORT=8001

# Django Settings
DEBUG=True
SECRET_KEY=your-secret-key-here
```

**⚠️ Important:** Replace `your-project-id` with your actual Firebase project ID.

### 5. State Management Setup

The Firebase MCP agent uses state management for conversation persistence. Choose one option:

#### Option A: Redis (Recommended for Production)

Install and run Redis on port 6379:

```powershell
# Install Redis using Chocolatey
choco install redis-64

# Or download from: https://github.com/microsoftarchive/redis/releases
# Then run Redis server
redis-server
```

Add to your `.env` file:

```env
# Redis Configuration
REDIS_URL=redis://localhost:6379
USE_REDIS=true
```

#### Option B: InMemorySaver (Quick Testing)

For quick testing without Redis, the agent will automatically use InMemorySaver. No additional setup required.

Add to your `.env` file:

```env
# Memory-based state (no persistence)
USE_REDIS=false
```

**Note:** InMemorySaver doesn't persist conversations between restarts, while Redis maintains state across sessions.

### 6. Quick Test with Standalone Agent

Test your setup immediately with the standalone Firebase agent:

```bash
# Run the standalone agent
python firebase_admin_mcp/standalone_firebase_agent.py
```

You should see:

```
🔥 Firebase MCP Agent Ready!
Type 'help' for available commands, 'quit' to exit.

>
```

Try these commands:

```
> List all Firebase collections
> Check Firebase health status
> help
> quit
```

### 7. Full Django Setup (Optional)

For full Django integration:

```bash
# Apply migrations
python manage.py migrate

# Create superuser (optional)
python manage.py createsuperuser

# Run Django development server
python manage.py runserver 8001
```

The MCP server will be available at: `http://127.0.0.1:8001/mcp/`

## 🛠️ Management Commands

### Core Commands

```bash
# Run standalone Firebase agent (quick testing)
python firebase_admin_mcp/standalone_firebase_agent.py

# Run MCP server via Django
python manage.py runserver 8001

# Run MCP server in stdio mode (for MCP clients)
python manage.py run_mcp --transport stdio

# Run MCP server in HTTP mode
python manage.py run_mcp --transport http --host 127.0.0.1 --port 8001

# Run standalone agent via Django management command
python manage.py run_standalone_agent
```

### Testing Commands

```bash
# Test Firebase connectivity
python firebase_admin_mcp/tests/test_firebase_connection.py

# Test MCP server completeness
python firebase_admin_mcp/tests/test_mcp_complete.py

# Demo Firebase agent
python firebase_admin_mcp/tests/demo_firebase_agent.py

# Demo standalone agent
python firebase_admin_mcp/demo_standalone_agent.py
```

## 🔧 Available Tools

The MCP server provides **14 Firebase tools** across three categories:

### 🔐 Authentication (4 tools)

- `firebase_verify_token` - Verify Firebase ID tokens
- `firebase_create_custom_token` - Create custom auth tokens
- `firebase_get_user` - Get user info by UID
- `firebase_delete_user` - Delete user accounts

### 📚 Firestore Database (6 tools)

- `firestore_list_collections` - List all collections
- `firestore_create_document` - Create new documents
- `firestore_get_document` - Retrieve documents
- `firestore_update_document` - Update documents
- `firestore_delete_document` - Delete documents
- `firestore_query_collection` - Query with filters

### 🗄️ Cloud Storage (4 tools)

- `storage_list_files` - List files with filtering
- `storage_upload_file` - Upload files
- `storage_download_file` - Download files
- `storage_delete_file` - Delete files

## 🧪 Quick Testing

### Test Server Health

```bash
curl http://127.0.0.1:8001/mcp/
```

### Test a Firebase Tool

```bash
curl -X POST http://127.0.0.1:8001/mcp/ \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "firestore_list_collections",
      "arguments": {}
    },
    "id": 1
  }'
```

## 🤖 AI Agent Integration

### LangChain Example

```python
from langchain_openai import ChatOpenAI
from langgraph.prebuilt import create_react_agent

# Import Firebase tools
from firebase_admin_mcp.tools.agents.firebase_mcp_client import ALL_FIREBASE_TOOLS

# Create agent with Firebase capabilities
model = ChatOpenAI(model="gpt-4")
agent = create_react_agent(
    model=model,
    tools=ALL_FIREBASE_TOOLS,
    prompt="You are a Firebase assistant with full database and storage access."
)

# Use the agent
response = agent.invoke({
    "messages": [{"role": "user", "content": "Show me all my Firestore collections"}]
})
```

## 📚 Documentation

This project includes comprehensive documentation:

- **[FIREBASE_ADMIN_MCP.md](FIREBASE_ADMIN_MCP.md)** - Complete technical documentation

  - Detailed API reference
  - All tool specifications
  - Advanced configuration
  - Security considerations
  - Production deployment guide

- **[STANDALONE_AGENT.md](STANDALONE_AGENT.md)** - Standalone agent documentation
  - Self-contained Firebase agent
  - Complete feature overview
  - Usage examples
  - Integration patterns

## 🔧 Troubleshooting

### Common Issues

**Problem:** `Default app does not exist` error
**Solution:** Verify `credentials.json` path in `.env` file

**Problem:** Server won't start
**Solution:** Check if port 8001 is available: `netstat -an | findstr :8001`

**Problem:** Firebase connection fails
**Solution:** Verify Firebase services are enabled in console

**Problem:** Import errors
**Solution:** Ensure all dependencies installed: `pip install -r requirements.txt`

**Problem:** Redis connection fails
**Solution:** Verify Redis is running: `redis-cli ping` (should return "PONG")

**Problem:** State not persisting between sessions
**Solution:** Check Redis configuration or switch to Redis from InMemorySaver

## 🎯 What's Next?

1. **Explore the Standalone Agent** - Perfect for quick testing and demos
2. **Read the Full Documentation** - See FIREBASE_ADMIN_MCP.md for complete details
3. **Integrate with Your AI Agents** - Use the MCP tools in your applications
4. **Customize for Your Needs** - Extend with additional Firebase operations

## 📝 Project Structure

```
django-firebase-mcp/
├── README.md                          # This file
├── FIREBASE_ADMIN_MCP.md             # Complete documentation
├── STANDALONE_AGENT.md               # Standalone agent guide
├── requirements.txt                   # Python dependencies
├── credentials.json                   # Firebase credentials (you create this)
├── .env                              # Environment variables (you create this)
├── manage.py                         # Django management
├── firebase_admin_mcp/               # Main MCP app
│   ├── standalone_firebase_agent.py  # Standalone agent
│   ├── tools/                        # Firebase MCP tools
│   ├── management/commands/          # Django commands
│   └── tests/                        # Test suite
└── django_firebase_mcp/             # Django project settings
```

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Test your changes
4. Submit a pull request

## 📄 License

MIT License - see LICENSE file for details.

---

**🔥 Ready to supercharge your AI agents with Firebase?**

Start with the standalone agent, then explore the full documentation for advanced usage!
