@agentauditai/mcp-server 0.0.0-stage → 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 agentauditAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,80 @@
-# Temporary Holding Version
+# @agentauditai/mcp-server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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.
+
+| 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 |
+
+## Install and run
+
+```bash
+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:
+
+```json
+{
+  "mcpServers": {
+    "agentaudit": {
+      "command": "npx",
+      "args": ["-y", "@agentauditai/mcp-server"],
+      "env": { "PRIVATE_KEY": "0x…", "RPC_BASE": "https://…" }
+    }
+  }
+}
+```
+
+## Environment variables
+
+| Variable | Used by | Notes |
+|---|---|---|
+| `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. |
+
+The server also loads a `.env` file from the working directory (dotenv). Variables already set in the environment take precedence.
+
+## Tools
+
+### `audit_action` (write, Base)
+
+Anchors one or more agent actions in **one** `commitBatch` transaction on AuditVault v2. Each call commits immediately; nothing is buffered between calls, so a restart cannot lose entries.
+
+- Input: `agent_id`, `entries[]` (`action_type`, `payload`, optional `risk_level` default `HIGH`, optional `timestamp_ms`), optional `agent_address` (defaults to the signer), `compliance_score` (0–100), `network` (default `base`).
+- Payloads are SHA-256 hashed (JCS for objects). Raw content never leaves the process. Each entry becomes an Evidence Schema v1 preimage with scope `agent_action:mcp:record_hash:<sha256>`.
+- Returns `txHash`, `batchIndex`, `merkle_root`, each entry's `action_ref` + `proof`, and the full evidence bundle. **Keep the bundle**: the batch payload is not stored anywhere else (`contentURI` is `memory://<root>`).
+- Errors (never a silent skip): the network has no AuditVault v2, the vault has no code, or the transaction emitted no `LogBatchCommitted` for the root.
+
+### `get_audit_log` (read, Base)
+
+Reads committed batches, either by `tx_hash` or by `agent_address` + `batch_index`. Returns the root, contentURI, event count, compliance score, submitter, timestamp and block.
+
+### `verify_proof` (read, Base)
+
+Checks one entry's inclusion proof with AuditVault v2 `verifyLog`. The leaf is always recomputed from the preimage, never taken from the caller (KI-2). Returns `valid`, the batch `submitter` and per-check results. Pass `expected_submitter` to pin the submitter (see the caveat below).
+
+### `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).
+
+### `get_compliance_report`, `get_risk_score`, `check_conformity` (read)
+
+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.
+
+## Caveat: AuditVault v2 does not authenticate submitters
+
+`commitBatch` on AuditVault v2 has no access control. **Anyone can commit a batch under any agent address.** A batch existing under an agent address therefore does not prove that agent's operator committed it, and batch counts can be inflated by third parties ([THREAT_MODEL KI-1](https://github.com/agentauditAI/AgentAudit/blob/main/docs/THREAT_MODEL.md)).
+
+When you verify, check the batch `submitter`: `get_audit_log` and `verify_proof` both return it, and `verify_proof` takes `expected_submitter` to enforce it. Accept a batch only if the submitter is an address you have authorized for that agent. For full bundles, the `agentaudit-verify` CLI in the repo does the same with `--submitter`.
+
+## License
+
+MIT

package/dist/deployments/phase7-arbitrumOne.json

@@ -0,0 +1,15 @@
+{
+  "network": "arbitrumOne",
+  "chainId": "42161",
+  "deployedAt": "2026-05-18T19:23:02.624Z",
+  "deployer": "0x218514Db9048AB350fA61Ef891ee20947c5Bbf8F",
+  "contracts": {
+    "AIBOMRegistry": "0x6B5BebC2f9172c6E17Df5ea59C1753D360866bDB",
+    "RiskManagementSystem": "0x9683C026434Ff9C0Ee036d655686Be5BD3F52331",
+    "HumanOversightRegistry": "0x291FE7352698CDBf6816A3F61CbF14b52D6a402b",
+    "IncidentRegistry": "0x6ad45a9B32e695e95492dC3796a5aC8543B2EA6F",
+    "ConformityAssessment": "0x976b03a2417cf7926813605F427ED499fdF61e10",
+    "DataGovernanceRegistry": "0xEb284d8aB1360082272FA9C860a0640B13af036E",
+    "QualityManagementSystem": "0xfCB684CDeC451Da0bA93B8F05215Ee49a9402210"
+  }
+}

package/dist/deployments/phase7-base.json

@@ -0,0 +1,15 @@
+{
+  "network": "base",
+  "chainId": "8453",
+  "deployedAt": "2026-05-18T19:22:22.838Z",
+  "deployer": "0x218514Db9048AB350fA61Ef891ee20947c5Bbf8F",
+  "contracts": {
+    "AIBOMRegistry": "0x6B5BebC2f9172c6E17Df5ea59C1753D360866bDB",
+    "RiskManagementSystem": "0x9683C026434Ff9C0Ee036d655686Be5BD3F52331",
+    "HumanOversightRegistry": "0x291FE7352698CDBf6816A3F61CbF14b52D6a402b",
+    "IncidentRegistry": "0x6ad45a9B32e695e95492dC3796a5aC8543B2EA6F",
+    "ConformityAssessment": "0x976b03a2417cf7926813605F427ED499fdF61e10",
+    "DataGovernanceRegistry": "0xEb284d8aB1360082272FA9C860a0640B13af036E",
+    "QualityManagementSystem": "0xfCB684CDeC451Da0bA93B8F05215Ee49a9402210"
+  }
+}

package/dist/deployments/phase7-mantle.json

@@ -0,0 +1,15 @@
+{
+  "network": "mantle",
+  "chainId": "5000",
+  "deployedAt": "2026-05-18T19:22:09.579Z",
+  "deployer": "0x218514Db9048AB350fA61Ef891ee20947c5Bbf8F",
+  "contracts": {
+    "AIBOMRegistry": "0x6B5BebC2f9172c6E17Df5ea59C1753D360866bDB",
+    "RiskManagementSystem": "0x9683C026434Ff9C0Ee036d655686Be5BD3F52331",
+    "HumanOversightRegistry": "0x291FE7352698CDBf6816A3F61CbF14b52D6a402b",
+    "IncidentRegistry": "0x6ad45a9B32e695e95492dC3796a5aC8543B2EA6F",
+    "ConformityAssessment": "0x976b03a2417cf7926813605F427ED499fdF61e10",
+    "DataGovernanceRegistry": "0xEb284d8aB1360082272FA9C860a0640B13af036E",
+    "QualityManagementSystem": "0xfCB684CDeC451Da0bA93B8F05215Ee49a9402210"
+  }
+}

package/dist/deployments/phase7-optimism.json

@@ -0,0 +1,15 @@
+{
+  "network": "optimism",
+  "chainId": "10",
+  "deployedAt": "2026-05-18T19:24:39.428Z",
+  "deployer": "0x218514Db9048AB350fA61Ef891ee20947c5Bbf8F",
+  "contracts": {
+    "AIBOMRegistry": "0x9683C026434Ff9C0Ee036d655686Be5BD3F52331",
+    "RiskManagementSystem": "0x291FE7352698CDBf6816A3F61CbF14b52D6a402b",
+    "HumanOversightRegistry": "0x6ad45a9B32e695e95492dC3796a5aC8543B2EA6F",
+    "IncidentRegistry": "0x976b03a2417cf7926813605F427ED499fdF61e10",
+    "ConformityAssessment": "0xEb284d8aB1360082272FA9C860a0640B13af036E",
+    "DataGovernanceRegistry": "0xfCB684CDeC451Da0bA93B8F05215Ee49a9402210",
+    "QualityManagementSystem": "0xCeE831070aa9081422f30df5559c125aa47A75DB"
+  }
+}

package/dist/deployments/phase7-polygon.json

@@ -0,0 +1,15 @@
+{
+  "network": "polygon",
+  "chainId": "137",
+  "deployedAt": "2026-05-18T19:24:57.683Z",
+  "deployer": "0x218514Db9048AB350fA61Ef891ee20947c5Bbf8F",
+  "contracts": {
+    "AIBOMRegistry": "0x6B5BebC2f9172c6E17Df5ea59C1753D360866bDB",
+    "RiskManagementSystem": "0x9683C026434Ff9C0Ee036d655686Be5BD3F52331",
+    "HumanOversightRegistry": "0x291FE7352698CDBf6816A3F61CbF14b52D6a402b",
+    "IncidentRegistry": "0x6ad45a9B32e695e95492dC3796a5aC8543B2EA6F",
+    "ConformityAssessment": "0x976b03a2417cf7926813605F427ED499fdF61e10",
+    "DataGovernanceRegistry": "0xEb284d8aB1360082272FA9C860a0640B13af036E",
+    "QualityManagementSystem": "0xfCB684CDeC451Da0bA93B8F05215Ee49a9402210"
+  }
+}

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

@@ -0,0 +1,175 @@
+/**
+ * RFC 8785 JSON Canonicalization Scheme.
+ * Strings and numbers use ECMAScript JSON.stringify serialization (as RFC 8785
+ * specifies); object keys are sorted by UTF-16 code units (Array#sort default).
+ */
+export declare function canonicalize(value: unknown): string;
+/** Lowercase hex SHA-256 of the UTF-8 bytes of `value`, no prefix */
+export declare function sha256Hex(value: string): string;
+export declare const EVIDENCE_SCHEMA = "agentaudit-evidence-v1";
+export interface ActionPreimage {
+    action_type: string;
+    agent_id: string;
+    scope: string;
+    timestamp_ms: number;
+}
+/** action_ref = SHA-256(JCS(preimage)), as 0x-prefixed bytes32 hex */
+export declare function computeActionRef(preimage: ActionPreimage): string;
+/** Percent-encode the characters that would break a scope segment */
+export declare function encodeScopeSegment(segment: string): string;
+/** §2.1 — tool_call:<tool>:result_hash:<sha256> */
+export declare function toolCallScope(tool: string, resultHash: string): string;
+/** §2.2 — data_read:<endpoint>:<dataset_version>:<result_hash> */
+export declare function dataReadScope(endpoint: string, datasetVersion: string, resultHash: string): string;
+/** §2.3 — llm_call:<model>:record_hash:<sha256(JCS(record))> */
+export declare function llmCallScope(model: string, record: object): string;
+/** Preimage for an LLM decision logged by the SDK wrappers */
+export declare function llmDecisionPreimage(agentId: number | string, model: string, record: object, timestampMs?: number): ActionPreimage;
+export declare function hashPair(a: string, b: string): string;
+/** All tree levels, leaves first, root level last */
+export declare function buildMerkleLevels(leaves: string[]): string[][];
+export declare function merkleRoot(leaves: string[]): string;
+/** Sibling path for leaf `index`; levels where the node was promoted are skipped */
+export declare function merkleProof(levels: string[][], index: number): string[];
+/** Off-chain mirror of AuditVault._verifyMerkle */
+export declare function verifyMerkleProof(leaf: string, proof: string[], root: string): boolean;
+export interface BatchEntry {
+    action_ref: string;
+    preimage: ActionPreimage;
+    /** Hashed audit record the scope commits to — never raw prompt/response content */
+    record?: object;
+}
+export interface BatchRecord {
+    schema: typeof EVIDENCE_SCHEMA;
+    batch_id: string;
+    agent_address: string;
+    merkle_root: string;
+    leaf_hash: "sha256(jcs(preimage))";
+    node_hash: "keccak256(sorted_pair)";
+    odd_node: "promote";
+    created_at_ms: number;
+    entries: BatchEntry[];
+}
+export interface BatchStore {
+    /** Persist the batch and return the contentURI to anchor on-chain */
+    put(record: BatchRecord): Promise<string>;
+    get(batchId: string): Promise<BatchRecord | null>;
+}
+export declare class MemoryBatchStore implements BatchStore {
+    private readonly records;
+    put(record: BatchRecord): Promise<string>;
+    get(batchId: string): Promise<BatchRecord | null>;
+}
+/** Writes one JSON file per batch: <dir>/<batch_id>.json */
+export declare class FileBatchStore implements BatchStore {
+    private readonly dir;
+    constructor(dir: string);
+    private file;
+    put(record: BatchRecord): Promise<string>;
+    get(batchId: string): Promise<BatchRecord | null>;
+}
+export interface CommitBatchParams {
+    agentAddress: string;
+    merkleRoot: string;
+    contentURI: string;
+    eventCount: number;
+    complianceScore: number;
+}
+export interface CommitBatchResult {
+    txHash: string;
+    /** Per-agent batch index from LogBatchCommitted; null if not found in receipt */
+    batchIndex: number | null;
+}
+/** Anything that can call AuditVault v2 commitBatch — AgentAudit implements it */
+export interface BatchCommitter {
+    commitBatch(params: CommitBatchParams): Promise<CommitBatchResult>;
+    /** Optional fail-fast check, called before a buffer is built for this committer */
+    assertBatchAnchoring?(): void;
+}
+export interface BatchBufferConfig {
+    committer: BatchCommitter;
+    /** Agent address the batch is committed under (AuditVault v2 keys agents by address) */
+    agentAddress: string;
+    store?: BatchStore;
+    /** Flush when this many entries are buffered (default 50) */
+    maxEntries?: number;
+    /** Flush this many seconds after the first buffered entry (default 60) */
+    maxAgeSeconds?: number;
+    /** uint8 0–100 passed to commitBatch (default 0 = not assessed by SDK) */
+    complianceScore?: number;
+    /** Receives errors from timer-triggered flushes (default console.error) */
+    onError?: (err: Error) => void;
+}
+export interface FlushResult {
+    batchId: string;
+    merkleRoot: string;
+    contentURI: string;
+    eventCount: number;
+    txHash: string;
+    batchIndex: number | null;
+}
+export interface InclusionProof {
+    leaf: string;
+    proof: string[];
+    root: string;
+    batchId: string;
+    /** Pass to AuditVault.verifyLog(agentAddress, batchIndex, leaf, proof) */
+    batchIndex: number | null;
+    agentAddress: string;
+    txHash: string;
+}
+/**
+ * Collects action_refs and anchors them as one Merkle root per batch.
+ * Flushes on maxEntries, on maxAgeSeconds after the first entry, or on flush().
+ * Flushes are serialized; a failed flush re-queues its entries for retry.
+ */
+export declare class BatchBuffer {
+    readonly agentAddress: string;
+    private readonly committer;
+    private readonly store;
+    private readonly maxEntries;
+    private readonly maxAgeMs;
+    private readonly complianceScore;
+    private readonly onError;
+    private pending;
+    private timer?;
+    private flushChain;
+    private readonly index;
+    private readonly batches;
+    constructor(config: BatchBufferConfig);
+    /** Number of entries waiting for the next flush */
+    get size(): number;
+    /**
+     * Buffer one action. Resolves once buffered — or, if this entry fills the
+     * batch, once that flush completes (so commit errors reach the caller).
+     */
+    add(preimage: ActionPreimage, record?: object): Promise<{
+        actionRef: string;
+    }>;
+    /** Anchor everything buffered now. Resolves null if there was nothing to flush. */
+    flush(): Promise<FlushResult | null>;
+    /** Stop the timer and flush whatever is left */
+    close(): Promise<FlushResult | null>;
+    /** Proof for a committed action_ref; null if unknown or still pending */
+    getInclusionProof(actionRef: string): InclusionProof | null;
+    private _flush;
+    private _armTimer;
+    private _clearTimer;
+}
+/** "batch" (default): buffer + commitBatch. "per_action": legacy one tx per call */
+export type AuditMode = "batch" | "per_action";
+export interface BatchOptions {
+    /** Share one buffer across several wrappers; other options are then ignored */
+    buffer?: BatchBuffer;
+    /** Defaults to the SDK signer's address */
+    agentAddress?: string;
+    store?: BatchStore;
+    maxEntries?: number;
+    maxAgeSeconds?: number;
+    complianceScore?: number;
+    onError?: (err: Error) => void;
+}
+/** Build (or reuse) the buffer a wrapper logs into */
+export declare function resolveBatchBuffer(sdk: BatchCommitter & {
+    getAddress(): string;
+}, options?: BatchOptions): BatchBuffer;