@peac/mappings-mcp 0.12.5 → 0.12.6

package/README.md

@@ -1,6 +1,6 @@
 # @peac/mappings-mcp
 
-Model Context Protocol (MCP) integration for PEAC
+Model Context Protocol (MCP) integration for PEAC: attach and extract signed evidence carriers via MCP `_meta` keys.
 
 ## Installation
 
@@ -8,9 +8,108 @@ Model Context Protocol (MCP) integration for PEAC
 pnpm add @peac/mappings-mcp
 ```
 
-## Documentation
+## What It Does
 
-See [peacprotocol.org](https://www.peacprotocol.org) for full documentation.
+`@peac/mappings-mcp` provides the carrier format for embedding PEAC signed receipts in MCP tool responses. It uses reverse-DNS `_meta` keys (`org.peacprotocol/receipt_ref`, `org.peacprotocol/receipt_jws`) to attach and extract evidence carriers, with budget enforcement utilities for cost-controlled tool calls. Legacy `peac_receipt` format is supported for backward compatibility.
+
+## How Do I Use It?
+
+### Attach a receipt to an MCP tool response
+
+```typescript
+import { attachReceiptToMeta } from '@peac/mappings-mcp';
+import type { McpResultLike } from '@peac/mappings-mcp';
+
+const result: McpResultLike = { content: [{ type: 'text', text: 'Done' }] };
+
+attachReceiptToMeta(result, carrier, {
+  agentId: 'agent:tool-server-1',
+  verifiedAt: new Date().toISOString(),
+});
+
+// result._meta now contains:
+//   "org.peacprotocol/receipt_ref": "sha256:..."
+//   "org.peacprotocol/receipt_jws": "eyJ..."
+//   "org.peacprotocol/agent_id": "agent:tool-server-1"
+```
+
+### Extract a receipt from an MCP tool response
+
+```typescript
+import { extractReceiptFromMeta, extractReceiptFromMetaAsync } from '@peac/mappings-mcp';
+
+// Sync: structural validation only
+const extracted = extractReceiptFromMeta(result);
+if (extracted) {
+  console.log(extracted.receipts[0].receipt_ref);
+}
+
+// Async: includes receipt_ref consistency verification
+const verified = await extractReceiptFromMetaAsync(result);
+if (verified && verified.violations.length === 0) {
+  console.log(verified.receipts[0].receipt_jws);
+}
+```
+
+### Use the carrier adapter interface
+
+```typescript
+import { McpCarrierAdapter } from '@peac/mappings-mcp';
+
+const adapter = new McpCarrierAdapter();
+
+// Extract from incoming MCP response
+const extracted = adapter.extract(mcpResult);
+
+// Attach to outgoing MCP response
+adapter.attach(mcpResult, [carrier]);
+```
+
+### Enforce budget limits on tool calls
+
+```typescript
+import { checkBudget } from '@peac/mappings-mcp';
+import type { BudgetConfig } from '@peac/mappings-mcp';
+
+const config: BudgetConfig = {
+  maxPerCallMinor: 500n, // $5.00 max per call
+  maxDailyMinor: 10000n, // $100.00 max per day
+  currency: 'USD',
+};
+
+const result = checkBudget(8500n, 1000n, 'USD', config);
+
+if (result.allowed) {
+  console.log(`Remaining: ${result.remainingMinor} minor units`);
+} else {
+  console.log(`Denied: ${result.reason}`);
+}
+```
+
+### Check for MCP reserved key collisions
+
+```typescript
+import { isMcpReservedKey, assertNotMcpReservedKey } from '@peac/mappings-mcp';
+
+isMcpReservedKey('dev.mcp/anything'); // true (reserved)
+isMcpReservedKey('org.peacprotocol/receipt_ref'); // false (safe)
+```
+
+## Integrates With
+
+- `@peac/kernel` (Layer 0): Evidence carrier types (`PeacEvidenceCarrier`, `CarrierAdapter`)
+- `@peac/schema` (Layer 1): Carrier schema validation and `computeReceiptRef()`
+- `@peac/mcp-server` (Layer 5): Uses this package for receipt attachment in tool responses
+
+## For Agent Developers
+
+If you are building an MCP tool server that issues or verifies signed receipts:
+
+- Use `attachReceiptToMeta()` to embed evidence in tool call responses
+- Use `extractReceiptFromMetaAsync()` to extract and verify receipts from incoming responses
+- Use `checkBudget()` for per-call and aggregate cost enforcement
+- All `_meta` keys use the `org.peacprotocol/` prefix, which does not collide with MCP reserved prefixes
+- See the [llms.txt](https://github.com/peacprotocol/peac/blob/main/llms.txt) for a concise protocol overview
 
 ## License
 

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@peac/mappings-mcp",
-  "version": "0.12.5",
+  "version": "0.12.6",
   "description": "Model Context Protocol (MCP) integration for PEAC",
   "main": "dist/index.cjs",
   "types": "dist/index.d.ts",
   "repository": {
     "type": "git",
-    "url": "https://github.com/peacprotocol/peac.git",
+    "url": "git+https://github.com/peacprotocol/peac.git",
     "directory": "packages/mappings/mcp"
   },
-  "author": "jithinraj <7850727+jithinraj@users.noreply.github.com>",
+  "author": "PEAC Protocol Contributors",
   "license": "Apache-2.0",
   "bugs": {
     "url": "https://github.com/peacprotocol/peac/issues"
@@ -23,8 +23,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@peac/kernel": "0.12.5",
-    "@peac/schema": "0.12.5"
+    "@peac/kernel": "0.12.6",
+    "@peac/schema": "0.12.6"
   },
   "devDependencies": {
     "@types/node": "^22.19.11",
@@ -41,6 +41,18 @@
     },
     "./package.json": "./package.json"
   },
+  "keywords": [
+    "peac",
+    "peacprotocol",
+    "interaction-records",
+    "signed-records",
+    "receipts",
+    "originary",
+    "mcp",
+    "model-context-protocol",
+    "tool-calls",
+    "tool-invocation"
+  ],
   "scripts": {
     "prebuild": "rm -rf dist",
     "build": "pnpm run build:js && pnpm run build:types",