pkinative-mcp

Overview Schema Source Related Servers Discussions Admin

Amend CMS (add an unsigned attribute or an RFC 3161 counter time-stamp)

amend_cms

Idempotent

Append an unsigned attribute or a counter time-stamp token to a CMS signed message without altering signed bytes. Checks the token's imprint against the signer's signature value before writing.

Instructions

The one edit a signed message legitimately receives afterwards, every signed octet unchanged: operation 'add-unsigned-attribute' appends attribute (one DER Attribute as hex) to signer signerIndex's unsigned attributes; 'add-timestamp' appends token — a TimeStampToken, or the whole TimeStampResp a TSA returned (unwrapped; a declined response is refused) — as id-aa-signatureTimeStampToken (CAdES-T / PAdES B-T). A counter time-stamp stamps the signer's SIGNATURE VALUE, not the document: the token's imprint is checked against that value BEFORE anything is written and a token over anything else is refused with VALIDATION_ERROR (data.detail PKI_REASON_TSP_IMPRINT_MISMATCH, with the remedy: inspect_cms fields:['signerInfos.signature'] → hash → create_timestamp_request digestHex → POST to your TSA yourself → amend_cms). Trust is not judged here (verify_cms is). Deterministic for the same inputs. Refuses: NOT_FOUND for a signerIndex past the last signer, PKI_API_MISUSE for a signed-only attribute type, PKI_* for unreadable bytes. Output DER (default), PEM (CMS) or hex, inline or as a sandbox file (never overwritten).

Input Schema

Name	Required	Description	Default
`token`	No	The time-stamp for add-timestamp: a TimeStampToken (.tst) or the whole TimeStampResp (.tsr, unwrapped to its token; a declined response is refused): exactly one of pem / derBase64 / path.
`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
`allowSha1`	No	Accept or produce SHA-1 signatures (legacy material you already trust). Default false: refused with PKI_CRYPTO_ALGORITHM_REFUSED on read, VALIDATION_ERROR on write.
`attribute`	No	One DER Attribute (SEQUENCE { type, SET OF values }) for add-unsigned-attribute. A type RFC 5652 allows only signed is refused (PKI_API_MISUSE). Hexadecimal (an 0x prefix, colons and spaces are tolerated).
`operation`	Yes	'add-unsigned-attribute' writes `attribute` verbatim; 'add-timestamp' writes `token` as id-aa-signatureTimeStampToken after checking its imprint.
`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 (.p7s .p7m .p7b .cms .der for der; .pem for pem). Key-bearing extensions (.key .p8 .p12 .pfx) are refused: nothing here writes a private key.
`signedData`	Yes	The CMS SignedData to amend (CMS / PKCS7 PEM, or DER: .p7s .p7m): exactly one of pem / derBase64 / path.
`signerIndex`	No	Which signer receives the attribute (encoded order; NOT_FOUND past the last).
`encodingRules`	No	'der' (strict X.690 DER, default) or 'ber' (indefinite / non-minimal lengths and constructed strings, as legacy CMS producers write).	der

Output Schema

Name	Required	Description
`hex`	No	The artefact as lowercase hex (when encoding='hex').
`mode`	Yes
`sha256`	Yes	SHA-256 of the DER bytes (lowercase hex) — the reproducibility proof.
`summary`	Yes
`encoding`	Yes
`filePath`	No	Sandboxed absolute path (when outputMode='file').
`sizeBytes`	Yes	Size of the DER artefact.
`diagnostics`	Yes	Non-fatal concerns the engine raised (PKI_DIAG_*, de-duplicated, at most 200; explain_code explains one).
`diagnosticCounts`	Yes	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.8/5.0

Behavior5/5

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

Annotations only declare non-read-only, non-destructive, idempotent; the description adds the real behavior: imprint is verified against the signer's signature value BEFORE anything is written, token over anything else is refused with VALIDATION_ERROR and PKI_REASON_TSP_IMPRINT_MISMATCH, declined TimeStampResp is refused, deterministic for the same inputs, and refusal codes (NOT_FOUND, PKI_API_MISUSE, PKI_*) are named.

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

Conciseness4/5

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

Front-loaded with the purpose and the two operations, and every sentence carries information (error codes, remedy path, refusal list). It is long and em-dash-dense, packing the imprint-mismatch remedy into one clause, which costs some readability but not correctness.

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?

For a mutation tool with nested inputs, 13 parameters, an output schema and several refusal modes, the description covers what is preserved (signed octets unchanged), what is validated before writing, which errors surface, what the outputs look like, and where trust is decided instead. Nothing an agent needs in order to call this correctly is missing.

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 already 100%, so the schema carries the parameter detail; the description goes beyond it by explaining the interaction semantics — that `token` is either a TimeStampToken or a whole unwrapped TimeStampResp, that `attribute` is one DER Attribute written verbatim, and that output is DER/PEM/hex inline or as a never-overwritten sandbox file. It does not add anything about `limits`, `strict`, `allowSha1`, or `encodingRules`, hence a 4 rather than 5.

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?

Names the exact verb and resource (amend a signed CMS message) and states the only two edit kinds: appending an unsigned attribute or a counter time-stamp. It explicitly separates this from verify_cms ('trust is not judged here') and from create_timestamp_request, so an agent can place it among siblings without opening any schema.

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

Usage Guidelines5/5

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

Per-operation guidance is explicit: 'add-unsigned-attribute' appends `attribute` to `signerIndex`; 'add-timestamp' appends `token` as id-aa-signatureTimeStampToken (CAdES-T / PAdES B-T). It also gives the exact remediation chain when the imprint does not match (inspect_cms → hash → create_timestamp_request → POST to TSA → amend_cms), which is an unusual level of routing detail.

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