This guide walks you through setting up and running the custom MCP (Model Context Protocol) servers in this repository.

• Prerequisites
• Database Setup
  • Automated Database Setup
  • Manual Database Setup
  • Database Schema
  • Useful Database Commands
• Automated Setup
• Manual Setup
  • Build MCP Servers
  • Build Docker Images
• Running the Application
  • Start the Application
  • Access the Application
• Environment Variables
• Next Steps
• Troubleshooting

• Docker Desktop installed on your machine
  • For Mac: Install Docker Desktop for Mac
  • For Windows: Install Docker Desktop for Windows
  • For Linux: Install Docker Engine and Docker Compose
  • After installation, make sure to start Docker Desktop or the Docker daemon
• Git repository cloned locally
• Node.js (v16 or later) and npm installed

The application uses a SQLite database to store Graph Mode data (nodes, edges, and conversation states). The database file (dev.db) is in .gitignore, so you need to set it up locally.

Run the database setup script from the repository root:

./setup-database.sh

This script will:

• Create a .env file with database configuration (if it doesn't exist)
• Install backend dependencies
• Generate the Prisma client
• Create the database and apply the schema
• Display useful database commands

If you prefer to set up the database manually:

1. Create Environment Configuration

   Create a .env file in the backend-mcp-client directory:

   cd backend-mcp-client
   echo 'DATABASE_URL="file:./dev.db"' > .env

2. Install Backend Dependencies

   npm install

3. Generate Prisma Client and Create Database

   npm run db:generate
   npm run db:push

The database includes the following models:

• GraphProject: Main graph container linked to frontend conversations
• GraphNode: Individual nodes with custom IDs, labels, types, position, and data
• GraphEdge: Connections between nodes with labels and metadata (including source, publications, qualifiers)
• GraphState: Snapshots for undo/redo functionality

From the backend-mcp-client directory:

# Open Prisma Studio to view/edit data in a GUI
npm run db:studio

# Regenerate Prisma client after schema changes
npm run db:generate

# Create a new migration
npm run db:migrate

# Push schema changes to database
npm run db:push

The simplest way to set up all custom MCP servers is to use the provided bash script:

# From the repository root
./custom-mcp-servers/build-all-mcps.sh

This script handles the entire setup process:

• Checks if Docker is running and starts it if needed
• Installs dependencies for all MCP servers
• Builds all MCP servers (TypeScript compilation)
• Builds the Docker images for Python, R, and R MCPs

If you prefer to set up the servers step by step, follow these instructions:

Note: Make sure you've completed the Database Setup before building and running MCP servers.

1. Ensure Docker is Running

   Before building any Docker images, make sure Docker Desktop is running:

   open -a Docker

   Wait for Docker Desktop to start completely.

2. Install and Build MCP Server Code

   From the repository root, run:

   # Install dependencies for all MCP servers
   npm run install:mcp-servers
   
   # Build all MCP servers
   npm run build:mcp-servers

   Alternatively, to build everything (MCP servers and main application):

   npm run build:all

1. Build the Python MCP Docker Image

   cd custom-mcp-servers/python-mcp
   # docker build -t my-python-mcp .
   docker pull namin/my-python-mcp
   docker tag namin/my-python-mcp my-python-mcp

   This process may take several minutes as it installs all required dependencies.

2. Verify the Build

   docker images

   You should see my-python-mcp in the list of available images.

1. Build the R MCP Docker Image

   cd custom-mcp-servers/r-mcp
   # docker build --platform linux/amd64 -t my-r-mcp .
   docker pull namin/my-r-mcp
   docker tag namin/my-r-mcp my-r-mcp

   The (commented out) process may take a long time (potentially 30+ minutes) as it installs R and all required packages. The --platform linux/amd64 flag ensures compatibility.

2. Verify the Build

   docker images

   You should see my-r-mcp in the list of available images.

1. Build the Racket MCP Docker Image

   cd custom-mcp-servers/racket-mcp
   docker build --platform linux/amd64 -t my-racket-mcp .

   The --platform linux/amd64 flag ensures compatibility.

2. Verify the Build

   docker images

   You should see my-racket-mcp in the list of available images.

After setting up the MCP servers and Docker images, you'll need to install the main application dependencies and start the application.

From the repository root, run:

# Install all dependencies for the main application
npm install

The application consists of a frontend and a backend server. You can start both simultaneously using:

# Start both the frontend and backend server
npm start

This command runs:

• The Vite development server for the frontend
• The backend server that manages MCP servers and handles API requests

Alternatively, you can run them separately:

# Start just the frontend
npm run dev --workspace=frontend-client

# Start just the backend server
npm run server:dev --workspace=backend-mcp-client

Read System Tests Readme for instructions on how to run cypress system tests.

Once started, the application will be available at:

• Frontend: http://localhost:5173
• Backend API: http://localhost:3000

Create a .env file in the MCP Client backend in ./backend-mcp-client root directory with the following variables (as needed):

# Server Configuration
PORT=3000
NODE_ENV=development

# Brave Search API (for brave-search MCP server)
BRAVE_API_KEY=your_brave_api_key_here

# PubMed/NCBI (for pubmed MCP server)
NCBI_API_KEY=your_ncbi_api_key_here
NCBI_TOOL_EMAIL=[email protected]

# Other API keys may be required depending on which MCP servers you use

Now that you have the application running, you can:

• Create new conversations in the UI
• Utilize the various MCP servers through the interface
• Develop and test your MCP implementations
• Make modifications to the codebase as needed

• If you see an error about Docker daemon not running, make sure Docker Desktop is started
• If build fails due to network issues, check your internet connection and try again
• If the application doesn't start, check that all dependencies are installed with npm install

• Database not found: Run ./setup-database.sh from the repository root to create the database
• Prisma client errors: Run npm run db:generate from the backend-mcp-client directory
• Schema sync issues: Run npm run db:push to sync your schema with the database
• Permission errors: Ensure the backend-mcp-client directory has write permissions
• View database contents: Run npm run db:studio from backend-mcp-client to open Prisma Studio

Located in src/utils/debug.ts, this utility helps collect and organize debug logs for easier troubleshooting.

1. In Browser DevTools Console:

// Start collecting logs
const stop = collectDebugLogs();

// Perform actions you want to debug
// ... do your actions ...

// Stop and display collected logs
const logs = stop();

2. Logs are automatically categorized by type:

• State Updates: [STATE UPDATE]
• Stream Debug: [STREAM DEBUG]
• Final Debug: [FINAL DEBUG]
• ID Debug: [ID DEBUG]
• ChatStore: ChatStore:
• Errors: Error:

Server-side logs are automatically saved to the ./logs directory:

• Application logs: ./logs/app.log
• Error logs: ./logs/error.log
• Debug logs: ./logs/debug.log

These log files are useful for debugging server-side issues or when the browser console isn't sufficient.

To make your logs work with this utility, use these prefixes in your console.log calls:

console.log('[STATE UPDATE: yourCategory]', { your: 'data' });
console.log('[STREAM DEBUG]', 'your message');

The utility will automatically collect and group these logs for easier debugging.

• Organized, categorized log output
• Easier tracking of state changes
• Simplified debugging of async operations
• Clean console output for specific debugging tasks

• If an MCP server fails to start, check its logs in the console output
• Ensure that all required environment variables are set (check .env files if they exist)
• For TypeScript errors, try rebuilding with npm run build:mcp-servers

• For Mac with Apple Silicon (M1/M2/M3), ensure Rosetta is installed if required by Docker

• If the build process is interrupted, you can simply run the build command again - Docker will use cached layers when possible
• If you encounter memory issues during the build, try increasing the resources allocated to Docker in Docker Desktop settings
• For Mac with Apple Silicon (M1/M2/M3), the --platform linux/amd64 flag is essential for compatibility

No known issues.

# Build the project
npm run build

# Run with CalDAV backend (default)
npm start

# Run with EventKit backend 
CAL_BACKEND=eventkit npm start

The server provides the following MCP tools:

Lists all available calendars from the configured calendar source.

Example usage:

const response = await mcpClient.callTool('list_calendars', {});

Gets events from a specified calendar within a date range.

Parameters:

• calendarId (optional): ID of the calendar to get events from
• start (optional): Start date in ISO format (defaults to today)
• end (optional): End date in ISO format (defaults to 7 days from start)
• query (optional): Search query to filter events by title, description, or location

Example usage:

const response = await mcpClient.callTool('get_calendar_events', {
  calendarId: 'https://caldav.example.com/calendars/user/calendar/',
  start: '2023-10-01T00:00:00Z',
  end: '2023-10-31T23:59:59Z',
  query: 'meeting'
});

• Connection Issues: Ensure your credentials are correct and the server URL is accessible
• Authentication Failures: Some providers may require app-specific passwords or other authentication methods
• Empty Calendar List: Verify that you have permissions to access the calendars on the server
• EventKit Permissions: If using EventKit, make sure you've run the helper once manually to grant permissions