MCP Dev Logger v3.2.1

Streamlined Development Server Manager for Amplify Gen 2 Projects

A Model Context Protocol (MCP) server that manages Amplify Gen2 sandbox and application development servers with intelligent logging and AI self-education features.

What This Does

Two core capabilities:

1. Amplify Sandbox Management - Start/stop/monitor npx ampx sandbox --stream-function-logs
2. Application Dev Server Management - Start/stop dev servers (Next.js, Vite, etc.) with optional port forcing (critical for OAuth)

Key Features:

• Multi-project safe (uses working directory detection)
• Auto-kills stuck processes before starting fresh
• Streams logs to organized directories (resources/sandbox/, resources/appserver/)
• AI self-education system (commands AI to learn Amplify on startup)

Installation

claude mcp add dev-logger -s user -- npx @chinchillaenterprises/mcp-dev-logger

Tools Provided

🔧 Amplify Sandbox Tools

dev_start_sandbox

Start Amplify Gen2 sandbox with streaming function logs.

What it does:

• Checks if a sandbox is already running in THIS project directory
• Kills existing sandbox if found (prevents stuck sandboxes)
• Starts fresh: npx ampx sandbox --stream-function-logs
• Streams logs to resources/sandbox/sandbox.log
• Commands AI to educate itself on Amplify Gen 2

Multi-project safe: Uses lsof to match working directory, only affects THIS project's sandbox

Usage:

dev_start_sandbox()

Returns:

{
  "success": true,
  "message": "Amplify sandbox started. Logs: /path/to/resources/sandbox/sandbox.log",
  "logFile": "/path/to/resources/sandbox/sandbox.log",
  "AI_INSTRUCTIONS": "🎓 AI INSTRUCTIONS - EXECUTE IMMEDIATELY:

1. Call mcp__amplify-docs__get_amplify_concepts with { \"concept\": \"core-principles\" }
2. Call mcp__amplify-docs__get_sandbox_details with { \"topic\": \"sandbox-workflow\" }
3. Read resources/patterns/README.md for implementation patterns with Amplify Gen 2

CRITICAL - UNDERSTAND THESE LOGS:
- CloudFormation deployment progress
- Lambda function invocations (GraphQL queries/mutations, auth)
- console.log statements from your Lambda code
- Errors and stack traces
..."
}

Why AI_INSTRUCTIONS? When a new AI or context-less AI starts the sandbox, they're automatically commanded to:

• Learn Amplify Gen 2 concepts via amplify-docs MCP tools
• Read the local patterns guide for implementation details
• Understand what's in the logs (not just deployment, but runtime execution)

This ensures every AI knows how to help with backend development immediately.

dev_stop_sandbox

Stop the running Amplify sandbox process.

Usage:

dev_stop_sandbox()

Returns:

{
  "success": true,
  "message": "Amplify sandbox stopped successfully."
}

Note: This does NOT delete CloudFormation stacks. To delete AWS resources, run npx ampx sandbox delete manually.

dev_tail_sandbox_logs

Get the last N lines from the sandbox log file.

Parameters:

• lines (optional): Number of lines to return (default: 50)

Usage:

// Last 50 lines
dev_tail_sandbox_logs()

// Last 100 lines
dev_tail_sandbox_logs({ "lines": 100 })

What you'll see:

• CloudFormation stack deployment progress
• Lambda function invocations when user tests the app
• console.log statements from Lambda code in amplify/data/*, amplify/auth/*, amplify/functions/*
• Errors and stack traces
• Real-time CloudWatch streaming

⚛️ Application Dev Server Tools

dev_start_appserver

Start application development server with optional port specification.

What it does:

• Starts npm run dev for application development (Next.js, Vite, etc.)
• Optionally kills any process on specified port (for OAuth callbacks requiring specific ports)
• Detects actual port from server output
• Streams logs to resources/appserver/appserver.log

Port Parameter (optional):

• Not specified: Server picks next available port (3000, 3001, 3002, etc.)
• Specified: Kills anything on that port first, then starts on that exact port

Usage:

// Let server pick the port
dev_start_appserver()

// Force port 3000 (kills anything on 3000 first)
dev_start_appserver({ "port": 3000 })

Why force a port? OAuth providers (Google, Cognito, Facebook) require exact redirect URIs like:

• http://localhost:3000/api/auth/callback

If your dev server starts on 3001, OAuth fails. Port forcing solves this.

Returns:

{
  "success": true,
  "message": "Started appserver. Running on port 3000. Logs: /path/to/resources/appserver/appserver.log",
  "logFile": "/path/to/resources/appserver/appserver.log",
  "port": 3000,
  "killedPort": 3000
}

dev_stop_appserver

Stop the running application development server.

Usage:

dev_stop_appserver()

Returns:

{
  "success": true,
  "message": "Appserver stopped successfully."
}

Typical Workflows

Full Stack Development

// 1. Start backend (Amplify sandbox)
dev_start_sandbox()
// AI automatically educates itself on Amplify Gen 2

// 2. Start appserver (dev server on port 3000 for OAuth)
dev_start_appserver({ "port": 3000 })

// 3. Work on code...
// Both servers auto-reload on changes

// 4. Debug backend issues
dev_tail_sandbox_logs({ "lines": 100 })

// 5. Stop when done
dev_stop_sandbox()
dev_stop_appserver()

Backend-Only Development

// Just working on Lambda functions, GraphQL, auth
dev_start_sandbox()

// Check logs when testing
dev_tail_sandbox_logs()

// Stop when done
dev_stop_sandbox()

Frontend-Only Development

// Just working on UI, already have backend deployed
dev_start_appserver()

// Stop when done
dev_stop_appserver()

Multi-Project Safety

Problem: You have 3 VSCode windows open with different Amplify projects, each running a sandbox and dev server.

How this tool handles it:

• Uses ps aux + lsof -a -d cwd -p <PID> to match processes to working directories
• Only kills/affects processes in the current project directory
• Other projects' servers continue running undisturbed
• Logs are organized per project: <project>/resources/sandbox/, <project>/resources/appserver/

AI Self-Education System

When dev_start_sandbox is called, the return includes AI_INSTRUCTIONS that command the AI to:

1. Learn theory - Call mcp__amplify-docs__get_amplify_concepts for architecture understanding
2. Learn workflow - Call mcp__amplify-docs__get_sandbox_details for deployment process
3. Learn practice - Read resources/patterns/README.md for implementation patterns

Why this matters:

• Dumb AIs or context-less AIs get instant Amplify knowledge
• AI understands what's in the logs (runtime execution, not just deployment)
• AI knows to call amplify-docs tools later when needed
• Reduces user handholding ("go read the docs")

Log Format

All logs are timestamped with ISO 8601 format:

[2025-10-03T14:23:45.123Z] Starting Amplify sandbox: npx ampx sandbox --stream-function-logs
[2025-10-03T14:23:50.456Z] Amplify Gen 2 sandbox starting...
[2025-10-03T14:24:10.789Z] [INFO] Stack deployment in progress...
[2025-10-03T14:24:15.012Z] Lambda function invoked: createTodo
[2025-10-03T14:24:15.234Z] console.log: Creating todo for user abc123
[2025-10-03T14:24:15.567Z] [ERROR] DynamoDB validation error: Missing required field 'title'
[2025-10-03T14:25:00.890Z] Amplify sandbox exited with code 0 and signal null

Requirements

• Node.js: 18+
• AWS Amplify Gen2 project (for sandbox tools)
• Development server project (Next.js, Vite, etc. - for appserver tools)
• AWS credentials configured (for sandbox)

The resources/ folder is created automatically if it doesn't exist.

Troubleshooting

Sandbox won't start

• Verify you're in an Amplify Gen2 project directory
• Check npx ampx is available: npx ampx --version
• Verify AWS credentials: aws sts get-caller-identity

Logs not appearing

• Check resources/sandbox/ or resources/appserver/ folders exist (auto-created)
• Call dev_tail_sandbox_logs() to verify logs are being written

Port already in use (dev server)

• Use port forcing: dev_start_appserver({ "port": 3000 })
• This kills anything on port 3000 first, then starts there

Process won't stop

• Call stop command again
• Restart Claude Code if stuck
• Processes are cleaned up automatically on MCP server shutdown

Development

# Build
npm run build

# Install locally for testing
claude mcp add dev-logger-test -s user -- node $(pwd)/dist/index.js

# Publish
npm publish --access public

Version History

v3.2.1 (Current)

• Renamed dev_start_nextjs → dev_start_appserver
• Renamed dev_stop_nextjs → dev_stop_appserver
• Updated all references from "frontend" to "appserver"
• Changed log directory from resources/frontend/ to resources/appserver/
• Prevents AI from using bash npm run dev instead of the tool

v3.2.0

• Added kill-existing-appserver logic (like sandbox has)
• Multi-project safety for appserver processes

v3.1.3

• AI self-education via AI_INSTRUCTIONS in sandbox return
• Commands AI to call amplify-docs MCP tools and read patterns guide

v3.1.0

• Added dev server management with port forcing for OAuth

v3.0.1

• Enhanced tool descriptions with educational context for AI

v3.0.0

• Major simplification: hardcoded sandbox command, removed complexity
• Multi-project detection with working directory matching
• Auto-kill existing sandbox before starting fresh

License

MIT License

Support

For issues and questions:

• GitHub: ChinchillaEnterprises/ChillMCP
• Open an issue in the repository