aipou-mcp-server 0.2.1 → 0.3.0

package/README.md

@@ -6,6 +6,25 @@ It does not detect hidden AI use, prove task quality, replace payment rails, or
 
 ## Fast Local Adoption Test
 
+From a source checkout, create and verify one disposable local receipt:
+
+```bash
+npm install
+npm run demo -w mcp-server
+```
+
+The command needs no wallet setup, funds, network, or claims. It prints a
+framework-ready `workReceiptId` object and deletes its ephemeral wallet,
+collector key, and receipt state before exiting.
+
+After the next npm release, the same check will run without cloning:
+
+```bash
+npx -y aipou-mcp-server --demo
+```
+
+For a complete framework lifecycle example, continue with the adapter below.
+
 If you are evaluating AIPOU for an agent framework, start with the lifecycle adapter example:
 
 ```bash

package/dist/canonical.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/canonical.test.js

@@ -0,0 +1,49 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { canonicalJson, sha256Hex } from "./canonical.js";
+test("canonicalJson serializes primitives correctly", () => {
+    assert.equal(canonicalJson(42), "42");
+    assert.equal(canonicalJson("hello"), "\"hello\"");
+    assert.equal(canonicalJson(true), "true");
+    assert.equal(canonicalJson(null), "null");
+});
+test("canonicalJson sorts object keys lexicographically", () => {
+    const unsorted = { b: 1, a: 2, c: 3 };
+    const sorted = { a: 2, b: 1, c: 3 };
+    assert.equal(canonicalJson(unsorted), canonicalJson(sorted));
+    assert.equal(canonicalJson(unsorted), "{\"a\":2,\"b\":1,\"c\":3}");
+});
+test("canonicalJson omits undefined values from objects", () => {
+    const obj = { a: 1, b: undefined, c: 3 };
+    assert.equal(canonicalJson(obj), "{\"a\":1,\"c\":3}");
+});
+test("canonicalJson handles nested objects with sorted keys", () => {
+    const obj = { outer: { z: 1, a: 2 } };
+    assert.equal(canonicalJson(obj), "{\"outer\":{\"a\":2,\"z\":1}}");
+});
+test("canonicalJson handles arrays preserving order", () => {
+    assert.equal(canonicalJson([3, 1, 2]), "[3,1,2]");
+    assert.equal(canonicalJson([{ b: 1, a: 2 }]), "[{\"a\":2,\"b\":1}]");
+});
+test("canonicalJson is deterministic for deeply nested mixed structures", () => {
+    const a = { z: [1, 2], y: { b: 2, a: 1 } };
+    const b = { y: { a: 1, b: 2 }, z: [1, 2] };
+    assert.equal(canonicalJson(a), canonicalJson(b));
+});
+test("sha256Hex produces a 0x-prefixed 64-char hex string", () => {
+    const hash = sha256Hex("test");
+    assert.match(hash, /^0x[0-9a-f]{64}$/);
+    assert.equal(hash, "0x9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08");
+});
+test("sha256Hex is deterministic for the same input", () => {
+    assert.equal(sha256Hex("hello"), sha256Hex("hello"));
+    assert.notEqual(sha256Hex("hello"), sha256Hex("world"));
+});
+test("canonicalJson handles empty objects and arrays", () => {
+    assert.equal(canonicalJson({}), "{}");
+    assert.equal(canonicalJson([]), "[]");
+});
+test("canonicalJson handles mixed undefined and null values", () => {
+    const obj = { a: null, b: undefined, c: 0, d: "" };
+    assert.equal(canonicalJson(obj), "{\"a\":null,\"c\":0,\"d\":\"\"}");
+});

package/dist/demo.d.ts

@@ -0,0 +1,30 @@
+export interface LocalDemoResult {
+    mode: "local_receipt_demo";
+    wallet: string;
+    storage: "removed_after_demo";
+    frameworkMetadata: {
+        aipou: {
+            type: "aipou.receipt";
+            workReceiptId: string;
+            receiptId: string;
+            factId: string;
+            evidenceClass: "issuer_asserted";
+            scheme: "aipou-receipt-v1";
+            status: "local_demo";
+            trustTier: "client_signed" | "provider_signed";
+        };
+    };
+    verification: {
+        walletAuthorization: boolean;
+        collectorSignature: boolean;
+    };
+    safety: {
+        networkRequired: false;
+        fundsMoved: false;
+        claimSubmitted: false;
+        rawPromptStored: false;
+        rawOutputStored: false;
+        privateKeyPrinted: false;
+    };
+}
+export declare function runLocalReceiptDemo(): Promise<LocalDemoResult>;

package/dist/demo.js

@@ -0,0 +1,97 @@
+import { createHash } from "node:crypto";
+import { mkdtemp, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { Wallet } from "ethers";
+import { canonicalJson, sha256Hex } from "./canonical.js";
+import { collectorFingerprint, verifyCollectorPayload } from "./collector.js";
+import { verifyTaskAuthorization } from "./identity.js";
+import { beginTask, completeTask } from "./receipts.js";
+const TOKEN_ADDRESS = "0x55f0Cc5e51A1284D20337d6cbb18938C8A1ABCbB";
+const CLAIMS_ADDRESS = "0x4ca4C98fB784D20EdC8E2A7F531dAab4c6e53058";
+const RECEIPT_SCHEME = "aipou-receipt-v1";
+const DEMO_ENVIRONMENT_KEYS = [
+    "AIPOU_AGENT_PRIVATE_KEY",
+    "AIPOU_CONTRACT_ADDRESS",
+    "AIPOU_CLAIMS_ADDRESS",
+    "AIPOU_DATA_DIR"
+];
+function deriveFactId(publicKey, nonce) {
+    const fingerprint = collectorFingerprint(publicKey);
+    const material = `${RECEIPT_SCHEME}\n${fingerprint}\n${nonce.toLowerCase()}`;
+    return `0x${createHash("sha256").update(material).digest("hex")}`;
+}
+export async function runLocalReceiptDemo() {
+    const previousEnvironment = new Map(DEMO_ENVIRONMENT_KEYS.map((key) => [key, process.env[key]]));
+    const dataDir = await mkdtemp(path.join(os.tmpdir(), "aipou-one-command-demo-"));
+    const wallet = Wallet.createRandom();
+    process.env.AIPOU_AGENT_PRIVATE_KEY = wallet.privateKey;
+    process.env.AIPOU_CONTRACT_ADDRESS = TOKEN_ADDRESS;
+    process.env.AIPOU_CLAIMS_ADDRESS = CLAIMS_ADDRESS;
+    process.env.AIPOU_DATA_DIR = dataDir;
+    try {
+        const taskHash = sha256Hex(canonicalJson({
+            kind: "demo.one-command-adoption",
+            intent: "create a private local AIPOU receipt without setup"
+        }));
+        const outputHash = sha256Hex(canonicalJson({
+            status: "ok",
+            artifact: "local receipt reference"
+        }));
+        const session = await beginTask({
+            provider: "local-demo",
+            model: "aipou-one-command-demo",
+            client: "aipou-cli",
+            taskHash,
+            chainId: 8453,
+            verifyingContract: CLAIMS_ADDRESS
+        });
+        const receipt = await completeTask({
+            nonce: session.nonce,
+            inputTokens: 18,
+            outputTokens: 12,
+            durationSeconds: 1,
+            outputHash
+        });
+        const { collectorSignature, ...signedPayload } = receipt;
+        return {
+            mode: "local_receipt_demo",
+            wallet: receipt.wallet,
+            storage: "removed_after_demo",
+            frameworkMetadata: {
+                aipou: {
+                    type: "aipou.receipt",
+                    workReceiptId: receipt.receiptId,
+                    receiptId: receipt.receiptId,
+                    factId: deriveFactId(receipt.collectorPublicKey, receipt.nonce),
+                    evidenceClass: "issuer_asserted",
+                    scheme: RECEIPT_SCHEME,
+                    status: "local_demo",
+                    trustTier: receipt.trustTier
+                }
+            },
+            verification: {
+                walletAuthorization: verifyTaskAuthorization(session),
+                collectorSignature: verifyCollectorPayload(signedPayload, collectorSignature, receipt.collectorPublicKey)
+            },
+            safety: {
+                networkRequired: false,
+                fundsMoved: false,
+                claimSubmitted: false,
+                rawPromptStored: false,
+                rawOutputStored: false,
+                privateKeyPrinted: false
+            }
+        };
+    }
+    finally {
+        await rm(dataDir, { recursive: true, force: true });
+        for (const key of DEMO_ENVIRONMENT_KEYS) {
+            const previous = previousEnvironment.get(key);
+            if (previous === undefined)
+                delete process.env[key];
+            else
+                process.env[key] = previous;
+        }
+    }
+}

package/dist/demo.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/demo.test.js

@@ -0,0 +1,27 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { runLocalReceiptDemo } from "./demo.js";
+test("one-command demo creates a verified receipt without persistent secrets or claims", async () => {
+    const previousPrivateKey = process.env.AIPOU_AGENT_PRIVATE_KEY;
+    const previousDataDir = process.env.AIPOU_DATA_DIR;
+    const result = await runLocalReceiptDemo();
+    assert.equal(result.mode, "local_receipt_demo");
+    assert.match(result.wallet, /^0x[0-9a-fA-F]{40}$/);
+    assert.match(result.frameworkMetadata.aipou.workReceiptId, /^0x[0-9a-f]{64}$/);
+    assert.equal(result.frameworkMetadata.aipou.workReceiptId, result.frameworkMetadata.aipou.receiptId);
+    assert.match(result.frameworkMetadata.aipou.factId, /^0x[0-9a-f]{64}$/);
+    assert.deepEqual(result.verification, {
+        walletAuthorization: true,
+        collectorSignature: true
+    });
+    assert.deepEqual(result.safety, {
+        networkRequired: false,
+        fundsMoved: false,
+        claimSubmitted: false,
+        rawPromptStored: false,
+        rawOutputStored: false,
+        privateKeyPrinted: false
+    });
+    assert.equal(process.env.AIPOU_AGENT_PRIVATE_KEY, previousPrivateKey);
+    assert.equal(process.env.AIPOU_DATA_DIR, previousDataDir);
+});

package/dist/index.js

@@ -6,6 +6,7 @@ import { z } from "zod";
 import { settleAllRewards, settleRewards } from "./claims.js";
 import { collectorFingerprint, getCollectorPublicKey } from "./collector.js";
 import { aipouClaimsAbi, aipouTokenAbi, getTokenContractConfig } from "./contract.js";
+import { runLocalReceiptDemo } from "./demo.js";
 import { agentWallet } from "./identity.js";
 import { beginTask, completeTask, exportReceipts } from "./receipts.js";
 import { estimateReward } from "./rewards.js";
@@ -16,7 +17,7 @@ const usageCounts = {
     outputTokens: z.number().int().min(0).max(10_000_000),
     durationSeconds: z.number().int().min(0).max(86_400)
 };
-const server = new McpServer({ name: "aipou-mcp", version: "0.2.1" }, {
+const server = new McpServer({ name: "aipou-mcp", version: "0.2.2" }, {
     instructions: "For meaningful AI tasks, call begin_ai_task before work and complete_ai_task after work using hashes, never raw prompts or outputs. " +
         "Use the dedicated farming identity only. Never reveal private keys or local collector state. " +
         "Call settle_all_ai_rewards after a broad user request such as 'claim my AIPOU' or 'settle all pending AIPOU'. " +
@@ -93,5 +94,22 @@ server.tool("settle_all_ai_rewards", "After an explicit broad claim request, set
     const result = await settleAllRewards(batchSize, maxBatches);
     return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
 });
-const transport = new StdioServerTransport();
-await server.connect(transport);
+const cliArguments = new Set(process.argv.slice(2));
+if (cliArguments.has("--demo")) {
+    console.log(JSON.stringify(await runLocalReceiptDemo(), null, 2));
+}
+else if (cliArguments.has("--help") || cliArguments.has("-h")) {
+    console.log(`AIPOU MCP Server
+
+Usage:
+  aipou-mcp                 Start the MCP stdio server
+  aipou-mcp --demo          Create and verify one disposable local receipt
+  aipou-mcp --help          Show this help
+
+The demo needs no wallet, funds, network, or configuration. Its temporary
+wallet, collector key, and receipt state are removed before the command exits.`);
+}
+else {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}

package/dist/protocol.test.js

@@ -53,6 +53,8 @@ test("creates verifiable receipts and rejects nonce/evidence replay", async () =
         chainId: 8453,
         verifyingContract
     });
+    assert.match(repeatedSession.nonce, /^0x[0-9a-f]{64}$/);
+    assert.notEqual(repeatedSession.nonce, session.nonce);
     await assert.rejects(completeTask({
         nonce: repeatedSession.nonce,
         inputTokens: 1200,

package/dist/rewards.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/rewards.test.js

@@ -0,0 +1,132 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { estimateReward } from "./rewards.js";
+test("client_signed tier applies 0.75 multiplier", () => {
+    const reward = estimateReward({
+        inputTokens: 1000,
+        outputTokens: 500,
+        durationSeconds: 300,
+        trustTier: "client_signed"
+    });
+    const tokenScore = Math.min(1500 / 1000, 30);
+    const durationScore = Math.min(300 / 300, 12);
+    const expected = (tokenScore + durationScore) * 0.75;
+    assert.equal(reward, expected.toFixed(4));
+});
+test("provider_signed tier applies 1.5 multiplier", () => {
+    const reward = estimateReward({
+        inputTokens: 1000,
+        outputTokens: 500,
+        durationSeconds: 300,
+        trustTier: "provider_signed"
+    });
+    const tokenScore = Math.min(1500 / 1000, 30);
+    const durationScore = Math.min(300 / 300, 12);
+    const expected = (tokenScore + durationScore) * 1.5;
+    assert.equal(reward, expected.toFixed(4));
+});
+test("provider_signed yields higher reward than client_signed for same input", () => {
+    const clientReward = Number(estimateReward({
+        inputTokens: 2000,
+        outputTokens: 800,
+        durationSeconds: 600,
+        trustTier: "client_signed"
+    }));
+    const providerReward = Number(estimateReward({
+        inputTokens: 2000,
+        outputTokens: 800,
+        durationSeconds: 600,
+        trustTier: "provider_signed"
+    }));
+    assert.ok(providerReward > clientReward);
+});
+test("token score is capped at 30", () => {
+    const lowTokens = estimateReward({
+        inputTokens: 500,
+        outputTokens: 500,
+        durationSeconds: 0,
+        trustTier: "client_signed"
+    });
+    const cappedTokens = estimateReward({
+        inputTokens: 100000,
+        outputTokens: 100000,
+        durationSeconds: 0,
+        trustTier: "client_signed"
+    });
+    assert.equal(Number(cappedTokens), 30 * 0.75);
+    assert.ok(Number(cappedTokens) > Number(lowTokens));
+});
+test("duration score is capped at 12", () => {
+    const lowDuration = estimateReward({
+        inputTokens: 0,
+        outputTokens: 0,
+        durationSeconds: 60,
+        trustTier: "client_signed"
+    });
+    const cappedDuration = estimateReward({
+        inputTokens: 0,
+        outputTokens: 0,
+        durationSeconds: 99999,
+        trustTier: "client_signed"
+    });
+    assert.equal(Number(cappedDuration), 12 * 0.75);
+    assert.ok(Number(cappedDuration) > Number(lowDuration));
+});
+test("total reward is capped at 50", () => {
+    const maxReward = estimateReward({
+        inputTokens: 1000000,
+        outputTokens: 1000000,
+        durationSeconds: 100000,
+        trustTier: "provider_signed"
+    });
+    assert.equal(Number(maxReward), 50);
+});
+test("zero input yields zero reward", () => {
+    const reward = estimateReward({
+        inputTokens: 0,
+        outputTokens: 0,
+        durationSeconds: 0,
+        trustTier: "client_signed"
+    });
+    assert.equal(reward, "0.0000");
+});
+test("negative token counts are treated as zero", () => {
+    const reward = estimateReward({
+        inputTokens: -500,
+        outputTokens: -200,
+        durationSeconds: 300,
+        trustTier: "client_signed"
+    });
+    const durationScore = Math.min(300 / 300, 12);
+    const expected = durationScore * 0.75;
+    assert.equal(reward, expected.toFixed(4));
+});
+test("negative duration is treated as zero", () => {
+    const reward = estimateReward({
+        inputTokens: 1000,
+        outputTokens: 0,
+        durationSeconds: -100,
+        trustTier: "client_signed"
+    });
+    const tokenScore = Math.min(1000 / 1000, 30);
+    const expected = tokenScore * 0.75;
+    assert.equal(reward, expected.toFixed(4));
+});
+test("reward is always a fixed 4-decimal string", () => {
+    const reward = estimateReward({
+        inputTokens: 100,
+        outputTokens: 100,
+        durationSeconds: 30,
+        trustTier: "client_signed"
+    });
+    assert.match(reward, /^\d+\.\d{4}$/);
+});
+test("high token count with low duration hits token cap but not total cap", () => {
+    const reward = estimateReward({
+        inputTokens: 50000,
+        outputTokens: 50000,
+        durationSeconds: 0,
+        trustTier: "client_signed"
+    });
+    assert.equal(Number(reward), 30 * 0.75);
+});

package/package.json

@@ -1,8 +1,9 @@
-{
+{
   "name": "aipou-mcp-server",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "mcpName": "io.github.0xddneto/ai-proof-of-us",
   "description": "MCP server for private, signed AI task receipts and optional validated AIPOU claims.",
+  "author": "0xddneto",
   "keywords": [
     "mcp",
     "model-context-protocol",
@@ -18,7 +19,7 @@
     "url": "git+https://github.com/0xddneto/AI-Proof-of-Us.git",
     "directory": "mcp-server"
   },
-  "homepage": "https://github.com/0xddneto/AI-Proof-of-Us#readme",
+  "homepage": "https://0xddneto.github.io/AI-Proof-of-Us/",
   "bugs": {
     "url": "https://github.com/0xddneto/AI-Proof-of-Us/issues"
   },
@@ -33,10 +34,11 @@
   "bin": {
     "aipou-mcp": "dist/index.js"
   },
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "test": "npm run build && node --test dist/protocol.test.js",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test dist/protocol.test.js dist/rewards.test.js dist/canonical.test.js dist/demo.test.js",
     "pack:check": "npm test && npm pack --dry-run",
+    "demo": "npm run build && node dist/index.js --demo",
     "dev": "tsx src/index.ts",
     "start": "node dist/index.js",
     "prepublishOnly": "npm test"
@@ -47,16 +49,16 @@
   "engines": {
     "node": ">=20"
   },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.13.0",
-    "dotenv": "^16.6.1",
-    "ethers": "^6.17.0",
-    "merkletreejs": "^0.6.0",
-    "zod": "^3.23.8"
-  },
-  "devDependencies": {
-    "@types/node": "^22.5.4",
-    "tsx": "^4.19.0",
-    "typescript": "^5.5.4"
-  }
-}
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.13.0",
+    "dotenv": "^16.6.1",
+    "ethers": "^6.17.0",
+    "merkletreejs": "^0.6.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.5.4",
+    "tsx": "^4.19.0",
+    "typescript": "^5.5.4"
+  }
+}

package/server.json

@@ -3,18 +3,18 @@
   "name": "io.github.0xddneto/ai-proof-of-us",
   "title": "AI Proof of Us",
   "description": "Private signed AI task receipts with replay checks and optional validated AIPOU claims.",
-  "websiteUrl": "https://github.com/0xddneto/AI-Proof-of-Us",
+  "websiteUrl": "https://0xddneto.github.io/AI-Proof-of-Us/",
   "repository": {
     "url": "https://github.com/0xddneto/AI-Proof-of-Us",
     "source": "github",
     "subfolder": "mcp-server"
   },
-  "version": "0.2.1",
+  "version": "0.3.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "aipou-mcp-server",
-      "version": "0.2.1",
+      "version": "0.3.0",
       "transport": {
         "type": "stdio"
       },