Pistachio Server

A remote MCP (Model Context Protocol) server built with Node.js and TypeScript for mobile app development. This server provides tools and prompts for remote project management, testing, and asset search.

Prerequisites

Before setting up this repository, ensure you have the following installed:

• Node.js (v20 or higher)
• Yarn (v4.10.3 or compatible version)
• Git

Setup Instructions

1. Clone the Repository

git clone <repository-url>
cd pistachio-mcp

2. Install Yarn (if not already installed)

This project uses Yarn 4.10.3 as the package manager. If you don't have Yarn installed or need to upgrade:

# Install Yarn globally (if needed)
npm install -g yarn

# Or use Corepack (recommended for Node.js 16.10+)
corepack enable
corepack prepare [email protected] --activate

3. Install Dependencies

Install all project dependencies using Yarn:

yarn install

This will install all dependencies listed in package.json, including:

• @modelcontextprotocol/sdk - MCP SDK
• firebase - Firebase SDK for Firestore and Auth
• @google-cloud/storage - Google Cloud Storage client
• zod - Schema validation
• TypeScript and development dependencies

4. Configure Environment Variables

Create a .env file in the root directory (if needed for custom configuration):

# Optional: Set custom port (default: 3001)
PORT=3001

# Optional: Set number of worker threads (default: 2)
NUM_WORKERS=2

# Optional: Set Node environment
NODE_ENV=development

# Optional: Set log level (default: info)
# Options: trace, debug, info, warn, error, fatal
LOG_LEVEL=info

# Optional: Firebase emulator configuration (for development)
FIREBASE_AUTH_EMULATOR_HOST=localhost:9099
FIRESTORE_EMULATOR_HOST=localhost:8080

# Optional: Google Cloud Storage bucket for weekly expiring assets
GCS_BUCKET_WEEKLY_EXPIRING=dev-pistachio-assets-weekly-expiring

Note: The project uses hardcoded Firebase configuration in src/utils/ServerStorageUtils.ts. For production, you may want to move this to environment variables.

5. Configure Google Cloud Storage (Optional)

If you plan to use Google Cloud Storage features (image uploads), you'll need to set up authentication:

1. Create a service account in Google Cloud Console
2. Download the service account key as a JSON file
3. Set the environment variable:

export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/service-account-key.json"

Alternatively, if running on Google Cloud Platform, authentication is handled automatically.

6. Build the Project

Compile TypeScript to JavaScript:

yarn build

This will generate the dist/ directory with compiled JavaScript files.

7. Verify Installation

Run the tests to verify everything is set up correctly:

yarn test:run

Running the Server

Development Mode

Run the server in development mode with hot reload:

yarn dev

The server will start on port 3001 by default (or the port specified by the PORT environment variable).

Production Mode

Using PM2

PM2 is a process manager that provides automatic restarts, log rotation, and process monitoring. To use PM2:

1. Install PM2 log rotation module (first time only):

   pm2 install pm2-logrotate
   pm2 set pm2-logrotate:max_size 10M
   pm2 set pm2-logrotate:retain 30
   pm2 set pm2-logrotate:compress true
   pm2 set pm2-logrotate:rotateInterval "0 0 * * *"
   

   Note: PM2 uses the pm2-logrotate module for automatic log rotation. The configuration above sets:

   • max_size: Maximum log file size before rotation (10M)
   • retain: Number of rotated log files to keep (30 days)
   • compress: Compress old log files to save space
   • rotateInterval: Time-based rotation schedule using cron format "0 0 * * *" (daily at midnight)

2. Build and start the server:

   yarn build
   yarn pm2:start
   

3. Monitor the server:

   # View logs
   yarn pm2:logs
   
   # Check status
   yarn pm2:status
   

4. Manage the server:

   # Restart
   yarn pm2:restart
   
   # Stop
   yarn pm2:stop
   
   # Remove from PM2
   yarn pm2:delete
   

Log Files:

• Combined logs: logs/combined.log (all stdout and stderr)
• Error logs: logs/error.log (error-level logs only)
• Logs are rotated daily at midnight and retained for 30 days
• Old logs are automatically compressed

Direct Node Execution

Build and run the compiled server directly:

yarn build
node dist/index.js

Direct Execution (Development)

Run TypeScript directly without building:

yarn start

Server Configuration

Default Settings

• Port: 3001 (configurable via PORT environment variable)
• Workers: 2 (configurable via NUM_WORKERS environment variable)
• Host: 0.0.0.0 (accessible from remote clients)

MCP Endpoint

The server exposes an MCP endpoint at /message that accepts:

• GET: Establish SSE stream for receiving messages
• POST: Send MCP requests
• OPTIONS: CORS preflight requests

Example endpoint: http://localhost:3001/message

Managing the Proxy

Build the project first to ensure the proxy is compiled:

yarn build

Then manage the processes via PM2:

# Start all services (MCP, rclone, and Proxy)
yarn mcp:start

# Manage only the proxy
yarn proxy:start
yarn proxy:logs
yarn proxy:status
yarn proxy:restart
yarn proxy:stop

Rclone

Client Configuration

When configuring your local rclone client, point it to the proxy port (8080) instead of the raw rclone port:

# Example client setup
rclone config create pistachio-server webdav url=http://<your-server-ip>:8080
rclone bisync ./local-folder pistachio-server:<project_id> --resync

Development

Running Tests

# Run tests in watch mode
yarn test

# Run tests once
yarn test:run

Linting

# Check for linting errors
yarn lint

# Fix linting errors automatically
yarn lint:fix

TypeScript Compilation Errors

If you encounter TypeScript errors:

# Clean and rebuild
rm -rf dist
yarn build

License

MIT