pluribus-context 0.3.37 → 0.3.38

package/CHANGELOG.md

@@ -4,6 +4,10 @@
 
 All notable changes to Pluribus are documented here.
 
+## 0.3.38 - 2026-06-06
+
+- Added `pluribus demo mcp-audit-receipt`, a tiny npm-runnable demo that validates privacy-safe MCP tool-call audit events and low-cardinality usage metrics without logging raw prompts, args, results, tokens, or row data.
+
 ## 0.3.37 - 2026-06-06
 
 - Published the canonical top-level Agent Skills layout (`skills/*/SKILL.md`) and backwards-compatible legacy mirrors so external skill registries can keep source links verifiable while package users get the current recipes from npm.

package/bin/pluribus.js

@@ -67,7 +67,7 @@ OPTIONS (watch)
   --debounce      Debounce delay in ms (minimum 300, default 400)
 
 OPTIONS (demo)
-  --receipt       Validate a custom skill use-rate receipt JSON file
+  --receipt       Validate a custom demo receipt JSON file
   --json          Print machine-readable demo results
 
 EXAMPLES
@@ -89,6 +89,8 @@ EXAMPLES
   pluribus watch --tools claude,cursor
   pluribus demo skill-use-rate
   pluribus demo skill-use-rate --json
+  pluribus demo mcp-audit-receipt
+  pluribus demo mcp-audit-receipt --json
 
 DOCS
   https://github.com/caioribeiroclw-pixel/pluribus

package/examples/mcp-audit-receipts/README.md

@@ -0,0 +1,24 @@
+# MCP audit receipt demo
+
+This example validates a privacy-safe audit receipt for MCP `tools/call` activity.
+
+Run from any directory after `pluribus-context@latest` is published:
+
+```bash
+npx --yes pluribus-context@latest demo mcp-audit-receipt
+npx --yes pluribus-context@latest demo mcp-audit-receipt --json
+```
+
+Or validate your own receipt shape:
+
+```bash
+npx --yes pluribus-context@latest demo mcp-audit-receipt --receipt ./mcp-audit-receipt.json
+```
+
+The point is to split:
+
+- **audit events**: correlation IDs, hashed user/token subject, token scopes, tool name, redacted argument shape, status, duration, result shape, and error class;
+- **usage metrics**: low-cardinality counters/histograms such as tool name, status, and token scope;
+- **privacy boundary**: no raw prompts, raw SQL, row data, tokens, tool outputs, or private connection strings in the receipt.
+
+This is for MCP server/gateway operators who need to answer: “who invoked which tool, under what scope, and did it succeed?” without dumping sensitive content into logs.

package/examples/mcp-audit-receipts/mcp-audit-receipt.json

@@ -0,0 +1,70 @@
+{
+  "schema": "pluribus.mcp_tool_call_audit_receipt.v1",
+  "run_id": "mcp-audit-2026-06-06T22:00Z",
+  "generated_at": "2026-06-06T22:00:00Z",
+  "server": {
+    "name": "analytics-mcp",
+    "transport": "http",
+    "version": "1.4.0"
+  },
+  "client": {
+    "name": "claude-desktop",
+    "workspace": "hashed:7f3f0f5f"
+  },
+  "audit_policy": {
+    "raw_arguments": "redacted_shape_only",
+    "raw_results": "redacted_shape_only",
+    "privacy_boundary": "no prompts, raw SQL, row data, tokens, or private connection strings in receipt"
+  },
+  "tool_calls": [
+    {
+      "event": "mcp.tool_call",
+      "request_id": "req_01JY6GATEWAY",
+      "session_id": "sess_01JY6RUN",
+      "user_id_hash": "sha256:0d9b4a1a3f0a6f2fd0dc8aa9d0c6f2b7a35f4f5d0b2a4d3e1e04a8b4b6b2e5d8",
+      "token_subject_hash": "sha256:6aaf4a3b4d10c45c8fd2cb4f3c73b8cde42bb62779b7e1c6a2c5e0dd8d78f4a1",
+      "token_scopes": ["database:read", "query:run"],
+      "tool_name": "query_database",
+      "args_shape": {
+        "database_id": "number",
+        "query": "redacted_sql",
+        "limit": "number"
+      },
+      "status": "ok",
+      "duration_ms": 184,
+      "result_shape": "rows:12 columns:4",
+      "error_class": null
+    },
+    {
+      "event": "mcp.tool_call",
+      "request_id": "req_01JY6DENIED",
+      "session_id": "sess_01JY6RUN",
+      "user_id_hash": "sha256:0d9b4a1a3f0a6f2fd0dc8aa9d0c6f2b7a35f4f5d0b2a4d3e1e04a8b4b6b2e5d8",
+      "token_subject_hash": "sha256:6aaf4a3b4d10c45c8fd2cb4f3c73b8cde42bb62779b7e1c6a2c5e0dd8d78f4a1",
+      "token_scopes": ["database:read"],
+      "tool_name": "update_dashboard",
+      "args_shape": {
+        "dashboard_id": "number",
+        "mutation": "redacted_object"
+      },
+      "status": "denied",
+      "duration_ms": 12,
+      "result_shape": "policy_denial",
+      "error_class": "insufficient_scope"
+    }
+  ],
+  "usage_metrics": [
+    {
+      "name": "mcp_tool_calls_total",
+      "type": "counter",
+      "value": "1",
+      "labels": ["tool_name", "status", "token_scope"]
+    },
+    {
+      "name": "mcp_tool_call_duration_ms",
+      "type": "histogram",
+      "value": "184",
+      "labels": ["tool_name", "status"]
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pluribus-context",
-  "version": "0.3.37",
+  "version": "0.3.38",
   "description": "AI context and rules sync CLI for Claude.md, Claude Code, Cursor, and Copilot instructions, with privacy-safe context receipts that prove what memory, tools, skills, compactions, and security findings crossed agent boundaries without logging raw content.",
   "type": "module",
   "homepage": "https://github.com/caioribeiroclw-pixel/pluribus#readme",

package/src/commands/demo.js

@@ -7,7 +7,11 @@ import * as path from 'path'
 import { fileURLToPath } from 'url'
 
 const DEFAULT_DEMO = 'skill-use-rate'
+const SKILL_USE_RATE_DEMO = 'skill-use-rate'
+const MCP_AUDIT_RECEIPT_DEMO = 'mcp-audit-receipt'
+const AVAILABLE_DEMOS = [SKILL_USE_RATE_DEMO, MCP_AUDIT_RECEIPT_DEMO]
 const SKILL_USE_RATE_SCHEMA = 'pluribus.skill_use_rate_receipt.v1'
+const MCP_AUDIT_RECEIPT_SCHEMA = 'pluribus.mcp_tool_call_audit_receipt.v1'
 
 /**
  * @param {Record<string, string | boolean>} args
@@ -16,29 +20,42 @@ const SKILL_USE_RATE_SCHEMA = 'pluribus.skill_use_rate_receipt.v1'
 export async function runDemo(args, positional = []) {
   const demoName = positional[0] || DEFAULT_DEMO
 
-  if (demoName !== DEFAULT_DEMO) {
-    console.error(`❌ Unknown demo: ${demoName}`)
-    console.error('   Available demos: skill-use-rate')
-    process.exit(1)
+  switch (demoName) {
+    case SKILL_USE_RATE_DEMO:
+      return runSkillUseRateDemo(args)
+    case MCP_AUDIT_RECEIPT_DEMO:
+      return runMcpAuditReceiptDemo(args)
+    default:
+      console.error(`❌ Unknown demo: ${demoName}`)
+      console.error(`   Available demos: ${AVAILABLE_DEMOS.join(', ')}`)
+      process.exit(1)
   }
+}
 
-  const receiptPath = typeof args.receipt === 'string' && args.receipt.trim()
-    ? path.resolve(process.cwd(), args.receipt)
-    : bundledSkillUseRateReceiptPath()
-
-  let receipt
+function readReceipt(receiptPath, label) {
   try {
-    receipt = JSON.parse(fs.readFileSync(receiptPath, 'utf8'))
+    return JSON.parse(fs.readFileSync(receiptPath, 'utf8'))
   } catch (err) {
-    console.error(`❌ Could not read skill use-rate receipt at ${receiptPath}: ${err.message}`)
+    console.error(`❌ Could not read ${label} receipt at ${receiptPath}: ${err.message}`)
     process.exit(1)
   }
+}
 
+function selectedReceiptPath(args, defaultPath) {
+  return typeof args.receipt === 'string' && args.receipt.trim()
+    ? path.resolve(process.cwd(), args.receipt)
+    : defaultPath
+}
+
+function runSkillUseRateDemo(args) {
+  const receiptPath = selectedReceiptPath(args, bundledSkillUseRateReceiptPath())
+  const receipt = readReceipt(receiptPath, 'skill use-rate')
   const result = validateSkillUseRateReceipt(receipt)
+
   if (Boolean(args.json)) {
     console.log(JSON.stringify({
       ok: result.errors.length === 0,
-      demo: DEFAULT_DEMO,
+      demo: SKILL_USE_RATE_DEMO,
       receipt: path.relative(process.cwd(), receiptPath) || receiptPath,
       summary: result.summary,
       warnings: result.warnings,
@@ -65,10 +82,48 @@ export async function runDemo(args, positional = []) {
   if (result.errors.length > 0) process.exit(1)
 }
 
+function runMcpAuditReceiptDemo(args) {
+  const receiptPath = selectedReceiptPath(args, bundledMcpAuditReceiptPath())
+  const receipt = readReceipt(receiptPath, 'MCP audit')
+  const result = validateMcpAuditReceipt(receipt)
+
+  if (Boolean(args.json)) {
+    console.log(JSON.stringify({
+      ok: result.errors.length === 0,
+      demo: MCP_AUDIT_RECEIPT_DEMO,
+      receipt: path.relative(process.cwd(), receiptPath) || receiptPath,
+      summary: result.summary,
+      warnings: result.warnings,
+      errors: result.errors,
+    }, null, 2))
+  } else {
+    console.log('🧪 Pluribus demo: MCP audit receipt')
+    console.log(`   Receipt: ${path.relative(process.cwd(), receiptPath) || receiptPath}`)
+    console.log('')
+
+    if (result.errors.length === 0) {
+      console.log(`✅ MCP audit receipt ok: ${result.summary.toolCallCount} tool calls, ${result.summary.auditEventCount} audit events, ${result.summary.metricCount} metrics`)
+      for (const warning of result.warnings) console.log(`   • ${warning}`)
+      console.log('')
+      console.log('Why this matters: production MCP needs audit events and low-cardinality metrics, not raw prompt/tool dumps. Prove who invoked which tool, under which scope, with redacted argument/result shape.')
+      console.log('Try your own receipt: pluribus demo mcp-audit-receipt --receipt path/to/mcp-audit-receipt.json')
+    } else {
+      console.error('❌ MCP audit receipt invalid:')
+      for (const error of result.errors) console.error(`   • ${error}`)
+    }
+  }
+
+  if (result.errors.length > 0) process.exit(1)
+}
+
 function bundledSkillUseRateReceiptPath() {
   return fileURLToPath(new URL('../../examples/skill-use-rate-receipts/skill-use-rate-receipt.json', import.meta.url))
 }
 
+function bundledMcpAuditReceiptPath() {
+  return fileURLToPath(new URL('../../examples/mcp-audit-receipts/mcp-audit-receipt.json', import.meta.url))
+}
+
 export function validateSkillUseRateReceipt(receipt) {
   const errors = []
   const warnings = []
@@ -153,3 +208,102 @@ export function validateSkillUseRateReceipt(receipt) {
     },
   }
 }
+
+export function validateMcpAuditReceipt(receipt) {
+  const errors = []
+  const warnings = []
+
+  function requireString(value, field) {
+    if (typeof value !== 'string' || value.trim() === '') {
+      errors.push(`${field} must be a non-empty string`)
+    }
+  }
+
+  function requireArray(value, field) {
+    if (!Array.isArray(value) || value.length === 0) {
+      errors.push(`${field} must be a non-empty array`)
+    }
+  }
+
+  function requireNonNegativeNumber(value, field) {
+    if (typeof value !== 'number' || Number.isNaN(value) || value < 0) {
+      errors.push(`${field} must be a non-negative number`)
+    }
+  }
+
+  if (receipt.schema !== MCP_AUDIT_RECEIPT_SCHEMA) {
+    errors.push(`schema must be ${MCP_AUDIT_RECEIPT_SCHEMA}`)
+  }
+
+  requireString(receipt.run_id, 'run_id')
+  requireString(receipt.generated_at, 'generated_at')
+  requireString(receipt.server?.name, 'server.name')
+  requireString(receipt.server?.transport, 'server.transport')
+  requireString(receipt.client?.name, 'client.name')
+  requireString(receipt.audit_policy?.raw_arguments, 'audit_policy.raw_arguments')
+  requireString(receipt.audit_policy?.raw_results, 'audit_policy.raw_results')
+  requireString(receipt.audit_policy?.privacy_boundary, 'audit_policy.privacy_boundary')
+  requireArray(receipt.tool_calls, 'tool_calls')
+  requireArray(receipt.usage_metrics, 'usage_metrics')
+
+  if (receipt.audit_policy?.raw_arguments !== 'redacted_shape_only') {
+    errors.push('audit_policy.raw_arguments must be redacted_shape_only')
+  }
+  if (receipt.audit_policy?.raw_results !== 'redacted_shape_only') {
+    errors.push('audit_policy.raw_results must be redacted_shape_only')
+  }
+
+  const lowCardinalityMetricLabels = new Set(['tool_name', 'status', 'token_scope', 'user_type'])
+
+  for (const [index, call] of (receipt.tool_calls || []).entries()) {
+    const prefix = `tool_calls[${index}]`
+    requireString(call.event, `${prefix}.event`)
+    requireString(call.request_id, `${prefix}.request_id`)
+    requireString(call.session_id, `${prefix}.session_id`)
+    requireString(call.user_id_hash, `${prefix}.user_id_hash`)
+    requireString(call.token_subject_hash, `${prefix}.token_subject_hash`)
+    requireArray(call.token_scopes, `${prefix}.token_scopes`)
+    requireString(call.tool_name, `${prefix}.tool_name`)
+    requireString(call.status, `${prefix}.status`)
+    requireNonNegativeNumber(call.duration_ms, `${prefix}.duration_ms`)
+    requireString(call.result_shape, `${prefix}.result_shape`)
+
+    if (call.event !== 'mcp.tool_call') errors.push(`${prefix}.event must be mcp.tool_call`)
+    if (!['ok', 'empty', 'error', 'timeout', 'denied'].includes(call.status)) {
+      errors.push(`${prefix}.status must be one of ok|empty|error|timeout|denied`)
+    }
+    if (!call.args_shape || typeof call.args_shape !== 'object' || Array.isArray(call.args_shape)) {
+      errors.push(`${prefix}.args_shape must be an object with redacted argument types/shapes`)
+    }
+    if (typeof call.args_preview === 'string' || typeof call.result_preview === 'string') {
+      errors.push(`${prefix} must not include raw args/results previews; use args_shape/result_shape instead`)
+    }
+    if (call.error_class != null && typeof call.error_class !== 'string') {
+      errors.push(`${prefix}.error_class must be string or null`)
+    }
+  }
+
+  for (const [index, metric] of (receipt.usage_metrics || []).entries()) {
+    const prefix = `usage_metrics[${index}]`
+    requireString(metric.name, `${prefix}.name`)
+    requireString(metric.type, `${prefix}.type`)
+    requireString(metric.value, `${prefix}.value`)
+    requireArray(metric.labels, `${prefix}.labels`)
+
+    for (const label of metric.labels || []) {
+      if (!lowCardinalityMetricLabels.has(label)) {
+        warnings.push(`${prefix}.labels includes high-cardinality label ${label}; prefer ${[...lowCardinalityMetricLabels].join(', ')}`)
+      }
+    }
+  }
+
+  return {
+    errors,
+    warnings,
+    summary: {
+      toolCallCount: Array.isArray(receipt.tool_calls) ? receipt.tool_calls.length : 0,
+      auditEventCount: Array.isArray(receipt.tool_calls) ? receipt.tool_calls.length : 0,
+      metricCount: Array.isArray(receipt.usage_metrics) ? receipt.usage_metrics.length : 0,
+    },
+  }
+}

package/src/utils/version.js

@@ -1 +1 @@
-export const VERSION = '0.3.37'
+export const VERSION = '0.3.38'