Firebase DAM MCP Server

Firebase MCP服务器

用于访问Firebase Firestore和存储的模型上下文协议（MCP）服务器实现，使用Python和FastMCP构建。

概述

此MCP服务器通过MCP兼容工具提供对Firebase Firestore集合和存储桶的安全访问。它专为具有预定义集合和访问模式的数字资产管理（DAM）系统而设计。

特性

• MCP协议合规性：完全符合官方MCP规范
• 消防通道：查询 assets, versions，以及 comments 收藏
• 存储访问：搜索Firebase存储桶中的文件
• 灵活过滤：支持各种过滤运算符，包括日期范围
• 双重运输：支持stdio和HTTP传输
• Docker支持：使用Docker进行容器化部署
• 安全：基于服务帐户的受限访问身份验证

安装

先决条件

• Python 3.11或更高版本
• 启用Firestore和存储的Firebase项目
• 具有适当权限的Google Cloud服务帐户

依赖项

pip install -r requirements.txt

必需的Python包

• fastmcp>=0.1.0
• firebase-admin>=6.5.0
• python-dateutil>=2.8.2
• typing-extensions>=4.9.0

用法

命令行

# Run with stdio transport (for MCP clients)
python main.py --google-credentials /path/to/service-account.json --transport stdio

# Run with HTTP transport (for web access)
python main.py --google-credentials /path/to/service-account.json --transport http --host 0.0.0.0 --port 8000

# Enable debug logging
python main.py --google-credentials /path/to/service-account.json --debug

码头工人

# Build the image
docker build -t firebase-mcp-server .

# Run with docker-compose
docker-compose up -d

# Run manually
docker run -p 8000:8000 -v /path/to/credentials.json:/app/credentials.json firebase-mcp-server

配置

克劳德桌面

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "firebase-dam": {
      "command": "python",
      "args": [
        "/path/to/mcp-server/main.py",
        "--google-credentials",
        "/path/to/your/service-account-credentials.json",
        "--transport",
        "stdio"
      ],
      "env": {
        "PYTHONPATH": "/path/to/mcp-server"
      }
    }
  }
}

服务帐户设置

⚠️ 安全警告：切勿将凭据文件提交到版本控制！

1. 在Firebase项目中创建服务帐户
2. 下载JSON凭据文件
3. 复制 credentials.json.example 向 credentials.json 并填写您的实际值
4. 授予服务帐户以下权限：

- 四大 ： Firebase Rules System, Cloud Datastore User - 储存： Storage Object Viewer

可用工具

搜索资产

在Firestore资产集合中搜索资产。

架构：

• id：string-唯一资产标识符
• title：string-资产标题
• description：string-资产描述
• category：string-资产类别
• tags：string\[\]-标记数组
• uploader：string-上传的用户ID
• uploadedAt：string-ISO8601时间戳
• updatedAt：string-ISO8601时间戳
• visibility：“公共”|“私人”
• latestVersionId：string（可选）

例子：

{
  "category": "image",
  "tags": ["banner"],
  "visibility": "public",
  "uploadedAt": ">=2024-06-01"
}

搜索版本

在Firestore版本集合中搜索版本。

架构：

• id：string-唯一版本标识符
• assetId：string-父资产ID
• version：string-版本标识符
• fileUrl：string-文件的URL
• fileName：string-原始文件名
• fileType：string-MIME类型
• fileSize：number-文件大小（字节）
• updatedAt：string-ISO8601时间戳
• updatedBy：string-更新的用户ID

例子：

{
  "assetId": "asset123",
  "fileType": "image/png",
  "updatedAt": ">=2024-06-01"
}

搜索_注释

在Firestore评论集合中搜索评论。

架构：

• id：string-唯一注释标识符
• assetId：string-正在评论的资产
• user：string-发表评论的用户ID
• text：string-注释文本
• createdAt：string-ISO8601时间戳

例子：

{
  "assetId": "asset123",
  "user": "user456",
  "createdAt": ">=2024-06-01"
}

搜索资产文件

在Firebase存储桶中搜索文件。

退货：

• name：string-完整文件路径
• size：number-文件大小（字节）
• contentType：string-MIME类型
• uploadedAt：string-ISO8601时间戳
• downloadUrl：string-公共URL
• etag：string-ETag用于版本控制
• generation：number-文件生成

例子：

{
  "prefix": "assets/",
  "contentType": "image/png",
  "uploadedAt": ">=2024-06-01"
}

过滤器操作员

• == -相等（默认）
• >= -大于或等于（日期）
• <= -小于或等于（日期）
• array_contains_any -数组包含任何值
• in -值在提供的数组中

建筑

src/
├── mcp_server_firebase/
│   ├── __init__.py
│   ├── server.py          # FastMCP server with tools
│   └── firebase_client.py # Firebase client wrapper
├── main.py                # Entry point
├── requirements.txt       # Python dependencies
├── Dockerfile            # Container configuration
├── docker-compose.yml    # Docker Compose setup
└── examples/             # Configuration examples

安全说明

• 集合和bucket名称在源代码中是硬编码的
• 访问仅限于只读操作
• 身份验证需要服务帐户凭据
• 没有记录或暴露敏感数据

发展

设置开发环境

# Clone the repository
git clone https://github.com/lt012071/dam-firebase-mcp-server.git
cd dam-firebase-mcp-server

# Install development dependencies
make install-dev

# Or manually:
pip install -r requirements.txt
pip install -r requirements-dev.txt
pre-commit install

运行测试

# Run all unit tests (recommended for development)
make test
# or: pytest tests/unit/ -v -m "unit"

# Run integration tests
make test-integration
# or: pytest tests/integration/ -v -m "integration and not slow"

# Run all tests with coverage
make test-all
# or: pytest tests/ --cov=src --cov-report=html

# Run slow tests (only on CI)
make test-slow
# or: pytest tests/integration/ -v -m "slow"

# Run tests in watch mode (for development)
make test-watch

代码质量

# Format code
make format
# or: black src/ tests/ && isort src/ tests/

# Run linting
make lint
# or: flake8 src/ tests/

# Type checking
make type-check
# or: mypy src/ --ignore-missing-imports

# Security scanning
make security
# or: bandit -r src/ && safety check

# Run all quality checks
make quality

# Run pre-commit hooks
make pre-commit

测试覆盖率

# Generate HTML coverage report
make coverage-html
# Open htmlcov/index.html in browser

# Generate XML coverage report (for CI)
make coverage-xml

Docker测试

# Build and test Docker image
make docker-build
make docker-test

# Run with docker-compose
make docker-compose-up

测试类别

• 单元测试 (tests/unit/)：具有模拟依赖关系的快速测试
• 集成测试 (tests/integration/)：测试MCP协议通信
• 慢速测试 （标有 @pytest.mark.slow)：性能和压力测试

写作测试

# Unit test example
@pytest.mark.unit
def test_firebase_client_init(test_credentials_file):
    client = FirebaseClient(test_credentials_file)
    assert client.credentials_path == test_credentials_file

# Integration test example  
@pytest.mark.integration
@pytest.mark.asyncio
async def test_mcp_tool_via_protocol(test_credentials_file):
    # Test actual MCP communication
    pass

# Slow test example
@pytest.mark.slow
@pytest.mark.integration
async def test_large_dataset_handling():
    # Performance test with large datasets
    pass

持续集成

测试在以下情况下自动运行：

• 推到 main/master 分支
• 拉取请求创建
• 多个Python版本（3.10、3.11、3.12）

CI管道包括：

• 覆盖范围的单元测试
• 集成测试
• 代码质量检查（linting、打字、安全）
• Docker构建验证

故障排除

常见问题

1. 未找到凭据：确保服务帐户JSON文件路径正确
2. 权限不足：验证服务帐户是否具有所需的Firebase权限
3. 连接问题：检查网络连接和Firebase项目设置
4. 导入错误：确保所有依赖项都已正确安装

调试模式

启用调试日志记录以查看详细的操作日志：

python main.py --google-credentials /path/to/credentials.json --debug

许可证

该项目根据MIT许可证获得许可。