Percival Ubuntu

Version 0.0.2

Python MCP percival.OS

📋 Description

Percival Ubuntu is a security-focused MCP server for safe Ubuntu operations, optimized specifically for the Nanobot agent. It allows file management and command execution under strict security policies.

This server is part of the percival.OS ecosystem, a Personal Agentic Operating System designed for autonomy, security, and absolute privacy.

---

🛡️ percival.OS Principles

Like all components of percival.OS, this MCP server strictly follows our core principles:

• Privacy & Control: You define exactly which paths and commands the agent can access through policies (secure, dev).
• Data Sovereignty: The agent operates locally on your Ubuntu host, without the need for external intermediaries for system management.
• Hardened Security: Path traversal protection, command sanitization (shell injection blocking), and resource limits to prevent system exhaustion.
• Transparency: Open-source and auditable, with detailed audit logs for every operation performed by the agent.

---

🚀 Features & Tools

File Operations

• ubuntu_list_directory(path): List directory contents with metadata.
• ubuntu_read_file(file_path): Read files with size validation.
• ubuntu_write_file(file_path, content, ...): Atomic file writing.

System Operations

• ubuntu_execute_command(command): Safe execution of allowed shell commands.
• ubuntu_get_system_info(): Get OS, memory, and disk usage information.
• ubuntu_get_server_status(): Returns uptime, active policy, and tool metrics.

Package Management

• ubuntu_search_packages(query): Search APT repositories.
• ubuntu_install_package(package_name): Check availability for installation.

---

⚙️ Configuration in percival.OS (Nanobot)

Add the following configuration to your ~/.nanobot/config.json:

{
  "tools": {
    "mcpServers": {
      "percival-ubuntu": {
        "command": "uv",
        "args": [
          "run",
          "--directory",
          "/path/to/percival-ubuntu-mcp",
          "percival-ubuntu-mcp",
          "--policy",
          "secure"
        ],
        "env": {
          "UBUNTU_MCP_RESPONSE_MODE": "compact",
          "UBUNTU_MCP_AUDIT_JSON": "true"
        }
      }
    }
  }
}

---

🛠️ Development & Testing

This project uses uv for dependency management.

# Sync environment
uv sync --dev

# Verify installation with internal tests
uv run python -m percival_ubuntu_mcp --test

# Test security measures
uv run python -m percival_ubuntu_mcp --security-test

---

📚 About the Project

This server is an integral module of the percival.OS project. It is an evolution of the original Secure Ubuntu MCP Server, optimized for system orchestration via Nanobot.

• Main Repository: https://github.com/bill-kopp-ai-dev/percival.OS
• License: MIT

---

Developed with ❤️ by the percival.OS Team