Local Testing Guide for MultiSynq MCP Integration

This guide explains how to run and test the MultiSynq MCP integration locally.

Prerequisites

Node.js 18+ and pnpm installed
PostgreSQL 14+ (for local development)
Docker and Docker Compose (optional, for containerized setup)
Git repository cloned

Local Database Setup

Option 1: Install PostgreSQL Locally (Recommended for Development)

# Ubuntu/Debian
sudo apt update
sudo apt install postgresql postgresql-contrib

# macOS
brew install postgresql
brew services start postgresql

# Start PostgreSQL service
sudo systemctl start postgresql  # Linux
brew services start postgresql    # macOS

Create Database and User

# Access PostgreSQL prompt
sudo -u postgres psql

# Create user and database
CREATE USER metamcp_user WITH PASSWORD 'm3t4mcp';
CREATE DATABASE metamcp_db OWNER metamcp_user;
GRANT ALL PRIVILEGES ON DATABASE metamcp_db TO metamcp_user;
\q

Option 2: Use Docker for PostgreSQL Only

# Start PostgreSQL container
docker run -d \
  --name metamcp-postgres \
  -e POSTGRES_USER=metamcp_user \
  -e POSTGRES_PASSWORD=m3t4mcp \
  -e POSTGRES_DB=metamcp_db \
  -p 5432:5432 \
  postgres:16-alpine

Quick Start - Local Development

1. Set Up Environment Variables

# From project root
cd multimcp  # or wherever you cloned the repo

# Create local environment file
cat > .env.local << EOF
# Database Configuration (Local PostgreSQL)
DATABASE_URL=postgresql://metamcp_user:m3t4mcp@localhost:5432/metamcp_db
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_USER=metamcp_user
POSTGRES_PASSWORD=m3t4mcp
POSTGRES_DB=metamcp_db

# Application Configuration
APP_URL=http://localhost:12008
NEXT_PUBLIC_APP_URL=http://localhost:12008
NODE_ENV=development

# Authentication (use a secure key in production!)
BETTER_AUTH_SECRET=dev-secret-key-change-in-production-at-least-32-chars

# Optional: Enable debug logging
LOG_LEVEL=debug
EOF

# Copy to root .env for convenience
cp .env.local .env

2. Install Dependencies and Build

# From project root
pnpm install

# Build all packages
pnpm build

3. Initialize Database

# From project root, you can use the convenience script
pnpm db:push:dev

# OR navigate to backend and run directly
cd apps/backend
pnpm db:push:dev

# Optional: Open database GUI (from project root)
pnpm db:studio:dev

4. Start Development Servers

# Option 1: From project root (opens two terminals)
pnpm dev:backend  # Terminal 1
pnpm dev:frontend # Terminal 2

# Option 2: Navigate to each app
cd apps/backend && pnpm dev   # Terminal 1
cd apps/frontend && pnpm dev  # Terminal 2

5. Verify Installation

# Test health endpoint
curl http://localhost:12008/api/health

# Expected response:
{
  "status": "ok",
  "timestamp": "2024-07-25T...",
  "multisynq": {
    "endpoint": "/sse",
    "status": "ready"
  }
}

Docker Compose Setup (Full Stack)

1. Using Docker Compose

# From project root
docker compose up -d

# Check logs
docker compose logs -f app

# Wait for: "✅ MultiSynq root endpoint initialized successfully"

2. Railway-Compatible Docker Setup

The Docker configuration is designed to work seamlessly with Railway:

Database: Railway automatically provisions PostgreSQL
Environment Variables: Railway injects DATABASE_URL and other variables
Migrations: The docker-entrypoint.sh script runs migrations automatically
Health Checks: Built-in health check endpoint at /api/health

Testing MultiSynq Integration

1. Test Public Endpoints

# Test SSE endpoint
curl http://localhost:12008/sse

# Test MCP endpoint  
curl http://localhost:12008/mcp

# Test API documentation
curl http://localhost:12008/api

# Test health with MultiSynq status
curl http://localhost:12008/api/health

2. Use MCP Inspector

Open MCP Inspector:
- Navigate to http://localhost:12008/mcp-inspector
Configure connection:
- Transport: SSE
- URL: http://localhost:12008/sse
- No authentication required
Test operations:
- Click "Connect"
- List available tools
- Search for "multisynq" in tools
- Execute search tool with query "what is multisynq"

3. Test with AI Tools Locally

Claude Desktop Configuration

Edit Claude Desktop config:
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Linux: ~/.config/Claude/claude_desktop_config.json

Add MultiSynq MCP server:

{
  "mcpServers": {
    "multisynq-local": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sse", "http://localhost:12008/sse"]
    }
  }
}

Restart Claude Desktop and look for "multisynq-local" in the MCP servers list

Cline (VS Code) Configuration

Install Cline extension in VS Code
Open Cline settings (Ctrl+Shift+P → "Cline: Open Settings")

Add MCP server:

{
  "multisynq-local": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-sse", "http://localhost:12008/sse"]
  }
}

4. Test MultiSynq Documentation Retrieval

Once connected via MCP Inspector or an AI tool, test these queries:

// Example tool calls to test
{
  "tool": "search",
  "query": "what is multisynq"
}

{
  "tool": "search", 
  "query": "how to use activities in multisynq"
}

{
  "tool": "search",
  "query": "multisynq authentication"
}

Available Scripts

Root-Level Scripts (run from project root)

# Development
pnpm dev              # Start both frontend and backend with hot reload
pnpm dev:backend      # Start only backend
pnpm dev:frontend     # Start only frontend

# Building
pnpm build            # Build all packages
pnpm clean            # Clean all build artifacts

# Database (convenience scripts)
pnpm db:push:dev      # Push schema to local database
pnpm db:studio:dev    # Open Prisma Studio GUI
pnpm db:push          # Push schema (uses .env)
pnpm db:studio        # Open Prisma Studio (uses .env)

# Testing
pnpm test:multisynq   # Run MultiSynq tests
pnpm test:playwright  # Run browser tests

# Docker
pnpm docker:up        # Start with docker compose
pnpm docker:down      # Stop docker services
pnpm docker:logs      # View docker logs

# Linting
pnpm lint             # Run linting
pnpm lint:fix         # Fix linting issues

Backend Scripts (in apps/backend)

# Development
pnpm dev              # Start development server with hot reload

# Database Management
pnpm db:push:dev      # Push schema to local database
pnpm db:studio:dev    # Open Prisma Studio GUI
pnpm db:generate:dev  # Generate Prisma client
pnpm db:migrate:dev   # Run migrations
pnpm db:reset         # Reset and seed database

# Testing
pnpm test:multisynq   # Run MultiSynq tests
pnpm test             # Run all tests
pnpm test:playwright  # Run browser tests

# Building
pnpm build            # Build for production
pnpm start            # Start production build

Database Management

View Database with Prisma Studio

# From project root
pnpm db:studio:dev

# OR from backend directory
cd apps/backend
pnpm db:studio:dev

# Opens at http://localhost:5555

Reset Database

cd apps/backend
pnpm db:reset

Manual Database Operations

# Connect to PostgreSQL
psql -U metamcp_user -d metamcp_db -h localhost

# Common queries
\dt                    # List all tables
\d+ "table_name"      # Describe table
SELECT * FROM users;   # Query data

Troubleshooting

Common Issues

Port 12008 already in use:

# Find and kill process
lsof -i :12008
kill -9 <PID>

Database connection errors:

# Check PostgreSQL is running
sudo systemctl status postgresql  # Linux
brew services list                 # macOS

# Check connection
psql -U metamcp_user -d metamcp_db -h localhost -c "SELECT 1"

# Common fix: ensure PostgreSQL is listening on localhost
# Edit postgresql.conf and set: listen_addresses = 'localhost'

pnpm command not found:

# Install pnpm
npm install -g pnpm
# or
curl -fsSL https://get.pnpm.io/install.sh | sh -

Build errors:

# Clean and rebuild
pnpm clean
pnpm install
pnpm build

MultiSynq endpoint not initialized:
- Check backend logs for errors
- Ensure database is accessible
- Verify Context7 MCP server is installed in Docker image
- The initialization should happen automatically on startup

"Cannot find module" errors:

# Ensure all packages are built
pnpm build

# If specific package fails, build it directly
cd packages/zod-types && pnpm build
cd packages/trpc && pnpm build

Viewing Logs

# Backend logs (development)
# Check the terminal where you ran `pnpm dev`

# Docker logs
docker compose logs -f app

# PostgreSQL logs
sudo journalctl -u postgresql  # Linux
tail -f /opt/homebrew/var/log/postgresql*.log  # macOS

# Check specific initialization
docker compose logs app | grep -i multisynq

Railway Deployment Compatibility

The local setup is designed to work seamlessly with Railway deployment:

Database: Railway provides PostgreSQL automatically
Environment Variables: Railway injects DATABASE_URL and other vars
Docker: The Dockerfile handles both local and Railway environments
Health Checks: Same endpoints work locally and on Railway

Development Tips

Hot Reload: Both frontend and backend support hot reload in development mode
Environment Variables:
- Use .env.local for local development
- Use .env for Docker
- Never commit these files to git
API Testing: Use the Swagger UI at http://localhost:12008/api
Rate Limiting: In local development, rate limiting is set to 100 requests/minute
Security Headers: Relaxed in development for easier testing
Database GUI: Prisma Studio provides a visual interface for your data

Stopping Services

# Stop local development servers
# Press Ctrl+C in each terminal

# Stop Docker services
docker compose down

# Stop and remove volumes (clean slate)
docker compose down -v

# Stop PostgreSQL
sudo systemctl stop postgresql  # Linux
brew services stop postgresql    # macOS

# Stop PostgreSQL Docker container
docker stop metamcp-postgres
docker rm metamcp-postgres

Need Help?

Check the logs first
Verify PostgreSQL is running and accessible
Ensure all dependencies are installed with pnpm install
Make sure all packages are built with pnpm build
Check the troubleshooting section above

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Local Testing Guide for MultiSynq MCP Integration

Prerequisites

Local Database Setup

Option 1: Install PostgreSQL Locally (Recommended for Development)

Create Database and User

Option 2: Use Docker for PostgreSQL Only

Quick Start - Local Development

1. Set Up Environment Variables

2. Install Dependencies and Build

3. Initialize Database

4. Start Development Servers

5. Verify Installation

Docker Compose Setup (Full Stack)

1. Using Docker Compose

2. Railway-Compatible Docker Setup

Testing MultiSynq Integration

1. Test Public Endpoints

2. Use MCP Inspector

3. Test with AI Tools Locally

Claude Desktop Configuration

Cline (VS Code) Configuration

4. Test MultiSynq Documentation Retrieval

Available Scripts

Root-Level Scripts (run from project root)

Backend Scripts (in apps/backend)

Database Management

View Database with Prisma Studio

Reset Database

Manual Database Operations

Troubleshooting

Common Issues

Viewing Logs

Railway Deployment Compatibility

Development Tips

Stopping Services

FilesExpand file tree

LOCAL_TESTING_GUIDE.md

Latest commit

History

LOCAL_TESTING_GUIDE.md

File metadata and controls

Local Testing Guide for MultiSynq MCP Integration

Prerequisites

Local Database Setup

Option 1: Install PostgreSQL Locally (Recommended for Development)

Create Database and User

Option 2: Use Docker for PostgreSQL Only

Quick Start - Local Development

1. Set Up Environment Variables

2. Install Dependencies and Build

3. Initialize Database

4. Start Development Servers

5. Verify Installation

Docker Compose Setup (Full Stack)

1. Using Docker Compose

2. Railway-Compatible Docker Setup

Testing MultiSynq Integration

1. Test Public Endpoints

2. Use MCP Inspector

3. Test with AI Tools Locally

Claude Desktop Configuration

Cline (VS Code) Configuration

4. Test MultiSynq Documentation Retrieval

Available Scripts

Root-Level Scripts (run from project root)

Backend Scripts (in apps/backend)

Database Management

View Database with Prisma Studio

Reset Database

Manual Database Operations

Troubleshooting

Common Issues

Viewing Logs

Railway Deployment Compatibility

Development Tips

Stopping Services