Pistachio MCP Server

# Pistachio MCP 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 ```bash 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: ```bash # Install Yarn globally (if needed) npm install -g yarn # Or use Corepack (recommended for Node.js 16.10+) corepack enable corepack prepare yarn@4.10.3 --activate ``` ### 3. Install Dependencies Install all project dependencies using Yarn: ```bash 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): ```bash # 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**: ```bash 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: ```bash 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: ```bash yarn test:run ``` ## Running the Server ### Development Mode Run the server in development mode with hot reload: ```bash 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): ```bash 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**: ```bash yarn build yarn pm2:start ``` 3. **Monitor the server**: ```bash # View logs yarn pm2:logs # Check status yarn pm2:status ``` 4. **Manage the server**: ```bash # 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: ```bash yarn build node dist/index.js ``` ### Direct Execution (Development) Run TypeScript directly without building: ```bash 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: ```bash yarn build ``` Then manage the processes via PM2: ```bash # 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: ```bash # 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 ```bash # Run tests in watch mode yarn test # Run tests once yarn test:run ``` ### Linting ```bash # Check for linting errors yarn lint # Fix linting errors automatically yarn lint:fix ``` ### TypeScript Compilation Errors If you encounter TypeScript errors: ```bash # Clean and rebuild rm -rf dist yarn build ``` ## License MIT