# agenticAI — MCP Tool Servers

A pair of [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) servers that expose useful tools to LLM agents (e.g. Claude, or any MCP-compatible client) over stdio, built with the official Python `mcp[cli]` SDK and `FastMCP`.

## Servers

### `nmap-server.py` — Network scanning tools

Wraps the `nmap` CLI as a set of async MCP tools, letting an agent run network scans, parse the XML output, and get back structured JSON. Includes target validation (IP / CIDR / hostname regex) before any command is executed, and a 10-minute timeout on every scan.

Exposed tools:

| Tool | Purpose |
|---|---|
| `nmap_ping_sweep` | Discover live hosts on a network |
| `nmap_tcp_scan` | TCP connect/SYN scan over a port range |
| `nmap_udp_scan` | UDP scan of common service ports |
| `nmap_service_scan` | Service/version detection |
| `nmap_os_detection` | OS fingerprinting |
| `nmap_aggressive_scan` | Combined OS/version/script/traceroute scan |
| `nmap_vuln_scan` | NSE vulnerability scripts |
| `nmap_script_scan` | Run a specific NSE script |
| `nmap_default_scripts` | Run nmap's default NSE script set |
| `nmap_stealth_scan` | SYN stealth scan |
| `nmap_timing_scan` | Scan with a chosen timing template (T0–T5) |
| `nmap_top_ports` | Scan the N most common ports |
| `nmap_custom_scan` | Pass arbitrary nmap flags |

Results are parsed from nmap's XML output into structured summaries (open ports, services, host state, etc.) rather than raw text.

### `todo-mcp.py` — Minimal task-list demo server

A small reference server (four tools: `count_tasks`, `show_tasks`, `add_task`, `search_tasks`) used to demonstrate the basic MCP tool pattern before building the more complex nmap server.

## Setup

Requires Python 3.11+ and [`uv`](https://github.com/astral-sh/uv).

```bash
uv sync
```

Run a server directly:

```bash
uv run nmap-server.py
uv run todo-mcp.py
```

Or point an MCP-compatible client (Claude Desktop, etc.) at either script as a stdio server.

> **Note:** `nmap-server.py` shells out to a locally installed `nmap` binary — only run scans against hosts/networks you're authorised to test.