mcp-server AGENTS.md

AGENTS.md

This repo will contain a Python Model Context Protocol (MCP) server that exposes the ScanMalware.com API as tools/resources for an MCP client.

API source of truth

• OpenAPI spec: https://scanmalware.com/openapi.json
• Base URL (OpenAPI omits servers): https://scanmalware.com
• API prefix: /api/v1
• OpenAPI currently lists ~146 paths / ~147 operations; many response schemas are {} (treat as untyped JSON and verify with live calls).

Practical note: some endpoints return binary despite the OpenAPI describing JSON:

• GET /api/v1/screenshot/{scan_id} returns PNG bytes.
• GET /api/v1/tls/{scan_id}/certificate/download returns PEM (application/x-pem-file).
• Other “download” style endpoints may be binary (verify with curl -D - -o /dev/null ...).

Authentication

Most endpoints are public (no auth in OpenAPI). Auth-gated endpoints in the spec:

• Bearer (HTTPBearer)
  • GET /api/v1/auth/profile
  • GET /api/v1/auth/admin
  • GET /api/v1/auth/analyst
• Optional bearer (OptionalHTTPBearer)
  • GET /api/v1/auth/test-optional
• HTTP Basic (HTTPBasic) (Module Monitoring)
  • GET /api/v1/modules/health
  • GET /api/v1/modules/stats
  • GET /api/v1/modules/failures
  • GET /api/v1/modules/stuck
  • GET /api/v1/modules/chains
  • GET /api/v1/modules/scan/{scan_id}
  • GET /api/v1/modules/percentiles/{module_name}
  • POST /api/v1/modules/admin/change-password

Recommended env vars (never hardcode secrets):

• SCANMALWARE_BASE_URL (default: https://scanmalware.com)
• SCANMALWARE_BEARER_TOKEN (optional; only needed for auth endpoints)
• SCANMALWARE_BASIC_USER / SCANMALWARE_BASIC_PASSWORD (optional; only needed for /modules/*)

Core scan workflow (API-level)

1. POST /api/v1/scan with JSON body:
   • url (required)
   • scan_type (default "public")
   • options (object, optional)
   • Optional headers: User-Agent
2. Poll for completion:
   • GET /api/v1/scan/{scan_id}/summary (compact; includes status, risk_score, counts)
   • and/or GET /api/v1/result/{scan_id}/progress
3. Fetch details:
   • GET /api/v1/result/{scan_id}
   • plus specialized endpoints (/ai/{scan_id}, /tls/{scan_id}, /technologies/by-scan/{scan_id}, etc.)