@agentauditai/mcp-server 2.0.0 → 3.0.0

package/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog — @agentauditai/mcp-server
+
+All notable changes to this package. Versions follow [SemVer](https://semver.org/).
+
+## 3.0.0 — 2026-11-08
+
+AgentAudit provides evidence, not certification. This release removes every tool
+output that read as a compliance verdict.
+
+### Breaking
+- **`check_conformity` removed.** The server no longer reads ConformityAssessment.
+  The deployed contract is unchanged; read it directly if you need the record.
+- **Evidence report output changed.** The ConformityAssessment section is gone and
+  the report lists on-chain records with a disclaimer instead of a verdict.
+- **`report_incident` no longer prints a reporting deadline.** Deadlines depend on
+  the type of incident; confirm them with your legal team. The tool states that it
+  creates an on-chain record, not a report to an authority.
+
+### Added
+- `get_evidence_report`. `get_compliance_report` stays as a deprecated alias and
+  will be removed in a future major version.
+- **Base Builder Code attribution (ERC-8021), on by default** for `audit_action`
+  and `report_incident`, on Base (8453) and Base Sepolia (84532) only. Appends a
+  29-byte suffix for `bc_pd681w25`; evidence bytes are unchanged, only the tx hash
+  differs. Turn it off with `AGENTAUDIT_BUILDER_CODE=false` (also `off`, `0`), or
+  set your own code. An invalid value stops the server at startup.
+- "Not legal advice." in evidence and incident tool descriptions and output.
+
+### Changed
+- MCP handshake version `3.0.0`.
+- `CHANGELOG.md` now ships in the package.
+
+## 2.0.0 — 2026-10-30
+
+First npm release: `audit_action` (AuditVault v2 `commitBatch` on Base),
+`get_audit_log`, `verify_proof`, `report_incident` (IncidentRegistry v2, 5
+networks), `get_compliance_report`, `get_risk_score`, `check_conformity`.

package/README.md

@@ -1,12 +1,12 @@
 # @agentauditai/mcp-server
 
-MCP (Model Context Protocol) server for [AgentAudit](https://github.com/agentauditAI/AgentAudit): on-chain audit logging and incident reporting for AI agents under the EU AI Act. Works with Claude, Cursor and any MCP client over stdio.
+MCP (Model Context Protocol) server for [AgentAudit](https://github.com/agentauditAI/AgentAudit): on-chain audit logging and incident records for AI agents, providing evidence that supports EU AI Act record-keeping. It does not determine whether any legal obligation is satisfied. Works with Claude, Cursor and any MCP client over stdio.
 
 | What | Where it is live |
 |---|---|
 | Audit logging: `audit_action`, `get_audit_log`, `verify_proof` (AuditVault v2, Art. 12, 19) | **Base only**: AuditVault v2 `0xCeE831070aa9081422f30df5559c125aa47A75DB` |
-| Incident reporting: `report_incident` (IncidentRegistry v2, Art. 73) | **5 networks**: mantle, base, arbitrum, optimism, polygon |
-| Compliance reads: `get_compliance_report`, `get_risk_score`, `check_conformity` (Art. 9, 43, 44, 73) | mantle, base, arbitrum, optimism, polygon |
+| Incident records: `report_incident` (IncidentRegistry v2, related to Art. 73) | **5 networks**: mantle, base, arbitrum, optimism, polygon |
+| Evidence reads: `get_evidence_report`, `get_risk_score` (related to Art. 9, 73) | mantle, base, arbitrum, optimism, polygon |
 
 ## Install and run
 
@@ -14,8 +14,6 @@ MCP (Model Context Protocol) server for [AgentAudit](https://github.com/agentaud
 npx -y @agentauditai/mcp-server        # starts the stdio server (bin: agentaudit-mcp)
 ```
 
-Until the package is on npm, run it from the repo: `git clone https://github.com/agentauditAI/AgentAudit && cd AgentAudit && npm install && npm run mcp`.
-
 The package is compiled JavaScript and needs Node.js 18 or newer; it does not use ts-node at runtime.
 
 Example MCP client config:
@@ -39,6 +37,7 @@ Example MCP client config:
 | `PRIVATE_KEY` | `audit_action`, `report_incident` | Signer for write tools. Not needed for read tools. Never commit it. |
 | `RPC_MANTLE`, `RPC_BASE`, `RPC_ARBITRUM`, `RPC_OPTIMISM`, `RPC_POLYGON` | all tools | Optional RPC overrides; public RPCs are used by default |
 | `AUDIT_VAULT_<NETWORK>` | `audit_action`, `get_audit_log`, `verify_proof` | Points a network at an AuditVault v2 deployment. Without it, every network except Base returns an error. |
+| `AGENTAUDIT_BUILDER_CODE` | `audit_action`, `report_incident` | Base Builder Code attribution, on Base / Base Sepolia only. Unset or empty: AgentAudit's code `bc_pd681w25`. `false`, `off` or `0` (any case): no suffix. Any other value: your own code. See below. |
 
 The server also loads a `.env` file from the working directory (dotenv). Variables already set in the environment take precedence.
 
@@ -63,11 +62,36 @@ Checks one entry's inclusion proof with AuditVault v2 `verifyLog`. The leaf is a
 
 ### `report_incident` (write, 5 networks)
 
-Registers a serious incident on IncidentRegistry v2 (Art. 73). Before sending, it checks the registry has code. After mining, it requires an `IncidentRegistered` event from the registry address; otherwise it returns an error and never reports success. The result includes the Art. 73§2 reporting deadline (2 / 10 / 15 days by severity).
+Records a serious incident on IncidentRegistry v2 (related to Art. 73). This is an on-chain record, not a report to any authority. Before sending, it checks the registry has code. After mining, it requires an `IncidentRegistered` event from the registry address; otherwise it returns an error and never reports success. It does not calculate reporting deadlines: they depend on the type of incident, so confirm them with your legal team.
+
+### `get_evidence_report`, `get_risk_score` (read)
+
+Read the Phase 7 contracts: RiskManagementSystem (related to Art. 9) and IncidentRegistry (related to Art. 73). If a contract has no code on the selected network, the tool returns an error naming the network and address.
+
+These tools list on-chain records. They do not determine whether any obligation under the EU AI Act or any other law is satisfied.
+
+`get_compliance_report` is a deprecated alias of `get_evidence_report` and will be removed in a future major version.
+
+## Evidence, not certification
+
+AgentAudit provides on-chain evidence. It does not certify AI systems, issue conformity assessments or replace an assessment under the EU AI Act. `check_conformity` was removed for this reason.
+
+## Base Builder Code attribution
 
-### `get_compliance_report`, `get_risk_score`, `check_conformity` (read)
+On **Base mainnet (8453) and Base Sepolia (84532) only**, the write tools (`audit_action`,
+`report_incident`) append a [Base Builder Code](https://docs.base.org/base-chain/builder-codes/builder-codes)
+suffix (ERC-8021, schema 0) to their transaction calldata. It is on by default with
+AgentAudit's code `bc_pd681w25`, so Base can attribute these transactions to AgentAudit.
 
-Read the Phase 7 contracts: ConformityAssessment (Art. 43, 44), RiskManagementSystem (Art. 9) and IncidentRegistry (Art. 73). If a contract has no code on the selected network, the tool returns an error naming the network and address.
+- **What is appended:** 29 bytes, `0x62635f70643638317732350b0080218021802180218021802180218021`
+  (`"bc_pd681w25"`, length `0x0b`, schema `0x00`, then the marker `0x8021` × 8).
+- **What stays the same:** the contracts ignore the suffix, so events and state are
+  identical, and no evidence changes (`action_ref`, Merkle root, bundle). Only the tx hash differs.
+- **The code is public** on-chain. The chain is read from the RPC (`eth_chainId`);
+  other chains never get a suffix.
+- **Turn it off:** `AGENTAUDIT_BUILDER_CODE=false`. **Use your own code:**
+  `AGENTAUDIT_BUILDER_CODE=bc_yourcode` (ERC-8021 rules: 7-bit ASCII, no comma, ≤ 255 bytes;
+  an invalid value stops the server at startup).
 
 ## Caveat: AuditVault v2 does not authenticate submitters
 

package/dist/sdk/src/attribution.d.ts

@@ -0,0 +1,42 @@
+import { ethers } from "ethers";
+/** AgentAudit's Base Builder Code, used unless the integrator passes `builderCode`. */
+export declare const AGENTAUDIT_BUILDER_CODE = "bc_pd681w25";
+/** Chains on which the suffix is appended: Base mainnet and Base Sepolia. */
+export declare const BUILDER_CODE_CHAIN_IDS: readonly bigint[];
+/** ERC-8021 marker: 0x8021 repeated 8 times (16 bytes), at the very end of the calldata. */
+export declare const ERC8021_MARKER = "0x80218021802180218021802180218021";
+/**
+ * Checks a code against the ERC-8021 rules: non-empty, 7-bit ASCII, no comma
+ * (0x2C, the delimiter), at most 255 bytes. Returns the code unchanged.
+ */
+export declare function validateBuilderCode(code: string): string;
+/**
+ * ERC-8021 schema-0 data suffix: `codes ‖ codesLength (1 B) ‖ schemaId 0x00 ‖ 0x8021×8`,
+ * where `codes` is the ASCII codes joined by commas.
+ */
+export declare function erc8021DataSuffix(codes: readonly string[]): string;
+/**
+ * Resolves the `builderCode` option: `undefined` → AgentAudit's code,
+ * `false` → no attribution (`null`), a string → that code (validated).
+ */
+export declare function resolveBuilderCode(option: string | false | undefined): string | null;
+/**
+ * Reads AGENTAUDIT_BUILDER_CODE semantics: unset or "" → `undefined` (default, on);
+ * "false" / "off" / "0" (any case) → `false`; anything else → that string, to be
+ * validated by `resolveBuilderCode`.
+ */
+export declare function builderCodeFromEnv(value: string | undefined): string | false | undefined;
+/** The suffix for `chainId`: the code's ERC-8021 suffix on Base / Base Sepolia, else "0x". */
+export declare function attributionSuffix(code: string | null, chainId: bigint): string;
+/**
+ * The chain id the RPC actually reports (`provider.getNetwork()`), cached per
+ * provider. A failed lookup is not cached. The configured network name is never used.
+ */
+export declare function providerChainId(provider: ethers.Provider): Promise<bigint>;
+/**
+ * Sends `contract.method(...args)` like ethers' own contract call, with the
+ * attribution suffix appended to the calldata when it applies. The signer
+ * populates the final transaction, so gas is estimated on the calldata incl.
+ * the suffix. Returns the same `ContractTransactionResponse` ethers would.
+ */
+export declare function sendAttributed(contract: ethers.Contract, method: string, args: readonly unknown[], builderCode: string | null): Promise<ethers.ContractTransactionResponse>;

package/dist/sdk/src/attribution.js

@@ -0,0 +1,133 @@
+"use strict";
+// Base Builder Code attribution (ERC-8021 schema 0) for AgentAudit contract calls.
+//
+// What: a 29-byte suffix appended to the calldata of the SDK's own contract
+// calls, on Base mainnet (8453) and Base Sepolia (84532) only. Contracts ignore
+// trailing calldata; Base indexers read the code from the end of the calldata.
+// The code is public on-chain. No audit evidence changes: action_ref, Merkle
+// root, scope, contentURI and payload hashes are computed before the call is
+// ABI-encoded, and the suffix goes after the encoding (only the tx hash differs).
+//
+// Opt out: `builderCode: false` (SDK) / AGENTAUDIT_BUILDER_CODE=false (MCP).
+// Own code: `builderCode: "<your code>"`. See README "Base Builder Code attribution".
+//
+// The encoding is implemented here (no runtime dependency); test/sdk/attribution.test.ts
+// checks it byte for byte against the ERC-8021 test vector and against `ox/erc8021`.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ERC8021_MARKER = exports.BUILDER_CODE_CHAIN_IDS = exports.AGENTAUDIT_BUILDER_CODE = void 0;
+exports.validateBuilderCode = validateBuilderCode;
+exports.erc8021DataSuffix = erc8021DataSuffix;
+exports.resolveBuilderCode = resolveBuilderCode;
+exports.builderCodeFromEnv = builderCodeFromEnv;
+exports.attributionSuffix = attributionSuffix;
+exports.providerChainId = providerChainId;
+exports.sendAttributed = sendAttributed;
+const ethers_1 = require("ethers");
+/** AgentAudit's Base Builder Code, used unless the integrator passes `builderCode`. */
+exports.AGENTAUDIT_BUILDER_CODE = "bc_pd681w25";
+/** Chains on which the suffix is appended: Base mainnet and Base Sepolia. */
+exports.BUILDER_CODE_CHAIN_IDS = [8453n, 84532n];
+/** ERC-8021 marker: 0x8021 repeated 8 times (16 bytes), at the very end of the calldata. */
+exports.ERC8021_MARKER = "0x80218021802180218021802180218021";
+const SCHEMA_ID_0 = "00";
+const MAX_CODES_LENGTH = 255; // codesLength is a single byte
+/**
+ * Checks a code against the ERC-8021 rules: non-empty, 7-bit ASCII, no comma
+ * (0x2C, the delimiter), at most 255 bytes. Returns the code unchanged.
+ */
+function validateBuilderCode(code) {
+    if (typeof code !== "string" || code.length === 0) {
+        throw new Error("Invalid builder code: must be a non-empty string");
+    }
+    if (!/^[\x00-\x7f]*$/.test(code)) {
+        throw new Error(`Invalid builder code ${JSON.stringify(code)}: ERC-8021 codes are 7-bit ASCII`);
+    }
+    if (code.includes(",")) {
+        throw new Error(`Invalid builder code ${JSON.stringify(code)}: ERC-8021 codes must not contain a comma`);
+    }
+    if (code.length > MAX_CODES_LENGTH) {
+        throw new Error(`Invalid builder code: ${code.length} bytes, ERC-8021 allows at most ${MAX_CODES_LENGTH}`);
+    }
+    return code;
+}
+/**
+ * ERC-8021 schema-0 data suffix: `codes ‖ codesLength (1 B) ‖ schemaId 0x00 ‖ 0x8021×8`,
+ * where `codes` is the ASCII codes joined by commas.
+ */
+function erc8021DataSuffix(codes) {
+    if (codes.length === 0)
+        throw new Error("ERC-8021 suffix needs at least one code");
+    const joined = codes.map(validateBuilderCode).join(",");
+    if (joined.length > MAX_CODES_LENGTH) {
+        throw new Error(`ERC-8021 codes are ${joined.length} bytes with delimiters; at most ${MAX_CODES_LENGTH} allowed`);
+    }
+    const lengthByte = joined.length.toString(16).padStart(2, "0");
+    return ethers_1.ethers.hexlify(ethers_1.ethers.toUtf8Bytes(joined)) + lengthByte + SCHEMA_ID_0 + exports.ERC8021_MARKER.slice(2);
+}
+/**
+ * Resolves the `builderCode` option: `undefined` → AgentAudit's code,
+ * `false` → no attribution (`null`), a string → that code (validated).
+ */
+function resolveBuilderCode(option) {
+    if (option === undefined)
+        return exports.AGENTAUDIT_BUILDER_CODE;
+    if (option === false)
+        return null;
+    if (typeof option !== "string") {
+        throw new Error("builderCode must be a string, false, or omitted");
+    }
+    return validateBuilderCode(option);
+}
+/**
+ * Reads AGENTAUDIT_BUILDER_CODE semantics: unset or "" → `undefined` (default, on);
+ * "false" / "off" / "0" (any case) → `false`; anything else → that string, to be
+ * validated by `resolveBuilderCode`.
+ */
+function builderCodeFromEnv(value) {
+    const v = value?.trim();
+    if (!v)
+        return undefined;
+    if (/^(false|off|0)$/i.test(v))
+        return false;
+    return v;
+}
+/** The suffix for `chainId`: the code's ERC-8021 suffix on Base / Base Sepolia, else "0x". */
+function attributionSuffix(code, chainId) {
+    if (code === null || !exports.BUILDER_CODE_CHAIN_IDS.includes(chainId))
+        return "0x";
+    return erc8021DataSuffix([code]);
+}
+const chainIds = new WeakMap();
+/**
+ * The chain id the RPC actually reports (`provider.getNetwork()`), cached per
+ * provider. A failed lookup is not cached. The configured network name is never used.
+ */
+function providerChainId(provider) {
+    let p = chainIds.get(provider);
+    if (!p) {
+        p = provider.getNetwork().then((n) => n.chainId);
+        p.catch(() => chainIds.delete(provider));
+        chainIds.set(provider, p);
+    }
+    return p;
+}
+/**
+ * Sends `contract.method(...args)` like ethers' own contract call, with the
+ * attribution suffix appended to the calldata when it applies. The signer
+ * populates the final transaction, so gas is estimated on the calldata incl.
+ * the suffix. Returns the same `ContractTransactionResponse` ethers would.
+ */
+async function sendAttributed(contract, method, args, builderCode) {
+    const signer = contract.runner;
+    if (!signer || typeof signer.sendTransaction !== "function" || !signer.provider) {
+        throw new Error("sendAttributed needs a contract connected to a signer with a provider");
+    }
+    const tx = await contract.getFunction(method).populateTransaction(...args);
+    if (builderCode !== null) {
+        const suffix = attributionSuffix(builderCode, await providerChainId(signer.provider));
+        if (suffix !== "0x")
+            tx.data = ethers_1.ethers.concat([tx.data, suffix]);
+    }
+    const sent = await signer.sendTransaction(tx);
+    return new ethers_1.ethers.ContractTransactionResponse(contract.interface, signer.provider, sent);
+}

package/dist/sdk/src/index.d.ts

@@ -1,5 +1,6 @@
 import type { BatchCommitter, CommitBatchParams, CommitBatchResult } from "./batch";
 export * from "./batch";
+export * from "./attribution";
 export declare const NETWORKS: {
     readonly mantle: {
         readonly rpc: "https://rpc.mantle.xyz";
@@ -70,6 +71,12 @@ export interface AgentAuditConfig {
     incidentRegistryAddress?: string;
     /** PostMarketMonitor contract address (Art. 72) */
     postMarketMonitorAddress?: string;
+    /**
+     * Base Builder Code (ERC-8021) appended to the calldata of this SDK's contract
+     * calls on Base / Base Sepolia only. Omitted: AgentAudit's code (`bc_pd681w25`).
+     * `false`: no suffix. A string: your own code. See README "Base Builder Code attribution".
+     */
+    builderCode?: string | false;
 }
 export interface LogActionParams {
     agentId: number | string;
@@ -138,6 +145,7 @@ export declare class AgentAudit implements BatchCommitter {
     private _incidentRegistry?;
     private _postMarketMonitor?;
     private config;
+    private builderCode;
     constructor(config: AgentAuditConfig);
     private get registration();
     private get auditVaultV2();
@@ -149,6 +157,8 @@ export declare class AgentAudit implements BatchCommitter {
     private incidentRegistry;
     private verifyIncidentRegistry;
     private get postMarketMonitor();
+    /** Every state-changing call goes through here (Builder Code suffix on Base only). */
+    private send;
     private hashPayload;
     private riskToUint;
     private enumIndex;
@@ -331,6 +341,14 @@ export declare class AgentAudit implements BatchCommitter {
         explorer: "https://polygonscan.com";
         name: "Polygon Mainnet";
     };
+    /**
+     * Base Builder Code this instance appends on Base / Base Sepolia, or null when disabled
+     */
+    getBuilderCode(): string | null;
+    /**
+     * The exact calldata suffix this instance appends on the RPC's actual chain ("0x" = none)
+     */
+    getAttributionSuffix(): Promise<string>;
     /**
      * Get connected wallet address
      */

package/dist/sdk/src/index.js

@@ -21,7 +21,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.AgentAudit = exports.NETWORKS = void 0;
 exports.createAgentAudit = createAgentAudit;
 const ethers_1 = require("ethers");
+const attribution_1 = require("./attribution");
 __exportStar(require("./batch"), exports);
+__exportStar(require("./attribution"), exports);
 // ─── Network Config ───────────────────────────────────────────────────────────
 //
 // vaultVersion: 1 = AuditVault v1, 2 = AuditVault v2 (verified bytecode),
@@ -127,6 +129,7 @@ const INCIDENT_STATUSES = ["OPEN", "REPORTED", "UNDER_INVESTIGATION", "RESOLVED"
 class AgentAudit {
     constructor(config) {
         this.config = config;
+        this.builderCode = (0, attribution_1.resolveBuilderCode)(config.builderCode);
         this.networkName = config.network ?? "base";
         this.network = exports.NETWORKS[this.networkName];
         const rpc = config.rpcUrl ?? this.network.rpc;
@@ -202,6 +205,10 @@ class AgentAudit {
         return this._postMarketMonitor;
     }
     // ─── Helpers ────────────────────────────────────────────────────────────────
+    /** Every state-changing call goes through here (Builder Code suffix on Base only). */
+    send(contract, method, ...args) {
+        return (0, attribution_1.sendAttributed)(contract, method, args, this.builderCode);
+    }
     hashPayload(payload) {
         const str = typeof payload === "string" ? payload : JSON.stringify(payload);
         return ethers_1.ethers.keccak256(ethers_1.ethers.toUtf8Bytes(str));
@@ -234,7 +241,7 @@ class AgentAudit {
         const payloadHash = this.hashPayload(params.payload);
         const risk = this.riskToUint(params.riskLevel);
         const agentId = String(params.agentId);
-        const tx = await this.auditVault.logAction(agentId, params.actionType, payloadHash, risk);
+        const tx = await this.send(this.auditVault, "logAction", agentId, params.actionType, payloadHash, risk);
         await tx.wait();
         return {
             txHash: tx.hash,
@@ -255,7 +262,7 @@ class AgentAudit {
         const actionTypes = actions.map(a => a.actionType);
         const payloadHashes = actions.map(a => this.hashPayload(a.payload));
         const riskLevels = actions.map(a => this.riskToUint(a.riskLevel));
-        const tx = await this.auditVault.logActionBatch(String(agentId), actionTypes, payloadHashes, riskLevels);
+        const tx = await this.send(this.auditVault, "logActionBatch", String(agentId), actionTypes, payloadHashes, riskLevels);
         await tx.wait();
         return {
             txHash: tx.hash,
@@ -276,7 +283,7 @@ class AgentAudit {
      */
     async commitBatch(params) {
         const vault = this.auditVaultV2;
-        const tx = await vault.commitBatch(params.agentAddress, params.merkleRoot, params.contentURI, params.eventCount, params.complianceScore);
+        const tx = await this.send(vault, "commitBatch", params.agentAddress, params.merkleRoot, params.contentURI, params.eventCount, params.complianceScore);
         const receipt = await tx.wait();
         let batchIndex = null;
         for (const log of receipt?.logs ?? []) {
@@ -312,7 +319,7 @@ class AgentAudit {
      * Register a new AI agent on-chain (KYA standard, Art. 13, 26)
      */
     async registerAgent(params) {
-        const tx = await this.registration.registerAgent(params.name, params.complianceLevel ?? "limited", params.spendLimit ?? ethers_1.ethers.parseEther("100"), params.auditVault ?? this.network.auditVault);
+        const tx = await this.send(this.registration, "registerAgent", params.name, params.complianceLevel ?? "limited", params.spendLimit ?? ethers_1.ethers.parseEther("100"), params.auditVault ?? this.network.auditVault);
         await tx.wait();
         // Get agent ID from event or return 0 (caller can query separately)
         return { agentId: 0, txHash: tx.hash, network: this.network.name };
@@ -321,7 +328,7 @@ class AgentAudit {
      * Revoke an agent
      */
     async revokeAgent(agentId) {
-        const tx = await this.registration.revokeAgent(agentId);
+        const tx = await this.send(this.registration, "revokeAgent", agentId);
         await tx.wait();
         return { txHash: tx.hash };
     }
@@ -353,7 +360,7 @@ class AgentAudit {
         const evidenceHash = params.evidenceHash ?? this.hashPayload(params.description);
         // Block time, not Date.now(): the registry rejects occurredAt > block.timestamp
         const occurredAt = params.occurredAt ?? (await this.provider.getBlock("latest")).timestamp;
-        const tx = await registry.registerIncident(this.incidentAgentId(params.agentId), severity, harmType, params.description, evidenceHash, affectedPersons, occurredAt);
+        const tx = await this.send(registry, "registerIncident", this.incidentAgentId(params.agentId), severity, harmType, params.description, evidenceHash, affectedPersons, occurredAt);
         const receipt = await tx.wait();
         let incidentId = 0;
         for (const log of receipt?.logs ?? []) {
@@ -378,7 +385,7 @@ class AgentAudit {
      */
     async markReportedToAuthority(incidentId, params) {
         const registry = await this.incidentRegistry();
-        const tx = await registry.markReportedToAuthority(incidentId, ethers_1.ethers.getAddress(params.authority), params.authorityRef);
+        const tx = await this.send(registry, "markReportedToAuthority", incidentId, ethers_1.ethers.getAddress(params.authority), params.authorityRef);
         const receipt = await tx.wait();
         let withinDeadline = false;
         for (const log of receipt?.logs ?? []) {
@@ -440,7 +447,7 @@ class AgentAudit {
      * Enroll an agent in post-market monitoring (Art. 72)
      */
     async enrollMonitoring(params) {
-        const tx = await this.postMarketMonitor.enroll(params.agentAddress, params.systemName, params.riskCategory, params.reviewIntervalDays);
+        const tx = await this.send(this.postMarketMonitor, "enroll", params.agentAddress, params.systemName, params.riskCategory, params.reviewIntervalDays);
         await tx.wait();
         return { txHash: tx.hash };
     }
@@ -448,7 +455,7 @@ class AgentAudit {
      * Record a performance metric (Art. 72)
      */
     async recordMetric(params) {
-        const tx = await this.postMarketMonitor.recordMetric(params.agentAddress, this.metricTypeToUint(params.metricType), params.metricName, params.value, params.threshold, params.context ?? "sdk", params.txRef ? ethers_1.ethers.encodeBytes32String(params.txRef.slice(0, 31)) : ethers_1.ethers.ZeroHash);
+        const tx = await this.send(this.postMarketMonitor, "recordMetric", params.agentAddress, this.metricTypeToUint(params.metricType), params.metricName, params.value, params.threshold, params.context ?? "sdk", params.txRef ? ethers_1.ethers.encodeBytes32String(params.txRef.slice(0, 31)) : ethers_1.ethers.ZeroHash);
         await tx.wait();
         return { txHash: tx.hash };
     }
@@ -457,7 +464,7 @@ class AgentAudit {
      * @param complianceScore 0-10000 (e.g. 9500 = 95.00%)
      */
     async recordReview(params) {
-        const tx = await this.postMarketMonitor.recordReview(params.agentAddress, params.complianceScore, params.notes);
+        const tx = await this.send(this.postMarketMonitor, "recordReview", params.agentAddress, params.complianceScore, params.notes);
         await tx.wait();
         return { txHash: tx.hash };
     }
@@ -475,6 +482,18 @@ class AgentAudit {
     getNetworkInfo() {
         return { name: this.networkName, ...this.network };
     }
+    /**
+     * Base Builder Code this instance appends on Base / Base Sepolia, or null when disabled
+     */
+    getBuilderCode() {
+        return this.builderCode;
+    }
+    /**
+     * The exact calldata suffix this instance appends on the RPC's actual chain ("0x" = none)
+     */
+    async getAttributionSuffix() {
+        return (0, attribution_1.attributionSuffix)(this.builderCode, await (0, attribution_1.providerChainId)(this.provider));
+    }
     /**
      * Get connected wallet address
      */

package/dist/src/mcp-server.d.ts

@@ -2,7 +2,7 @@
 import "dotenv/config";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 type NetworkKey = "mantle" | "base" | "arbitrum" | "optimism" | "polygon";
-type Phase7Contract = "RiskManagementSystem" | "ConformityAssessment" | "IncidentRegistry";
+type Phase7Contract = "RiskManagementSystem" | "IncidentRegistry";
 export interface McpServerOptions {
     /** Signer key for audit_action and report_incident (env PRIVATE_KEY) */
     privateKey?: string;
@@ -12,6 +12,12 @@ export interface McpServerOptions {
     auditVaults?: Partial<Record<NetworkKey, string>>;
     /** Phase 7 address overrides; defaults come from deployments/phase7-<network>.json */
     phase7?: Partial<Record<NetworkKey, Partial<Record<Phase7Contract, string>>>>;
+    /**
+     * Base Builder Code (ERC-8021) appended to audit_action / report_incident calldata on
+     * Base and Base Sepolia only (env AGENTAUDIT_BUILDER_CODE). Omitted: AgentAudit's code
+     * `bc_pd681w25`. `false`: no suffix. A string: your own code.
+     */
+    builderCode?: string | false;
 }
 /** Options read from the environment — what the stdio entry point uses */
 export declare function optionsFromEnv(env?: NodeJS.ProcessEnv): McpServerOptions;

package/dist/src/mcp-server.js

@@ -80,7 +80,8 @@ function optionsFromEnv(env = process.env) {
         if (vault)
             auditVaults[net] = vault;
     }
-    return { privateKey: env.PRIVATE_KEY, rpcUrls, auditVaults };
+    // unset or "" → default code; "false" / "off" / "0" → off; anything else → custom code
+    return { privateKey: env.PRIVATE_KEY, rpcUrls, auditVaults, builderCode: (0, index_1.builderCodeFromEnv)(env.AGENTAUDIT_BUILDER_CODE) };
 }
 // ─── ABIs ────────────────────────────────────────────────────────────────────
 const VAULT_ABI = [...verify_1.AUDIT_VAULT_V2_ABI, "function getBatchCount(address agentId) view returns (uint256)"];
@@ -90,11 +91,6 @@ const RISK_ABI = [
     "function getAgentRisks(bytes32 agentId) external view returns (uint256[])",
     "function risks(uint256 id) external view returns (uint256 id, bytes32 agentId, uint8 category, uint8 severity, uint8 status, string description, string evidenceUri, uint16 likelihood, uint16 impact, address identifiedBy, uint256 identifiedAt, uint256 updatedAt)",
 ];
-const CONFORMITY_ABI = [
-    "function isValid(bytes32 agentId) external view returns (bool)",
-    "function getRecord(bytes32 agentId) external view returns (tuple(bytes32 agentId, uint8 assessmentType, uint8 status, string providerName, string providerAddress, string systemDescription, string notifiedBodyName, string notifiedBodyRef, string certificateRef, string standardsApplied, string declarationUri, uint256 validFrom, uint256 validUntil, address registeredBy, uint256 registeredAt, uint256 updatedAt, string withdrawalReason))",
-    "function getRegisteredCount() external view returns (uint256)",
-];
 const INCIDENT_ABI = [
     "function registerIncident(bytes32 agentId, uint8 severity, uint8 harmType, string description, string evidenceHash, uint256 affectedPersons, uint256 occurredAt) external returns (uint256 id)",
     "function getAgentIncidents(bytes32 agentId) external view returns (uint256[])",
@@ -104,7 +100,12 @@ const INCIDENT_ABI = [
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 const SEVERITY_LABELS = ["NEGLIGIBLE", "LOW", "MEDIUM", "HIGH", "CRITICAL"];
 const RISK_STATUS_LABELS = ["IDENTIFIED", "ASSESSED", "MITIGATED", "TESTED", "RESIDUAL", "CLOSED"];
-const CONFORMITY_STATUS_LABELS = ["PENDING", "CERTIFIED", "WITHDRAWN", "EXPIRED"];
+// ─── Output Notices ──────────────────────────────────────────────────────────
+const EVIDENCE_DISCLAIMER = "This output lists on-chain records found by the checks above. " +
+    "It does not determine whether any obligation under the EU AI Act or any other law is satisfied. " +
+    "Not legal advice.";
+const INCIDENT_RECORD_NOTE = "This is an on-chain record, not a report to any authority. " +
+    "This tool does not calculate reporting deadlines: they depend on the type of incident, so confirm them with your legal team. Not legal advice.";
 const INCIDENT_SEVERITY_LABELS = ["LOW", "MEDIUM", "HIGH", "CRITICAL"];
 const HARM_TYPE_LABELS = ["DEATH", "SERIOUS_HEALTH_HARM", "SIGNIFICANT_PROPERTY_DAMAGE", "FUNDAMENTAL_RIGHTS_VIOLATION", "OTHER"];
 /** Integration tag stored in each audit_action record (EVIDENCE_SCHEMA §2.5) */
@@ -124,6 +125,8 @@ function errorMessage(err) {
 // ─── MCP Server ──────────────────────────────────────────────────────────────
 function createServer(options = optionsFromEnv()) {
     const rpcUrl = (net) => options.rpcUrls?.[net] ?? DEFAULT_RPC_URLS[net];
+    // Validated at startup so a bad AGENTAUDIT_BUILDER_CODE fails fast
+    const builderCode = (0, index_1.resolveBuilderCode)(options.builderCode);
     const providers = new Map();
     // cacheTimeout -1: back-to-back writes must not reuse a cached nonce
     const provider = (net) => {
@@ -164,7 +167,7 @@ function createServer(options = optionsFromEnv()) {
         throw new Error(`Audit logging is live on Base only: ${net} has no AuditVault v2 (default ${sdkNet.auditVault} ${what}, no commitBatch). ` +
             `Use network "base" or set AUDIT_VAULT_${net.toUpperCase()} to an AuditVault v2 deployment.`);
     }
-    const server = new mcp_js_1.McpServer({ name: "agentaudit", version: "2.0.0" }, { capabilities: { tools: {} } });
+    const server = new mcp_js_1.McpServer({ name: "agentaudit", version: "3.0.0" }, { capabilities: { tools: {} } });
     // ─── Tool 1: audit_action ────────────────────────────────────────────────────
     server.tool("audit_action", `Anchor one or more agent actions on AuditVault v2 in one commitBatch transaction (EU AI Act Art. 12, 19). ` +
         `Live on Base only (AuditVault v2 ${BASE_VAULT}); any other network returns an error unless AUDIT_VAULT_<NETWORK> points at an AuditVault v2. ` +
@@ -183,7 +186,13 @@ function createServer(options = optionsFromEnv()) {
     }, async ({ agent_id, entries, agent_address, compliance_score, network }) => {
         const vault = auditVault(network);
         await requireCode(network, vault, "AuditVault v2");
-        const sdk = new index_1.AgentAudit({ privateKey: privateKey(), network, rpcUrl: rpcUrl(network), auditVaultAddress: vault });
+        const sdk = new index_1.AgentAudit({
+            privateKey: privateKey(),
+            network,
+            rpcUrl: rpcUrl(network),
+            auditVaultAddress: vault,
+            builderCode: builderCode ?? false,
+        });
         const agentAddress = agent_address ? ethers_1.ethers.getAddress(agent_address) : sdk.getAddress();
         // One buffer per call, flushed once. The committer is one-shot so the
         // buffer's retry timer can never resend a batch after this call returned.
@@ -394,46 +403,9 @@ function createServer(options = optionsFromEnv()) {
         }
         return { content: [{ type: "text", text: lines.join("\n") }] };
     });
-    // ─── Tool 5: check_conformity ────────────────────────────────────────────────
-    server.tool("check_conformity", "Query the ConformityAssessment contract for an agent's EU Declaration of Conformity status (Art. 43, 44). Deployed on mantle, base, arbitrum, optimism, polygon.", {
-        agent_id: zod_1.z.string().regex(/^0x[0-9a-fA-F]{1,64}$/).describe("Agent ID as a hex bytes32 string"),
-        network: networkEnum.default("mantle"),
-    }, async ({ agent_id, network }) => {
-        const agentId = ethers_1.ethers.zeroPadValue(agent_id, 32);
-        const addr = phase7Address(network, "ConformityAssessment");
-        await requireCode(network, addr, "ConformityAssessment");
-        const contract = new ethers_1.ethers.Contract(addr, CONFORMITY_ABI, provider(network));
-        const isValid = await contract.isValid(agentId);
-        let record = null;
-        try {
-            record = await contract.getRecord(agentId);
-        }
-        catch {
-            // not registered
-        }
-        const lines = [
-            `check_conformity — network=${network}  agentId=${agent_id}`,
-            `contract=${addr}`,
-            "",
-            `Valid (certified + not expired): ${isValid ? "YES ✓" : "NO ✗"}`,
-        ];
-        if (record) {
-            const statusLabel = CONFORMITY_STATUS_LABELS[Number(record.status)] ?? "UNKNOWN";
-            const assessmentLabel = Number(record.assessmentType) === 0 ? "SELF_ASSESSMENT" : "NOTIFIED_BODY";
-            const validFrom = new Date(Number(record.validFrom) * 1000).toISOString().slice(0, 10);
-            const validUntil = new Date(Number(record.validUntil) * 1000).toISOString().slice(0, 10);
-            lines.push(`Status       : ${statusLabel}`, `Assessment   : ${assessmentLabel}`, `Provider     : ${record.providerName}`, `Valid from   : ${validFrom}`, `Valid until  : ${validUntil}`, `Declaration  : ${record.declarationUri || "(none)"}`, `Certificate  : ${record.certificateRef || "(none)"}`, `Notified body: ${record.notifiedBodyName || "(none)"}`);
-            if (record.withdrawalReason) {
-                lines.push(`Withdrawal   : ${record.withdrawalReason}`);
-            }
-        }
-        else {
-            lines.push("No conformity record found for this agent.");
-        }
-        return { content: [{ type: "text", text: lines.join("\n") }] };
-    });
-    // ─── Tool 6: report_incident ─────────────────────────────────────────────────
-    server.tool("report_incident", "Register a serious AI incident with IncidentRegistry v2 (EU AI Act Art. 73). Live on mantle, base, arbitrum, optimism, polygon. " +
+    // ─── Tool 5: report_incident ─────────────────────────────────────────────────
+    server.tool("report_incident", "Record a serious AI incident on IncidentRegistry v2 (related to EU AI Act Art. 73). Live on mantle, base, arbitrum, optimism, polygon. " +
+        "This is an on-chain record only, not a report to any authority. " +
         "Fails unless the registry has code and the transaction emits IncidentRegistered.", {
         agent_id: zod_1.z.string().regex(/^0x[0-9a-fA-F]{1,64}$/).describe("Agent ID as a hex bytes32 string"),
         severity: zod_1.z.enum(["LOW", "MEDIUM", "HIGH", "CRITICAL"]).describe("Incident severity"),
@@ -451,7 +423,15 @@ function createServer(options = optionsFromEnv()) {
         await requireCode(network, addr, "IncidentRegistry");
         const signer = new ethers_1.ethers.Wallet(privateKey(), provider(network));
         const contract = new ethers_1.ethers.Contract(addr, INCIDENT_ABI, signer);
-        const tx = await contract.registerIncident(agentId, severityIdx, harmTypeIdx, description, evidence_hash, affected_persons, occurred_at);
+        const tx = await (0, index_1.sendAttributed)(contract, "registerIncident", [
+            agentId,
+            severityIdx,
+            harmTypeIdx,
+            description,
+            evidence_hash,
+            affected_persons,
+            occurred_at,
+        ], builderCode);
         const receipt = await tx.wait();
         // Only an IncidentRegistered from the registry itself counts as registration
         let incidentId = null;
@@ -472,12 +452,11 @@ function createServer(options = optionsFromEnv()) {
         if (incidentId === null) {
             throw new Error(`Incident NOT registered: tx ${tx.hash} on ${network} emitted no IncidentRegistered from ${addr}`);
         }
-        const deadline = severity === "CRITICAL" ? "2 days" : severity === "HIGH" ? "10 days" : "15 days";
         return {
             content: [{
                     type: "text",
                     text: [
-                        `report_incident — Art. 73`,
+                        `report_incident — IncidentRegistry v2 (related: Art. 73)`,
                         `network=${network}  contract=${addr}`,
                         "",
                         `Incident ID      : ${incidentId}`,
@@ -485,22 +464,26 @@ function createServer(options = optionsFromEnv()) {
                         `Severity         : ${severity}`,
                         `Harm type        : ${harm_type}`,
                         `Affected persons : ${affected_persons}`,
-                        `Art. 73§2 deadline: report to authority within ${deadline} of occurrence`,
+                        "",
+                        INCIDENT_RECORD_NOTE,
                     ].join("\n"),
                 }],
         };
     });
-    // ─── Tool 7: get_compliance_report ───────────────────────────────────────────
-    server.tool("get_compliance_report", "Generate an EU AI Act compliance report for an agent from the Phase 7 contracts (ConformityAssessment, RiskManagementSystem, IncidentRegistry) " +
-        "on one or all of mantle, base, arbitrum, optimism, polygon. Read-only.", {
+    // ─── Tool 6: get_evidence_report (+ deprecated get_compliance_report alias) ──
+    const evidenceReportSchema = {
         agent_id: zod_1.z.string().regex(/^0x[0-9a-fA-F]{1,64}$/).describe("Agent ID as a hex bytes32 string"),
         network: zod_1.z.enum([...NETWORKS, "all"]).default("all"),
-    }, async ({ agent_id, network }) => {
+    };
+    const evidenceReportDescription = "List the on-chain records found for an agent in the Phase 7 contracts (RiskManagementSystem, IncidentRegistry) " +
+        "on one or all of mantle, base, arbitrum, optimism, polygon. Read-only. " +
+        "It does not determine whether any legal obligation is satisfied. Not legal advice.";
+    const evidenceReport = async ({ agent_id, network }) => {
         const agentId = ethers_1.ethers.zeroPadValue(agent_id, 32);
         const targets = network === "all" ? [...NETWORKS] : [network];
         const lines = [
             "═══════════════════════════════════════════════════════════",
-            "  AgentAudit — EU AI Act Compliance Report",
+            "  AgentAudit — On-chain Evidence Report",
             `  Agent   : ${agent_id}`,
             `  Date    : ${new Date().toISOString()}`,
             "═══════════════════════════════════════════════════════════",
@@ -508,26 +491,7 @@ function createServer(options = optionsFromEnv()) {
         for (const net of targets) {
             const p = provider(net);
             lines.push("", `── Network: ${net.toUpperCase()} ──────────────────────────────────`);
-            // Art. 43/44 — Conformity Assessment
-            try {
-                const addr = phase7Address(net, "ConformityAssessment");
-                await requireCode(net, addr, "ConformityAssessment");
-                const conformity = new ethers_1.ethers.Contract(addr, CONFORMITY_ABI, p);
-                const isValid = await conformity.isValid(agentId);
-                let statusLabel = "NOT REGISTERED";
-                let validUntil = "";
-                try {
-                    const rec = await conformity.getRecord(agentId);
-                    statusLabel = CONFORMITY_STATUS_LABELS[Number(rec.status)];
-                    validUntil = new Date(Number(rec.validUntil) * 1000).toISOString().slice(0, 10);
-                }
-                catch { /* not registered */ }
-                lines.push(`  Art. 43/44 Conformity  : ${statusLabel}${validUntil ? `  (expires ${validUntil})` : ""}`, `    → Currently valid    : ${isValid ? "YES ✓" : "NO ✗"}`);
-            }
-            catch (e) {
-                lines.push(`  Art. 43/44 Conformity  : error — ${errorMessage(e)}`);
-            }
-            // Art. 9 — Risk Management
+            // RiskManagementSystem
             try {
                 const addr = phase7Address(net, "RiskManagementSystem");
                 await requireCode(net, addr, "RiskManagementSystem");
@@ -537,12 +501,12 @@ function createServer(options = optionsFromEnv()) {
                     risk.risksAboveSeverity(agentId, 3),
                     risk.risksAboveSeverity(agentId, 4),
                 ]);
-                lines.push(`  Art. 9   Risk Mgmt     : open=${openCount}  HIGH+=${highCount}  CRITICAL=${criticalCount}`);
+                lines.push(`  RiskManagementSystem (related: Art. 9): open=${openCount}  HIGH+=${highCount}  CRITICAL=${criticalCount}`);
             }
             catch (e) {
-                lines.push(`  Art. 9   Risk Mgmt     : error — ${errorMessage(e)}`);
+                lines.push(`  RiskManagementSystem (related: Art. 9): error — ${errorMessage(e)}`);
             }
-            // Art. 73 — Incident Registry
+            // IncidentRegistry
             try {
                 const addr = phase7Address(net, "IncidentRegistry");
                 await requireCode(net, addr, "IncidentRegistry");
@@ -554,15 +518,17 @@ function createServer(options = optionsFromEnv()) {
                     if (Number(inc.status) < 3)
                         openIncidents++; // < RESOLVED
                 }
-                lines.push(`  Art. 73  Incidents     : total=${ids.length}  open=${openIncidents}`);
+                lines.push(`  IncidentRegistry (related: Art. 73): total=${ids.length}  open=${openIncidents}`);
             }
             catch (e) {
-                lines.push(`  Art. 73  Incidents     : error — ${errorMessage(e)}`);
+                lines.push(`  IncidentRegistry (related: Art. 73): error — ${errorMessage(e)}`);
             }
         }
-        lines.push("", "═══════════════════════════════════════════════════════════", "  Contracts queried: ConformityAssessment, RiskManagementSystem,", "  IncidentRegistry (Phase 7 deployment)", "═══════════════════════════════════════════════════════════");
+        lines.push("", "═══════════════════════════════════════════════════════════", "  Contracts queried: RiskManagementSystem, IncidentRegistry", "  (Phase 7 deployment)", "", `  ${EVIDENCE_DISCLAIMER}`, "═══════════════════════════════════════════════════════════");
         return { content: [{ type: "text", text: lines.join("\n") }] };
-    });
+    };
+    server.tool("get_evidence_report", evidenceReportDescription, evidenceReportSchema, evidenceReport);
+    server.tool("get_compliance_report", `Deprecated alias of get_evidence_report; it will be removed in a future major version. ${evidenceReportDescription}`, evidenceReportSchema, evidenceReport);
     return server;
 }
 // ─── Start ───────────────────────────────────────────────────────────────────

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@agentauditai/mcp-server",
-  "version": "2.0.0",
-  "description": "MCP server for AgentAudit: EU AI Act audit logging on AuditVault v2 (Base), incident reporting (Art. 73) and compliance reads.",
+  "version": "3.0.0",
+  "description": "MCP server for AgentAudit: audit logging on AuditVault v2 (Base), on-chain incident records and evidence reads for EU AI Act record-keeping.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -20,7 +20,8 @@
     "dist/sdk/src",
     "dist/tools/verify/src",
     "dist/deployments",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "build": "node scripts/clean.js && tsc -p tsconfig.build.json && node scripts/copy-deployments.js",