# MCP Debug Server - Development Setup Guide
This guide will help you set up your development environment for working on the MCP Debug Server project.
## Prerequisites
### Required Software
1. **Node.js** (v18.0.0 or higher, 20.x recommended)
- Download from [nodejs.org](https://nodejs.org/)
- Verify installation: `node --version`
2. **pnpm** (required — the `workspace:*` protocol requires pnpm)
- Install: `npm install -g pnpm`
- Verify installation: `pnpm --version`
3. **Git**
- Download from [git-scm.com](https://git-scm.com/)
- Verify installation: `git --version`
4. **Python** (v3.7 or higher) - For testing Python debugging
- Download from [python.org](https://www.python.org/)
- Verify installation: `python --version`
5. **Visual Studio Code** (Recommended)
- Download from [code.visualstudio.com](https://code.visualstudio.com/)
- Install recommended extensions (see below)
### Optional Software
1. **Docker** - For testing Docker deployment
- Download from [docker.com](https://www.docker.com/)
- Verify installation: `docker --version`
2. **Go** (1.18+) and **Delve** - For Go debugging
- Install Delve: `go install github.com/go-delve/delve/cmd/dlv@latest`
3. **Rust toolchain** - For Rust debugging
- Install via rustup: `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`
- CodeLLDB auto-downloads during `pnpm install`
## Initial Setup
### 1. Clone the Repository
```bash
git clone https://github.com/your-username/debug-mcp-server.git
cd debug-mcp-server
```
### 2. Install Dependencies
```bash
pnpm install
```
This will install all required dependencies across the monorepo workspace.
### 3. Install Python debugpy
The server requires `debugpy` for Python debugging:
```bash
pip install debugpy
```
Or if using pip3:
```bash
pip3 install debugpy
```
### 4. Build the Project
```bash
npm run build
```
This compiles TypeScript files to JavaScript in the `dist/` directory.
### 5. Verify Installation
Run the test suite to ensure everything is set up correctly:
```bash
npm test
```
All tests should pass. If any fail, check the error messages for missing dependencies.
## Development Workflow
### Directory Structure
```
mcp-debugger/
├── packages/ # Monorepo workspace packages
│ ├── shared/ # Shared interfaces, types, and utilities
│ ├── adapter-python/ # Python debug adapter (debugpy)
│ ├── adapter-javascript/# JavaScript/Node.js adapter (js-debug)
│ ├── adapter-rust/ # Rust adapter (CodeLLDB)
│ ├── adapter-go/ # Go adapter (Delve)
│ ├── adapter-mock/ # Mock adapter for testing
│ └── mcp-debugger/ # Self-contained CLI bundle (npx distribution)
├── src/ # Core server source code
│ ├── adapters/ # Adapter loading and registry
│ ├── cli/ # CLI commands and setup
│ ├── container/ # Dependency injection
│ ├── proxy/ # DAP proxy components
│ ├── session/ # Session management
│ └── utils/ # Utilities
├── tests/ # Test files
│ ├── core/ # Core unit and integration tests
│ ├── adapters/ # Adapter-specific tests
│ ├── e2e/ # End-to-end tests
│ └── test-utils/ # Shared test utilities
├── docs/ # Documentation
├── examples/ # Example scripts
├── dist/ # Compiled output
└── coverage/ # Test coverage reports
```
### Common Commands
```bash
# Development build (watch mode)
npm run dev
# Production build
npm run build
# Run all tests
npm test
# Run tests in watch mode
npm run test:watch
# Run tests with coverage
npm run test:coverage
# View coverage report
npm run coverage:report
# Lint code
npm run lint
# Fix linting issues
npm run lint:fix
# Type checking
npm run type-check
```
### Running the Server Locally
#### STDIO Mode (Default)
```bash
node dist/index.js stdio
```
#### SSE Mode
```bash
node dist/index.js sse -p 3001
```
#### With Debug Logging
```bash
node dist/index.js sse -p 3001 --log-level debug --log-file ./logs/debug.log
```
Note: In STDIO mode, console output is silenced to avoid corrupting JSON-RPC protocol communication. Use `--log-file` to capture logs.
## VS Code Setup
### Recommended Extensions
Create `.vscode/extensions.json`:
```json
{
"recommendations": [
"dbaeumer.vscode-eslint",
"esbenp.prettier-vscode",
"vitest.explorer",
"ms-vscode.vscode-typescript-next",
"streetsidesoftware.code-spell-checker",
"eamodio.gitlens"
]
}
```
### Launch Configuration
Create `.vscode/launch.json`:
```json
{
"version": "0.2.0",
"configurations": [
{
"type": "node",
"request": "launch",
"name": "Debug Server (STDIO)",
"skipFiles": ["<node_internals>/**"],
"program": "${workspaceFolder}/dist/index.js",
"outFiles": ["${workspaceFolder}/dist/**/*.js"],
"preLaunchTask": "npm: build"
},
{
"type": "node",
"request": "launch",
"name": "Debug Server (SSE)",
"skipFiles": ["<node_internals>/**"],
"program": "${workspaceFolder}/dist/index.js",
"args": ["sse", "-p", "6111", "--log-level", "debug"],
"outFiles": ["${workspaceFolder}/dist/**/*.js"],
"preLaunchTask": "npm: build"
},
{
"type": "node",
"request": "launch",
"name": "Debug Tests",
"skipFiles": ["<node_internals>/**"],
"program": "${workspaceFolder}/node_modules/vitest/vitest.mjs",
"args": ["run", "${file}"],
"cwd": "${workspaceFolder}",
"console": "internalConsole"
}
]
}
```
### Tasks Configuration
Create `.vscode/tasks.json`:
```json
{
"version": "2.0.0",
"tasks": [
{
"type": "npm",
"script": "build",
"group": {
"kind": "build",
"isDefault": true
},
"problemMatcher": "$tsc",
"label": "npm: build"
},
{
"type": "npm",
"script": "dev",
"group": "build",
"problemMatcher": "$tsc-watch",
"isBackground": true,
"label": "npm: dev"
},
{
"type": "npm",
"script": "test",
"group": {
"kind": "test",
"isDefault": true
},
"label": "npm: test"
}
]
}
```
## Environment Variables
### Development Environment
Create a `.env` file for development:
```bash
# Logging
LOG_LEVEL=debug
LOG_FILE=./logs/debug.log
# Python
PYTHON_PATH=python
# Server
MCP_SERVER_PORT=6111
# Testing
TEST_TIMEOUT=30000
```
### Available Environment Variables
| Variable | Description | Default |
|----------|-------------|---------|
| `LOG_LEVEL` | Logging level (error, warn, info, debug) | `info` |
| `LOG_FILE` | Path to log file | None (console only) |
| `PYTHON_PATH` | Path to Python executable | Auto-detected |
| `MCP_SERVER_PORT` | SSE port for server | `3001` |
| `DEBUG` | Enable debug output | `false` |
## Troubleshooting Setup Issues
### Node.js Issues
**Problem**: `npm install` fails with permission errors
**Solution**:
```bash
# On Unix/macOS
sudo npm install -g npm@latest
# On Windows (run as Administrator)
npm install -g npm@latest
```
**Problem**: Node version is too old
**Solution**: Use nvm (Node Version Manager):
```bash
# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
# Install and use Node 18
nvm install 18
nvm use 18
```
### Python Issues
**Problem**: `debugpy` not found
**Solution**:
```bash
# Ensure pip is up to date
python -m pip install --upgrade pip
# Install debugpy
python -m pip install debugpy
# Verify installation
python -c "import debugpy; print(debugpy.__version__)"
```
**Problem**: Multiple Python versions
**Solution**: Set `PYTHON_PATH` environment variable:
```bash
# Unix/macOS
export PYTHON_PATH=/usr/bin/python3
# Windows
set PYTHON_PATH=C:\Python39\python.exe
```
### Build Issues
**Problem**: TypeScript compilation errors
**Solution**:
```bash
# Clean and rebuild
npm run build:clean
pnpm install
npm run build
```
**Problem**: Module resolution errors
**Solution**:
```bash
# Clear Node.js cache
npm cache clean --force
# Reinstall dependencies
rm -rf node_modules pnpm-lock.yaml
pnpm install
```
## Development Best Practices
### 1. Code Style
The project uses ESLint and Prettier for code formatting:
```bash
# Check code style
npm run lint
# Fix automatically
npm run lint:fix
```
### 2. Commit Messages
Follow conventional commit format:
```
type(scope): subject
body
footer
```
Examples:
```
feat(session): add timeout configuration
fix(proxy): handle connection errors properly
docs(api): update endpoint documentation
test(integration): add Python 3.11 tests
```
### 3. Branch Naming
- `feature/description` - New features
- `fix/description` - Bug fixes
- `docs/description` - Documentation updates
- `test/description` - Test additions/fixes
- `refactor/description` - Code refactoring
### 4. Testing
Always write tests for new features:
```typescript
// Unit test example
describe('MyComponent', () => {
it('should handle specific case', () => {
// Arrange
const component = new MyComponent(mockDependencies);
// Act
const result = component.doSomething();
// Assert
expect(result).toBe(expectedValue);
});
});
```
### 5. Documentation
Update documentation when adding features:
- API changes → Update component docs
- New patterns → Add to pattern docs
- User-facing changes → Update README
## Next Steps
1. Read the [Testing Guide](./testing-guide.md) to understand the test suite
2. Review the [Architecture Overview](../architecture/system-overview.md)
3. Check [Contributing Guidelines](../../CONTRIBUTING.md) before submitting PRs
4. Join the development discussion on [GitHub Issues](https://github.com/your-username/debug-mcp-server/issues)
## Getting Help
- **Documentation**: Check the `docs/` directory
- **Examples**: See `examples/` for usage examples
- **Issues**: Report bugs on GitHub
- **Discussions**: Use GitHub Discussions for questions
Happy coding! 🚀
