# 🤖 Percival Ubuntu - percival.OS MCP

**Version 0.0.2**

[![Python](https://img.shields.io/badge/python-3.11+-yellow.svg)]()
[![MCP](https://img.shields.io/badge/mcp-server-blue.svg)]()
[![percival.OS](https://img.shields.io/badge/percival.OS-ecosystem-orange.svg)](https://github.com/bill-kopp-ai-dev/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`:

```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.

```bash
# 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](https://github.com/bill-kopp-ai-dev/percival.OS)
- **License**: MIT

---
*Developed with ❤️ by the percival.OS Team*