mcp-server: Instructions file for Codex

AGENTS.md

This repo contains a Python Model Context Protocol (MCP) server that exposes the ScanMalware.com API as tools/resources for an MCP client (128 tools on mcp 2.3.0, served at https://mcp.scanmalware.com/mcp; operations in docs/OPERATIONS.md). The sections below are the original design notes; where they differ from the code, the code and the runbook are current.

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

The server deliberately exposes none of these auth-gated or /modules/* endpoints, so it needs no Basic credentials.

Env vars (never hardcode secrets; full list in docs/OPERATIONS.md):

• SCANMALWARE_BASE_URL (default: https://scanmalware.com)
• SCANMALWARE_BEARER_TOKEN (optional; needed for private scans)