CHANGE LOG OF SNMP4J-MCP
========================

[2026-08-03] Version 1.0.0:

Initial release. SNMP4J-MCP is a Model Context Protocol (MCP) server that gives an AI agent
first-class SNMP and SMI/MIB capabilities: it can look up and compile MIB modules, talk SNMP to
real agents, retrieve tables and subtrees, and inspect or craft SNMP messages down to the BER
level. It is built on SNMP4J 3.13.1 and the SNMP4J-SMI-PRO 2.1.1 MIB engine.

Supported MCP setups:

* Runs as a local MCP server over the stdio transport, based on the MCP Java SDK 1.1.3 (MCP
  protocol 1.x). It therefore works with any MCP host that launches a server as a child process
  and speaks stdio - desktop and CLI AI assistants, IDE integrations, the MCP Inspector, and
  custom agents built on an MCP client library. The server is normally started by the host, but it
  can also be launched manually for testing (see snmp4j-mcp-on-mcp-inspector.sh).
* One server process serves one MCP client session. Because stdout and stderr are reserved for the
  stdio transport, all diagnostic output is appended to '.snmp4j-mcp-log' in the working directory.
* Requires Java 21 or later and a SNMP4J-SMI-PRO license key for the MIB/SMI features. The key,
  the MIB repository path, and the configuration file can be supplied on the command line
  (--license, --repoPath, --config) or through the JSON configuration file, which defaults to
  '.snmp4j-mcp-config.json' in the working directory. The --port option is reserved for future
  network transports and is unused by the stdio transport.
* The MIB repository, the MIB source directory readable by the compiler tools, and the set of SNMP
  targets an agent may reach are all fixed by that configuration file, so the operator - not the
  model - decides which endpoints and files are in scope.
* Announced server capabilities are tools, resources with list-change notifications, resource
  template argument completion, and logging. Long-running table and subtree retrievals report
  progress notifications to the client while they run.

MIB and SMI features:

* 'find_mib_objects' searches the loaded MIB modules by OID, object name, SMI type, or regular
  expression, and can match arbitrary SmiObject properties against a JSON pattern.
* 'semantic_search_mib' performs natural-language vector search over all loaded MIB objects, so
  queries such as "interface throughput" find ifSpeed and ifHighSpeed. It uses OpenAI embeddings
  when OPENAI_API_KEY (or the openai.api.key system property) is set, and otherwise a local ONNX
  embedding model when the DJL ONNX dependencies are on the classpath.
* 'check_mib', 'check_mib_completely', and 'compile_mib' compile SMIv1/SMIv2 specifications with
  selectable strictness: the first two validate without touching the repository (with and without
  an error-count limit), the third stores the result into the repository.
* 'get_mib_file_text' returns the text of a MIB source file, including single entries of ZIP
  archives, from the configured MIB source directory. Paths that escape that directory are
  rejected.
* Resource templates publish MIB module and MIB object definitions ('mib/module/{moduleName}',
  'mib/object/{moduleName}/{objectName}', 'mib/object/{oid}') with argument auto-completion, so an
  agent can read the authoritative SMI definition of anything it found.

SNMP features:

* 'snmp_command_generator' sends any GET, GETNEXT, GETBULK, SET, or INFORM PDU described as JSON
  and returns the response event as JSON. Variable binding types are inferred from the loaded MIBs
  when they are not given explicitly, including textual conventions.
* 'snmp_set' is the plain-text counterpart for quick reads and writes: a newline- or
  comma-separated list of OIDs, or of OID=value assignments in SNMP4J syntax, defaulting to a
  read-only GET.
* 'snmp_get_table' retrieves tabular data as JSON with an optional index range and cell OIDs, and
  'snmp_walk_subtree' walks a subtree with GETNEXT or GETBULK. Both are bounded by row, binding,
  and timeout limits and report progress while running.
* 'snmp_detect_mib_modules' probes a target with GET and GETNEXT requests to determine which of
  the loaded MIB modules it actually implements.
* Targets are configured by name and support SNMPv1, SNMPv2c, and SNMPv3 with USM, as well as the
  secure transports 'tls:' (RFC 6353) and 'dtls:' (RFC 5953) with the Transport Security Model of
  RFC 5591. Key and trust stores, certificate fingerprints, the expected peer identity, protocol
  versions, and revocation checking are all part of the target configuration.
* Target configurations are exposed as the 'snmp/target/{targetName}' resource with completion
  support. Every property whose name ends in Passphrase, Password, or Key is removed from that
  representation, so credentials are never handed to the model.

Byte-level and security-testing features:

* 'snmp_message_ber' decodes a raw SNMP message from hex into an indented text tree or a JSON
  object tree, for SNMPv1, SNMPv2c, and SNMPv3, and decrypts authPriv messages when a configured
  SNMPv3 target provides the matching credentials and authoritative engine ID.
* 'snmp_encode_ber' encodes such a tree back into a raw message and can inject faults on the way -
  overridden or indefinite lengths, truncated or appended content, omitted or raw-replaced nodes -
  including JSON-Pointer mutations and generated permutations for fuzzing.
* 'snmp_send_raw' delivers a caller-supplied byte sequence to a configured target without any BER
  or PDU processing and captures the raw response, in send, receive, or send-and-receive mode, so
  malformed and non-compliant messages can be used for robustness and security testing. The
  destination is always the configured target and cannot be redirected.
* Targets may opt in to per-call parameter overrides ("allowAdhocParameterOverwrite": true), which
  lets an agent vary community strings, SNMPv3 credentials, security levels, and (D)TLS parameters
  for negative testing. The target address, and therefore the endpoint under test, can never be
  overridden.

Further notes:

* The JSON request and response payloads of the tools are described by JSON Schemas (Draft
  2020-12) that the server publishes as MCP resources, together with a sample SET PDU that creates
  an snmpTargetAddrTable row. The schema and configuration definitions are also shipped on disk
  under 'doc/json/' of the distribution.
* Each tool declares the contexts it depends on - the model repository context for the MIB tools,
  the SNMP agent context for the tools that reach an agent - which is what binds them to the MIB
  repository and to the configured target list.
* All tools carry MCP tool annotations that mark whether they are read-only, idempotent,
  potentially destructive, and whether they interact with the outside world, so a host can decide
  which of them need user confirmation.

