Roze MCP Bridge Server

A hardened MCP (Model Context Protocol) server that provides dev-only proxies, contract tools, and inter-agent communication for A1 (Astro), A2 (Flutter), and A3 (Backend) to collaborate seamlessly.

Features

• Contract-first API: OpenAPI spec as source of truth
• Schema validation: JSON Schema validation with AJV before proxying
• Dev-only proxies: Secure proxy mode that blocks production calls
• Inter-agent communication: Messages, shared state, and task coordination
• PII redaction: Safe logging with email/amount redaction
• Environment management: Separate dev (emulator) and prod base URLs
• Health checks: Built-in health monitoring for both environments
• TypeScript: Full type safety with structured error responses

Quick Start

# Install dependencies
npm install

# Copy environment template (optional - only for log level)
cp .env.example .env

# Build the server
npm run build

# Start the server
npm run dev

Available Tools

Contract Management

• contracts_read_openapi - Returns OpenAPI specification with version and changelog
• contracts_read_schema - Returns JSON schema for specific endpoints (order.create, subscribe.create)

Environment

• env_get_api_base(target) - Get API base URL for dev (emulator) or prod environment

API Calls (Dev-Only Proxies)

• api_orders_create(payload, target) - Create order with validation (dev-only proxy)
• api_subscribe_create(payload, target) - Create subscription with validation (dev-only proxy)
• healthz(target) - Health check for target environment

Inter-Agent Communication

• agents_send_message(from, to, content) - Send message to another agent
• agents_get_messages(agentId, unreadOnly) - Get messages for your agent
• agents_mark_read(messageId, agentId) - Mark message as read
• agents_list_active() - List currently active agents

Shared State Management

• state_set(key, value, updatedBy) - Set shared state for other agents
• state_get(key) - Get shared state by key
• state_list_keys() - List all available shared state keys

Task Coordination

• tasks_create(title, description, createdBy, priority) - Create coordination task
• tasks_assign(taskId, assignedTo, assignedBy) - Assign task to agent
• tasks_update_status(taskId, status, updatedBy) - Update task status
• tasks_get_queue(status, assignedTo) - Get tasks (with optional filters)

Agent Communication

Agent IDs

• A1: Astro frontend agent
• A2: Flutter mobile agent
• A3: Backend/coordination agent
• "all": Broadcast to all agents

Communication Patterns

A1 ↔ A2: Frontend coordination (UI consistency, shared components)
A1 ↔ A3: Backend integration, API changes, deployment coordination
A2 ↔ A3: Mobile-specific backend needs, push notifications, offline sync
A1 ↔ A2 ↔ A3: Project-wide announcements, major changes, task coordination

Example Usage

• Message: agents_send_message("A3", "A1", "API endpoint updated, please test")
• Shared State: state_set("current_api_version", "1.2.0", "A3")
• Task: tasks_create("Update mobile UI", "Implement new design system", "A1", "high")

Tool Arguments

Tool	Arguments	Description
contracts_read_openapi	None	Returns full OpenAPI spec
contracts_read_schema	name: "order.create" | "subscribe.create"	Returns specific JSON schema
env_get_api_base	target: "dev" | "prod"	Returns base URL for environment
api_orders_create	payload: object, target: "dev" | "prod"	Creates order (prod blocked)
api_subscribe_create	payload: object, target: "dev" | "prod"	Creates subscription (prod blocked)
healthz	target: "dev" | "prod"	Health check for environment

Dev-Only Proxy Policy

Development (target: "dev"): ✅ Allowed

• Proxies to emulator base URL
• Full validation and error handling
• Safe for development and testing

Production (target: "prod"): ❌ Blocked

• Returns structured error with clear message
• Prevents accidental production calls from MCP
• Forces proper authentication in app clients

Production Block Response

{
  "ok": false,
  "status": 403,
  "body": {
    "error": "Proxy disabled in prod; call from app clients with App Check/Auth",
    "target": "prod",
    "proxyMode": "dev-only"
  }
}

VS Code Integration

Add to your VS Code settings:

{
  "augment.mcpServers": {
    "roze-bridge": {
      "command": "node",
      "args": ["c:\\repos\\roze-mcp\\dist\\server.js"],
      "env": {
        "API_BASE_DEV": "http://127.0.0.1:5001/PROJECT_ID/us-central1",
        "API_BASE_PROD": "https://REGION-PROJECT_ID.cloudfunctions.net",
        "PROXY_MODE": "dev-only",
        "LOG_LEVEL": "info"
      }
    }
  }
}

Or in Augment Settings UI:

• Name: roze-bridge
• Command: node c:\repos\roze-mcp\dist\server.js
• Environment Variables:
  • API_BASE_DEV: http://127.0.0.1:5001/PROJECT_ID/us-central1
  • API_BASE_PROD: https://REGION-PROJECT_ID.cloudfunctions.net
  • PROXY_MODE: dev-only (recommended)
  • LOG_LEVEL: info (optional)

Development

npm run dev          # Start with hot reload
npm run build        # Build TypeScript
npm run start        # Run built server
npm run check:schemas # Validate schemas

Architecture

• src/server.ts - MCP server entrypoint
• src/mcp.ts - Tool registration and validation
• src/http.ts - HTTP client helpers
• src/config.ts - Environment configuration
• schemas/ - JSON Schema definitions
• contracts/ - OpenAPI specifications