aipou-mcp-server 0.2.0 → 0.2.2

package/README.md

@@ -1,6 +1,6 @@
 # AIPOU MCP Server
 
-`aipou-mcp-server` records private, signed receipts for authorized AI tasks. It supports local receipt collection and optional claims for validated work on Base.
+`aipou-mcp-server` records private, signed receipts for authorized AI tasks. It supports local receipt collection, reward status checks, and optional claims for validated work on Base.
 
 It does not detect hidden AI use, prove task quality, replace payment rails, or require raw prompts and outputs to leave the user's machine.
 
@@ -18,9 +18,17 @@ npm run demo
 
 The demo launches this MCP server over stdio, creates a local signed receipt with an ephemeral wallet, and prints the `receiptId` reference a framework can attach to metadata. It does not claim rewards or move funds.
 
+## Run From npm
+
+MCP clients can launch the published package with:
+
+```bash
+npx -y aipou-mcp-server
+```
+
 ## Run locally from this repository
 
-The npm package metadata is prepared, but the first public npm publish must be performed by the repository owner. Until `aipou-mcp-server` is published, run the MCP server from a local checkout:
+For local development or source review, run the MCP server from a checkout:
 
 ```bash
 npm install
@@ -34,14 +42,6 @@ For development:
 npm run dev -w mcp-server
 ```
 
-## Run after npm publication
-
-After the package is published to npm, MCP clients can launch it with:
-
-```bash
-npx -y aipou-mcp-server
-```
-
 Required configuration:
 
 ```text
@@ -50,13 +50,13 @@ AIPOU_CONTRACT_ADDRESS=0x55f0Cc5e51A1284D20337d6cbb18938C8A1ABCbB
 AIPOU_CLAIMS_ADDRESS=0x4ca4C98fB784D20EdC8E2A7F531dAab4c6e53058
 ```
 
-Use a new dedicated farming wallet, never a primary wallet. Do not commit the private key. Optional claims and settlement occur only after an explicit user request.
+Use a new dedicated farming wallet, never a primary wallet. Do not commit the private key. Status checks can show already claimed and pending AIPOU without moving funds. Optional claims and settlement occur only after an explicit user request.
 
 Do not configure `AIPOU_VALIDATOR_PRIVATE_KEY` on a user installation. That key is only for the separate protocol validator service. The local Ed25519 collector key and receipt metadata are stored unencrypted under `AIPOU_DATA_DIR`; restrict that directory with operating-system permissions and use encrypted backups.
 
 The default network is Base mainnet. `AIPOU_RPC_URL` and `AIPOU_DATA_DIR` can be set when a custom RPC endpoint or receipt directory is needed.
 
-Publication checklist: [docs/npm-publication.md](https://github.com/0xddneto/AI-Proof-of-Us/blob/main/docs/npm-publication.md).
+Publication details: [docs/npm-publication.md](https://github.com/0xddneto/AI-Proof-of-Us/blob/main/docs/npm-publication.md).
 
 ## Documentation
 

package/dist/claims.d.ts

@@ -1,2 +1,3 @@
-import type { SettlementResult } from "./types.js";
+import type { SettlementAllResult, SettlementResult } from "./types.js";
 export declare function settleRewards(maxReceipts?: number): Promise<SettlementResult>;
+export declare function settleAllRewards(batchSize?: number, maxBatches?: number): Promise<SettlementAllResult>;

package/dist/claims.js

@@ -86,16 +86,17 @@ async function verifyReceipt(receipt, trustedCollectors) {
         throw new Error(`Invalid trust tier for ${receipt.receiptId}`);
 }
 export async function settleRewards(maxReceipts = 25) {
-    const candidates = await unsettledReceipts(maxReceipts);
+    const candidates = await unsettledReceipts(Number.MAX_SAFE_INTEGER);
     if (candidates.length === 0)
         throw new Error("There are no unsettled receipts");
     const policy = settlementPolicyFromEnv();
     const recentlySettled = await settledReceiptsSince(Date.now() - DAY_MS);
-    const { eligible: receipts, skipped } = filterEligibleReceipts(candidates, recentlySettled, policy);
-    if (receipts.length === 0) {
+    const { eligible, skipped } = filterEligibleReceipts(candidates, recentlySettled, policy);
+    if (eligible.length === 0) {
         const reasons = skipped.map((item) => `${item.receiptId.slice(0, 10)}…: ${item.reason}`).join("; ");
         throw new Error(`No receipts pass the settlement policy. Skipped: ${reasons}`);
     }
+    const receipts = eligible.slice(0, maxReceipts);
     const trustedCollectors = await trustedCollectorFingerprints();
     for (const receipt of receipts)
         await verifyReceipt(receipt, trustedCollectors);
@@ -148,3 +149,40 @@ export async function settleRewards(maxReceipts = 25) {
     await markBatchSettled(batch);
     return { ...batch, skippedReceipts: skipped };
 }
+export async function settleAllRewards(batchSize = 100, maxBatches = 20) {
+    const batches = [];
+    const skippedByReceiptId = new Map();
+    let stoppedReason;
+    for (let index = 0; index < maxBatches; index += 1) {
+        try {
+            const batch = await settleRewards(batchSize);
+            batches.push(batch);
+            for (const skipped of batch.skippedReceipts) {
+                skippedByReceiptId.set(skipped.receiptId, skipped);
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (message === "There are no unsettled receipts")
+                break;
+            stoppedReason = message;
+            break;
+        }
+    }
+    if (!stoppedReason && batches.length === maxBatches) {
+        stoppedReason = `Stopped after maxBatches=${maxBatches}; run settle_all_ai_rewards again for any remaining receipts`;
+    }
+    const pendingReceiptCount = (await unsettledReceipts(Number.MAX_SAFE_INTEGER)).length;
+    const skippedReceipts = [...skippedByReceiptId.values()];
+    return {
+        batches,
+        batchCount: batches.length,
+        settledReceiptCount: batches.reduce((total, batch) => total + batch.receiptIds.length, 0),
+        skippedReceipts,
+        pendingReceiptCount,
+        publishTransactions: batches.map((batch) => batch.publishTransaction),
+        claimTransactions: batches.map((batch) => batch.claimTransaction),
+        stoppedReason,
+        settledAt: new Date().toISOString()
+    };
+}

package/dist/contract.d.ts

@@ -2,6 +2,7 @@ export interface TokenContractConfig {
     name: string;
     symbol: string;
     address: string | null;
+    logoURI: string | null;
     decimals: number;
     chainId: number;
     chainName: string;

package/dist/contract.js

@@ -1,5 +1,6 @@
 import { readFile } from "node:fs/promises";
 import path from "node:path";
+const DEFAULT_LOGO_URI = "https://raw.githubusercontent.com/0xddneto/AI-Proof-of-Us/main/assets/token/aipou.png";
 export const aipouTokenAbi = [
     "function name() view returns (string)",
     "function symbol() view returns (string)",
@@ -39,6 +40,7 @@ function envConfig() {
         name: "AI Proof of Use",
         symbol: "AIPOU",
         address,
+        logoURI: process.env.AIPOU_LOGO_URI || DEFAULT_LOGO_URI,
         decimals: 18,
         chainId: Number(process.env.AIPOU_CHAIN_ID || 8453),
         chainName: process.env.AIPOU_CHAIN_NAME || "Base Mainnet",
@@ -61,6 +63,7 @@ async function deploymentFileConfig() {
             name: deployment.token?.name || "AI Proof of Use",
             symbol: deployment.token?.symbol || "AIPOU",
             address,
+            logoURI: deployment.token?.logoURI || process.env.AIPOU_LOGO_URI || DEFAULT_LOGO_URI,
             decimals: deployment.token?.decimals || 18,
             chainId: deployment.chain?.id || 8453,
             chainName: deployment.chain?.name || "Base Mainnet",
@@ -89,6 +92,7 @@ export async function getTokenContractConfig() {
             name: "AI Proof of Use",
             symbol: "AIPOU",
             address: null,
+            logoURI: process.env.AIPOU_LOGO_URI || DEFAULT_LOGO_URI,
             decimals: 18,
             chainId: 8453,
             chainName: "Base Mainnet",

package/dist/index.js

@@ -3,22 +3,24 @@ import "dotenv/config";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { settleRewards } from "./claims.js";
+import { settleAllRewards, settleRewards } from "./claims.js";
 import { collectorFingerprint, getCollectorPublicKey } from "./collector.js";
 import { aipouClaimsAbi, aipouTokenAbi, getTokenContractConfig } from "./contract.js";
 import { agentWallet } from "./identity.js";
 import { beginTask, completeTask, exportReceipts } from "./receipts.js";
 import { estimateReward } from "./rewards.js";
+import { getAipouStatus } from "./status.js";
 const bytes32 = z.string().regex(/^0x[a-fA-F0-9]{64}$/);
 const usageCounts = {
     inputTokens: z.number().int().min(0).max(10_000_000),
     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.0" }, {
+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_ai_rewards only after the user explicitly asks to claim or settle their AIPOU; it submits two on-chain transactions. " +
+        "Call settle_all_ai_rewards after a broad user request such as 'claim my AIPOU' or 'settle all pending AIPOU'. " +
+        "Call settle_ai_rewards only when the user asks for a single limited batch. Settlement submits on-chain transactions. " +
         "The host client and its user always keep the final say on transaction confirmation policy."
 });
 server.tool("get_aipou_contract", "Return the configured AIPOU token contract address, Base network details, explorer URL, and minimal ABI.", {}, async () => {
@@ -37,6 +39,10 @@ server.tool("get_aipou_identity", "Return the dedicated farming wallet address a
             }]
     };
 });
+server.tool("get_aipou_status", "Show recorded, pending, and already claimed AIPOU receipts plus the farming wallet's on-chain AIPOU balance. Does not reveal private keys or full receipt payloads.", {}, async () => {
+    const status = await getAipouStatus();
+    return { content: [{ type: "text", text: JSON.stringify(status, null, 2) }] };
+});
 server.tool("estimate_ai_reward", "Estimate the client-signed AIPOU reward before a task is completed. The final tier is derived by the validator.", usageCounts, async (input) => ({
     content: [{
             type: "text",
@@ -76,9 +82,16 @@ server.tool("export_ai_receipts", "Export stored signed AI task receipts, option
     const receipts = await exportReceipts(wallet);
     return { content: [{ type: "text", text: JSON.stringify({ count: receipts.length, receipts }, null, 2) }] };
 });
-server.tool("settle_ai_rewards", "After an explicit user claim request, validate eligible receipts against the settlement policy, publish a Merkle root, and mint the included rewards. Submits two on-chain transactions; the host's own confirmation policy applies.", { maxReceipts: z.number().int().min(1).max(100).default(25) }, async ({ maxReceipts }) => {
+server.tool("settle_ai_rewards", "After an explicit user claim request for one limited batch, validate eligible receipts against the settlement policy, publish a Merkle root, and mint the included rewards. Submits two on-chain transactions; the host's own confirmation policy applies.", { maxReceipts: z.number().int().min(1).max(100).default(25) }, async ({ maxReceipts }) => {
     const batch = await settleRewards(maxReceipts);
     return { content: [{ type: "text", text: JSON.stringify(batch, null, 2) }] };
 });
+server.tool("settle_all_ai_rewards", "After an explicit broad claim request, settle all currently pending eligible receipts from the shared AIPOU data directory by submitting as many bounded batches as needed. Each batch publishes one Merkle root and submits one claim transaction.", {
+    batchSize: z.number().int().min(1).max(100).default(100),
+    maxBatches: z.number().int().min(1).max(50).default(20)
+}, async ({ batchSize, maxBatches }) => {
+    const result = await settleAllRewards(batchSize, maxBatches);
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+});
 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/status.d.ts

@@ -0,0 +1 @@
+export declare function getAipouStatus(): Promise<Record<string, unknown>>;

package/dist/status.js

@@ -0,0 +1,73 @@
+import { Contract, JsonRpcProvider, formatUnits } from "ethers";
+import { aipouTokenAbi, getTokenContractConfig } from "./contract.js";
+import { agentWallet } from "./identity.js";
+import { exportStoredReceipts, protocolStateCounts, unsettledReceipts } from "./store.js";
+function sumRewards(receipts) {
+    const total = receipts.reduce((sum, receipt) => sum + Number(receipt.estimatedReward), 0);
+    return Number.isInteger(total) ? total.toFixed(0) : total.toFixed(6).replace(/0+$/, "").replace(/\.$/, "");
+}
+export async function getAipouStatus() {
+    const wallet = agentWallet().address;
+    const contract = await getTokenContractConfig();
+    const receipts = await exportStoredReceipts(wallet);
+    const pendingReceipts = await unsettledReceipts(Number.MAX_SAFE_INTEGER);
+    const walletPendingReceipts = pendingReceipts.filter((receipt) => receipt.wallet.toLowerCase() === wallet.toLowerCase());
+    const claimedReceipts = receipts.filter((receipt) => receipt.claimTransaction);
+    const counts = await protocolStateCounts();
+    let onchain = { available: false };
+    if (contract.address) {
+        try {
+            const provider = new JsonRpcProvider(contract.rpcUrl);
+            const token = new Contract(contract.address, aipouTokenAbi, provider);
+            const [decimals, balance, totalSupply] = await Promise.all([
+                token.decimals(),
+                token.balanceOf(wallet),
+                token.totalSupply()
+            ]);
+            onchain = {
+                available: true,
+                wallet,
+                balance: formatUnits(balance, decimals),
+                totalSupply: formatUnits(totalSupply, decimals),
+                explorerUrl: `${contract.blockExplorer}/token/${contract.address}?a=${wallet}`
+            };
+        }
+        catch (error) {
+            onchain = {
+                available: false,
+                error: error instanceof Error ? error.message : String(error)
+            };
+        }
+    }
+    const lastClaim = claimedReceipts
+        .filter((receipt) => receipt.claimTransaction)
+        .sort((a, b) => Date.parse(b.recordedAt) - Date.parse(a.recordedAt))[0];
+    return {
+        wallet,
+        chainId: contract.chainId,
+        tokenAddress: contract.address,
+        claimsAddress: contract.claimsAddress,
+        receipts: {
+            recorded: receipts.length,
+            claimed: claimedReceipts.length,
+            pending: walletPendingReceipts.length,
+            incompleteSessions: counts.incompleteSessions,
+            batches: counts.batches
+        },
+        rewards: {
+            claimedEstimated: sumRewards(claimedReceipts),
+            pendingEstimated: sumRewards(walletPendingReceipts),
+            totalEstimated: sumRewards(receipts),
+            unit: "AIPOU"
+        },
+        latestClaim: lastClaim
+            ? {
+                receiptId: lastClaim.receiptId,
+                transaction: lastClaim.claimTransaction,
+                explorerUrl: `${contract.blockExplorer}/tx/${lastClaim.claimTransaction}`,
+                recordedAt: lastClaim.recordedAt
+            }
+            : null,
+        onchain
+    };
+}

package/dist/store.d.ts

@@ -4,5 +4,11 @@ export declare function getSession(nonce: string): Promise<TaskSession | null>;
 export declare function saveCompletedReceipt(evidenceKey: string, receipt: UsageReceipt): Promise<void>;
 export declare function exportStoredReceipts(wallet?: string): Promise<UsageReceipt[]>;
 export declare function unsettledReceipts(limit: number): Promise<UsageReceipt[]>;
+export declare function protocolStateCounts(): Promise<{
+    sessions: number;
+    completedSessions: number;
+    incompleteSessions: number;
+    batches: number;
+}>;
 export declare function settledReceiptsSince(sinceMs: number): Promise<UsageReceipt[]>;
 export declare function markBatchSettled(batch: ClaimBatch): Promise<void>;

package/dist/store.js

@@ -103,6 +103,16 @@ export async function exportStoredReceipts(wallet) {
 export async function unsettledReceipts(limit) {
     return (await readState()).receipts.filter((receipt) => !receipt.claimTransaction).slice(0, limit);
 }
+export async function protocolStateCounts() {
+    const state = await readState();
+    const sessions = Object.values(state.sessions);
+    return {
+        sessions: sessions.length,
+        completedSessions: sessions.filter((session) => session.completedAt).length,
+        incompleteSessions: sessions.filter((session) => !session.completedAt).length,
+        batches: state.batches.length
+    };
+}
 export async function settledReceiptsSince(sinceMs) {
     const receipts = [...(await readArchivedReceipts()), ...(await readState()).receipts];
     return receipts.filter((receipt) => receipt.claimTransaction && Date.parse(receipt.recordedAt) >= sinceMs);

package/dist/types.d.ts

@@ -64,6 +64,17 @@ export interface SkippedReceipt {
 export interface SettlementResult extends ClaimBatch {
     skippedReceipts: SkippedReceipt[];
 }
+export interface SettlementAllResult {
+    batches: SettlementResult[];
+    batchCount: number;
+    settledReceiptCount: number;
+    skippedReceipts: SkippedReceipt[];
+    pendingReceiptCount: number;
+    publishTransactions: string[];
+    claimTransactions: string[];
+    stoppedReason?: string;
+    settledAt: string;
+}
 export interface ProtocolState {
     sessions: Record<string, TaskSession>;
     receipts: UsageReceipt[];

package/package.json

@@ -1,6 +1,6 @@
-{
+{
   "name": "aipou-mcp-server",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "mcpName": "io.github.0xddneto/ai-proof-of-us",
   "description": "MCP server for private, signed AI task receipts and optional validated AIPOU claims.",
   "keywords": [
@@ -18,7 +18,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,8 +33,8 @@
   "bin": {
     "aipou-mcp": "dist/index.js"
   },
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
     "test": "npm run build && node --test dist/protocol.test.js",
     "pack:check": "npm test && npm pack --dry-run",
     "dev": "tsx src/index.ts",
@@ -47,16 +47,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.0",
+  "version": "0.2.2",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "aipou-mcp-server",
-      "version": "0.2.0",
+      "version": "0.2.2",
       "transport": {
         "type": "stdio"
       },