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

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

---

Tools Provided

$3

#### 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:
`typescript
dev_start_sandbox()
`

Returns:
`json
{
"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:
`typescript
dev_stop_sandbox()
`

Returns:
`json
{
"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:
`typescript
// 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

---

$3

#### 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:
`typescript
// 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:
`json
{
"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:
`typescript
dev_stop_appserver()
`

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

---

Typical Workflows

$3


`typescript
// 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()
`

$3


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

// Check logs when testing
dev_tail_sandbox_logs()

// Stop when done
dev_stop_sandbox()
`

$3


`typescript
// 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 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: /resources/sandbox/, /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

$3


- 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

$3

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

$3

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

$3

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

---

Development

`bash


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