MCP server for SAM Protocol - verify, validate, evaluate, compose, and sign SAM envelopes (sam.json).
Strong tool definitions with comprehensive descriptions (avg 280 chars, well above 194 baseline) and detailed parameter documentation. All 7 tools have explicit schemas with type definitions and descriptions. Tool names follow verb_noun pattern (sam_verify, sam_validate, sam_evaluate, sam_fetch, sam_resolve, sam_generate, sam_sign). Annotations present (readOnlyHint, destructiveHint, idempotentHint, openWorldHint). Key gaps: output schemas not formally documented in code; error handling lacks recovery guidance; some parameter descriptions could be more prescriptive about constraints.
Locally evaluate a merchant-issued policy mandate (sam:mandate) against a proposed agent action. This is a pure local check — NO network call is made. It implements grammar v0.1 with strict AND across all primitives: autoExecute, maxAmount, maxPriceDrift, allowedCategories, deniedCategories, allowedRegions, validityWindow, and agentClass. One failed primitive = refuse.
Follow sam:composes references in a SAM envelope and fetch composed documents. This tool reads the sam:composes block (which declares references to UCP, AP2, MCP, ACP, A2A) and fetches each declared reference over HTTPS. Useful for agents that need to understand the full composition chain of a merchant's capabilities.
Generate a draft (unsigned) sam.json from merchant configuration. This tool constructs a SAM envelope from merchant metadata, capabilities, composition references, and optional mandate. The result is a valid but unsigned envelope ready for review or signing.
Fetch and verify a sam-operator.json from an operator domain. Operator documents declare operator-level policies, capabilities, and signing keys. This tool fetches the document, validates its structure, and optionally verifies its signature.
Sign a SAM envelope with a provided ed25519 seed. This tool takes an unsigned (or previously signed) envelope and produces a cryptographically signed version using ed25519. WARNING: pass only ephemeral or dev keys via this tool; never expose production root keys.
Output schemas not formally documented. Tools return structured results (fetched_url, http_status, schema_valid, etc.) but the response schema is not declared in tool registration or code comments. LLMs cannot plan downstream operations without knowing return field names and types.
Error handling lacks recovery guidance. Functions return errorResult() with a message, but do not categorize errors as retryable/user-fixable/fatal or suggest next steps. E.g., 'Failed to fetch a SAM envelope' does not tell the LLM whether to retry, ask the user, or abort.
sam_sign_envelope accepts privateKeyBase64 as a parameter. While the description warns against production keys, passing secrets as parameters is a security anti-pattern, they appear in logs and traces. Should use server-side secret injection via environment variables or vault.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | C | 62 | 2025-06-18+ | v2 |
Structurally validate a JSON document against the SAM Protocol v2.2 JSON Schema (Draft 2020-12). This is a STRUCTURAL check only. It validates required fields, types, formats, value enumerations, and the L0/L1/L2 cross-field rules. It does NOT verify signatures or freshness — use sam_verify_envelope for that. Args: - envelope (object): The parsed JSON envelope to validate. - response_format ('markdown' | 'json'). Returns: { valid: boolean, errors: Array<{ path, message, keyword }> }
Fetch a SAM Protocol envelope (sam.json) from a merchant domain and verify it. This tool performs the full chain of checks a conformant agent must run before acting: 1. Resolves the URL (https://<domain>/.well-known/sam.json by default). 2. Fetches the document over HTTPS with timeout and size cap. 3. Validates structure against the SAM v2.2 JSON Schema. 4. Checks the freshness window (sam:signature.validUntil must be in the future). 5. If a public key is provided, verifies the ed25519 signature over the canonicalized envelope. Args: - domain (string): Merchant domain (e.g. 'example.com') or a full https:// URL. - publicKeyBase64 (string, optional): Merchant ed25519 public key (32 bytes, base64). - response_format ('markdown' | 'json'): Output format. Returns: Structured result with fields: fetched_url, http_status, schema_valid, schema_errors, freshness_status ('current' | 'expired' | 'no-window'), signature_status ('verified' | 'invalid' | 'skipped' | 'no-signature'), claimed_conformance_level, and a parsed envelope object.
Parameter constraints not fully specified. E.g., 'response_format' enum is declared, but numeric parameters (amount, priceDriftPercent) lack min/max bounds. 'domain' parameter accepts both bare domains and full URLs but the parsing logic is implicit, should document the resolution order explicitly.
sam_generate_envelope has complex nested parameter structure (composes, capabilities, mandate, human, agentAuth) with interdependencies not fully documented. E.g., 'capabilities required when composes.ucp is absent' and 'mandate required for L2' are stated but mutual exclusivity and conditional requirements could be clearer.