MCP Tools¶

The CyberEco MCP server exposes 7 tools organized into three categories: data layer operations, permission checks, and schema exploration.

Data Layer Tools¶

These tools provide CRUD access to Firestore collections. They require a valid Firebase service account configured via GOOGLE_APPLICATION_CREDENTIALS or FIREBASE_SERVICE_ACCOUNT_KEY.

`get_document`¶

Fetch a single document from a Firestore collection by its ID.

Parameters:

Name	Type	Required	Description
`collection`	`string`	Yes	The Firestore collection name (must be in the allowlist)
`document_id`	`string`	Yes	The document ID to retrieve

Returns: JSON string of the document data with the id field injected, or an error message if not found.

Validation:

Collection name must be in the allowed collection whitelist
Document ID must be a non-empty string

Example: Fetch a user record

Call:

{
  "tool": "get_document",
  "arguments": {
    "collection": "users",
    "document_id": "abc123"
  }
}

Response:

{
  "id": "abc123",
  "email": "jane@example.com",
  "displayName": "Jane Doe",
  "apps": ["hub", "justsplit"],
  "isAdmin": false,
  "createdAt": "2025-01-15T10:30:00Z"
}

Example: Document not found

Response:

{
  "error": "Document abc123 not found in users"
}

`query_collection`¶

Query a Firestore collection with optional filters.

Parameters:

Name	Type	Required	Default	Description
`collection`	`string`	Yes	--	The Firestore collection name
`filters`	`list[dict]`	No	`None`	List of filter objects (see below)
`limit`	`int`	No	`20`	Maximum documents to return (capped at 100)

Filter Object Format:

{
  "field": "status",
  "operator": "==",
  "value": "active"
}

Supported Operators:

Operator	Description	Example Value
`==`	Equal to	`"active"`
`!=`	Not equal to	`"deleted"`
`<`	Less than	`100`
`<=`	Less than or equal	`100`
`>`	Greater than	`0`
`>=`	Greater than or equal	`50`
`in`	In array	`["active", "beta"]`
`array-contains`	Array contains value	`"hub"`

Operator validation

Any operator not in the allowlist above will be rejected before the query reaches Firestore. This prevents injection of unsupported or dangerous operators.

Example: Query active apps

Call:

{
  "tool": "query_collection",
  "arguments": {
    "collection": "apps",
    "filters": [
      {"field": "status", "operator": "==", "value": "active"}
    ],
    "limit": 10
  }
}

Response:

href="#__codelineno-5-1">{ "collection": "apps", "count": 3, "limit": 10, "data": [ { "id": "hub", "name": "CyberEco Hub", "status": "active", "category": "identity" }, { "id": "justsplit", "name": "JustSplit", "status": "active", "category": "finance" }, { "id": "demos", "name": "Demos", "status": "active", "category": "governance" } ] }

Example: Query users who have access to an app

Call:

{
  "tool": "query_collection",
  "arguments": {
    "collection": "users",
    "filters": [
      {"field": "apps", "operator": "array-contains", "value": "justsplit"}
    ]
  }
}

`create_document`¶

Create a new document in a Firestore collection.

Write protection

This tool requires the MCP_ENABLE_WRITES=true environment variable to be set. Without it, all write operations are rejected with an error.

Parameters:

Name	Type	Required	Description
`collection`	`string`	Yes	The Firestore collection name
`data`	`dict`	Yes	The document data as a dictionary
`document_id`	`string`	No	Specific document ID. If omitted, Firestore auto-generates one.

Returns: JSON string with the created document ID and success status.

Example: Create a notification

Call:

{
  "tool": "create_document",
  "arguments": {
    "collection": "notifications",
    "data": {
      "userId": "abc123",
      "type": "info",
      "title": "Welcome to CyberEco",
      "message": "Your account has been set up successfully.",
      "read": false,
      "appId": "hub",
      "createdAt": "2025-06-01T12:00:00Z"
    }
  }
}

Response:

{
  "id": "auto-generated-id-here",
  "success": true
}

Example: Create with specific ID

Call:

{
  "tool": "create_document",
  "arguments": {
    "collection": "apps",
    "document_id": "my-new-app",
    "data": {
      "name": "My New App",
      "description": "A CyberEco ecosystem application",
      "status": "beta",
      "category": "community"
    }
  }
}

Response:

{
  "id": "my-new-app",
  "success": true
}

Example: Writes disabled

Response (when MCP_ENABLE_WRITES is not set):

{
  "error": "Write operations are disabled. Set MCP_ENABLE_WRITES=true to enable.",
  "success": false
}

Permission Tools¶

These tools check and list user permissions using the CyberEco 4-tier role hierarchy.

Role Hierarchy¶

owner (4)  >  admin (3)  >  moderator (2)  >  member (1)

A user with a higher-tier role automatically satisfies checks for lower-tier roles. For example, an admin (level 3) passes a moderator (level 2) check.

`check_permission`¶

Check if a user has a specific permission for an app.

Parameters:

Name	Type	Required	Default	Description
`user_id`	`string`	Yes	--	The user ID to check permissions for
`app_id`	`string`	Yes	--	The application ID to check access to
`permission`	`string`	No	`"access"`	The permission to check (see below)

Permission Types:

Permission Value	Check Type	Description
`"access"`	App access	Does the user have access to this app at all?
`"owner"`	Role check	Does the user have the `owner` role (level 4)?
`"admin"`	Role check	Does the user have `admin` or higher (level >= 3)?
`"moderator"`	Role check	Does the user have `moderator` or higher (level >= 2)?
`"member"`	Role check	Does the user have `member` or higher (level >= 1)?
Any other string	Feature check	Is this feature name in the user's `features` array?

Evaluation Order:

Check if user document exists
Check if user is a global admin (isAdmin: true) -- grants all permissions
Check if app_id is in the user's apps array
Find the AppPermission entry matching the app_id
Evaluate based on permission type (access / role / feature)

Example: Check basic app access

Call:

{
  "tool": "check_permission",
  "arguments": {
    "user_id": "abc123",
    "app_id": "justsplit"
  }
}

Response (access granted):

{
  "user_id": "abc123",
  "app_id": "justsplit",
  "permission": "access",
  "granted": true,
  "roles": ["admin"],
  "features": ["dashboard", "export", "settings"]
}

Example: Check admin role

Call:

{
  "tool": "check_permission",
  "arguments": {
    "user_id": "abc123",
    "app_id": "justsplit",
    "permission": "admin"
  }
}

Response:

{
  "user_id": "abc123",
  "app_id": "justsplit",
  "permission": "admin",
  "granted": true,
  "user_roles": ["admin"],
  "reason": "Role check: requires 'admin' (level 3)"
}

Example: Check feature permission

Call:

{
  "tool": "check_permission",
  "arguments": {
    "user_id": "abc123",
    "app_id": "justsplit",
    "permission": "export"
  }
}

Response:

{
  "user_id": "abc123",
  "app_id": "justsplit",
  "permission": "export",
  "granted": true,
  "available_features": ["dashboard", "export", "settings"],
  "reason": "Feature check: 'export' found in user features"
}

Example: Permission denied

Response:

{
  "user_id": "xyz789",
  "app_id": "justsplit",
  "permission": "access",
  "granted": false,
  "reason": "User does not have access to app 'justsplit'"
}

`list_user_permissions`¶

List all permissions for a user across all apps.

Parameters:

Name	Type	Required	Description
`user_id`	`string`	Yes	The user ID to list permissions for

Returns: The user's complete permission profile including global admin status, app access list, and per-app permission entries.

Example: List all permissions

Call:

{
  "tool": "list_user_permissions",
  "arguments": {
    "user_id": "abc123"
  }
}

Response:

{
  "user_id": "abc123",
  "is_admin": false,
  "apps": ["hub", "justsplit", "demos"],
  "permissions": [
    {
      "appId": "hub",
      "roles": ["member"],
      "features": ["dashboard", "profile"]
    },
    {
      "appId": "justsplit",
      "roles": ["admin"],
      "features": ["dashboard", "export", "settings"]
    },
    {
      "appId": "demos",
      "roles": ["moderator"],
      "features": ["dashboard", "proposals", "voting"]
    }
  ]
}

Schema Tools¶

These tools provide metadata about the CyberEco data model. They work offline -- no Firestore connection required.

`list_collections`¶

List all available Firestore collections in the CyberEco ecosystem.

Parameters: None.

Returns: JSON array of collection summaries with name, description, document type, owner, and field count.

Example: List all collections

Call:

{
  "tool": "list_collections",
  "arguments": {}
}

Response:

{
  "collections": [
    {
      "name": "users",
      "description": "Central user records for the CyberEco ecosystem",
      "document_type": "HubUser / SharedUserProfile",
      "owner": "Hub",
      "field_count": 10
    },
    {
      "name": "transactions",
      "description": "Cross-app financial records",
      "document_type": "Transaction",
      "owner": "Hub",
      "field_count": 10
    },
    {
      "name": "groups",
      "description": "Cross-app group memberships",
      "document_type": "SharedGroup",
      "owner": "Hub",
      "field_count": 6
    }
  ]
}

`describe_collection`¶

Get the full schema for a specific Firestore collection, including detailed field definitions matching the TypeScript types in @cyber-eco/types.

Parameters:

Name	Type	Required	Description
`collection_name`	`string`	Yes	The collection name to describe

Example: Describe the users collection

Call:

{
  "tool": "describe_collection",
  "arguments": {
    "collection_name": "users"
  }
}

Response:

{
  "collection": "users",
  "description": "Central user records for the CyberEco ecosystem",
  "document_type": "HubUser / SharedUserProfile",
  "owner": "Hub",
  "fields": {
    "id": {
      "type": "string",
      "description": "User ID (matches Firebase Auth UID)"
    },
    "email": {
      "type": "string",
      "description": "User email address"
    },
    "displayName": {
      "type": "string",
      "description": "User display name"
    },
    "apps": {
      "type": "string[]",
      "description": "List of app IDs user has access to"
    },
    "isAdmin": {
      "type": "boolean",
      "description": "Global admin flag"
    }
  }
}

Example: Collection not found

Response:

{
  "error": "Collection 'nonexistent' not found",
  "available_collections": [
    "users", "transactions", "groups", "notifications",
    "permissions", "resourcePermissions", "permissionLogs",
    "apps", "friendships", "webhookRegistrations",
    "userPreferences", "dataSyncStatus"
  ]
}

Available Collections¶

The following 12 collections are accessible through the data layer tools:

Collection	Document Type	Owner	Description
`users`	HubUser / SharedUserProfile	Hub	Central user records
`transactions`	Transaction	Hub	Cross-app financial records
`groups`	SharedGroup	Hub	Cross-app group memberships
`notifications`	Notification	Hub	Cross-app notification queue
`permissions`	ResourcePermission	Hub	Fine-grained resource access
`resourcePermissions`	ResourcePermission	Hub	Resource-level permissions with compound key
`permissionLogs`	PermissionChangeLog	Hub	Audit trail for permission changes
`apps`	App	Hub	App registry for the ecosystem
`friendships`	Friendship	Shared	Social connections between users
`webhookRegistrations`	WebhookRegistration	Hub	External webhook endpoints
`userPreferences`	UserPreferences	Hub	Extended user preferences
`dataSyncStatus`	DataSyncStatus	Hub	Per-user, per-app sync state

Error Handling¶

All tools return JSON responses. Errors follow a consistent format:

{
  "error": "Description of the error"
}

Common error scenarios:

Error	Cause	Resolution
`Collection 'X' is not allowed`	Collection name not in whitelist	Use `list_collections` to see valid names
`document_id is required`	Empty or missing document ID	Provide a non-empty string
`Write operations are disabled`	`MCP_ENABLE_WRITES` not set	Set `MCP_ENABLE_WRITES=true` in environment
`Invalid operator: 'X'`	Unsupported filter operator	Use one of: `==`, `!=`, `<`, `<=`, `>`, `>=`, `in`, `array-contains`
`Failed to initialize Firestore`	Missing credentials	Set `GOOGLE_APPLICATION_CREDENTIALS` or `FIREBASE_SERVICE_ACCOUNT_KEY`

MCP Tools¶

Data Layer Tools¶

get_document¶

query_collection¶

create_document¶

Permission Tools¶

Role Hierarchy¶

check_permission¶

list_user_permissions¶

Schema Tools¶

list_collections¶

describe_collection¶

Available Collections¶

Error Handling¶

`get_document`¶

`query_collection`¶

`create_document`¶

`check_permission`¶

`list_user_permissions`¶

`list_collections`¶

`describe_collection`¶