Skip to content

Add pip-installable MCP server support to packages #80

@troylar

Description

@troylar

Description

Add support for pip-installable MCP servers in DevSync packages. When extracting, DevSync should detect pip-installed MCP servers and include them in the package manifest with their pip package specifier. When installing, DevSync should pip install the declared packages. When updating, pip packages should be updated alongside practice files.

Context

Currently, MCP servers in DevSync are handled as either:

  • JSON config files (v1 ai-config-kit-package.yaml components)
  • Abstract declarations with command/args (v2 MCPDeclaration)

Neither format captures the concept of a pip-installable MCP server. Many MCP servers are distributed via pip (e.g., mcp-server-github, mcp-server-filesystem) and launched via uvx, python -m, or entry-point scripts. DevSync should be able to:

  1. Detect pip-installed MCP servers during extraction (query importlib.metadata)
  2. Declare them in the manifest with version constraints (e.g., mcp-server-github>=1.0.0)
  3. Install them via pip install during devsync install (with user confirmation)
  4. Update them via a new devsync update command or flag

Affected Files

  • devsync/core/practice.py — Add pip_package field to MCPDeclaration
  • devsync/core/package_manifest_v2.py — Parse pip_package from manifest YAML
  • devsync/core/component_detector.py — Detect pip-installed MCP servers via importlib.metadata
  • devsync/core/extractor.py — Include pip package info in extracted MCP declarations
  • devsync/cli/install_v2.py — Run pip install for declared pip packages during install
  • devsync/cli/main.py — Add update command (or --update flag on install)
  • devsync/llm/prompts.py — Update extraction prompts to detect pip packages
  • tests/unit/core/test_mcp_credential_prompter.py — Update for pip_package field
  • tests/unit/llm/test_response_models.py — Update for new MCPDeclaration fields

Acceptance Criteria

  • MCPDeclaration supports optional pip_package: str field (e.g., mcp-server-github>=1.0.0)
  • devsync extract detects pip-installed MCP servers and includes pip_package in the manifest
  • devsync-package.yaml schema supports pip_package field on mcp_servers entries
  • devsync install prompts user before running pip install for any declared pip packages
  • devsync install skips pip install if package is already installed at compatible version
  • Update mechanism exists (new command or flag) that updates pip packages to latest compatible version
  • Manifest never stores credential values — only pip package specifiers and credential specs
  • --no-ai / offline mode still works when pip packages are already installed
  • Tests pass: invoke test-unit
  • Lint passes: invoke lint

Implementation Notes

Manifest format addition:

mcp_servers:
  - name: github
    description: GitHub API access
    pip_package: mcp-server-github>=1.0.0
    command: mcp-server-github
    args: []
    credentials:
      - name: GITHUB_TOKEN
        description: GitHub personal access token
        required: true

Detection approach: Use importlib.metadata.distributions() to find packages with mcp entry points or matching mcp-server-* naming patterns. Cross-reference with detected MCP configs in .claude/settings.local.json to match running servers to their pip packages.

Security: pip install is a privileged operation. The install command should clearly show what will be installed and require explicit user confirmation. Consider supporting --skip-pip flag for users who manage packages separately.

Metadata

Metadata

Assignees

Labels

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions