MCP Server Osascript

MCP osascript服务器

中文版

通过具有可配置安全配置文件和自动TCC权限处理的模型上下文协议为AI应用程序安全执行AppleScript。

概述

此MCP服务器通过安全的AppleScript执行在AI模型和macOS自动化之间提供桥梁。它采用模块化架构，具有可配置的安全配置文件、自动权限管理和全面的错误处理。

安装

开发设置

# Clone and setup dependencies
uv sync

# Optional: Development mode installation
uv pip install -e .

生产装置

# System-wide installation with uvx
uvx install /path/to/mcp-server-osascript

# From Git repository
uvx install git+https://github.com/your-username/mcp-server-osascript.git

# From PyPI (when published)
uvx install mcp-server-osascript

用法

生产使用

# After uvx installation (available system-wide)
mcp-server-osascript

开发用途

# From project directory
uv run mcp-server-osascript

# From any directory
uv run --project /path/to/mcp-server-osascript mcp-server-osascript

# Alternative: Direct module execution
uv run python -m mcp_server_osascript.server

MCP客户端配置

将此配置添加到MCP客户端：

生产配置：

{
  "mcpServers": {
    "osascript": {
      "command": "mcp-server-osascript",
      "args": []
    }
  }
}

开发配置：

{
  "mcpServers": {
    "osascript": {
      "command": "uv",
      "args": ["run", "--project", "/path/to/mcp-server-osascript", "mcp-server-osascript"]
    }
  }
}

建筑

服务器采用模块化架构构建，由六个重点组件组成：

• 安全系统：具有三个安全配置文件的可配置风险评估
• 执行引擎：通过超时管理直接执行osascript
• 权限处理程序：自动触发TCC权限对话框
• 响应生成器：标准化的API响应格式
• 用户界面：交互式确认对话框
• 服务器核心：FastMCP集成和工具注册

特性

可配置的安全配置文件

• 严格：通过阻止危险操作实现最高安全性
• 平衡的：建议默认值，带有风险警告（默认值）
• 宽松的：对审计日志记录的限制最小

高级权限管理

• 自动触发TCC权限对话框
• 智能错误解析和用户指导
• 支持常见的macOS应用程序
• 手动权限配置说明

综合工具界面

• 单一统一 execute_osascript 工具
• 不执行脚本分析的模拟运行模式
• 可配置的执行超时
• 详细的成功和错误报告

工具参考

execute_osascript

执行或分析具有全面安全性和权限处理的AppleScript/JavaScript代码。

参数：

• script （str）：要执行的AppleScript或JavaScript代码
• execution_timeout （int）：超时秒数（默认值：30）
• security_profile （str）：安全级别-“严格”、“平衡”或“允许”（默认值：“平衡”）
• enable_auto_permissions （bool）：自动触发TCC权限对话框（默认值：true）
• dry_run （bool）：分析脚本而不执行（默认值：false）

响应结构：

{
  "status": "success|error",
  "timestamp": "2024-01-01T12:00:00.000Z",
  "data": {
    "stdout": "execution output",
    "stderr": "error output",
    "execution_time": 1.23
  }
}

错误响应：

{
  "status": "error",
  "timestamp": "2024-01-01T12:00:00.000Z",
  "error": {
    "type": "SECURITY_BLOCKED|TCC_PERMISSION_DENIED|EXECUTION_TIMEOUT|SYNTAX_ERROR",
    "message": "Human-readable error description",
    "details": "Additional error context and repair suggestions"
  }
}

安全功能

脚本分析

• 危险操作的模式匹配
• 风险评分和分类
• 高风险操作确认提示
• 全面的审计日志记录

权限管理

• TCC错误代码检测（-1743）
• 特定应用程序权限指南
• 自动权限对话框触发
• 手动配置说明

执行安全

• 直接执行以正确显示TCC对话框
• 可配置的超时保护
• 子流程错误处理
• 内存和资源管理

系统要求

• 操作系统：macOS（AppleScript运行时所需）
• python：3.10或更高
• 程序包管理器：uv（推荐）或pip
• 权限：用户必须为目标应用程序授予必要的TCC权限

发展

测试

# Validate syntax for all modules
python3 -m py_compile mcp_server_osascript/*.py

# Test individual modules
python3 -c "from mcp_server_osascript.security import SecurityProfileManager; print('Security module OK')"

架构概述

代码库遵循模块化设计，关注点明确分离：

• 安全评估和政策执行
• 脚本执行和子流程管理
• 权限处理和TCC错误解析
• 标准化响应格式
• 用户界面和确认对话框

许可证

MIT许可证