PortArrange MCP Server

A Model Context Protocol (MCP) server for intelligent port management and allocation in development environments. PortArrange helps developers avoid port conflicts and manage port assignments across multiple applications and services.

English | 中文

🌟 Features

Intelligent Port Allocation: Automatically assigns port ranges to applications with conflict detection
Service Type Recognition: Smart port assignment based on service types (web, api, database, cache, monitoring)
Persistent Storage: SQLite-based storage for port assignments across sessions
Docker Integration: Generates Docker Compose port configurations automatically
Temporary Port Allocation: Support for temporary port assignments with expiration
Conflict Detection: Proactive scanning and resolution of port conflicts
Configuration Management: Reads port planning from workspace CLAUDE.md configuration
MCP Protocol Support: Full integration with Claude and other MCP-compatible AI assistants

💡 Use Cases

AI Coding Servers

When running AI coding servers that need to manage multiple AI application containers, PortArrange automatically allocates ports for each container, ensuring no conflicts and maintaining organized port mapping. Perfect for:

AI Development Platforms: Managing ports for hundreds of AI model serving containers
LLM Application Deployment: Allocating ports for different LLM services (inference, training, evaluation)
Multi-tenant AI Services: Isolating port ranges for different users or projects
AutoGPT/Agent Systems: Dynamic port allocation for autonomous agent instances

Microservices Development

Local Development: Manage ports for 20+ microservices running locally
Docker Compose Projects: Automatically generate port mappings for complex service architectures
Service Mesh Testing: Coordinate ports for service discovery and load balancing

Multi-Project Development

Freelancers/Agencies: Manage ports across multiple client projects
Open Source Contributors: Keep ports organized when working on multiple projects
Educational Environments: Allocate port ranges for student projects

CI/CD Pipelines

Parallel Testing: Dynamically allocate ports for parallel test runners
Preview Environments: Assign temporary ports for PR preview deployments
Integration Testing: Manage ports for test databases and services

Container Orchestration

Docker Swarm: Pre-allocate port ranges for service replicas
Kubernetes Development: Local port forwarding management
Container Testing: Temporary port allocation for container health checks

Team Collaboration

Remote Development: Assign port ranges to team members to avoid conflicts
Pair Programming: Share port allocations across development environments
DevOps Workflows: Coordinate port usage between development and operations teams

🚀 Quick Start

Prerequisites

Node.js >= 18.0.0
npm or yarn
An MCP-compatible client (e.g., Claude Desktop)

Installation

Clone the repository:

git clone https://github.com/zhuzhe1983/portarrange.git
cd portarrange

Install dependencies:

npm install

Build the project:

npm run build

Configuration for Claude Desktop

Add the following to your Claude configuration file:

macOS/Linux: ~/.claude.json
Windows: %APPDATA%\Claude\claude.json

{
  "mcpServers": {
    "port-arrange": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/portarrange/dist/index.js"]
    }
  }
}

📖 Usage

Available MCP Tools

1. `port_check` - Check Port Availability

Check if a specific port is available on the system.

{
  "tool": "port_check",
  "arguments": {
    "port": 3000
  }
}

2. `port_allocate` - Allocate Application Ports

Allocate a port range and specific service ports for an application.

{
  "tool": "port_allocate",
  "arguments": {
    "appName": "my-app",
    "appType": "web_app",
    "services": [
      {"name": "frontend", "type": "web"},
      {"name": "backend", "type": "api"},
      {"name": "postgres", "type": "database"},
      {"name": "redis", "type": "cache"}
    ]
  }
}

3. `port_release` - Release Application Ports

Release all ports allocated to an application.

{
  "tool": "port_release",
  "arguments": {
    "appName": "my-app"
  }
}

4. `app_list` - List All Applications

Get a list of all registered applications and their port ranges.

{
  "tool": "app_list"
}

5. `app_get` - Get Application Details

Retrieve detailed port allocation information for a specific application.

{
  "tool": "app_get",
  "arguments": {
    "appName": "my-app"
  }
}

6. `conflict_scan` - Scan for Port Conflicts

Detect port conflicts between allocated ports and system usage.

{
  "tool": "conflict_scan"
}

7. `port_allocate_temp` - Allocate Temporary Port

Allocate a temporary port with an expiration time.

{
  "tool": "port_allocate_temp",
  "arguments": {
    "serviceName": "test-server",
    "durationHours": 2,
    "requestor": "developer@example.com"
  }
}

8. `docker_generate` - Generate Docker Compose Config

Generate Docker Compose port configuration for an application.

{
  "tool": "docker_generate",
  "arguments": {
    "appName": "my-app"
  }
}

9. `port_check_range` - Check Port Range

Check availability of a range of ports.

{
  "tool": "port_check_range",
  "arguments": {
    "start": 3000,
    "end": 3010
  }
}

🏗️ Architecture

Port Allocation Strategy

PortArrange uses a two-tier allocation system:

Application Level: Each application gets a 50-port range
- Starting from port 7000 and incrementing by 50
- Example: App1 (7000-7049), App2 (7050-7099), App3 (7100-7149)
Service Level: Within each application's range
- Intelligent offset assignment based on service type
- Database services get specific offsets matching their default ports

Default Port Offsets

Service Type	Offset	Example Services	Default Port
Web	0	Frontend, UI	80/8080
API	1	REST API, GraphQL	3000
Database	2	Primary database	-
Cache	29	Redis, Memcached	6379
Monitoring	40	Prometheus, Grafana	9090

Database-Specific Offsets:

PostgreSQL: basePort + 32 (maps to 5432)
MySQL: basePort + 6 (maps to 3306)
MongoDB: basePort + 17 (maps to 27017)
Redis: basePort + 29 (maps to 6379)

📊 Examples

Example 1: Web Application with Microservices

const result = await portAllocate({
  appName: "ecommerce-platform",
  appType: "platform",
  services: [
    { name: "web-frontend", type: "web" },
    { name: "api-gateway", type: "api" },
    { name: "auth-service", type: "api" },
    { name: "postgres-main", type: "database" },
    { name: "redis-cache", type: "cache" },
    { name: "grafana", type: "monitoring" }
  ]
});

// Result:
// ecommerce-platform: 7000-7049
// - web-frontend: 7000
// - api-gateway: 7001
// - auth-service: 7004
// - postgres-main: 7032 (PostgreSQL)
// - redis-cache: 7029 (Redis)
// - grafana: 7041 (Monitoring)

Example 2: Docker Compose Generation

Input:

await dockerGenerate({ appName: "my-app" });

Output:

version: '3.8'

services:
  web-frontend:
    ports:
      - "7000:80"
    networks:
      - my-app-network
  
  api-gateway:
    ports:
      - "7001:3000"
    networks:
      - my-app-network
  
  postgres-main:
    ports:
      - "7032:5432"
    environment:
      POSTGRES_PORT: 5432
    networks:
      - my-app-network
  
  redis-cache:
    ports:
      - "7029:6379"
    environment:
      REDIS_PORT: 6379
    networks:
      - my-app-network

networks:
  my-app-network:
    driver: bridge

Example 3: Workspace Configuration (CLAUDE.md)

Create a CLAUDE.md file in your workspace root to define port allocations:

### Port Allocations

\```yaml
port_planning:
  application_range: 7000-8999
  temp_service_range: 9000-9999
  ports_per_app: 50

current_allocations:
  - app1: 7000-7049
  - app2: 7050-7099
  - app3: 7100-7149
\```

🔧 Development

Project Structure

portarrange/
├── src/
│   ├── core/
│   │   └── port-manager.ts       # Core port management logic
│   ├── database/
│   │   ├── database.ts           # Database operations
│   │   └── schema.sql            # SQLite schema
│   ├── mcp/
│   │   └── server.ts             # MCP server implementation
│   ├── types/
│   │   └── index.ts              # TypeScript type definitions
│   ├── utils/
│   │   ├── port-checker.ts      # Port availability checking
│   │   └── claude-config-reader.ts # Configuration utilities
│   └── index.ts                  # Entry point
├── examples/                     # Usage examples
│   ├── basic-allocation.js
│   ├── docker-integration.js
│   └── CLAUDE.md.sample
├── tests/                        # Test files
├── dist/                         # Compiled JavaScript
├── package.json
├── tsconfig.json
├── LICENSE
└── README.md

Building

# Development build with watch mode
npm run dev

# Production build
npm run build

# Run tests
npm test

# Lint code
npm run lint

# Format code
npm run format

Testing

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run specific test file
npm test -- port-manager.test.ts

# Run in watch mode
npm run test:watch

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Code Style

Use TypeScript for all new code
Follow the existing code style
Add tests for new features
Update documentation as needed

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Model Context Protocol for the MCP specification
Anthropic Claude for AI assistant integration
SQLite for reliable embedded database
The open source community for continuous inspiration

📞 Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Documentation: Wiki

🗺️ Roadmap

📈 Stats

Made with ❤️ by the development community

Name		Name	Last commit message	Last commit date
examples		examples
src		src
.env.example		.env.example
.gitignore		.gitignore
.npmignore		.npmignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
PUBLISH.md		PUBLISH.md
README.md		README.md
README.zh.md		README.zh.md
SETUP_GITHUB.md		SETUP_GITHUB.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation

PortArrange MCP Server

🌟 Features

💡 Use Cases

AI Coding Servers

Microservices Development

Multi-Project Development

CI/CD Pipelines

Container Orchestration

Team Collaboration

🚀 Quick Start

Prerequisites

Installation

Configuration for Claude Desktop

📖 Usage

Available MCP Tools

1. port_check - Check Port Availability

2. port_allocate - Allocate Application Ports

3. port_release - Release Application Ports

4. app_list - List All Applications

5. app_get - Get Application Details

6. conflict_scan - Scan for Port Conflicts

7. port_allocate_temp - Allocate Temporary Port

8. docker_generate - Generate Docker Compose Config

9. port_check_range - Check Port Range