Skip to main content

​
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_type": "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_type": "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_type": "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_type": "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_type": "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_type
  • 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:
  1. Organization variables or secrets - Global settings for your organization
  2. Registry variables or secrets - Shared configuration across the registry
  3. 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_type": "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_type": "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_type": "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:

​
Need Help?

For package configuration support:
⌘I