Package Configuration

Package configuration allows you to specify executable packages from various registries including npm, PyPI, Docker, and Homebrew that can be used to run your MCP servers. This provides flexibility in choosing the right runtime environment and dependencies for your specific use case.

Overview

Pylee supports packages from multiple registries, enabling you to:

Run Node.js packages from npm registry
Execute Python packages from PyPI
Use containerized applications from Docker Hub
Install system tools via Homebrew
Handle custom packages from unknown registries

Each package configuration includes runtime settings, arguments, and environment variables to customize execution behavior.

Supported Package Registries

npm (Node.js)

Execute Node.js packages directly from the npm registry:

{
  "registry_name": "npm",
  "name": "@modelcontextprotocol/server-filesystem",
  "version": "0.4.0",
  "runtime_hint": "node",
  "runtime_arguments": ["--max-old-space-size=4096"],
  "package_arguments": [],
  "environment_variables": [
    {
      "name": "NODE_ENV",
      "value": "production",
      "is_required": true,
      "is_secret": false
    }
  ]
}

Common npm packages for MCP:

@modelcontextprotocol/server-filesystem - File system access
@modelcontextprotocol/server-git - Git repository integration
@modelcontextprotocol/server-sqlite - SQLite database access
@modelcontextprotocol/server-postgres - PostgreSQL integration

PyPI (Python)

Run Python packages from the Python Package Index:

{
  "registry_name": "pypi",
  "name": "mcp-server-github",
  "version": "1.2.0",
  "runtime_hint": "python",
  "runtime_arguments": ["-u", "-m"],
  "package_arguments": ["--config", "/app/config.json"],
  "environment_variables": [
    {
      "name": "PYTHONPATH",
      "value": "/app/lib",
      "is_required": false,
      "is_secret": false
    },
    {
      "name": "GITHUB_TOKEN",
      "value": "",
      "is_required": true,
      "is_secret": true
    }
  ]
}

Popular Python MCP packages:

mcp-server-github - GitHub API integration
mcp-server-slack - Slack workspace access
mcp-server-gdrive - Google Drive file management
mcp-server-notion - Notion database operations

Docker

Execute containerized applications using Docker:

{
  "registry_name": "docker",
  "name": "ghcr.io/modelcontextprotocol/server-memory",
  "version": "latest",
  "runtime_hint": "docker",
  "runtime_arguments": ["run", "--rm", "-i"],
  "package_arguments": ["--memory-limit", "512MB"],
  "environment_variables": [
    {
      "name": "REDIS_URL",
      "value": "redis://localhost:6379",
      "is_required": true,
      "is_secret": false
    }
  ]
}

Docker-specific considerations:

Use fully qualified image names (registry/namespace/image)
Configure port mappings through runtime arguments
Mount volumes for persistent data access
Set resource limits via package arguments

Homebrew (macOS/Linux)

Install and run system tools via Homebrew:

{
  "registry_name": "homebrew",
  "name": "jq",
  "version": "1.7",
  "runtime_hint": "brew",
  "runtime_arguments": ["exec"],
  "package_arguments": ["-r", "."],
  "environment_variables": []
}

Homebrew usage patterns:

System utilities and CLI tools
Development tools and compilers
Database clients and servers
Networking and security tools

Unknown Registry

For custom or private registries:

{
  "registry_name": "unknown",
  "name": "custom-mcp-server",
  "version": "1.0.0",
  "runtime_hint": "/usr/local/bin/custom-runtime",
  "runtime_arguments": ["--config", "/etc/custom.conf"],
  "package_arguments": ["--verbose"],
  "environment_variables": [
    {
      "name": "CUSTOM_API_KEY",
      "value": "",
      "is_required": true,
      "is_secret": true
    }
  ]
}

Package Configuration Fields

Required Fields

registry_name

The package registry identifier
Supported values: npm, pypi, docker, homebrew, unknown
Determines how the package will be resolved and executed

name

The package name as it appears in the registry
For Docker: use fully qualified image names
For npm/PyPI: use exact package names
For Homebrew: use formula names

version

Package version to install/use
Use latest for the most recent version
Specify exact versions for reproducible builds
Support for semantic versioning ranges

Optional Fields

runtime_hint

Hint about the runtime environment
Common values: node, python, docker, brew
Can specify full paths to custom runtimes
Used to optimize execution strategy

runtime_arguments

Arguments passed to the runtime (not the package)
Examples: Node.js memory flags, Python optimization flags
Docker run options, Homebrew execution parameters
Array of strings for complex argument structures

package_arguments

Arguments passed directly to the package
Configuration flags, input parameters
Package-specific options and settings
Executed after runtime arguments

environment_variables

Array of environment variable definitions
Each variable has name, value, required, and secret flags
Used for API keys, configuration paths, feature flags
Supports both required and optional variables

Environment Variables

Environment variables provide configuration and secrets to your packages:

Variable Properties

{
  "name": "API_KEY",
  "value": "your-secret-key",
  "is_required": true,
  "is_secret": true
}

name (required)

Environment variable name
Should follow standard naming conventions (UPPERCASE_SNAKE_CASE)
Used as the actual environment variable name during execution

value (optional)

The variable value
Can be empty for runtime-provided values
Supports string interpolation in some contexts

is_required (default: false)

Whether the variable must have a value
Required variables without values will prevent execution
Used for validation before package execution

is_secret (default: false)

Whether the variable contains sensitive information
Secret variables are masked in logs and UI
Should be used for API keys, passwords, tokens

Common Environment Patterns

API Configuration

[
  {
    "name": "API_BASE_URL",
    "value": "https://api.example.com",
    "is_required": true,
    "is_secret": false
  },
  {
    "name": "API_KEY",
    "value": "",
    "is_required": true,
    "is_secret": true
  }
]

Runtime Behavior

[
  {
    "name": "DEBUG",
    "value": "false",
    "is_required": false,
    "is_secret": false
  },
  {
    "name": "LOG_LEVEL",
    "value": "info",
    "is_required": false,
    "is_secret": false
  }
]
}

Variables in Package Configuration

Package configuration supports dynamic variables using bracket notation ({variable_name}) to avoid hardcoding sensitive information or environment-specific values. Variables are resolved at runtime through a hierarchical lookup system.

Variable Resolution Order

When a variable is referenced, Pylee resolves its value by checking the following sources in order:

Organization variables or secrets - Global settings for your organization
Registry variables or secrets - Shared configuration across the registry
User prompt - Interactive prompt when no value is found for required variables

Using Variables in Package Configuration

Variables can be used in any string value within your package configuration: Environment Variables with Dynamic Values:

{
  "environment_variables": [
    {
      "name": "DATABASE_URL",
      "value": "postgresql://{db_user}:{db_password}@{db_host}:5432/{db_name}",
      "is_required": true,
      "is_secret": true
    },
    {
      "name": "API_TOKEN",
      "value": "{github_token}",
      "is_required": true,
      "is_secret": true
    }
  ]
}

Package Arguments with Variables:

{
  "package_arguments": [
    "--config", "{config_path}",
    "--max-connections", "{max_conn}",
    "--debug={debug_mode}"
  ]
}

For comprehensive information about variables configuration, see the Variables Configuration Guide.

Configuration Examples

Complete npm Package Setup

{
  "registry_name": "npm",
  "name": "@modelcontextprotocol/server-filesystem",
  "version": "0.4.0",
  "runtime_hint": "node",
  "runtime_arguments": [
    "--max-old-space-size=2048",
    "--enable-source-maps"
  ],
  "package_arguments": [
    "--root-path",
    "/workspace",
    "--watch-changes"
  ],
  "environment_variables": [
    {
      "name": "NODE_ENV",
      "value": "production",
      "is_required": true,
      "is_secret": false
    },
    {
      "name": "FS_MAX_FILE_SIZE",
      "value": "10MB",
      "is_required": false,
      "is_secret": false
    }
  ]
}

Python Package with Secrets

{
  "registry_name": "pypi",
  "name": "mcp-server-github",
  "version": "1.2.0",
  "runtime_hint": "python",
  "runtime_arguments": ["-u", "-W", "ignore::DeprecationWarning"],
  "package_arguments": ["--enable-webhooks", "--cache-responses"],
  "environment_variables": [
    {
      "name": "GITHUB_TOKEN",
      "value": "",
      "is_required": true,
      "is_secret": true
    },
    {
      "name": "GITHUB_ORG",
      "value": "your-organization",
      "is_required": true,
      "is_secret": false
    },
    {
      "name": "RATE_LIMIT_REQUESTS",
      "value": "5000",
      "is_required": false,
      "is_secret": false
    }
  ]
}

Docker Container Configuration

{
  "registry_name": "docker",
  "name": "postgres:15-alpine",
  "version": "15.4",
  "runtime_hint": "docker",
  "runtime_arguments": [
    "run",
    "--rm",
    "-p", "5432:5432",
    "-v", "postgres_data:/var/lib/postgresql/data"
  ],
  "package_arguments": [],
  "environment_variables": [
    {
      "name": "POSTGRES_DB",
      "value": "mcp_database",
      "is_required": true,
      "is_secret": false
    },
    {
      "name": "POSTGRES_USER",
      "value": "mcp_user",
      "is_required": true,
      "is_secret": false
    },
    {
      "name": "POSTGRES_PASSWORD",
      "value": "",
      "is_required": true,
      "is_secret": true
    }
  ]
}

Best Practices

Version Management

Pin Specific Versions

{
  "name": "@modelcontextprotocol/server-filesystem",
  "version": "0.4.0"  // Specific version for reproducibility
}

Use Semantic Versioning

{
  "name": "mcp-server-github",
  "version": "^1.2.0"  // Compatible updates within major version
}

Security Considerations

Protect Sensitive Data

{
  "environment_variables": [
    {
      "name": "DATABASE_PASSWORD",
      "value": "",  // Leave empty, provide at runtime
      "is_required": true,
      "is_secret": true
    }
  ]
}

Validate Input Arguments

{
  "package_arguments": [
    "--max-connections", "100",  // Limit resource usage
    "--timeout", "30s",         // Prevent hanging operations
    "--safe-mode"               // Enable safety checks
  ]
}

Performance Optimization

Configure Runtime Limits

{
  "runtime_arguments": [
    "--max-old-space-size=1024",  // Node.js memory limit
    "--gc-interval=100"           // Garbage collection frequency
  ]
}

Enable Caching

{
  "package_arguments": [
    "--cache-dir", "/tmp/mcp-cache",
    "--cache-ttl", "3600"
  ]
}

Troubleshooting

Common Issues

Package Not Found

Verify the package name matches the registry exactly
Check if the version exists in the registry
Ensure network access to the package registry

Runtime Errors

Review runtime_arguments for compatibility
Check environment variable requirements
Validate package_arguments syntax

Permission Issues

Ensure proper file system permissions
Check Docker daemon access (for Docker packages)
Verify Homebrew installation permissions

Environment Variable Problems

Confirm required variables have values
Check for typos in variable names
Validate secret variable handling

Debugging Tips

Enable Debug Logging

{
  "environment_variables": [
    {
      "name": "DEBUG",
      "value": "*",
      "is_required": false,
      "is_secret": false
    }
  ]
}

Test Package Execution

{
  "package_arguments": [
    "--version",  // Test basic package functionality
    "--help"      // Verify argument parsing
  ]
}

Next Steps

After configuring your packages:

Learn about MCP server configuration for advanced settings
Set up local connections for development
Configure remote connections for production
Explore MCP server examples

Need Help?

For package configuration support:

Check the MCP Server Registry for examples
Review package-specific documentation
Visit community discussions
Explore [registry-specific documentation](https://docs.npmjs.com/, https://pypi.org/help/, https://docs.docker.com/)

Get Started

Using Pylee

Understanding Pylee

MCP Servers

Support

Packages Configuration

Package Configuration

Overview

Supported Package Registries

npm (Node.js)

PyPI (Python)

Docker

Homebrew (macOS/Linux)

Unknown Registry

Package Configuration Fields

Required Fields

Optional Fields

Environment Variables

Variable Properties

Common Environment Patterns

Variables in Package Configuration

Variable Resolution Order

Using Variables in Package Configuration

Configuration Examples

Complete npm Package Setup

Python Package with Secrets

Docker Container Configuration

Best Practices

Version Management

Security Considerations

Performance Optimization

Troubleshooting

Common Issues

Debugging Tips

Next Steps

Need Help?

Get Started

Using Pylee

Understanding Pylee

MCP Servers

Support

​Package Configuration

​Overview

​Supported Package Registries

​npm (Node.js)

​PyPI (Python)

​Docker

​Homebrew (macOS/Linux)

​Unknown Registry

​Package Configuration Fields

​Required Fields

​Optional Fields

​Environment Variables

​Variable Properties

​Common Environment Patterns

​Variables in Package Configuration

​Variable Resolution Order

​Using Variables in Package Configuration

​Configuration Examples

​Complete npm Package Setup

​Python Package with Secrets

​Docker Container Configuration

​Best Practices

​Version Management

​Security Considerations

​Performance Optimization

​Troubleshooting

​Common Issues

​Debugging Tips

​Next Steps

​Need Help?

Package Configuration

Overview

Supported Package Registries

npm (Node.js)

PyPI (Python)

Docker

Homebrew (macOS/Linux)

Unknown Registry

Package Configuration Fields

Required Fields

Optional Fields

Environment Variables

Variable Properties

Common Environment Patterns

Variables in Package Configuration

Variable Resolution Order

Using Variables in Package Configuration

Configuration Examples

Complete npm Package Setup

Python Package with Secrets

Docker Container Configuration

Best Practices

Version Management

Security Considerations

Performance Optimization

Troubleshooting

Common Issues

Debugging Tips

Next Steps

Need Help?