Metadata-Version: 2.4
Name: mcp-botnex
Version: 0.1.2
Summary: MCP Server for BotNEX - VAPT scans, reports and CVE intelligence for AI clients
Author: BotNEX Team
License: MIT
Project-URL: Homepage, https://github.com/ivedha-tech/botnex-mcp-server
Project-URL: Repository, https://github.com/ivedha-tech/botnex-mcp-server
Project-URL: Documentation, https://github.com/ivedha-tech/botnex-mcp-server#readme
Keywords: mcp,botnex,vapt,security,cve,vulnerability,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 :: Security
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
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.30.0; extra == "dev"

# mcp-botnex

MCP (Model Context Protocol) server for **BotNEX** — exposes VAPT scans,
reports, and CVE intelligence to AI clients such as Cursor and the NEXA
platform. It is a thin, secure bridge to the existing `botnex-backend` REST
API and authenticates with a **user-scoped API token** (no JWT).

## Features

- **8 tools** for scan lifecycle, reports, and CVE lookup
- **6 resources** (`botnex://…`) for `@`-mentionable context in Cursor
- **Dual transport**: stdio (Cursor / Claude Desktop) and HTTP (NEXA / Docker)
- **API-token auth** mapped per-user on the backend — RBAC enforced server-side
- AI-friendly formatters (severity-first findings, normalized CVE output)

## Installation

```bash
pip install mcp-botnex
```

## Authentication

1. Log in to the BotNEX UI.
2. Create an API token: **API Tokens → Create** (calls `POST /api/v1/users/api-tokens/`).
3. Copy the raw token once and provide it to the MCP server via `BOTNEX_API_KEY`.

The token is sent as `Authorization: Bearer <token>` on every backend request.
The backend resolves it to your user account and enforces all authorization
and per-user data scoping.

## Configuration

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `BOTNEX_BACKEND_URL` | Yes | – | Backend origin, e.g. `https://botnex.example.com` (no `/api/v1`) |
| `BOTNEX_API_KEY` | Yes | – | User API token |
| `BOTNEX_MCP_SERVER_PORT` | No | `8001` | HTTP mode port |
| `BOTNEX_LOG_LEVEL` | No | `INFO` | Log level |
| `BOTNEX_BACKEND_TIMEOUT` | No | `60.0` | Backend HTTP timeout (s) |
| `BOTNEX_FINDINGS_PAGE_SIZE` | No | `50` | Default findings page size |
| `BOTNEX_SCAN_PAGE_SIZE` | No | `25` | Default page size for scan list resources |
| `BOTNEX_CVE_PAGE_SIZE` | No | `20` | Default page size for `botnex://cve/latest` |

See `.env.example` for the full list.

## Usage — Cursor (stdio)

Add to your Cursor MCP config:

```json
{
  "mcpServers": {
    "botnex": {
      "command": "mcp-botnex",
      "env": {
        "BOTNEX_BACKEND_URL": "https://botnex.example.com",
        "BOTNEX_API_KEY": "your-api-token"
      }
    }
  }
}
```

## Usage — HTTP (NEXA / Docker)

```bash
mcp-botnex-http
# or
uvicorn botnex_mcp.http_server:app --host 0.0.0.0 --port 8001
```

Endpoints: `GET /mcp/tools`, `POST /mcp/tools/call`, `GET /mcp/resources`,
`POST /mcp/resources/read`, `GET /health`.

## Tools

| Tool | Description |
|------|-------------|
| `list_scans` | List the user's scans and statuses |
| `trigger_scan` | Start a security or asset-discovery scan |
| `get_scan_findings` | Paginated, severity-ordered findings for a scan |
| `get_scan_summary` | Aggregated dashboard summary |
| `list_scheduled_scans` | Upcoming scheduled scans |
| `generate_report` | Generate a PDF/CSV/DOCX report |
| `search_cves` | Full-text CVE search |
| `get_cve_by_id` | CVE detail by id |

## Resources

All list resources are paginated and field-slimmed to keep responses small
and the LLM context cheap. Pagination is controlled with `?page=` and
`?size=` query parameters; `size` is capped at 100.

| URI | Paginated | Description |
|-----|-----------|-------------|
| `botnex://scans/all` | Yes | Slim list of the user's scans |
| `botnex://scans/summary` | – | Aggregated severity counts and risk metrics |
| `botnex://scans/scheduled` | Yes | Upcoming scheduled scans |
| `botnex://scan/{scan_id}/findings` | Yes | Severity-ordered findings for a scan |
| `botnex://cve/{cve_id}` | – | Compact CVE summary |
| `botnex://cve/latest` | Yes | Most recently published CVEs |

Examples:

- `botnex://scans/all?page=2&size=20`
- `botnex://scan/<scan_id>/findings?page=2&size=25`
- `botnex://cve/latest?page=1&size=10`

Paginated resources return:

```json
{"items": [...], "page": 2, "size": 20, "total": 47, "pages": 3, "has_more": true}
```

## Development

```bash
pip install -e ".[dev]"
pytest
```

## License

MIT
