mpak run: respect compatibility.runtimes.python from manifest

Open
#65 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
45/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Stale
Tech stack
cli, python, typescript
Domain
backend, cli

Research direction

Start with packages/cli/src/commands/packages/run.ts, especially findPythonCommand() and its call in handleRun(), then read the existing tests in packages/cli/src/commands/packages/run.test.ts. Check how the manifest exposes compatibility.runtimes.python and how Python versions are detected. Done means version-aware resolution and a clear error for a mismatch, with tests covering the specified and unspecified runtime cases.

Written by the indexing model from the issue text.

Description

Problem

mpak run uses findPythonCommand() which grabs whatever python3 is on the user's PATH. Python MCPB bundles vendor native .so files compiled for a specific CPython minor version (e.g., cpython-313). If the user has Python 3.12 but the bundle was built with 3.13 deps, they get a confusing ModuleNotFoundError.

Reported in NimbleBrainInc/mcp-folk#1. Reproduced — running the darwin-arm64 bundle with Python 3.12 produces the exact same traceback.

Root Cause

findPythonCommand() in packages/cli/src/commands/packages/run.ts (line 318) tries python3 then python with no version awareness. The MCPB v0.4 manifest schema already has compatibility.runtimes.python but mpak run doesn't read it.

Proposed Fix

Update findPythonCommand() to accept the manifest and:

  1. Read compatibility.runtimes.python from the manifest (e.g., "3.13")
  2. If specified, try python3.13 first, then python3, then python — checking --version output matches
  3. If no matching Python found, give a clear error:
    => Error: This bundle requires Python 3.13 but found Python 3.12.10
    => Install it: brew install [email protected]
    
  4. If compatibility.runtimes.python is not set, fall back to current behavior (try python3 then python)
Stretch: auto-install via uv

If uv is available on PATH, mpak run could auto-install the required Python:

uv python install 3.13

This would make it zero-friction for users. Lower priority than the error message fix.

Files to Change

  • packages/cli/src/commands/packages/run.ts — findPythonCommand() + call site in handleRun()
  • packages/cli/src/commands/packages/run.test.ts — tests for version-aware Python resolution

Related

  • NimbleBrainInc/mcp-folk#1 — original user report
  • NimbleBrainInc/mcp-folk#2 — add compatibility.runtimes.python to folk manifest
Dominant language
TypeScript
Stars
14
Forks
13
Avg merge
16m
Merged PRs (30d)
4

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from NimbleBrainInc/mpak

All issues in NimbleBrainInc/mpak

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.