# ManageEngine Endpoint Central — MCP Server

A Python server that exposes **106 ManageEngine Endpoint Central REST API endpoints as MCP tools**, enabling Gemini Enterprise to query and manage organizational endpoints through natural language.

## What This Does

End users ask questions in **Gemini Enterprise** (Google's AI assistant) such as:
- "Which systems have critical patches pending?"
- "Show me all devices with BitLocker not enabled"
- "List software installed on computer XYZ"
- "Approve patch ID 12345 on all Windows systems"

Gemini selects and calls the appropriate MCP tool on this server, which in turn calls the ManageEngine Endpoint Central REST API and returns the data.

## Architecture

```
User in Gemini Enterprise
        │
        ▼
Gemini Enterprise (AI + OAuth 2.0 with Zoho)
        │ passes Bearer token
        ▼
MCP Server (Google Cloud Run) — /mcp endpoint
        │ forwards as Zoho-oauthtoken header
        ▼
ManageEngine Endpoint Central REST API
        │
        ▼
Response → Gemini → User
```

See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the detailed component breakdown.

## Production Endpoint

```
https://verse-manageengine-mcp-server-852267154002.asia-south1.run.app/mcp
```

## Quick Start — Local Development

```bash
# Install
pip install -e .

# Configure
cp .env.example .env
# Edit .env and set ME_BASE_URL to your ManageEngine server

# Run
python -m src.server
# Server starts at http://0.0.0.0:8000/mcp

# Test
ME_BASE_URL=http://test pytest tests/
```

## Documentation

| Document | Contents |
|---|---|
| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | System components, request flow, auth modes |
| [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) | Step-by-step Cloud Run deployment guide |
| [docs/CONFIGURATION.md](docs/CONFIGURATION.md) | All environment variables and their meaning |
| [docs/INTEGRATIONS.md](docs/INTEGRATIONS.md) | Zoho OAuth setup, Gemini Enterprise registration |
| [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) | Common errors and how to fix them |
| [docs/MAINTENANCE.md](docs/MAINTENANCE.md) | Updates, monitoring, token rotation, limitations |

## Environment Variables

| Variable | Required | Description |
|---|---|---|
| `ME_BASE_URL` | **Yes** | ManageEngine Endpoint Central base URL |
| `IAM_NAME` | No | Zoho IAM name prefix (default: `AaaServer`) |
| `CRVIEW` | No | Custom report view name (default: `CustomReportView`) |
| `PORT` | No | Server port (default: `8000`; Cloud Run uses `8080`) |
| `LOG_LEVEL` | No | Log verbosity (default: `INFO`) |
| `ZOHO_CLIENT_ID` | No* | Zoho OAuth Client ID |
| `ZOHO_CLIENT_SECRET` | No* | Zoho OAuth Client Secret |
| `ZOHO_REFRESH_TOKEN` | No* | Zoho OAuth Refresh Token |
| `ZOHO_TOKEN_URL` | No | Zoho token endpoint (default: `https://accounts.zoho.in/oauth/v2/token`) |

\* Required only for server-managed token refresh mode. When using Gemini Enterprise OAuth delegation, only `ME_BASE_URL` is required.

See `.env.example` for the full template and [docs/CONFIGURATION.md](docs/CONFIGURATION.md) for detailed explanations.

## Tool Categories (106 tools total)

| Category | Count | Examples |
|---|---|---|
| Patch Management | 28 | `patch_list_all`, `patch_approve`, `patch_install`, `patch_apd_create` |
| Vulnerability Management | 8 | `vuln_list`, `vuln_get_system_report` |
| Device Control | 9 | `dc_get_device_audit`, `dc_list_blocked_devices` |
| Custom Fields | 11 | `cf_list`, `cf_create`, `cf_update_value` |
| Inventory | 17 | `inv_list_software`, `inv_get_installed_software` |
| SOM (Systems & OS Mgmt) | 6 | `som_list_computers`, `som_install_agent` |
| Reports | 4 | `report_list_query_reports`, `report_get_custom_data` |
| BitLocker / Encryption | 3 | `bitlocker_get_report`, `bitlocker_get_recovery_keys` |
| DLP | 11 | `dlp_get_endpoint_activity`, `dlp_get_data_rule_violations` |
| Common | 2 | `common_list_custom_groups` |
| DEX | 7 | `dex_get_latest_experience`, `dex_get_device_profile` |

All write/destructive tools are annotated with `destructiveHint=True` so Gemini prompts users for confirmation before executing them.

## Project Structure

```
├── README.md                   — This file
├── docs/
│   ├── ARCHITECTURE.md         — Component map and request flow
│   ├── DEPLOYMENT.md           — Cloud Run deployment guide
│   ├── CONFIGURATION.md        — Environment variable reference
│   ├── INTEGRATIONS.md         — Zoho OAuth + Gemini Enterprise setup
│   ├── TROUBLESHOOTING.md      — Common errors and fixes
│   └── MAINTENANCE.md          — Updates, monitoring, token rotation
├── src/
│   ├── server.py               — Entry point; FastMCP + middleware setup
│   ├── config.py               — Pydantic settings from environment
│   ├── context.py              — Per-request token context variable
│   ├── api/
│   │   ├── client.py           — httpx client with auth + retry logic
│   │   └── endpoints.py        — All ManageEngine API path constants
│   ├── auth/
│   │   └── token_manager.py    — Zoho token auto-refresh manager
│   ├── tools/                  — One file per feature domain (11 modules)
│   │   ├── patch.py
│   │   ├── vulnerability.py
│   │   ├── device_control.py
│   │   ├── custom_field.py
│   │   ├── inventory.py
│   │   ├── som.py
│   │   ├── reports.py
│   │   ├── bitlocker.py
│   │   ├── dlp.py
│   │   ├── common.py
│   │   └── dex.py
│   └── utils/
│       ├── pagination.py       — Unified pagination metadata wrapper
│       ├── errors.py           — Typed exceptions
│       └── logger.py           — Loguru logger config
├── tests/
│   └── test_pagination.py      — Regression tests for pagination logic
├── Dockerfile                  — Container build (Python 3.12-slim)
├── pyproject.toml              — Project metadata and dependencies
├── requirements.txt            — Pip-installable dependencies
├── .env.example                — Environment variable template
├── .dockerignore               — Docker build exclusions
└── GEMINI_SETUP.md             — Gemini Enterprise OAuth setup reference
```

## Deployment

Deployed to Google Cloud Run. To redeploy after code changes:

```bash
gcloud run deploy verse-manageengine-mcp-server \
  --source . \
  --platform managed \
  --region asia-south1 \
  --project gemini-project-n1 \
  --port 8080 \
  --set-env-vars "ME_BASE_URL=https://endpointcentral.manageengine.in,IAM_NAME=AaaServer,CRVIEW=CustomReportView,LOG_LEVEL=INFO,ZOHO_TOKEN_URL=https://accounts.zoho.in/oauth/v2/token"
```

See [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) for the full guide including first-time setup, IAM configuration, and rollback procedures.