Py MCP Installer Service

py-mcp安装服务

用于AI编码工具的通用MCP服务器安装程序

   

概述

py-mcp-installer-service 是一个用于安装和管理的全面Python库 模型上下文协议（MCP） 跨多个AI编码平台的服务器。它提供自动平台检测、智能安装方法选择以及具有验证和自动修复功能的原子配置更新。

主要特点

• 平台自动检测：自动检测Claude Desktop、Cline、Roo Code、Continue、Zed和其他MCP兼容平台
• 多格式支持：处理现代JSON和传统的cline_mcp_settings.JSON格式
• 智能安装：选择最佳安装方法（uv run、pipx、direct、python-m）
• 原子操作：所有配置更改都是原子性的，具有验证和回滚功能
• 遗留迁移：自动将传统格式配置迁移到现代JSON
• 全面验证：验证配置、检测冲突并提出修复建议
• 自动修复功能：可以自动修复常见的配置问题
• 干运行模式：在应用更改之前预览所有更改

支持的平台

安装

作为独立图书馆

# From PyPI (when published)
pip install py-mcp-installer

# From source
pip install git+https://github.com/bobmatnyc/py-mcp-installer-service.git

开发安装

git clone https://github.com/bobmatnyc/py-mcp-installer-service.git
cd py-mcp-installer-service
pip install -e .

作为另一个项目的子模块

# Add as git submodule
git submodule add https://github.com/bobmatnyc/py-mcp-installer-service.git src/services/py_mcp_installer

# Initialize and update
git submodule update --init --recursive

# Use in your code
from py_mcp_installer import MCPInstaller

快速开始

from py_mcp_installer import MCPInstaller

# Auto-detect platform and install server
installer = MCPInstaller.auto_detect()
result = installer.install_server(
    name="mcp-ticketer",
    command="mcp-ticketer",
    args=["mcp"],
    description="Ticket management interface"
)

if result.success:
    print(f"✅ Installed on {result.platform.value} using {result.method.value}")
    print(f"Config: {result.config_path}")
else:
    print(f"❌ Failed: {result.message}")

特性

平台自动检测

自动检测安装了哪些MCP兼容平台：

from py_mcp_installer import MCPInstaller

installer = MCPInstaller.auto_detect(verbose=True)
print(f"Detected platform: {installer.platform.value}")

智能安装方式选择

根据您的环境选择最佳安装方法：

from py_mcp_installer import MCPInstaller, InstallMethod

# Let installer choose best method
installer = MCPInstaller.auto_detect()
result = installer.install_server(name="my-server", command="my-command")

# Or specify method explicitly
result = installer.install_server(
    name="my-server",
    command="uv",
    args=["run", "my-package"],
    method=InstallMethod.UV_RUN
)

原子配置更新

所有配置更改都是原子性的，并具有自动验证功能：

# Changes are validated before being written
result = installer.install_server(
    name="my-server",
    command="invalid-command"  # Will be validated
)

# On failure, original config is preserved
if not result.success:
    print(f"Config unchanged: {result.message}")

传统格式迁移

自动将旧的cline_mcp_settings.json迁移为现代格式：

from py_mcp_installer.migration import migrate_legacy_config

success = migrate_legacy_config(
    legacy_path=".continue/cline_mcp_settings.json",
    target_path=".continue/config.json",
    backup=True  # Creates .bak file
)

全面验证

验证和检查现有配置：

from py_mcp_installer.inspector import MCPInspector

inspector = MCPInspector(config_path=".continue/config.json")
issues = inspector.inspect()

for issue in issues:
    print(f"{issue.severity}: {issue.message}")
    if issue.auto_fix_available:
        print(f"  Fix: {issue.suggested_fix}")

自动修复功能

自动修复常见配置问题：

from py_mcp_installer.inspector import MCPInspector

inspector = MCPInspector(config_path=".continue/config.json")
fixed = inspector.auto_fix()

print(f"Fixed {len(fixed)} issues")

干运行模式

应用前预览更改：

installer = MCPInstaller.auto_detect(dry_run=True, verbose=True)
result = installer.install_server(name="test-server", command="test")

# No actual changes made, but full validation performed
print(f"Would install: {result.success}")
print(f"Would write to: {result.config_path}")

使用示例

基本安装

from py_mcp_installer import MCPInstaller

installer = MCPInstaller.auto_detect()
result = installer.install_server(
    name="mcp-github",
    command="npx",
    args=["-y", "@modelcontextprotocol/server-github"],
    description="GitHub MCP server"
)

print(f"Installed: {result.success}")

使用环境变量进行安装

result = installer.install_server(
    name="mcp-ticketer",
    command="mcp-ticketer",
    args=["mcp"],
    env={
        "LINEAR_API_KEY": "your-api-key",
        "GITHUB_TOKEN": "your-token"
    }
)

列出已安装的服务器

servers = installer.list_servers()
for server in servers:
    print(f"{server.name}: {server.command} {' '.join(server.args or [])}")

检查并修复配置

from py_mcp_installer.inspector import MCPInspector

# Inspect for issues
inspector = MCPInspector(config_path=".continue/config.json")
issues = inspector.inspect()

# Auto-fix what we can
fixed = inspector.auto_fix()
print(f"Fixed {len(fixed)} issues automatically")

# Report remaining issues
remaining = inspector.inspect()
for issue in remaining:
    if not issue.auto_fix_available:
        print(f"Manual fix needed: {issue.message}")

迁移旧配置

from py_mcp_installer.migration import migrate_legacy_config

success = migrate_legacy_config(
    legacy_path=".continue/cline_mcp_settings.json",
    target_path=".continue/config.json",
    backup=True,
    preserve_legacy=False  # Remove old file after migration
)

if success:
    print("✅ Migration complete")

卸载服务器

success = installer.uninstall_server(name="mcp-ticketer")
print(f"Uninstalled: {success}")

具体平台和范围

from py_mcp_installer import MCPInstaller, Platform, Scope

# Install to specific platform
installer = MCPInstaller(platform=Platform.CLAUDE_DESKTOP)

# Install globally vs. project-scoped
result = installer.install_server(
    name="global-server",
    command="server-cmd",
    scope=Scope.GLOBAL
)

api参考

有关API的详细文档，请参阅 docs/快速参考.md.

核心类

• MCPInstaller：主安装程序编排器
• MCP检查员：配置验证和修复
• 配置管理器：低级配置文件操作
• 安装策略：平台特定的安装逻辑

关键方法

# MCPInstaller
installer = MCPInstaller.auto_detect(dry_run=False, verbose=False)
result = installer.install_server(name, command, args, env, description, scope, method)
servers = installer.list_servers()
success = installer.uninstall_server(name)

# MCPInspector
inspector = MCPInspector(config_path)
issues = inspector.inspect()
fixed = inspector.auto_fix()
is_valid = inspector.validate()

建筑

该库被组织成模块化组件：

py_mcp_installer/
├── types/           # Core types and enums
├── exceptions/      # Custom exceptions
├── utils/           # Platform detection and utilities
├── config/          # Configuration management
├── strategies/      # Platform-specific strategies
├── commands/        # Command builders
├── inspector/       # Validation and auto-fix
├── migration/       # Legacy format migration
└── installer.py     # Main orchestrator

有关详细的体系结构文档，请参阅 docs/ARCHITECTURE.md.

发展

先决条件

• Python 3.11或更高版本
• pip或uv用于包装管理

设置

# Clone repository
git clone https://github.com/bobmatnyc/py-mcp-installer-service.git
cd py-mcp-installer-service

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # or `.venv\Scripts\activate` on Windows

# Install in development mode
pip install -e .

# Install development dependencies
pip install -e ".[dev]"

运行测试

# Run all tests
pytest

# Run with coverage
pytest --cov=py_mcp_installer --cov-report=html

# Run specific test file
pytest tests/test_installer.py

# Run with verbose output
pytest -v

代码格式化

# Format code with black
black src/

# Sort imports with isort
isort src/

# Check with flake8
flake8 src/

类型检查

# Run mypy type checker
mypy src/py_mcp_installer

贡献

欢迎投稿！请遵循以下指南：

1. 复刻仓库 并创建一个特征分支
2. 遵循规范标准:

- 使用黑色进行格式化 - 对所有函数使用类型提示 - 为公共API编写文档字符串 - 遵循SOLID原则

1. 编写测试 所有新功能
2. 更新文档 API变更
3. 提交拉取请求 描述清晰

代码规范

• 类型提示：所有公共函数都必须有类型提示
• 文档字符串：所有类和公共方法的谷歌风格文档字符串
• 错误处理：使用自定义异常，从不接受错误
• 测试：新代码的最小代码覆盖率为80%
• 日志记录：使用结构化日志记录，从不打印语句

测试要求

• 所有核心功能的单元测试
• 针对平台特定策略的集成测试
• 模拟外部依赖关系（文件系统、子流程调用）
• 测试误差条件和边缘情况

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

致谢

• 作为 mcp票务员 项目
• 专为 克劳德MPM 框架
• 灵感来自 模型上下文协议 规格

链接

• 文档: docs/
• 问题追踪:
• 更新日志: 更改日志.md
• MCP规范: https://modelcontextprotocol.io/

______________________________________________________________________

需要帮助？ 打开问题或检查 文档.