pkinative-mcp

Overview Schema Source Related Servers Discussions Admin

Create time-stamp request (RFC 3161 TimeStampReq over data or a digest)

create_timestamp_request

Builds an RFC 3161 TimeStampReq for POSTing to a TSA: hash data or supply a digest, set nonce/policy/certReq, and output DER, PEM, or hex.

Instructions

Build the RFC 3161 TimeStampReq you POST to a TSA yourself (Content-Type application/timestamp-query; this server never talks to a network): the message imprint is hashAlgorithm (SHA-256 default, SHA-384, SHA-512) over data, or digestHex already computed with it (wrong length → VALIDATION_ERROR). nonce:'random' draws 63 bits from node:crypto (summary.randomNonce:true; never cached) — without a nonce nothing ties the response to THIS request; a decimal or 0x-hex value pins it. policy names the TSA policy, certReq (default true) asks for the TSA certificate in the token. For a counter time-stamp over a CMS signature, the data is the signer's SIGNATURE VALUE (inspect_cms fields:['signerInfos.signature']), never the document. Keep the request bytes (or summary.imprintHex and nonce): verify_timestamp checks the response against them. Output DER (default; .tsq), PEM or hex, inline or as a sandbox file (never overwritten).

Input Schema

Name	Required	Description	Default
`data`	No	The data to time-stamp (hashed here with hashAlgorithm; for a counter time-stamp, the signer's signature value from inspect_cms): exactly one of text / base64 / path.
`label`	No	The PEM label for encoding:'pem' (default TIMESTAMP REQUEST; upper-case words and digits). A private-key label is refused.
`nonce`	No	A nonce the TSA must echo (RFC 3161 §2.4.1): 'random' (63 bits from node:crypto — summary.randomNonce reports it; such a call is never cached), a decimal or an 0x-hex integer. Without one, nothing ties a response to THIS request.
`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.
`policy`	No	The TSA policy to issue under (dotted OID); the TSA's default when absent.
`strict`	No	Escalate the first engine warning to a PKI_STRICT_DIAGNOSTIC error instead of listing it in diagnostics[].
`certReq`	No	Ask the TSA to include its certificate in the token (what verify_timestamp needs unless you pass candidates).
`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
`digestHex`	No	The digest to stamp, already computed with hashAlgorithm (its length must match). Exclusive with data. Hexadecimal (an 0x prefix, colons and spaces are tolerated).
`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 (.tsq .der .bin for der; .pem for pem). Key-bearing extensions (.key .p8 .p12 .pfx) are refused: nothing here writes a private key.
`encodingRules`	No	'der' (strict X.690 DER, default) or 'ber' (indefinite / non-minimal lengths and constructed strings, as legacy CMS producers write).	der
`hashAlgorithm`	No	The message imprint algorithm.	SHA-256

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?

Goes well beyond the annotations: states an error contract (wrong digest length → VALIDATION_ERROR), a caching guarantee ('nonce never cached', consistent with idempotentHint=false), a no-overwrite guarantee on sandbox files, refusal of key-bearing extensions, and a size ceiling on hex output. It also reinforces openWorldHint=false with the explicit 'never talks to a network' statement rather than contradicting it.

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?

Purpose is front-loaded in the first clause and every sentence carries actionable content. It is, however, a single dense paragraph with deeply nested parentheticals and backticked fragments, which makes it harder to scan than a lightly segmented version.

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 14-parameter, zero-required builder with a full output schema, the description covers the entire workflow end to end: input mode selection, nonce/policy/certReq choices, encoding and output destination, the error case, and the handoff to verify_timestamp. Remaining knobs (limits, strict, pemMode, encodingRules) are fully documented in the schema and need no repetition here.

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 the baseline is 3; the description earns above that by explaining the mutual exclusivity semantics (data vs digestHex), the default SHA-256 imprint over data, and nonce behavior ('random' = 63 bits from node:crypto surfaced in summary.randomNonce, vs a pinned decimal/0x value). It adds the 'why' for nonce and certReq that the schema alone does not convey.

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?

States a specific verb and artifact: 'Build the RFC 3161 TimeStampReq you POST to a TSA yourself', and immediately clarifies scope ('this server never talks to a network'). This cleanly separates it from inspect_timestamp (which reads a response) and verify_timestamp (which validates one), so an agent can route correctly without opening a 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?

Explicitly gives the when: you must POST the query to a TSA yourself. It also names alternatives and the downstream handoff ('verify_timestamp checks the response against them'), plus a concrete conditional branch — for counter time-stamps feed the SIGNATURE VALUE from inspect_cms, 'never the document'.

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