Installation

This guide walks you through installing A²D locally for development or self-hosting.

Overview

Installation involves three main steps:

Clone the repository
Install dependencies
Verify installation

Time required: ~5-10 minutes

Step 1: Clone the Repository

First, clone the A²D repository from GitHub:

git clone https://github.com/amirkhan-ak-sf/mulesoft-mcp-mock-specs.git
cd mulesoft-mcp-mock-specs

Alternative: If you plan to contribute, fork the repository first:

# Fork on GitHub, then clone your fork
git clone https://github.com/YOUR-USERNAME/mulesoft-mcp-mock-specs.git
cd mulesoft-mcp-mock-specs
 
# Add upstream remote
git remote add upstream https://github.com/amirkhan-ak-sf/mulesoft-mcp-mock-specs.git

The repository is ~2-3 MB. Cloning takes 10-30 seconds depending on your internet speed.

Step 2: Install Dependencies

Install all required npm packages:

npm install

What gets installed:

Package	Version	Purpose
Next.js	16.1.1	React framework with App Router
React	19.0.0	UI library
TypeScript	5.7.3	Type safety
Supabase	2.49.2	Database client
MCP SDK	1.0.4	Model Context Protocol
shadcn/ui	Latest	UI components
Tailwind CSS	3.4.17	Styling framework

Expected time: 1-3 minutes depending on your internet connection

The node_modules directory will be ~400-500 MB after installation.

Step 3: Verify Installation

Check that dependencies installed correctly:

npm list --depth=0

Expected output:

mule-mcp-designer@1.0.0 /path/to/mulesoft-mcp-mock-specs
├── @apidevtools/swagger-parser@10.1.1
├── @modelcontextprotocol/sdk@1.0.4
├── @supabase/supabase-js@2.49.2
├── next@16.1.1
├── react@19.0.0
├── typescript@5.7.3
└── ... (more packages)

If you see errors, try:

rm -rf node_modules package-lock.json
npm install

Project Structure

After installation, your directory structure will look like this:

mulesoft-mcp-mock-specs/
├── app/                    # Next.js App Router
│   ├── (app)/             # Protected routes
│   │   ├── dashboard/     # Dashboard page
│   │   ├── servers/       # MCP servers management
│   │   ├── agent-cards/   # Agent Cards management
│   │   └── settings/      # User settings
│   ├── (auth)/            # Authentication pages
│   │   ├── login/         # Login page
│   │   └── signup/        # Signup page
│   ├── api/               # API routes (serverless functions)
│   │   ├── platform/      # MCP endpoints
│   │   ├── exchange/      # Anypoint integration
│   │   └── mcp/           # MCP utilities
│   ├── layout.tsx         # Root layout
│   ├── page.tsx           # Landing page
│   └── globals.css        # Global styles
│
├── components/            # React components
│   ├── ui/               # shadcn/ui base components
│   │   ├── button.tsx
│   │   ├── card.tsx
│   │   ├── dialog.tsx
│   │   └── ... (more UI components)
│   ├── app-sidebar.tsx   # Navigation sidebar
│   ├── tool-schema-builder.tsx
│   ├── compliance-display.tsx
│   └── ... (custom components)
│
├── lib/                   # Utility libraries
│   ├── supabase/         # Database clients
│   │   ├── client.ts     # Browser client
│   │   ├── server.ts     # Server client
│   │   └── service.ts    # Service role client
│   ├── mcp/              # MCP utilities
│   │   ├── stateless-server-utils.ts
│   │   ├── mock-executor.ts
│   │   └── openapi-converter.ts
│   ├── design-rules/     # Compliance validation
│   └── utils.ts          # Common utilities
│
├── types/                 # TypeScript types
│   └── database.ts       # Supabase generated types
│
├── supabase/             # Database configuration
│   └── migrations/       # SQL migration files
│       ├── 20240101000000_initial_schema.sql
│       ├── 20240101000001_rls_policies.sql
│       └── ... (10 total migrations)
│
├── public/               # Static assets
│   ├── favicon.ico
│   └── ... (images, etc.)
│
├── .env.example          # Example environment variables
├── .env.local           # Your environment variables (create this)
├── .gitignore           # Git ignore rules
├── middleware.ts        # Next.js middleware (auth)
├── next.config.ts       # Next.js configuration
├── package.json         # Dependencies and scripts
├── tailwind.config.ts   # Tailwind configuration
├── tsconfig.json        # TypeScript configuration
└── README.md            # Project documentation

Available Scripts

A²D includes several npm scripts for development:

npm run dev
 
# Starts Next.js dev server with Turbopack
# Access at http://localhost:3000

npm run build
 
# Creates optimized production build
# Output in .next/ directory

npm run start
 
# Runs production build locally
# Must run 'npm run build' first

npm run lint
 
# Runs ESLint to check code quality
# Auto-fixes some issues

Running the Development Server

Alternative Workflow: For contributors working on the full A²D ecosystem, consider using the A²D CLI Tool which provides unified commands for starting services, running tests, and managing git workflows.

Start the development server:

npm run dev

Expected output:

▲ Next.js 16.1.1
- Local:        http://localhost:3000
- Environments: .env.local
 
✓ Ready in 2.3s
○ Compiling / ...

You’ll see database connection errors at this point. This is expected! Continue to Database Setup to configure Supabase.

What’s Running:

Next.js development server on port 3000
Turbopack for fast hot module replacement
API routes as serverless functions
File watching for auto-reload

Using Turbopack

A²D uses Turbopack (Next.js 16’s next-generation bundler) by default.

Benefits:

⚡ Faster HMR: Updates appear instantly
🚀 Quick startup: Initial compilation in seconds
📦 Better performance: Optimized for large projects
🔄 Incremental compilation: Only rebuilds changed files

Enabled automatically via the --turbopack flag in package.json:

{
  "scripts": {
    "dev": "next dev --turbopack"
  }
}

To disable Turbopack (if needed):

next dev

Installing Supabase CLI

The Supabase CLI is optional but highly recommended for easier database management.

Installation

npm install -g supabase

Verify Installation

supabase --version

Expected output:

supabase version 1.x.x

Benefits

Name	Type	Description
`Automated Migrations`	convenience	Push all database migrations with one command instead of manual SQL execution
`Type Generation`	development	Generate TypeScript types from your database schema automatically
`Project Linking`	management	Link local project to remote Supabase projects easily
`Local Development`	advanced	Run Supabase stack locally with Docker (advanced use case)

If you skip the CLI, you can manually run migrations by copying SQL from the supabase/migrations/ folder into the Supabase SQL Editor.

Documentation: docs.supabase.com/guides/cli

Troubleshooting Installation

npm install fails with EACCES error

Problem: Permission denied errors during npm install

Solution: Fix npm permissions

# macOS/Linux
sudo chown -R $(whoami) ~/.npm
sudo chown -R $(whoami) /usr/local/lib/node_modules
 
# Or use nvm (Node Version Manager) to avoid permission issues
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 18

Port 3000 already in use

Problem: Another application is using port 3000

Solution 1: Use a different port

PORT=3001 npm run dev

Solution 2: Kill the process on port 3000

# macOS/Linux
lsof -ti:3000 | xargs kill -9
 
# Windows
netstat -ano | findstr :3000
taskkill /PID <PID> /F

Turbopack compilation errors

Problem: Turbopack fails to compile

Solution: Try without Turbopack

next dev

If that works, there may be a Turbopack-specific issue. Report it on the Next.js GitHub.

Installation takes too long

Problem: npm install is very slow (>5 minutes)

Solutions:

npm install -g yarn
yarn install

npm install -g pnpm
pnpm install

npm cache clean --force
npm install

Missing dependencies errors

Problem: “Module not found” errors after installation

Solution: Clear and reinstall

rm -rf node_modules package-lock.json
npm install

Alternative: Try with --legacy-peer-deps flag

npm install --legacy-peer-deps

TypeScript errors

Problem: TypeScript compilation errors

Solution: Ensure TypeScript is installed

npm install --save-dev typescript @types/node @types/react @types/react-dom

ENOTFOUND or network errors

Problem: Cannot reach npm registry

Solutions:

# Check internet connection
ping registry.npmjs.org
 
# Use different registry
npm config set registry https://registry.npmjs.org/
 
# If behind corporate proxy
npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080

System Requirements Validation

Verify your system meets the requirements:

node --version
# Should show v18.0.0 or higher

npm --version
# Should show 9.0.0 or higher

# macOS
vm_stat
 
# Linux
free -h
 
# Should have at least 4 GB available

# macOS/Linux
df -h .
 
# Should have at least 500 MB free

Next Steps

Now that A²D is installed, proceed to:

Database Setup - Configure Supabase and run migrations
Configuration - Set up environment variables
Deploy to Vercel - Deploy to production (optional)

Need Help? Check the Troubleshooting section or open an issue.

Prerequisites Sign Up