add python mcp server support

[j4ys0n]

No description provided.

[j4ys0n]

Automated review 🤖

Summary of Changes
Adds first-class Python MCP server support to mcp-api, enabling installation, upgrade, and management of Python-based MCP servers via pip in isolated virtual environments. The implementation extends PackageService, env, API schemas (openapi-packages.json), and documentation (README.md, .nexus/guides/python-mcp-servers-implementation.md) to support a new runtime: "python" discriminator, pythonModule entrypoint, and pip-based dependency management while preserving existing Node.js behavior. Includes comprehensive unit tests (test/packages-python.spec.ts) and Dockerfile updates to embed Python 3.13.

Key Changes & Positives

• Introduces PackageRuntime type ('node' | 'python') and extends PackageInfo/InstallPackageRequest with runtime, pythonModule, venvPath, and pip index configuration fields in src/services/packages.ts (lines 27–33, 50–55).
• Implements robust Python venv isolation: ensureVenv, pipInstall, venvPythonPath, and buildPythonEnv helpers ensure deterministic installs and correct environment setup in src/services/packages.ts (lines 81–201).
• Adds Python-specific branches in installPackage, upgradePackage, and checkForUpdates to use pip instead of npm, avoiding shell interpolation and enforcing stdio-only transport in src/services/packages.ts (lines 306–380, 803–839, 703–727).
• Preserves backward compatibility: Node installs explicitly set runtime: 'node' after success (line 555), and existing stdio/streamable HTTP paths remain unchanged.
• Includes validation guards: pythonModule required for Python, transportType must be stdio, and streamable HTTP fields rejected for Python runtime in src/services/packages.ts (lines 312–321).
  🟢

Potential Issues & Recommendations

1. Issue / Risk: pip index versions fallback returns "unknown" when pip lacks support (older versions), causing updateAvailable: false even if newer versions exist.
   Impact: Users may miss available updates silently.
   Recommendation: Add a warning log when pipIndexLatestVersion fails and consider falling back to pip install --dry-run --upgrade or PyPI JSON API for robustness.
   Status: 🟡 Needs review

2. Issue / Risk: resolvePythonExecutable tries python3/python only if PYTHON_BIN is unset, but does not validate the executable is ≥3.13 (required by klaviyo-mcp-server).
   Impact: Python 3.13+ features may fail at runtime if older interpreters are used.
   Recommendation: Add version check (e.g., execFile(python, ['-c', 'import sys; assert sys.version_info >= (3,13)'])) and fail fast if version is insufficient.
   Status: 🟡 Needs review

3. Issue / Risk: installMissingPackage skips automatic reinstall for Python servers (line 207), but no alternative recovery path is documented or implemented.
   Impact: Failed Python servers may remain uninstalled without manual intervention.
   Recommendation: Add a log message indicating manual reinstall is required or implement a dedicated reinstallPackage method for Python.
   Status: 🟡 Needs review

Language/Framework Checks

• execFile used consistently for pip commands (argument arrays), avoiding shell injection in src/services/packages.ts (lines 113–124, 142–152).
• Platform-specific handling for venv paths (Scripts vs bin, .exe suffix) in venvBinDir, venvPythonPath, venvPipPath (lines 90–103).
• Regex validation for pythonModule (/^[a-zA-Z0-9_.]+$/) and package name (/^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/) prevents injection in src/services/packages.ts (lines 313–315).

Security & Privacy

• Python package names validated against PyPI-safe characters only (no extras/VCS URLs), preventing malformed specs in src/services/packages.ts (line 315).
• Virtual environment paths are sanitized via sanitizeServerName (replacing non-alphanumeric chars with -) before resolution in src/services/packages.ts (line 81).
• PYTHONUNBUFFERED=1 and VIRTUAL_ENV set in server env ensures stderr logs reach MCP service correctly (lines 195–201).

Build/CI & Ops

• Dockerfile adds Python 3.13 runtime artifacts from a multi-stage build (python:3.13-slim-bookworm) and sets PYTHON_BIN=/usr/local/bin/python3.13 (lines 2–29).
• docker-compose.yml explicitly sets PYTHON_BIN=/usr/local/bin/python3.13 in environment (line 14).
• example.env and README.md document Python-related environment variables (PYTHON_BIN, PYTHON_VENV_DIR, PIP_INDEX_URL, PIP_EXTRA_INDEX_URL).

Tests

• Unit tests cover Python install rejection (missing pythonModule), venv setup, stdio server registration with correct env vars, and upgrade/update-check flows in test/packages-python.spec.ts (lines 1–323).
• Tests mock execFile/exec to verify pip arguments (['install', ...], ['show', ...], ['index', 'versions', ...]) and env injection (PYTHONUNBUFFERED, VIRTUAL_ENV, PATH).
• Missing integration test fixture (test/fixtures/python-mcp-server) as noted in guide—should be added before production deployment.

Approval Recommendation
Approve with caveats

• Add version check in resolvePythonExecutable to enforce ≥3.13.
• Implement fallback strategy (e.g., PyPI JSON API) for checkForUpdates when pip index versions fails.
• Document manual recovery steps for failed Python servers in installMissingPackage.
• Add minimal Python MCP server fixture under test/fixtures/python-mcp-server before merging.

[Copilot]

Pull request overview

This PR adds first-class support for installing, managing, and running Python MCP servers alongside the existing Node.js package support. The implementation creates isolated virtual environments for each Python MCP server, uses pip for package management, and registers them with the same MCP service infrastructure used for Node.js servers.

Changes:

• Added Python runtime support with virtual environment isolation and pip-based package management
• Extended package installation API to accept runtime, pythonModule, pythonArgs, and pip configuration options
• Implemented Python-specific upgrade and update-check flows using pip commands
• Added comprehensive test coverage for Python runtime functionality
• Updated Docker image to include Python 3.13 runtime
• Extended API documentation and OpenAPI schema with Python examples

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
src/services/packages.ts	Core implementation: added Python runtime type, venv helpers, pip operations, and Python-specific install/upgrade/check-update logic
test/packages-python.spec.ts	Comprehensive test suite for Python runtime validation, installation, upgrades, and update checks
src/env.ts	Added Python configuration environment variables (PYTHON_BIN, PYTHON_VENV_DIR, PIP_INDEX_URL, PIP_EXTRA_INDEX_URL)
openapi-packages.json	Extended API schema with Python runtime fields and example requests
example.env	Documented Python-specific environment variable options
README.md	Added Python installation examples and runtime behavior documentation
Dockerfile	Multi-stage build to include Python 3.13 runtime from official image
docker-compose.yml	Set default PYTHON_BIN environment variable for container deployments
package.json	Version bump from 1.9.0 to 1.10.0
.nexus/guides/python-mcp-servers-implementation.md	Comprehensive implementation guide documenting design decisions, security requirements, and data model changes

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.