pkinative-mcp

Overview Schema Source Related Servers Discussions Admin

Decode ASN.1 (node tree, typed read, re-encode)

decode_asn1

Read-onlyIdempotent

Decodes DER/BER ASN.1 into a node tree for inspecting tags, lengths, OIDs and primitive values, and optionally reads or re-encodes selected nodes.

Instructions

Read-only X.690 view of any DER object (BER with encodingRules:'ber'): the node tree — offset, header and content lengths, tag class / number / name, constructed flag, child count, a hex preview of each primitive (maxPreviewBytes, default 32) and the dotted value + registered name of every OBJECT IDENTIFIER — depth-first, capped at 20000 nodes (truncated:true). nodePath ('0.2.1' = child indices from the root; each node's path is what to pass) narrows to a subtree; read applies a typed reader to the selected node (boolean, integer, small-integer, enumerated, null, bit-string, octet-string, oid, relative-oid, string with stringType for an IMPLICIT tag, time with timeType) and returns value in wire form (bigint as decimal string, bytes as hex, time as epoch ms + ISO); reencode:true re-encodes the selected node through the engine and delivers it as an artefact (der / hex / pem for a labelled whole input; inline or a sandbox file) with reencode.identical; sequence:true decodes several top-level values back to back; allowTrailingData:true tolerates bytes after a single value. Refuses a private key or a PKCS#12 file — by PEM label, or when the DER parses as PKCS#8 / PKCS#12 — with SECURITY_VIOLATION (inspect_private_key / inspect_pkcs12 report them safely); a missing nodePath step is NOT_FOUND naming the range; a wrong reader tag is PKI_ASN1_UNEXPECTED_TAG; an IMPLICIT string / time without stringType / timeType is PKI_API_MISUSE; X.690 violations are PKI_ASN1_* (BER forms: encodingRules:'ber'). Token-frugal: verbosity:'summary' (node count, root tag, value), fields:['nodes.path','nodes.tagName'].

Input Schema

Name	Required	Description	Default
`read`	No	Apply this typed reader to the selected node (the root without nodePath) and return `value`; a wrong tag is PKI_ASN1_UNEXPECTED_TAG.
`input`	Yes	The DER / BER object (any PEM label except a private key, or DER): exactly one of pem / derBase64 / path. A private key or a PKCS#12 file is refused (SECURITY_VIOLATION).
`label`	No	reencode + encoding:'pem': the PEM label of the artefact (required when the input had no label or nodePath selects a sub-node; upper-case words and digits). A private-key label is refused.
`fields`	No	Dot-paths to keep after verbosity (arrays map over elements); unmatched paths land in _meta.unmatchedFields.
`limits`	No	Raise pkinative's 22 named security bounds for this call (trusted input only; absent keys keep the engine defaults). A value above an operator ceiling (PKINATIVE_MCP_MAX_INPUT_BYTES, PKINATIVE_MCP_MAX_KDF_ITERATIONS, PKINATIVE_MCP_MAX_PATHS_EXPLORED) is LIMIT_CEILING_EXCEEDED; describe_engine lists the defaults and the ceilings.
`strict`	No	Escalate the first engine warning to a PKI_STRICT_DIAGNOSTIC error instead of listing it in diagnostics[].
`pemMode`	No	'strict' (RFC 7468 exactly, default) or 'lax' (tolerates whitespace, line length and RFC 1421 headers).	strict
`encoding`	No	Artefact encoding: 'pem' (RFC 7468 text), 'der' (raw bytes), 'hex' (lowercase hex in structuredContent, inline only, ≤ 64 KiB). Default 'der'.	der
`nodePath`	No	Child indices from the root, dot-separated ('0.2.1' = children[0].children[2].children[1]): the subtree listed, read or re-encoded. Omitted: the root. NOT_FOUND names the available range.
`reencode`	No	Re-encode the selected node through the engine encoder and deliver it as an artefact (`encoding` der by default, hex, or pem under the input label or `label`); `reencode.identical` says whether the bytes are the input bytes.
`sequence`	No	The input is several top-level values back to back: decode each (exclusive with nodePath / read / reencode).
`timeType`	No	read:'time' on an IMPLICIT-tagged node: the time type (required then).
`verbosity`	No	'summary' keeps the scalar fields only (token-frugal).	full
`outputMode`	No	'base64' (default) returns the artefact inline as an embedded resource (≤ 50 MiB). 'file' writes it inside PKINATIVE_MCP_OUTPUT_DIR (never overwrites; ≤ 1 GiB) and returns a resource_link.	base64
`outputPath`	No	Relative path inside the sandbox (only when outputMode='file'); the extension must match the encoding (.der .bin .asn1 for der; .pem for pem). Key-bearing extensions (.key .p8 .p12 .pfx) are refused: nothing here writes a private key.
`stringType`	No	read:'string' on an IMPLICIT-tagged node: the charset to decode with (required then — PKI_API_MISUSE otherwise).
`encodingRules`	No	'der' (strict X.690 DER, default) or 'ber' (indefinite / non-minimal lengths and constructed strings, as legacy CMS producers write).	der
`maxPreviewBytes`	No	Content bytes of a primitive shown in `preview` (hex; 0 hides previews; default 32).
`allowTrailingData`	No	Accept bytes after the outermost value instead of PKI_ASN1_TRAILING_DATA (single value only; sequence:true decodes them instead).

Output Schema

Name	Required	Description
`label`	No	The PEM label of the input, null for DER.
`nodes`	No	The selected subtree (or every top-level tree with sequence:true), depth-first in input order.
`value`	No	read: the typed value. boolean → boolean; integer / enumerated → decimal string; small-integer → number; null → null; bit-string → { hex, unusedBits }; octet-string → hex; oid / relative-oid → dotted string (name for a registered OID); string → { stringType, value }; time → { type, epochMilliseconds, iso, text }.
`rootTag`	No	tagName of the first node listed (null when nothing was listed).
`artefact`	No	The artefact delivered alongside the report: its facts here, its bytes once as the embedded resource (or the resource_link in file mode).
`reencode`	No
`identical`	No	reencode: the bytes are identical.
`nodeCount`	No
`sizeBytes`	No	Bytes of the input object.
`truncated`	No	true when the listing stopped at 20000 nodes (use nodePath to walk the rest).
`diagnostics`	No	Non-fatal concerns the engine raised (PKI_DIAG_*, de-duplicated, at most 200; explain_code explains one).
`diagnosticCount`	No
`diagnosticCounts`	No	Occurrences per diagnostic code.
`diagnosticsTruncated`	No	true when distinct diagnostics beyond the 200 listed were dropped.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Oct 27, 2026

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/idempotent/non-destructive, yet the description still carries real weight: refusal of private keys and PKCS#12 with SECURITY_VIOLATION, the specific error codes (NOT_FOUND, PKI_ASN1_UNEXPECTED_TAG, PKI_API_MISUSE), and the token-frugal `verbosity`/`fields` options. One blemish: it says the tree is 'capped at 20000 nodes' while the schema documents maxNodes default 200000, a numeric inconsistency that could mislead.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

It is a single dense paragraph that packs roughly a dozen distinct behaviors into one block; the core purpose is front-loaded, but the error-code and option details run together with no structure. Nothing is wasted, yet the density makes it hard to scan for the one clause an agent needs.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 19 parameters, nested input object, an output schema, and full annotation coverage, the description covers the remaining gaps: input source exclusivity, artefact delivery modes, security refusals, and error semantics. An agent has everything needed to select and invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so 3 is the floor, but the description earns more by explaining that `nodePath` uses child indices and that each node's `path` is the value to pass, that `stringType`/`timeType` are required for IMPLICIT tags, and what `reencode.identical` means. The list of typed readers and their wire representations (bigint as decimal string, bytes as hex) adds meaning beyond the enum.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening clause gives a specific verb and resource — a read-only X.690 view of any DER/BER object producing a node tree — and immediately enumerates the three modes (tree listing, typed `read`, `reencode`). It distinguishes itself from siblings like encode_asn1 and explicitly routes private keys / PKCS#12 to inspect_private_key and inspect_pkcs12.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states conditions for each mode (`nodePath` narrows to a subtree, `sequence:true` for back-to-back values, `allowTrailingData` for stray bytes) and names the alternatives for refused inputs. What is missing is a positive statement of when to reach for this versus inspect_certificate or inspect_cms when the object is a known structure.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.