Metadata-Version: 2.4
Name: mcp-agentnex
Version: 0.1.0
Summary: MCP Server for AgentNEX - Bridge between NEXA AI and AgentNEX Backend
Author: AgentNEX Team
License: MIT
Project-URL: Homepage, https://github.com/ivedha-tech/agentnex-mcpserver
Project-URL: Repository, https://github.com/ivedha-tech/agentnex-mcpserver
Project-URL: Documentation, https://github.com/ivedha-tech/agentnex-mcpserver#readme
Keywords: mcp,agentnex,nexa,device-management,ai,model-context-protocol
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: mcp>=1.0.0
Requires-Dist: fastapi>=0.109.0
Requires-Dist: uvicorn[standard]>=0.27.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: structlog>=23.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-httpx>=0.25.0; extra == "dev"

# AgentNEX MCP Server

Model Context Protocol (MCP) server for AgentNEX - enabling AI assistants to manage and monitor devices through the AgentNEX platform.

## Overview

This MCP server provides AI assistants (like NEXA) with secure access to AgentNEX device management capabilities. It supports both:
- **HTTP REST API** - For NEXA platform integration (cloud deployment)
- **stdio (JSON-RPC)** - For local MCP clients (Claude Desktop)

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                    NEXA Platform / AI Assistant             │
└───────────────────────────┬─────────────────────────────────┘
                            │ HTTP REST API
┌───────────────────────────▼─────────────────────────────────┐
│                     MCP Server (FastAPI)                    │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │    Tools    │  │  Resources  │  │    Formatters       │  │
│  │  (7 tools)  │  │(3 resources)│  │ (telemetry/action)  │  │
│  └──────┬──────┘  └──────┬──────┘  └──────────┬──────────┘  │
│         └────────────────┼───────────────────┘              │
│                          │                                  │
│              ┌───────────▼───────────┐                      │
│              │    Backend Client     │                      │
│              └───────────┬───────────┘                      │
└──────────────────────────┼──────────────────────────────────┘
                           │ HTTP + API Key
┌──────────────────────────▼──────────────────────────────────┐
│                   AgentNEX Backend API                      │
└─────────────────────────────────────────────────────────────┘
```

## Features

### MCP Tools (7 available)

| Tool | Description |
|------|-------------|
| `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, etc.) |
| `flush_dns` | Flush DNS resolver cache |
| `restart_service` | Restart a Windows service |

### MCP Resources (3 available)

| Resource URI | Description |
|--------------|-------------|
| `agentnex://devices/all` | List of all registered devices |
| `agentnex://devices/{id}/status` | Device connection status |
| `agentnex://devices/{id}/telemetry` | Latest device telemetry data |

## Project Structure

```
agentnex-mcpserver/
├── app/
│   ├── client/
│   │   └── backend_client.py    # HTTP client for AgentNEX backend
│   ├── core/
│   │   ├── config.py            # Settings and configuration
│   │   └── exceptions.py        # Custom exceptions
│   ├── formatters/
│   │   ├── telemetry_formatter.py  # Format telemetry for AI
│   │   └── action_formatter.py     # Format action results
│   ├── resources/
│   │   ├── base.py              # Base resource class
│   │   └── device_resources.py  # Device resource implementations
│   ├── schemas/
│   │   ├── backend_schemas.py   # Backend API schemas
│   │   └── mcp_schemas.py       # MCP protocol schemas
│   ├── tools/
│   │   ├── base.py              # Base tool class
│   │   ├── telemetry_tools.py   # Telemetry tools
│   │   └── action_tools.py      # Action tools
│   ├── http_server.py           # FastAPI HTTP server (for NEXA)
│   ├── mcp_server.py            # stdio MCP server (for Claude Desktop)
│   └── main.py                  # Entry point
├── tests/
│   ├── test_api_key.py
│   ├── test_backend_integration.py
│   ├── test_backend_simple.py
│   ├── test_mcp_server.py
│   └── test_refactored_tools.py
├── .env                         # Environment variables (create from env.example)
├── env.example                  # Example environment configuration
├── requirements.txt             # Python dependencies
├── run_http_server.py           # Run HTTP server (for NEXA)
└── run_server.py                # Run stdio server (for Claude Desktop)
```

## Installation

### Prerequisites

- Python 3.11+ 
- AgentNEX Backend running and accessible
- Valid API key for AgentNEX Backend

### Quick Start (PyPI Installation)

Install the MCP server directly from PyPI:

```bash
pip install mcp-agentnex
```

After installation, configure environment variables and run:

```bash
# Set required environment variables
export AGENTNEX_BACKEND_URL=https://your-backend-url.com
export AGENTNEX_API_KEY=your-api-key-here

# Run the MCP server
mcp-agentnex
```

**For Claude Desktop Integration:**

Add to your Claude Desktop configuration file:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "agentnex": {
      "command": "mcp-agentnex",
      "env": {
        "AGENTNEX_BACKEND_URL": "https://your-backend-url.com",
        "AGENTNEX_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

### Alternative Installation Methods

#### Option 1: Docker (Recommended for Production)

1. **Configure environment:**
   ```bash
   # Copy example config
   cp env.example .env
   
   # Edit .env with your settings
   nano .env
   ```

2. **Build and run with Docker Compose:**
   ```bash
   # Build and start
   docker-compose up --build -d
   
   # View logs
   docker-compose logs -f
   
   # Stop
   docker-compose down
   ```

3. **Or build and run manually:**
   ```bash
   # Build image
   docker build -t agentnex-mcp-server .
   
   # Run container
   docker run -d \
     --name agentnex-mcp-server \
     -p 8001:8001 \
     -e AGENTNEX_BACKEND_URL=http://host.docker.internal:8000/api \
     -e AGENTNEX_API_KEY=your-api-key \
     agentnex-mcp-server
   ```

#### Option 2: Development Installation from Source

1. **Clone and navigate to the project:**
   ```bash
   git clone https://github.com/ivedha-tech/agentnex-mcpserver.git
   cd agentnex-mcpserver
   ```

2. **Create virtual environment:**
   ```bash
   python -m venv venv
   
   # Windows
   .\venv\Scripts\Activate.ps1
   
   # Linux/Mac
   source venv/bin/activate
   ```

3. **Install in development mode:**
   ```bash
   # Install with dependencies
   pip install -e .
   
   # Or install with dev dependencies for testing
   pip install -e ".[dev]"
   ```

4. **Configure environment:**
   ```bash
   # Copy example config
   cp .env.example .env
   
   # Edit .env with your settings
   nano .env  # or use any text editor
   ```

5. **Update `.env` file:**
   ```env
   AGENTNEX_BACKEND_URL=http://localhost:8000
   AGENTNEX_API_KEY=your-internal-api-key-here
   MCP_SERVER_PORT=8001
   ```

6. **Run the server:**
   ```bash
   # Run via CLI command
   mcp-agentnex
   
   # Or run directly with Python
   python -m app.mcp_server
   ```

## Running the Server

### Docker (Production)

```bash
# Start with Docker Compose
docker-compose up -d

# Check status
docker-compose ps

# View logs
docker-compose logs -f mcp-server

# Stop
docker-compose down
```

### Local Development

#### HTTP Server (for NEXA Platform)

```bash
# Activate virtual environment first
.\venv\Scripts\Activate.ps1  # Windows
source venv/bin/activate      # Linux/Mac

# Run HTTP server
python run_http_server.py
```

Server will start at `http://localhost:8001`

#### stdio Server (for Claude Desktop)

**If installed via PyPI:**
```bash
mcp-agentnex
```

**If running from source:**
```bash
python run_server.py
```

## API Endpoints

### Health Check
```
GET /health
Response: {"status": "healthy", "backend_connected": true}
```

### List Tools
```
GET /mcp/tools
Response: {"tools": [...]}
```

### Call Tool
```
POST /mcp/tools/call
Content-Type: application/json

{
  "name": "get_device_telemetry",
  "arguments": {
    "device_id": "your-device-uuid"
  }
}
```

### List Resources
```
GET /mcp/resources
Response: {"resources": [...]}
```

### Read Resource
```
POST /mcp/resources/read
Content-Type: application/json

{
  "uri": "agentnex://devices/all"
}
```

## Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `AGENTNEX_BACKEND_URL` | AgentNEX backend API URL | `http://localhost:8000` |
| `AGENTNEX_API_KEY` | Internal API key for authentication | Required |
| `MCP_SERVER_PORT` | HTTP server port | `8001` |
| `MCP_SERVER_NAME` | Server name for MCP protocol | `agentnex-mcp-server` |
| `MCP_SERVER_VERSION` | Server version | `1.0.0` |
| `LOG_LEVEL` | Logging level | `INFO` |
| `BACKEND_TIMEOUT` | Backend request timeout (seconds) | `30` |
| `BACKEND_RETRY_ATTEMPTS` | Number of retry attempts | `3` |

## Testing

```bash
# Activate virtual environment
.\venv\Scripts\Activate.ps1

# Run specific test
python tests/test_api_key.py
python tests/test_mcp_server.py

# Run all tests with pytest
python -m pytest tests/ -v
```

## NEXA Platform Integration

To integrate with NEXA platform:

1. Deploy HTTP server to a publicly accessible endpoint
2. Register the MCP server URL in NEXA
3. Configure agents to use the MCP tools

### Example Tool Usage in NEXA Agent

```
Tool: get_device_telemetry
Input: {"device_id": "0682f172-cd1f-450a-97c9-bfc4ae56adcc"}
Output: Formatted telemetry data for AI consumption
```

## Docker Deployment

### Build Options

```bash
# Standard build
docker build -t agentnex-mcp-server .

# Build with specific tag
docker build -t agentnex-mcp-server:v1.0.0 .

# Build for production registry
docker build -t your-registry.com/agentnex-mcp-server:latest .
docker push your-registry.com/agentnex-mcp-server:latest
```

### Environment Variables for Docker

| Variable | Description | Default |
|----------|-------------|---------|
| `AGENTNEX_BACKEND_URL` | Backend URL (use `host.docker.internal` for local backend) | Required |
| `AGENTNEX_API_KEY` | Internal API key | Required |
| `MCP_SERVER_PORT` | Server port | `8001` |
| `LOG_LEVEL` | Log level (DEBUG, INFO, WARNING, ERROR) | `INFO` |
| `LOG_FORMAT` | Log format (json, text) | `json` |

### Docker Compose with Full Stack

To run MCP server alongside the backend:

```yaml
# docker-compose.full.yml
version: '3.8'

services:
  backend:
    image: agentnex-backend:latest
    ports:
      - "8000:8000"
    networks:
      - agentnex-network

  mcp-server:
    image: agentnex-mcp-server:latest
    ports:
      - "8001:8001"
    environment:
      - AGENTNEX_BACKEND_URL=http://backend:8000/api
      - AGENTNEX_API_KEY=${AGENTNEX_API_KEY}
    depends_on:
      - backend
    networks:
      - agentnex-network

networks:
  agentnex-network:
    driver: bridge
```

### Health Check

The container includes a health check endpoint:

```bash
# Check container health
docker inspect --format='{{.State.Health.Status}}' agentnex-mcp-server

# Manual health check
curl http://localhost:8001/health
```

## Security

- API key authentication required for all backend requests
- CORS enabled for cross-origin requests
- Supports HTTPS for production deployment
- No sensitive data logged
- Container runs as non-root user
- Multi-stage build minimizes attack surface

## Publishing to PyPI

To publish a new version to PyPI:

1. **Update version in `pyproject.toml`**
2. **Update `CHANGELOG.md`** with changes
3. **Build the package:**
   ```bash
   python -m pip install --upgrade build twine
   python -m build
   ```
4. **Upload to PyPI:**
   ```bash
   # Test PyPI (optional)
   python -m twine upload --repository testpypi dist/*
   
   # Production PyPI
   python -m twine upload dist/*
   ```

## Contributing

Contributions are welcome! Please ensure:
- Code follows existing style and conventions
- All tests pass (`pytest tests/`)
- Documentation is updated for new features

## Support

For issues and questions:
- Open an issue on [GitHub](https://github.com/ivedha-tech/agentnex-mcpserver/issues)
- Contact: AgentNEX Team at IVedha Technologies

## License

MIT License

Copyright (c) 2025 IVedha Technologies - AgentNEX Team
