Preview This is the v1.0 preview line. It documents a rebuild that is still in alpha — schemas, tool names, and package contents change without notice, and nothing here is covered by a stability guarantee. For the released line, see the v0.x documentation.

Python MCP runtime contract

Supported Python, uv, dependency, cache, and transport behavior.

Python is an intentional processkit runtime dependency. It implements the MCP servers; it is not required by the Model Context Protocol itself. The native Rust CLI owns installation and lifecycle safety. Native diagnostics and process supervision wrap that Python implementation; they do not reimplement MCP behavior.

Current alpha requirements

  • Python 3.10 or newer must be discoverable by uv.
  • uv must support PEP 723 script metadata.
  • The installed gateway script and processkit shared Python library must be readable from the selected project root.
  • The first preparation may require network access to populate the uv cache.
  • Direct uv run startup remains a supported compatibility and development interface.

Every shipped MCP entry point declares its Python constraint and dependencies in a PEP 723 block. The gateway currently declares:

requires-python = ">=3.10"
dependencies = [
  "mcp[cli]>=1.0,<2.0",
  "pyyaml>=6.0",
  "jsonschema>=4.0",
  "jinja2>=3.1",
  "httpx>=0.27",
  "sqlite-vec>=0.1.0",
]

The release manifest records a digest of every server dependency header. Changing a header requires regenerating that manifest and restarting the server.

The release also ships .processkit/installer/runtime/python-uv.json. This deterministic policy is generated exclusively from the MCP servers under the release’s src/context/ producer tree. It records each server header, its dependency profile, and an aggregate digest. Installed projects receive it as .processkit/runtime/python-uv.json.

The release also installs a universal, hash-checked requirements lock at .processkit/runtime/python-requirements.lock. The policy binds its SHA-256. Runtime preparation refuses a missing, symlinked, unhashed, or digest-mismatched lock and passes the lock directly to uv.

Dependency and cache behavior

uv resolves PEP 723 dependencies and stores downloaded artifacts and environments in its user cache. Operators may select a separate cache through UV_CACHE_DIR. The cache must remain outside processkit’s managed project content; normal MCP startup must not modify context/, src/context/, or tracked configuration.

Resolved runtime versions and distributions are locked with hashes. A cold offline installation still requires a prepared cache because wheels are not embedded in the release. Prepare the locked runtime into the selected cache:

processkit mcp prepare --root .
processkit mcp prepare --root . --cache-dir /absolute/cache/path

Then prove that the same policy is usable without network resolution:

processkit mcp prepare --root . --offline
processkit mcp prepare --root . \
  --cache-dir /absolute/cache/path \
  --offline \
  --json

Offline verification fails if the cache directory is absent, symlinked, or cannot satisfy any dependency profile. Preparation validates the installed policy identity, aggregate digest, profile digests, representative server paths, dependency strings, and Python constraints before invoking uv without a shell.

Startup and transport

Direct gateway startup is:

uv run context/skills/processkit/processkit-gateway/mcp/server.py \
  serve --transport stdio

The gateway also supports streamable HTTP on loopback and a stdio proxy. A non-loopback HTTP listener requires an explicit deployment security layer; processkit does not expose it remotely by default.

The v1.x-dev line implements the first read-only native diagnostic:

processkit doctor --root . --json
processkit doctor --root . --category drift

It validates the project root and doctor script, probes uv, launches the authoritative Python doctor without a shell, and wraps its structured result in processkit.projectious.work/runtime/v1alpha1. It intentionally exposes no fix flags.

The v1.x-dev line also implements the native supervision interface:

processkit mcp verify
processkit mcp prepare
processkit mcp prepare --offline
processkit mcp serve --transport stdio
processkit mcp serve --transport streamable-http
processkit mcp proxy --url http://127.0.0.1:8000/mcp

These commands validate a regular, non-symlink gateway path and launch uv with a direct argument vector, without shell interpretation. The child is scoped to the canonical project root and its exit status is preserved. Streamable HTTP and proxy URLs are restricted to explicit loopback hosts; remote exposure remains an operator-owned deployment concern.

Diagnostic contract

The native doctor preserves Python findings, reports whether it is running on a local host or in a container, and lists deferred host-only checks with stable IDs, severity, and remediation. The host-only IDs are host.docker-engine, host.filesystem-permissions, and host.network-release-access.

Runtime failures cover:

  • missing or unsupported Python;
  • missing or incompatible uv;
  • unreadable gateway or shared-library paths;
  • invalid PEP 723 metadata;
  • unavailable, unsafe, or incomplete runtime cache;
  • gateway initialization or startup timeout;
  • invalid harness projection;
  • optional semantic-index degradation.

Missing optional sqlite-vec acceleration must not be confused with failure of the canonical file-backed entity operations. Diagnostic output must never include environment secrets, provider credentials, private signing material, or private TeamMember memory.