Class McpSkillBundle

java.lang.Object
com.soklet.McpSkillBundle
@ThreadSafe public final class McpSkillBundle extends Object
Immutable snapshot of application-supplied Skills files and document metadata.

Logical file paths are bundle-relative names, not filesystem locations. Construction performs no file access, remote fetching, execution, or endpoint publication. Applications own loading the bytes before supplying them here. Metadata and path getters return cached immutable views; only file-byte inspection creates defensive copies.

Author:
Mark Allen

  • Method Details

    • fromFiles

      public static @NonNull McpSkillBundle fromFiles(@NonNull Map<@NonNull String, byte @NonNull []> fileContentsByLogicalPath)
      Validates and snapshots a bundle, including its required root SKILL.md.

      Keys must be unique NFC logical paths with no empty, dot, or dot-dot segments, backslashes, percent signs, or control characters. A file cannot also be a directory prefix of another file (for example, ref and ref/notes.md). Names are case-sensitive and are not case-folded; applications loading or materializing files on a case-insensitive filesystem must account for names that differ only by case. Each path is limited to 8,192 UTF-8 bytes. Bundles contain at most 512 files and 16 MiB of raw content; individual resource representations remain subject to the stricter MCP output limits. Supplied arrays are defensively copied. Do not mutate the map or its arrays while construction is in progress.

      The complete root document, including its body, must be valid UTF-8 and fit within 4 MiB. Frontmatter parsing and resolution share fixed bounds: nesting depth 128; 1,000,000 syntax and resolved nodes; 1,048,576 UTF-16 code units per scalar; 4,194,304 aggregate charged scalar characters; and 50,000,000 metered work units. The production JSON profile independently constrains resolved metadata and resource delivery. These construction bounds are not configurable through this factory.

      Metadata validation errors identify the fixed field and violated rule without including authored values or custom metadata keys. The exception remains an IllegalArgumentException; diagnostics are not a structured validation API. Metadata validation does not repair or rewrite the document.

      Parameters:
      fileContentsByLogicalPath - logical file paths and complete file contents
      Returns:
      immutable validated bundle
      Throws:
      NullPointerException - if the map, a path, or file bytes are null
      IllegalArgumentException - if paths, metadata, content, or limits are invalid

    • getName

      public @NonNull String getName()
      Returns:
      validated skill name from the root document

    • getDescription

      public @NonNull String getDescription()
      Returns:
      skill description from the root document

    • getDocumentMetadata

      public @NonNull McpJsonObject getDocumentMetadata()
      Returns cached root frontmatter, including supported unknown fields.
      Returns:
      immutable complete document metadata, not protocol _meta

    • getFilePaths

      public @NonNull Set<@NonNull String> getFilePaths()
      Returns cached canonical logical paths without filesystem resolution.
      Returns:
      immutable ordered set, root SKILL.md first and remaining paths in unsigned UTF-8 byte order

    • findFileBytes

      public @NonNull Optional<byte @NonNull []> findFileBytes(@NonNull String logicalFilePath)
      Copies the requested file without copying the complete bundle.
      Parameters:
      logicalFilePath - exact, case-sensitive logical file path
      Returns:
      defensive file-byte copy, or empty when the path is absent
      Throws:
      NullPointerException - if the path is null

    • equals

      public boolean equals(@Nullable Object other)
      Overrides:
      equals in class Object
      Returns:
      whether logical paths and exact snapshot bytes match

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object
      Returns:
      structural bundle hash code without copying inspection bytes

    • toString

      public @NonNull String toString()
      Overrides:
      toString in class Object
      Returns:
      diagnostic rendering without authored metadata, paths, or bytes