@goparrot/franchise-mcp-server/README.md

MCP Server for Franchise API

# Franchise MCP Server

A comprehensive Model Context Protocol (MCP) server implementation providing a unified interface for franchise business operations. This server acts as a central hub for managing all aspects of franchise operations including:

- Store and merchant management
- Menu and catalog operations
- Order processing and fulfillment
- Payment processing and integrations
- User access and role management
- Service charge and tax configurations

The server implements a modular architecture with specialized services for:

- **Store Operations**: Complete store lifecycle management and configuration
- **Menu Management**: Comprehensive menu orchestration, synchronization, and item management
- **Order Processing**: Order handling, service charges, and configurations
- **Payment Systems**: Multi-provider payment processing with legacy system support
- **User Management**: Role-based access control and account management
- **Merchant Operations**: Merchant-level configurations and multi-store management

This implementation serves as the backbone for franchise operations, providing a scalable and maintainable API system that handles both modern and legacy requirements.

## Features

- **Store Management API**
  - Create, read, update, and delete store operations
  - Store listing with pagination
  - Store configuration management
- **Order Management**
  - Order listing with pagination
  - Order details retrieval
  - Order action handling
- **Service Charge Management**
  - Service charge CRUD operations
  - Store-specific service charge configuration
- **Merchant Management**
  - Merchant creation and retrieval
  - Merchant profile updates
  - Merchant configuration management

## Installation

```bash
npm install -g @goparrot/franchise-mcp-server
```

## Usage

### As a Command Line Tool

```bash
franchise-mcp-server start
```

### As a Module

```typescript
import { startServer } from "@goparrot/franchise-mcp-server";

// Start the server
startServer();
```

## Goose Integration

### Command Line Integration

You can add the Franchise MCP Server as a Goose extension using the CLI:

```bash
goose-configure
```

Follow these steps in the interactive prompt:

1. Select "Add Extension"
2. Choose "Command-line Extension"
3. Enter "Franchise MCP Server" as the extension name
4. Set "franchise-mcp-server" as the command
5. Set timeout to 300 seconds
6. Add required environment variable:
   - `DASHBOARD_ACCESS_TOKEN`: Your dashboard access token
7. Optional environment variables:
   - `WEBSTORE_GATEWAY_BASE_URL`: Base URL for webstore API gateway
   - `DASHBOARD_GATEWAY_BASE_URL`: Base URL for dashboard API gateway
   - `DISALLOW_WRITES`: Set to "true" to prevent write operations (defaults to true)

### Desktop UI Integration

1. Open Goose Desktop application
2. Click on the menu in the top right
3. Select "Settings"
4. Navigate to the "Extensions" section
5. Click "Add Extension"
6. Fill in the following details:
   - Name: Franchise MCP Server
   - Type: Command Line
   - Command: franchise-mcp-server
   - Timeout: 300
   - Required Environment Variables:
     - DASHBOARD_ACCESS_TOKEN
   - Optional Environment Variables:
     - WEBSTORE_GATEWAY_BASE_URL
     - DASHBOARD_GATEWAY_BASE_URL
     - DISALLOW_WRITES

![img_1.png](img_1.png)

_Figure: Goose Desktop Extension Configuration Screen_

### Environment Variables

- `DASHBOARD_ACCESS_TOKEN`: JWT token for dashboard API access (Required)
- `WEBSTORE_GATEWAY_BASE_URL`: (Optional) Base URL for webstore API gateway
- `DASHBOARD_GATEWAY_BASE_URL`: (Optional) Base URL for dashboard API gateway
- `DISALLOW_WRITES`: (Optional) Set to "true" to prevent write operations. When true, only read operations are allowed. Defaults to true

## API Overview

### Webstore API Methods

- **Store Operations**
  - `GET /api/v3/stores/{storeId}` - Get store by ID
- **Merchant Operations**
  - `GET /api/v3/merchants/{merchantId}` - Get merchant by ID

### Dashboard API Methods

The dashboard API is organized into several logical groups:

#### Order Related APIs
- **Order Management**
  - `PATCH /orders/api/v2/orders/{uuid}/actions` - Handle order actions
  - `GET /orders/api/v2/orders/{uuid}` - Get order details
- **Order Configuration**
  - Configuration endpoints for order settings

#### Menu Related APIs
- **Menu Orchestrator**
  - Menu structure and organization endpoints
- **Menu Sync**
  - `Menu Sync Item` - Item synchronization
  - `Menu Sync Config` - Configuration synchronization
  - `Menu Sync Tax` - Tax settings synchronization

#### Store Items APIs
- **Location Items**
  - Location-specific item management
  - Item base and group management
  - Item options and sets
  - Store bundles and combos
- **Merchant Items**
  - Merchant-level item management
  - Item base and group management
  - Item options and sets
  - Store bundles and combos
- **Categories and Concepts**
  - Location and merchant categories
  - Menu concepts management
- **Selection Types**
  - Location selection types
  - Merchant selection types
- **Tax Management**
  - Store-specific tax configuration

#### Payment Related APIs
- **Payment Management**
  - Payment store configuration
  - OAuth integration
- **Payment Domain**
  - Domain-specific payment settings
- **Legacy Payment**
  - Legacy app integration
  - Square payment integration

#### User Related APIs
- **User Management**
  - User CRUD operations
  - User invitations and franchise connections
- **Role Management**
  - Role definitions and assignments
  - Merchant-specific roles
- **Account Management**
  - Password reset
  - Email confirmation

#### Other APIs
- **Store Management**
  - Store CRUD operations
  - Store configuration
- **Service Charge Management**
  - Service charge CRUD operations
  - Store-specific charges
- **Merchant Management**
  - Merchant CRUD operations
  - Merchant configuration

Each API group is organized in its own directory with dedicated handlers and methods:

```
src/dashboard/services/
├── order/                 # Order related services
├── menu/                  # Menu related services
├── storeitems/           # Store items services
├── payment/              # Payment related services
├── user/                 # User related services
└── ...                   # Other services
```

## Development

1. Clone the repository
2. Install dependencies:
   ```bash
   npm install
   ```
3. Copy environment configuration:
   ```bash
   cp .env.example .env
   ```
4. Start development server:
   ```bash
   npm run start:dev
   ```

### Available Scripts

- `npm run build` - Build the project
- `npm run watch` - Watch mode for development
- `npm run start` - Start the production server
- `npm run start:dev` - Start the development server
- `npm run format` - Format code with Prettier
- `npm run lint` - Run ESLint
- `npm run typecheck` - Run TypeScript type checking

## License

Apache-2.0 © Block, Inc