claude-faf-mcp

Overview Schema Source Related Servers Discussions Admin

Trust Receipt

faf_trust

Read-onlyIdempotent

Verify a project's .faf file by validating and scoring it, then generating a SHA-256 hash of the score for independent verification. Only valid files with known scores receive a trust receipt.

Instructions

Attest the project's .faf: faf-cli's validateFaf, faf-cli's score, and a faf-parity/v1 hash (claude-faf-mcp's own spec) of that score that anyone can check with sha256(projection) === parityHash. Returns a trust receipt whose subject is the project. An invalid .faf, or a score that is unknown, gets no receipt (isError). Reads only.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`path`	No	Project path. Sets session context for subsequent calls.

Output Schema

TableJSON Schema

Name	Required	Description
`path`	No	Path that was attested
`tier`	No	Tier name for this score
`score`	No	AI-readiness score, 0-100
`valid`	Yes	Whether faf-cli's validateFaf accepts the .faf
`errors`	No	faf-cli's validateFaf errors, when valid is false
`hasFaf`	Yes	Whether a project.faf was found
`parity`	No	faf-parity/v1 — claude-faf-mcp's own spec (no other engine computes it yet): sha256 over a canonical projection of faf-cli's score for these exact bytes. Check it yourself: sha256(projection) === parityHash.
`reason`	No	Why no receipt was issued
`receipt`	No	The trust receipt — render-identical, self-verifying score + parity.
`subject`	No	The project the receipt attests: project.name, else its folder name
`sourceSha256`	No	SHA-256 of the raw .faf bytes

Schema Changelog

Changes observed during successful MCP inspections.

Changed16 schema fields changedv6.0.0Sep 13, 2026

changedOutput schema / description

Previous value: -"Trust attestation: validity, score, and a third-party-verifiable determinism parity receipt."New value: +"Trust attestation: faf-cli's validity and score, and a faf-parity/v1 receipt."

addedOutput schema / properties / errors

Added value: +{
+  "description": "faf-cli's validateFaf errors, when valid is false",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

changedOutput schema / properties / parity / description

Previous value: -"Determinism parity receipt (same shape as faf_score.parity)."New value: +"faf-parity/v1 — claude-faf-mcp's own spec (no other engine computes it yet): sha256 over a canonical projection of faf-cli's score for these exact bytes. Check it yourself: sha256(projection) === parityHash."

addedOutput schema / properties / parity / properties / algo / description
```
Added value: +"Hash algorithm (sha256)"
```
addedOutput schema / properties / parity / properties / parityHash / description
```
Added value: +"sha256(projection)"
```
addedOutput schema / properties / parity / properties / producedBy / description
```
Added value: +"The server that emitted this receipt (metadata, not hashed)"
```

addedOutput schema / properties / parity / properties / projection / description

Added value: +"The exact canonical string that was hashed (for verification)"

addedOutput schema / properties / parity / properties / scorer / description

Added value: +"The single deterministic source the score comes from (faf-cli)"

addedOutput schema / properties / parity / properties / sourceSha256 / description
```
Added value: +"SHA-256 of the raw .faf bytes"
```
addedOutput schema / properties / parity / properties / spec / description
```
Added value: +"Parity spec id: faf-parity/v1"
```

changedOutput schema / properties / reason / description

Previous value: -"Why validation failed, when valid is false"New value: +"Why no receipt was issued"

changedOutput schema / properties / receipt / description

Previous value: -"The ✪ trust receipt — render-identical, self-verifying score+parity artifact."New value: +"The trust receipt — render-identical, self-verifying score + parity."

changedOutput schema / properties / receipt / properties / seal / description

Previous value: -"Quiet-ladder glyph for this score (✪ at Trophy)"New value: +"Quiet-ladder glyph for this score (✪ only at 100)"

addedOutput schema / properties / receipt / properties / subject / description
```
Added value: +"The project: project.name, else its folder name"
```

addedOutput schema / properties / subject

Added value: +{
+  "description": "The project the receipt attests: project.name, else its folder name",
+  "type": "string"
+}

changedOutput schema / properties / valid / description

Previous value: -"Whether the project.faf is readable and valid"New value: +"Whether faf-cli's validateFaf accepts the .faf"

Changed2 schema fields changedv5.9.0Jun 12, 2026

addedInput schema / properties / path

Added value: +{
+  "description": "Project path. Sets session context for subsequent calls.",
+  "type": "string"
+}

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "additionalProperties": true,
+  "description": "Trust attestation: validity, score, and a third-party-verifiable determinism parity receipt.",
+  "properties": {
+    "hasFaf": {
+      "description": "Whether a project.faf was found",
+      "type": "boolean"
+    },
+    "parity": {
+      "description": "Determinism parity receipt (same shape as faf_score.parity).",
+      "properties": {
+        "algo": {
+          "type": "string"
+        },
+        "parityHash": {
+          "type": "string"
+        },
+        "producedBy": {
+          "type": "string"
+        },
+        "projection": {
+          "type": "string"
+        },
+        "scorer": {
+          "type": "string"
+        },
+        "sourceSha256": {
+          "type": "string"
+        },
+        "spec": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "spec",
+        "parityHash",
+        "sourceSha256",
+        "projection"
+      ],
+      "type": "object"
+    },
+    "path": {
+      "description": "Path that was attested",
+      "type": "string"
+    },
+    "reason": {
+      "description": "Why validation failed, when valid is false",
+      "type": "string"
+    },
+    "receipt": {
+      "description": "The ✪ trust receipt — render-identical, self-verifying score+parity artifact.",
+      "properties": {
+        "issued": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "score": {
+          "type": "number"
+        },
+        "seal": {
+          "description": "Quiet-ladder glyph for this score (✪ at Trophy)",
+          "type": "string"
+        },
+        "spec": {
+          "type": "string"
+        },
+        "subject": {
+          "type": "string"
+        },
+        "tests": {
+          "description": "Optional test attestation",
+          "type": [
+            "object",
+            "null"
+          ]
+        },
+        "tier": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "spec",
+        "seal",
+        "subject",
+        "score"
+      ],
+      "type": "object"
+    },
+    "score": {
+      "description": "AI-readiness score, 0-100",
+      "type": "number"
+    },
+    "sourceSha256": {
+      "description": "SHA-256 of the raw .faf bytes",
+      "type": "string"
+    },
+    "tier": {
+      "description": "Tier name for this score",
+      "type": "string"
+    },
+    "valid": {
+      "description": "Whether the project.faf is readable and valid",
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "valid",
+    "hasFaf"
+  ],
+  "type": "object"
+}

First observedv4.0.0May 2, 2026

TDQS

A3.5/5.0

Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, closed-world. The description adds the important failure behavior: invalid .faf or unknown score yields isError/no receipt; 'Reads only' is redundant but consistent. It stops short of permission/rate-limit context.

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 verb and core behavior, then return and error condition; no bloated preamble. The final 'Reads only' is redundant against annotations, keeping it from a perfect score.

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

Completeness4/5

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

Output schema exists and annotations cover safety, so return values and read-only nature need not be fully explained here. The description does cover the receipt and error case, making it sufficiently complete for this read-only attestation tool.

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

Parameters3/5

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

Single path parameter has 100% schema description coverage, so the schema already explains its role. The description adds no further syntax/default/context for path, so baseline 3.

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

Purpose4/5

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

States a specific verb ('Attest') and resource (the project's .faf) and enumerates the composite checks (validateFaf, score, parity hash) and returned receipt. This is clearly not a bare score tool, but it does not name a sibling alternative to route among faf_score/faf_doctor.

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

Usage Guidelines2/5

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

No when-to-use guidance, prerequisites, or alternatives to sibling tools are provided. Usage is only implied by the attestation purpose, so an agent gets little help choosing this over faf_score or faf_doctor.

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

Deploy Server