spec.md — Athena

WHEN environment is emulator
THEN initialize firebase-admin with projectId only and set Firestore host to 127.0.0.1:{port} with SSL disabled

Scenario: Staging/prod connection

WHEN environment is staging or prod
THEN require service account JSON path from ROOMY_MCP_SERVICE_ACCOUNT_PATH_STAGING or ROOMY_MCP_SERVICE_ACCOUNT_PATH_PROD

Scenario: Missing service account

WHEN environment is staging or prod and service account path is not set
THEN server fails fast with a clear error message

Requirement: Datamodel Registry

The system SHALL derive entity definitions from YAML files in roomy-firebase/data_models/.

Scenario: Scan datamodels

WHEN server initializes
THEN recursively scan data_models/**/*.yaml for datamodel definitions

Scenario: Parse entity locations

WHEN a YAML file contains locations array
THEN parse each location to extract collectionPathTemplate, pathParams, and docIdParamName

Scenario: Placeholder parsing

WHEN location contains {$id} or {code} style placeholders
THEN extract placeholder name as parameter

Scenario: Entity key derivation

WHEN location is scrapingSessions/{$sessionId}/logs/{$id}
THEN entity key is scrapingSessions_logs (static segments joined by underscore)

Scenario: Ignore non-entity YAMLs

WHEN a YAML file has no locations field
THEN skip it during registry loading

Requirement: Schema Tools

The system SHALL provide list_collections and get_schema tools for schema discovery.

Scenario: List collections

WHEN list_collections tool is called
THEN return array of { type, dtoName, location, collectionPathTemplate, pathParams, docIdParamName }

Scenario: Get schema

WHEN get_schema tool is called with { type: "users" }
THEN return schema with timestampFormat: { __time__: "<ISO string>" } and fields map

Requirement: Single Document CRUD

The system SHALL provide get_doc, list_docs, create_doc, update_doc, and delete_doc tools.

Scenario: Get document

WHEN get_doc is called with { type, id }
THEN return document data or null if not found

Scenario: List documents

WHEN list_docs is called with { type, limit? }
THEN return array of documents

Scenario: Create document

WHEN create_doc is called with { type, data }
THEN create document with auto-generated ID and ensure createdAt and updatedAt timestamps

Scenario: Create document with ID

WHEN create_doc is called with { type, id, data }
THEN create document with specified ID

Scenario: Update document

WHEN update_doc is called with { type, id, data }
THEN update document and ensure updatedAt timestamp

Scenario: Upsert document

WHEN update_doc is called with { type, id, data, upsert: true }
THEN create document if missing (merge=true)

Scenario: Delete document

WHEN delete_doc is called with { type, id }
THEN return { id, deleted: true } if deleted, { id, deleted: false } if not found

Requirement: Batch CRUD

The system SHALL provide create_docs, update_docs, and delete_docs tools for batch operations.

Scenario: Batch create

WHEN create_docs is called with { operations: [...] }
THEN create all documents with timestamps

Scenario: Batch update

WHEN update_docs is called with { operations: [...], upsert: true }
THEN upsert all documents

Scenario: Batch delete

WHEN delete_docs is called with { operations: [...] }
THEN delete all specified documents

Scenario: Batch limit (non-transaction)

WHEN transaction=false and operations exceed 500
THEN reject with error

Requirement: Subcollection Support

The system SHALL support subcollection paths via pathParams.

Scenario: Subcollection CRUD

WHEN entity has pathParams (e.g., cleaningSchedules_cleaningTimeSlots)
THEN require pathParams object in tool calls to resolve collection path

Requirement: Timestamp Serialization

The system SHALL serialize all Firestore timestamps as { "__time__": "<ISO8601>" }.

Scenario: Output serialization

WHEN reading a document with Firestore Timestamp or Date fields
THEN convert to { "__time__": "2025-12-08T23:39:28.359Z" } format

Scenario: Input deserialization

WHEN writing a document with { "__time__": "..." } fields
THEN convert to Firestore Timestamp

Requirement: MCP Configuration

The system SHALL be configurable via .mcp.json for Cursor/Claude Code integration.

Scenario: MCP entry

WHEN .mcp.json contains roomy-firestore-mcp entry
THEN Cursor/Claude Code can connect to the server via stdio

Reacties

Nog geen reacties

Athena — roomy-mobile/archive/changes/2026-01-05-add-roomy-firestore-mcp/specs/firestore-mcp/spec.md

ADDED Requirements

Requirement: MCP Server Package

Scenario: Server starts successfully

Scenario: Server logs to stderr only

Requirement: Environment Management

Scenario: Get current environment

Scenario: Set environment

Scenario: Default environment

Requirement: Project Configuration Discovery

Scenario: Load project IDs

Scenario: Load emulator port

Scenario: Missing configuration

Requirement: Firestore Connection

Scenario: Emulator connection