Development Setup

This guide will help you set up your development environment for contributing to Seed.

Prerequisites

Before you begin, ensure you have the following installed:

Tool	Minimum Version	Purpose
Node.js	24.0.0+	Runtime environment
npm	Bundled with Node.js	Package manager
Git	Any recent version	Version control
Redis	6.0+	Session storage (optional for dev)

Node.js Installation

Using nvm (recommended):

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Install Node.js 24
nvm install 24
nvm use 24
nvm alias default 24

Direct download:

• Visit nodejs.org and download Node.js 24.x LTS

Verify installation:

node --version  # Should show v24.x.x
npm --version   # Should show 10.x.x or higher

Redis Installation

macOS (Homebrew):

brew install redis
brew services start redis

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install redis-server
sudo systemctl start redis

Docker:

docker run -d --name redis -p 6379:6379 redis:7-alpine

Verify Redis:

redis-cli ping  # Should return "PONG"

Getting Started

1. Clone the Repository

# Clone via HTTPS
git clone https://gitlab.byterecursion.com/mcp-servers/seed.git
cd seed

# Or via SSH
git clone git@gitlab.byterecursion.com:mcp-servers/seed.git
cd seed

2. Install Dependencies

npm install

This installs:

• Runtime dependencies: Express, MCP SDK, Redis client, JOSE (JWT library)
• Development dependencies: TypeScript, Vitest, ESLint, Prettier, Supertest

Expected output:

added XXX packages in XXs

3. Configure Environment

Copy the example environment file:

cp .env.example .env

Edit .env with your settings. For local development, you can disable authentication:

# .env
PORT=3000
AUTH_REQUIRED=false  # Disable authentication for local dev

Minimal Development Configuration

For local development and testing, you only need AUTH_REQUIRED=false. All OIDC configuration is optional when authentication is disabled.

Production Configuration

Never deploy to production with AUTH_REQUIRED=false. See Configuration for full production setup.

4. Verify Setup

Run the development server:

npm run dev

Expected output:

Seed MCP Server v0.1.3
Server started on http://localhost:3000

Test the server:

# In another terminal
curl http://localhost:3000/health

Expected response:

{
  "status": "ok",
  "version": "0.1.3",
  "timestamp": "2025-12-09T12:00:00.000Z"
}

Development Workflow

Project Structure

seed/
├── src/                      # Source code
│   ├── config/              # Configuration modules
│   ├── middleware/          # Express middleware (auth, CORS, etc.)
│   ├── mcp/                 # MCP server implementation
│   │   └── tools/          # MCP tool implementations
│   ├── routes/             # HTTP route handlers
│   ├── services/           # Business logic (Redis, JWKS, etc.)
│   ├── types/              # TypeScript type definitions
│   ├── app.ts              # Express app setup
│   └── index.ts            # Entry point
├── wiki/                    # Documentation (VitePress)
├── vitepress/              # VitePress configuration
├── dist/                   # Compiled output (gitignored)
├── coverage/               # Test coverage reports (gitignored)
└── node_modules/           # Dependencies (gitignored)

Available Scripts

Script	Command	Purpose
Development	npm run dev	Start dev server with hot reload
Build	npm run build	Compile TypeScript to dist/
Start	npm start	Run compiled code from dist/
Test	npm test	Run all tests once
Test Watch	npm run test:watch	Run tests in watch mode
Test Coverage	npm run test:coverage	Run tests with coverage report
Lint	npm run lint	Lint source code with ESLint
Format	npm run format	Format code with Prettier
Format Check	npm run format:check	Check code formatting
Type Check	npm run typecheck	Check types without emitting files
Validate	npm run validate	Run format + lint + typecheck + test:coverage
Docs Dev	npm run docs:dev	Start documentation dev server
Docs Build	npm run docs:build	Build documentation

Development Server

The development server uses tsx for hot reloading:

npm run dev

Features:

• Automatic restart on file changes
• TypeScript compilation on-the-fly
• Source maps for debugging
• No build step required

Watching:

• All files in src/**/*.ts
• Configuration changes require manual restart

Making Changes

1. Create a feature branch:

git checkout -b feature/my-feature

2. Make your changes:

# Edit files in src/
vim src/routes/my-route.ts

3. Run validation:

npm run validate

This runs:

• prettier --write src - Format code
• eslint src - Lint code
• tsc --noEmit - Type check
• vitest run --coverage - Run tests with coverage

4. Commit your changes:

git add .
git commit -m "feat: add new feature"

5. Push to GitLab:

git push origin feature/my-feature

Docker Development

Build Docker Image

docker build -t seed:dev .

Run with Docker Compose

Create docker-compose.yml:

version: '3.8'

services:
  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redis-data:/data

  seed:
    build: .
    ports:
      - "3000:3000"
    environment:
      - PORT=3000
      - AUTH_REQUIRED=false
      - REDIS_URL=redis://redis:6379
    depends_on:
      - redis

volumes:
  redis-data:

Start services:

docker-compose up

Development with Docker

Mount source code for hot reloading:

seed:
  build: .
  volumes:
    - ./src:/app/src
  command: npm run dev

IDE Setup

Visual Studio Code

Recommended extensions:

• ESLint
• Prettier
• TypeScript Vue Plugin (Volar)

Workspace settings (.vscode/settings.json):

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "typescript.tsdk": "node_modules/typescript/lib",
  "typescript.enablePromptUseWorkspaceTsdk": true
}

Other IDEs

WebStorm:

• Enable ESLint: Settings → Languages & Frameworks → JavaScript → Code Quality Tools → ESLint
• Enable Prettier: Settings → Languages & Frameworks → JavaScript → Prettier

Vim/Neovim:

• Use coc.nvim with coc-eslint and coc-prettier
• Or ale with ESLint and Prettier

Troubleshooting

Port Already in Use

# Error: EADDRINUSE: address already in use :::3000

Solution 1: Change port in .env:

PORT=3001

Solution 2: Kill process using port 3000:

# macOS/Linux
lsof -ti:3000 | xargs kill -9

# Or find and kill manually
lsof -i:3000
kill -9 <PID>

Redis Connection Failed

# Error: connect ECONNREFUSED 127.0.0.1:6379

Solution:

# Check if Redis is running
redis-cli ping

# Start Redis if not running
# macOS
brew services start redis

# Linux
sudo systemctl start redis

# Docker
docker start redis

Workaround for development: Set AUTH_REQUIRED=false to disable Redis dependency.

Module Not Found

# Error: Cannot find module 'some-package'

Solution:

# Clean install
rm -rf node_modules package-lock.json
npm install

TypeScript Errors in IDE

# Error: Cannot find module or its type declarations

Solution:

# Restart TypeScript server in VS Code
# Cmd/Ctrl + Shift + P → "TypeScript: Restart TS Server"

# Or rebuild
npm run build

Test Failures

# Error: Tests failing locally

Solution:

# Clear Vitest cache
npx vitest run --clearCache

# Update snapshots if needed
npx vitest run -u

Next Steps

• Testing Guide - Learn how to write and run tests
• Code Quality - Understand linting and formatting standards
• Adding MCP Tools - Create custom MCP tools
• Contributing Guide - Submit your changes

Environment Variable Reference

Development Settings

# Server
PORT=3000                    # Server port (default: 3000)

# Authentication
AUTH_REQUIRED=false          # Disable auth for local dev (default: true)

# Redis
REDIS_URL=redis://localhost:6379  # Redis connection (default: redis://redis:6379)

Full Configuration

See Configuration Reference for all environment variables including OIDC, OAuth, and DCR settings.