io.github.JC7333/mandatia

Overview Schema Source Related Servers Discussions Admin

register_principal_key

Registers a principal's Ed25519 public key once so mandates from that principal must be signed with the matching private key; use at onboarding before mandate creation.

Instructions

After registration, create_mandate refuses any mandate from this principal that is not signed with the matching private key. The key cannot be replaced or removed in this version. For an ordinary principal_id the registry does not check who registers it: the first registration wins. Expose this tool to principals (or their back office) only, never to the agents they govern, and register each key at onboarding.

did:web principals (principal_id "did:web:"): the key is accepted only if the domain publishes it in https:///.well-known/did.json (W3C did:web). This needs AMR_DID_WEB_RESOLVE=1 in the server's process environment (one HTTPS request per registration; refused otherwise). The SHA-256 of the document read and the verification time are sealed with the key and shown by get_proof. It proves control of the domain at registration time, not a qualified signature.

Proof of possession: proof_signature is the principal's signature of the canonical JSON {"context": "amr.principal_key.v1", "principal_id": ..., "public_key": ...} (sorted keys, no spaces, UTF-8; public_key base64url without padding).

Args: principal_id: The principal the key belongs to. Example: "user:audric" public_key: Raw 32-byte Ed25519 public key, base64url. Example: "11qYAYKxCrfVS_7TyWQHOg7hcvPapiMlrwIaaPcHURo" proof_signature: Base64url Ed25519 signature of the registration payload.

Returns: JSON string with keys: status ("registered"), principal_id, key_id, registered_at, chain_hash, domain_proof ({did_document_url, did_document_sha256, verified_at} for a did:web principal, else null). On error: {"error": "...", "code": "..."} with code principal_id_invalid, public_key_invalid, principal_signature_invalid, principal_key_proof_invalid, principal_key_already_registered, principal_id_lookalike (a scheme prefix such as "did:web:" written with non-ASCII look-alike characters), or for did:web: did_web_resolution_disabled, did_web_invalid, did_web_not_canonical (then canonical_principal_id), did_web_unreachable, did_web_address_refused, did_web_https_required, did_web_redirect, did_web_document_invalid or did_web_key_not_published.

Input Schema

Name	Required	Description	Default
`public_key`	Yes
`principal_id`	Yes
`proof_signature`	Yes

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.1Nov 7, 2026

TDQS

A4.7/5.0

Behavior4/5

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

With no annotations, the description carries the full burden and does most of it: keys are immutable ("cannot be replaced or removed"), first registration wins with no registrar authentication check, did:web triggers one HTTPS fetch and fails otherwise, and the domain proof is scoped to control-at-registration only, not a qualified signature. Minor gap: no disclosure of rate limits or idempotency behavior on retry beyond the already_registered error code.

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 core action and constraint, then progressively deeper detail; every paragraph maps to a distinct decision an agent must make. The long enumerated error-code list and return-field inventory run somewhat against conciseness given an output schema already exists.

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?

A high-stakes, irreversible, security-sensitive write tool with three undocumented schema params — the description covers the authorization model, immutability, did:web resolution requirements, proof-of-possession payload, and failure modes. Nothing an agent needs in order to call it safely is missing.

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

Parameters5/5

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

Schema coverage is 0% and the schema has bare titles, so the description does all the work: each parameter is documented with encoding, byte length, and a concrete example, and the exact canonical JSON payload for proof_signature is spelled out (sorted keys, no spaces, UTF-8, unpadded base64url). This is meaning the agent cannot get from the schema.

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?

Opens with a specific verb+resource+cardinality: "Register the Ed25519 public key of a principal, once." It also states the downstream effect on create_mandate, which separates it cleanly from every sibling in the registry family.

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?

Gives explicit audience restrictions ("principals or their back office only, never the agents they govern") and a timing rule ("register each key at onboarding"), plus the conditional path for did:web principals and the AMR_DID_WEB_RESOLVE prerequisite. When-not guidance is explicit rather than inferred.

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

Deploy Server