mcp-agentnex 0.1.9
MCP Server for AgentNEX - Bridge between NEXA AI and AgentNEX Backend
License: MIT
Requires Python: >=3.11
Keywords: mcp, agentnex, nexa, device-management, ai, model-context-protocol

# AgentNEX MCP Server

A Model Context Protocol (MCP) server that provides AI assistants with secure access to AgentNEX device management and monitoring capabilities.

[![PyPI version](https://badge.fury.io/py/mcp-agentnex.svg)](https://badge.fury.io/py/mcp-agentnex)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Overview

The AgentNEX MCP Server enables AI assistants to interact with the AgentNEX platform through the Model Context Protocol. It provides tools for device management, telemetry monitoring, and system actions via stdio (JSON-RPC) transport.

## Features

### Tools (8 Available)

| Tool | Description |
|------|-------------|
| `list_devices` | List all registered devices for the account |
| `get_device_telemetry` | Get real-time CPU, memory, disk, and network metrics |
| `get_device_processes` | List running processes with resource usage |
| `restart_process` | Restart a specific process by name |
| `kill_process` | Terminate a process by name or PID |
| `clear_cache` | Clear application cache (Chrome, Edge, Teams, Outlook) |
| `flush_dns` | Flush DNS resolver cache |
| `restart_service` | Restart a Windows service |

### Resources (3 Available)

| Resource URI | Description |
|--------------|-------------|
| `agentnex://devices/all` | List of all registered devices |
| `agentnex://device/{device_id}/status` | Device connection status |
| `agentnex://device/{device_id}/telemetry` | Latest device telemetry data |

## Installation

### From PyPI (Recommended)

```bash
pip install mcp-agentnex
```

### From Source

```bash
git clone https://github.com/ivedha-tech/agentnex-mcpserver.git
cd agentnex-mcpserver
pip install -e .
```

## Quick Start

### 1. Set Environment Variables

```bash
export AGENTNEX_BACKEND_URL=<your-backend-url>
export AGENTNEX_API_KEY=<your-api-key>
```

### 2. Run the Server

```bash
mcp-agentnex
```

The server runs in stdio mode and communicates via JSON-RPC over stdin/stdout.

## Configuration

### Required Environment Variables

| Variable | Description |
|----------|-------------|
| `AGENTNEX_BACKEND_URL` | AgentNEX backend API endpoint |
| `AGENTNEX_API_KEY` | API key for backend authentication |

### Optional Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `AGENTNEX_MCP_SERVER_NAME` | Server name for MCP protocol | `agentnex-mcp-server` |
| `AGENTNEX_MCP_SERVER_VERSION` | Server version | `1.0.0` |
| `AGENTNEX_LOG_LEVEL` | Logging level (DEBUG, INFO, WARNING, ERROR) | `INFO` |
| `AGENTNEX_BACKEND_TIMEOUT` | Backend request timeout (seconds) | `30.0` |
| `AGENTNEX_BACKEND_RETRY_ATTEMPTS` | Number of retry attempts | `3` |

## Usage

### MCP Protocol Communication

The server uses stdio transport and follows the Model Context Protocol specification:

#### Initialize Connection
```json
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{}}}
```

#### List Available Tools
```json
{"jsonrpc":"2.0","id":2,"method":"tools/list"}
```

#### Call a Tool
```json
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_device_telemetry","arguments":{"device_id":"device-uuid"}}}
```

#### List Available Resources
```json
{"jsonrpc":"2.0","id":4,"method":"resources/list"}
```

#### Read a Resource
```json
{"jsonrpc":"2.0","id":5,"method":"resources/read","params":{"uri":"agentnex://devices/all"}}
```

## Integration

### With AI Platforms

AI platforms can integrate with this MCP server by:

1. Installing the package: `pip install mcp-agentnex`
2. Configuring backend URL and API key as environment variables
3. Starting the server as a subprocess
4. Communicating via JSON-RPC messages over stdin/stdout

### Example Integration Code

```python
import subprocess
import json

# Start the MCP server
proc = subprocess.Popen(
    ['mcp-agentnex'],
    stdin=subprocess.PIPE,
    stdout=subprocess.PIPE,
    stderr=subprocess.PIPE,
    env={
        'AGENTNEX_BACKEND_URL': 'https://your-backend-url',
        'AGENTNEX_API_KEY': 'your-api-key'
    }
)

# Send initialize request
request = {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {"protocolVersion": "2024-11-05", "capabilities": {}}
}
proc.stdin.write(json.dumps(request).encode() + b'\n')
proc.stdin.flush()

# Read response
response = proc.stdout.readline()
print(json.loads(response))
```

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                      AI Platform / Client                   │
└───────────────────────────┬─────────────────────────────────┘
                            │ stdio (JSON-RPC)
                            │ stdin/stdout
┌───────────────────────────▼─────────────────────────────────┐
│                  MCP Server (mcp-agentnex)                  │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │    Tools    │  │  Resources  │  │    Formatters       │  │
│  │  (8 tools)  │  │(3 resources)│  │ (telemetry/action)  │  │
│  └──────┬──────┘  └──────┬──────┘  └──────────┬──────────┘  │
│         └────────────────┼───────────────────┘              │
│                          │                                  │
│              ┌───────────▼───────────┐                      │
│              │    Backend Client     │                      │
│              └───────────┬───────────┘                      │
└──────────────────────────┼──────────────────────────────────┘
                           │ HTTP + API Key
┌──────────────────────────▼──────────────────────────────────┐
│                   AgentNEX Backend API                      │
└─────────────────────────────────────────────────────────────┘
```

## Security

- **API Key Authentication**: All backend requests require valid API key
- **Subprocess Isolation**: Server runs as isolated subprocess
- **No Network Exposure**: stdio transport eliminates network attack surface
- **Input Validation**: All tool arguments are validated before execution
- **Secure Communication**: HTTPS support for backend API calls
- **No Sensitive Logging**: API keys and credentials are never logged

## Development

### Setup Development Environment

```bash
# Clone repository
git clone https://github.com/ivedha-tech/agentnex-mcpserver.git
cd agentnex-mcpserver

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Linux/Mac
.\venv\Scripts\Activate.ps1  # Windows

# Install in development mode
pip install -e ".[dev]"

# Configure environment
cp .env.example .env
# Edit .env with your settings
```

### Run Tests

```bash
# Activate virtual environment
source venv/bin/activate

# Run tests
python -m pytest tests/ -v
```

### Test Locally Before PyPI

Use a clean venv and run the full pre-PyPI check (pytest, build, install from wheel, config with NEXA-like extra env):

```bash
# From repo root
python -m venv .venv
.\.venv\Scripts\Activate.ps1   # Windows
# source .venv/bin/activate      # Linux/Mac

pip install -e ".[dev]"
pip install requests            # optional, for test_http_api.py

# Run tests (excludes test_http_api if requests not installed)
python -m pytest tests/ -v --ignore=tests/test_http_api.py

# Config with NEXA/K8s extra env (extra="ignore")
python -m pytest tests/test_config_extra_env.py -v

# Build and verify install
pip install build
python -m build --outdir dist
pip install --force-reinstall dist/mcp_agentnex-*.whl
python -c "from app.mcp_server import cli; from app.core.config import settings; print('OK', settings.agentnex_mcp_server_name)"

# Simulate NEXA env: set postgres_*, openai_api_key, backend_base_url, then load config
# (Should not raise; Settings ignores extra env vars.)
```

Or run the script: `python scripts/test_local_before_pypi.py` (requires `pip install requests` for full test suite).

### Test stdio (health, tools/list, tools/call)

From the repo root with venv activated and `AGENTNEX_BACKEND_URL` and `AGENTNEX_API_KEY` set:

```powershell
# Windows
.\.venv\Scripts\Activate.ps1
$env:AGENTNEX_BACKEND_URL = "https://your-backend-url"
$env:AGENTNEX_API_KEY = "your-api-key"
python scripts/test_stdio_health_and_tools.py
```

```bash
# Linux/Mac
source .venv/bin/activate
export AGENTNEX_BACKEND_URL="https://your-backend-url"
export AGENTNEX_API_KEY="your-api-key"
python scripts/test_stdio_health_and_tools.py
```

This runs initialize (health), `tools/list`, and `tools/call` for `list_devices` over stdio. Expect: `1. Health (initialize): OK`, `2. tools/list: OK`, `3. tools/call list_devices: OK`, then `stdio test: all OK`.

## Publishing

To publish a new version to PyPI:

```bash
# 1. Update version in pyproject.toml and docs/CHANGELOG.md

# 2. (Optional) Run stdio test before release
python scripts/test_stdio_health_and_tools.py

# 3. Build the package
python -m pip install --upgrade build twine
python -m build

# 4. Upload to PyPI (upload only the new version to avoid "File already exists" for old versions)
python -m twine upload dist/mcp_agentnex-0.1.5*   # replace 0.1.5 with your new version
# Or: Remove-Item dist\* -Force; python -m build; python -m twine upload dist/*
```

## Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## Support

For issues and questions:
- GitHub Issues: [https://github.com/ivedha-tech/agentnex-mcpserver/issues](https://github.com/ivedha-tech/agentnex-mcpserver/issues)
- Contact: AgentNEX Team at IVedha Technologies

## License

MIT License - Copyright (c) 2025 IVedha Technologies

## Links

- **PyPI**: [https://pypi.org/project/mcp-agentnex/](https://pypi.org/project/mcp-agentnex/)
- **GitHub**: [https://github.com/ivedha-tech/agentnex-mcpserver](https://github.com/ivedha-tech/agentnex-mcpserver)
- **Documentation**: [https://github.com/ivedha-tech/agentnex-mcpserver/wiki](https://github.com/ivedha-tech/agentnex-mcpserver/wiki)