MCP Server

This directory contains the MCP server, which will host the AI agent and manage integrations with various data sources.

Prerequisites

• Node.js >= 14

• A Supabase project (for credential storage)

• direnv (optional, for directory-specific environment variable loading)

Note: On startup (npm start or npm run dev), the server will automatically:

• Create the AI & User Review/ folder

• Scaffold the PROGRESS.md progress tracker

• Bootstrap the database schema

See "Automated Database Setup" below.

Directory-specific environment loading (optional)
To automatically load your project-specific OPENAI_API_KEY (and other env vars) when you enter this directory, consider using direnv.
Copy .envrc.example to .envrc, fill in your OPENAI_API_KEY, then run direnv allow.

Related MCP server: MySQL MCP Server

Folder Structure

• Progress Review/
  Directory for storing user-provided review artifacts (screenshots, logs, transcripts).
  The CLI ensures this folder exists automatically on startup.

• PROGRESS.md
  Markdown file auto-generated to track project progress and next steps.

• .envrc.example
  Template for direnv configuration to auto-load project-specific environment variables.

Quickstart

The easiest way to bootstrap a new MCP Server project is via the create-mcp-server CLI:

# Scaffold a new project in one command (requires Node.js >=14)
npx create-mcp-server my-mcp-server
cd my-mcp-server
# The above will install dependencies, prompt for env vars, setup the database,
# and prepare the review folder.

npm start

Setup

1. Run the interactive initialization script to configure core and integration-specific environment variables and bootstrap your project (you'll be prompted to select which integrations to configure):

   npm run init

2. Install dependencies:

   npm install

   Note: If you selected Google Custom Search integration, this will install the googleapis package required for the google_cse helper.

3. Start the server (creates review folder, applies migrations, and bootstraps database automatically):

   npm start

Environment Variables

See .env.example for the full list.

Development

To start in watch mode (with nodemon):

npm run dev

Deployment to Vercel

This project can be deployed to Vercel. To do so:

1. Create a new project in your Vercel organization.

2. Set the following Environment Variables in the Vercel dashboard (under Project Settings → Environment Variables):

   • SUPABASE_URL

   • SUPABASE_SERVICE_ROLE_KEY (or SUPABASE_ANON_KEY)

   • GOHIGHLEVEL_API_KEY

   • STRIPE_SECRET_KEY

   • QUICKBOOKS_CLIENT_ID

   • QUICKBOOKS_CLIENT_SECRET

   • AIRTABLE_API_KEY

   • AIRTABLE_BASE_ID

   • N8N_ENDPOINT

   • N8N_API_KEY

   • ANTHROPIC_API_KEY

   • GOOGLE_CSE_API_KEY

   • GOOGLE_CSE_ENGINE_ID

3. Connect your GitHub repository (using a personal access token if needed) and deploy.

MCP Server Development Guide

A comprehensive MCP Server Development Guide is available in the docs directory. It covers:

• Core MCP concepts (tools, resources, prompts)

• Implementation examples in various languages

• Claude Desktop integration steps

• Security and debugging considerations

• Production deployment guidance

Agents ("Butler") Endpoint

Before using the agents endpoints, create an agents table in your Supabase database with the following columns:

Endpoints

• POST /agents
  Create a new agent.
  Request body:

  {
    "name": "butler",
    "description": "The initial AI butler agent",
    "config": { /* integration settings, credentials ref, etc. */ }
  }

  Response: 201 with the created agent.

• GET /agents
  List all registered agents.
  Response: 200 with an array of agents.

Database Setup

Automated Database Setup

Database/table migrations run automatically on server start via the prestart and predev hooks.

When you execute npm start or npm run dev, the required agents and orders tables will be created if they do not already exist.

Migrations: All SQL migrations are located in scripts/migrations. The first migration enables the raw_sql helper and required extensions; subsequent migrations create the agents and orders tables and add RLS policies. The db:setup script will automatically apply these migrations (in sorted order) on every server start.

Manual Database Setup

Before applying migrations or starting the server, ensure the raw_sql helper exists in your database. In your Supabase SQL editor, run:

create extension if not exists pgre_modules;
create or replace function raw_sql(sql text) returns jsonb language plpgsql as $$
declare result jsonb;
begin
  execute sql into result;
  return to_jsonb(result);
end;
$$;

Then run the following SQL to create the necessary tables if you prefer manual setup:

-- Table for agent definitions (the "butler")
create table if not exists agents (
  id uuid primary key default gen_random_uuid(),
  name text not null,
  description text,
  config jsonb,
  created_at timestamptz default now()
);

-- Table for agent orders
create table if not exists orders (
  id uuid primary key default gen_random_uuid(),
  agent_id uuid references agents(id) not null,
  payload jsonb not null,
  status text default 'pending',
  created_at timestamptz default now()
);