nanobot/mcp-servers/README.md

# Local MCP servers

This repo uses a **local-clone policy** for MCP servers: clone upstream repos into `./mcp-servers/` and run them from disk (instead of fetching from npm/PyPI at runtime).

## Gitea MCP

- **Upstream**: `https://gitea.com/gitea/gitea-mcp.git`
- **Local path**: `mcp-servers/gitea-mcp/`
- **Binary**: `mcp-servers/gitea-mcp/gitea-mcp`

Build it with:

```bash
./scripts/setup-mcp-servers.sh gitea
```

Then configure nanobot (example):

```jsonc
{
  "tools": {
    "mcpServers": {
      "gitea": {
        "command": "./mcp-servers/gitea-mcp/gitea-mcp",
        "args": ["-t", "stdio", "--host", "http://10.0.30.169:3000"],
        "env": {
          "GITEA_ACCESS_TOKEN": "$NANOBOT_GITLE_TOKEN"
        }
      }
    }
  }
}
```

## Proxmox MCP (ProxmoxMCP-Plus)

[ProxmoxMCP-Plus](https://github.com/RekklesNA/ProxmoxMCP-Plus.git) integrates Proxmox VE over MCP stdio. It registers **many** tools; use nanobot **`tools.toolProfiles`** so only **one MCP server** (plus builtins) is connected per turn, and **`tools.toolRouting.enabled`** so the right profile is chosen from the user message (keyword fast-paths for Proxmox and Gitea in `nanobot/agent/tool_routing.py`, then a small router LLM call).

### Prerequisites

- Python **3.11+** where the server runs.
- Proxmox API token (Datacenter → Permissions → API Tokens). Scope roles to what you accept (`PVEAuditor` for read-only).

### Install (local clone)

From the nanobot repo root (e.g. `/mnt/data/nanobot`):

```bash
# optional: source venv/bin/activate — setup script prefers ./venv/bin/python when present
./scripts/setup-mcp-servers.sh proxmox-mcp-plus
```

This clones into `mcp-servers/proxmox-mcp-plus/` and runs `pip install -e` using **`venv/bin/python`** in the repo if it exists, otherwise `python3`. Override with `NANOBOT_PYTHON=/path/to/python` if needed. No extra `.venv` under the clone.

It also seeds `proxmox-config/config.json` from `config.example.json` if missing.

Edit **`mcp-servers/proxmox-mcp-plus/proxmox-config/config.json`**: set `proxmox.host`, `auth.user`, `auth.token_name`, `auth.token_value`. Keep `mcp.transport` **`STDIO`** for nanobot. Do not commit secrets (the tree under `mcp-servers/` is gitignored except this file).

### Register in nanobot `config.json`

Use the **same Python** that ran `pip install -e` (absolute path avoids `PATH` mismatches in Docker/systemd).

Example for this checkout (`venv` at repo root — adjust if your clone lives elsewhere):

```jsonc
{
  "tools": {
    "mcpServers": {
      "proxmox": {
        "command": "/mnt/data/nanobot/venv/bin/python",
        "args": ["-m", "proxmox_mcp.server"],
        "env": {
          "PROXMOX_MCP_CONFIG": "/mnt/data/nanobot/mcp-servers/proxmox-mcp-plus/proxmox-config/config.json"
        }
      }
    }
  }
}
```

(`pip install -e` registers `proxmox_mcp`; you do not need `PYTHONPATH` for normal use.)

Tools appear as `mcp_proxmox_<tool>` (normalized from upstream names).

### One profile per MCP (local LLMs)

Add **`tools.toolProfiles`**: each profile’s `mcpServers` lists **only** the server keys to connect for that turn. A **`default`** profile with **`"mcpServers": []`** keeps ordinary chat free of huge MCP tool lists.

Example (trim or extend profiles to match your `mcpServers` keys):

```jsonc
{
  "tools": {
    "defaultToolProfile": "default",
    "toolRouting": { "enabled": true },
    "mcpServers": {
      "gmail_mcp": {
        "command": "npx",
        "args": ["-y", "@gongrzhe/server-gmail-autoauth-mcp"]
      },
      "gitea": {
        "command": "/mnt/data/nanobot/mcp-servers/gitea-mcp/gitea-mcp",
        "args": ["-t", "stdio", "--host", "https://gitea.example.com"],
        "env": { "GITEA_ACCESS_TOKEN": "$GITEA_TOKEN" }
      },
      "proxmox": {
        "command": "/mnt/data/nanobot/venv/bin/python",
        "args": ["-m", "proxmox_mcp.server"],
        "env": {
          "PROXMOX_MCP_CONFIG": "/mnt/data/nanobot/mcp-servers/proxmox-mcp-plus/proxmox-config/config.json"
        }
      }
    },
    "toolProfiles": {
      "default": {
        "description": "Built-in tools only (filesystem, shell, web, cron, etc.). No MCP servers.",
        "mcpServers": []
      },
      "gmail_mcp": {
        "description": "Gmail: read/search/send mail via Gmail MCP.",
        "mcpServers": ["gmail_mcp"]
      },
      "gitea": {
        "description": "Gitea: pull requests, issues, repos, code search.",
        "mcpServers": ["gitea"]
      },
      "proxmox": {
        "description": "Proxmox VE: nodes, VMs, LXC, storage, snapshots, backups, cluster status.",
        "mcpServers": ["proxmox"]
      }
    }
  }
}
```

Profile keys **`proxmox`** and **`gitea`** are matched by router heuristics. For Gmail, use profile key **`gmail_mcp`** if that matches your server name, or rely on the router model and each profile’s `description`.

### Verify

1. Start nanobot with the edited config.
2. Ask something Proxmox-specific (e.g. “list VMs on Proxmox”) and check logs for `Tool profile 'proxmox': … tools exposed`.
3. Confirm only `mcp_proxmox_*/tools` are available for that turn.