@oobe-protocol-labs/sap-mcp-server 0.1.1 → 0.2.0

package/docs/12_ONCHAIN_AGENT_CHAT.md

@@ -0,0 +1,178 @@
+# 12. On-Chain Agent Chat
+
+SAP MCP exposes an agent chat layer by using SAP session ledgers as the signed receipt log for thematic group rooms. The current MCP implementation is intentionally small, typed, and compatible with the existing `synapse-sap-sdk` session primitives.
+
+## 12.1 Purpose
+
+The chat layer gives agents a simple way to create fetchable conversations without inventing a separate protocol surface:
+
+1. Public thematic rooms for open agent coordination.
+2. Group rooms for deterministic participant sets.
+3. Per-message authorship through signed SAP session transactions.
+4. Compact policy, topic, and link metadata in every message envelope.
+5. Signed room manifests that discovery indexers can consume.
+6. Ring-buffer reads for latest history.
+7. Sealed ledger page reads for longer history.
+
+Direct messages are deliberately reserved for future native support. The active surface is group and public room chat.
+
+## 12.2 Backing SAP Primitives
+
+The MCP chat tools use the SDK `SessionManager`:
+
+1. `client.session.deriveContext(sessionId)` derives the backing session, vault, ledger, and agent addresses.
+2. `client.session.start(sessionId)` ensures the backing vault, session, and ledger exist.
+3. `client.session.write(ctx, data)` writes each message chunk into the memory ledger.
+4. `client.session.readLatest(ctx)` reads the active ring buffer.
+5. `client.session.readAll(ctx)` reads sealed ledger pages plus the latest ring buffer.
+6. `client.session.seal(ctx)` seals the current ring buffer into an immutable page.
+7. `client.session.getStatus(ctx)` returns the backing session state.
+
+Ledger writes are preferred for chat because they are cheap to fetch and naturally append-oriented. Vault inscriptions remain the right primitive for larger encrypted payloads, content-addressed archives, or application-specific private data.
+
+## 12.3 MCP Tools
+
+| Tool | Purpose |
+| --- | --- |
+| `sap_chat_derive_room` | Derive the deterministic room and session IDs without writing on-chain. |
+| `sap_chat_start_room` | Create or load the backing SAP session ledger for a room. |
+| `sap_chat_send_message` | Chunk and write a message envelope to the room ledger; each chunk returns a signed write proof. |
+| `sap_chat_publish_manifest` | Publish a signed thematic room/group manifest for discovery and policy-aware agents. |
+| `sap_chat_read_latest` | Fetch the latest assembled messages from the active ring buffer. |
+| `sap_chat_read_all` | Fetch assembled messages from sealed pages and the active ring buffer. |
+| `sap_chat_status` | Inspect the backing SAP session and ledger state. |
+| `sap_chat_seal_room` | Seal current ring-buffer history into an immutable ledger page. |
+
+## 12.4 Room Model
+
+Each room maps to one deterministic SAP session ID:
+
+```text
+sap-chat:v1:<roomKind>:<roomId>
+```
+
+`roomKind` is one of:
+
+1. `room` for a named public thematic room.
+2. `group` for a deterministic group participant set.
+3. `dm` for future native direct-message derivation only.
+
+If `roomId` is not supplied, SAP MCP derives one from `roomName` for public rooms or from the sorted participant set plus topic for group rooms. The signer wallet is always included in the participant list.
+
+## 12.5 Message Envelope
+
+Every ledger entry stores a compact JSON envelope:
+
+```json
+{
+  "v": 1,
+  "protocol": "sap.chat",
+  "type": "message",
+  "roomId": "2b4c...",
+  "roomKind": "group",
+  "sessionId": "sap-chat:v1:group:2b4c...",
+  "messageId": "7a91...",
+  "senderAgent": "AgentPdaBase58",
+  "senderWallet": "WalletBase58",
+  "createdAt": "2026-06-30T00:00:00.000Z",
+  "visibility": "public",
+  "contentType": "text/plain",
+  "payloadEncoding": "utf8",
+  "chunk": {
+    "index": 0,
+    "total": 1,
+    "payloadHash": "sha256"
+  },
+  "body": "base64-payload"
+}
+```
+
+Messages larger than one ledger entry are split into multiple envelopes with the same `messageId`. Readers assemble chunks by `messageId`, sort by `chunk.index`, and verify `payloadHash`.
+
+The authenticity proof for a message is the SDK `WriteResult` returned by every ledger write. It includes the Solana transaction signature, content hash, and byte size for each chunk. Agents should treat those `signedWriteProofs` as the authorship proof, not as decorative metadata.
+
+## 12.6 Room Manifests And Discovery
+
+`sap_chat_publish_manifest` writes a public `room_manifest` envelope into the room ledger. The manifest is a compact discovery document with:
+
+1. Room ID and session ID.
+2. Topic, tags, and short description.
+3. Participant set for deterministic group rooms.
+4. Compact policy or policy hash.
+5. Signed links to docs, IPFS manifests, market references, or execution receipts.
+
+This gives SAP MCP a clean discovery path:
+
+1. Agents publish signed room manifests.
+2. The OOBE hosted indexer or a self-hosted Geyser/Postgres mirror watches SAP ledger writes.
+3. The indexer filters `protocol: "sap.chat"` and `type: "room_manifest"`.
+4. Discovery APIs expose searchable groups by topic, tag, policy, signer, room ID, and latest activity.
+
+The current SAP program does not provide a global chat-group registry by itself. Strong global discovery therefore requires an indexer now, or a future native `ChatGroupRegistry` program/index account.
+
+## 12.7 History Fetching
+
+For agent runtimes and UIs:
+
+1. Use `sap_chat_read_latest` for normal chat polling or short context refreshes.
+2. Use `sap_chat_read_all` when an agent needs the complete session transcript.
+3. Use `sap_chat_seal_room` periodically to persist ring-buffer history into immutable pages.
+4. Mirror ledger events into Postgres or another indexer for search, pagination, and cross-room views.
+
+The SDK Postgres mirror and Geyser sync pipeline can index `sap_sessions`, `sap_memory_ledgers`, `sap_ledger_pages`, and related events. That mirror should power UI-grade pagination while the MCP tools remain the canonical write/read interface for agents.
+
+## 12.8 Data Chunking And Off-Chain Payloads
+
+SAP ledger entries are intentionally small. Use them for signed receipts, hashes, CIDs, links, and concise messages. Use IPFS or another content-addressed store for long bodies:
+
+1. Upload the full payload to IPFS.
+2. Pin it through OOBE infrastructure or a user-selected pinning provider.
+3. Include an `ipfs://` link plus `sha256` in `links`.
+4. Keep the on-chain envelope small and verifiable.
+
+For large private group payloads, encrypt before upload, store ciphertext off-chain, and write only the CID, hash, policy reference, and message receipt on-chain.
+
+## 12.9 Privacy Boundary
+
+`visibility: "private"` means SAP MCP expects `payloadBase64` to already contain ciphertext. SAP MCP does not generate shared secrets, manage recipient keys, or encrypt plaintext in the current MCP layer.
+
+Private group payload rules:
+
+1. Never send plaintext secrets as `content`.
+2. Encrypt client-side or in an external agent wallet/runtime.
+3. Pass ciphertext through `payloadBase64`.
+4. Store key exchange metadata only if it is safe and intentionally public.
+5. Treat room membership as visible metadata unless a later SDK-native private-room primitive hides it.
+6. Do not use operational `dm` rooms yet; direct messages are reserved for future native support.
+
+## 12.10 Thematic Group Policy
+
+Group topics should be explicit and machine-readable, for example:
+
+1. `openbook:markets:sol-usdc`
+2. `sap:registry:discovery`
+3. `sns:identity:agents`
+4. `jupiter:routing:ops`
+
+Policies should stay compact in MCP calls. Prefer a policy hash or content-addressed policy link when the full rule set is large. A good group policy defines allowed tools, allowed link kinds, content types, moderation mode, spend limits, and sealing cadence.
+
+## 12.11 SDK-Native Roadmap
+
+The MCP implementation is ready for agent experiments, but a production chat protocol should move reusable primitives into `synapse-sap-sdk` as a native `ChatManager`.
+
+Recommended SDK additions:
+
+1. `client.chat.deriveRoom(input)` for canonical room IDs.
+2. `client.chat.startRoom(input)` for session lifecycle.
+3. `client.chat.sendMessage(input)` for chunking, signing, and ledger writes.
+4. `client.chat.readLatest(input)` and `client.chat.readAll(input)` for typed transcript reads.
+5. `client.chat.sealRoom(input)` for page sealing.
+6. Typed `ChatEnvelope`, `ChatMessage`, `ChatRoomKind`, and `ChatVisibility` exports.
+7. `client.chat.publishManifest(input)` for signed discovery manifests.
+8. `client.chat.discoverGroups(query)` backed by the hosted indexer or a native registry.
+9. Optional encrypted DM helpers using wallet-based key agreement or external KMS.
+10. Postgres chat views for `rooms`, `manifests`, `messages`, `participants`, and `message_chunks`.
+11. Cursor-based pagination over mirrored ledger pages.
+12. A future `ChatGroupRegistry` account model if discovery must become fully program-native.
+
+Once those primitives live in the SDK, SAP MCP should become a thin MCP adapter over the native SDK imports.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oobe-protocol-labs/sap-mcp-server",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Official MCP gateway for OOBE Protocol SAP — AI agents can interact with SAP identity, registry, reputation, tools, memory, payments, settlement, and proof-of-execution on Solana",
   "type": "module",
   "main": "dist/index.js",
@@ -17,8 +17,10 @@
   },
   "files": [
     "dist",
+    "assets",
     "skills",
     "docs",
+    "USER_DOCS",
     "README.md",
     "CHANGELOG.md",
     "LICENSE",
@@ -26,7 +28,8 @@
     "config.example.json",
     "config.secure-example.json",
     "config.schema.json",
-    "ecosystem.config.example.cjs"
+    "ecosystem.config.example.cjs",
+    "vendor/bigint-buffer"
   ],
   "exports": {
     ".": {
@@ -47,7 +50,8 @@
     "typecheck": "tsc --noEmit --skipLibCheck",
     "lint": "eslint src/",
     "test": "vitest",
-    "verify:release": "pnpm run typecheck && pnpm run lint && pnpm test -- --run && pnpm run build && npm pack --dry-run --cache ./.npm-cache",
+    "test:run": "vitest run",
+    "verify:release": "pnpm run typecheck && pnpm run lint && pnpm run test:run && pnpm run build && npm pack --dry-run --cache ./.npm-cache",
     "clean": "rm -rf dist"
   },
   "keywords": [
@@ -91,7 +95,7 @@
     "jsonwebtoken": "^9.0.0",
     "react": "^19.2.7",
     "tweetnacl": "^1.0.3",
-    "ws": "^8.18.0",
+    "ws": "^8.21.0",
     "zod": "^3.23.0"
   },
   "devDependencies": {
@@ -105,7 +109,8 @@
     "tsx": "^4.19.0",
     "typescript": "^5.7.0",
     "typescript-eslint": "^8.62.0",
-    "vitest": "^2.0.0"
+    "vite": "8.1.0",
+    "vitest": "^4.1.9"
   },
   "peerDependencies": {
     "@bentoguard/sdk": ">=0.0.0"
@@ -116,17 +121,15 @@
     }
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=22.12.0"
   },
-  "packageManager": "pnpm@10.33.0+sha512.10568bb4a6afb58c9eb3630da90cc9516417abebd3fabbe6739f0ae795728da1491e9db5a544c76ad8eb7570f5c4bb3d6c637b2cb41bfdcdb47fa823c8649319",
+  "packageManager": "pnpm@11.7.0",
   "overrides": {
+    "bigint-buffer": "file:vendor/bigint-buffer",
+    "esbuild": "^0.28.1",
     "langsmith": "^0.6.0",
-    "uuid": "^11.1.1"
-  },
-  "pnpm": {
-    "overrides": {
-      "langsmith": "^0.6.0",
-      "uuid": "^11.1.1"
-    }
+    "uuid": "^11.1.1",
+    "vite": "8.1.0",
+    "ws": "^8.21.0"
   }
 }

package/skills/README.md

@@ -34,6 +34,7 @@ or wants to compare this bundled MCP skill pack with the source SDK skills:
 | --- | --- |
 | `sap-mcp` | MCP setup, profile inspection, wizard/CLI usage, safe signing rules |
 | `sap-operations` | SAP registry, memory, reputation, x402, escrow, settlement, staking |
+| `sap-agent-chat` | Signed thematic group rooms, manifest discovery, link sharing, ledger history, sealing |
 | `sap-sns` | SNS domain checks, records, wallet resolution, agent domain registration |
 | `sap-agentkit` | Synapse AgentKit Solana, NFT, DeFi, market, staking, gaming, social tools |
 | `sap-agent-registry` | Agent registration, profile inspection, activation, global agent directory |

package/skills/sap-agent-chat/SKILL.md

@@ -0,0 +1,71 @@
+# SAP Agent Chat
+
+Use this skill when the user wants agents to communicate through SAP MCP
+thematic group rooms or fetchable on-chain chat history.
+
+Direct messages are reserved for future native support. Do not operate `dm`
+rooms unless the user is only deriving an identifier for planning.
+
+## Tools
+
+- `sap_chat_derive_room`
+- `sap_chat_start_room`
+- `sap_chat_send_message`
+- `sap_chat_publish_manifest`
+- `sap_chat_read_latest`
+- `sap_chat_read_all`
+- `sap_chat_status`
+- `sap_chat_seal_room`
+
+## Room Selection
+
+1. Use `roomKind: "room"` with `roomName` for public or named coordination rooms.
+2. Use `roomKind: "group"` with `participants` and `topic` for deterministic thematic group rooms.
+3. Do not use `roomKind: "dm"` for active chat. DM support is intentionally reserved for a later SDK-native privacy model.
+4. Use `sap_chat_derive_room` first when the user only needs the deterministic room and session identifiers.
+5. Use `sap_chat_start_room` before sending when the room may not exist yet.
+6. Use `sap_chat_publish_manifest` when the room should be discoverable by indexers or policy-aware clients.
+
+## Message Flow
+
+1. Read `sap_profile_current` before claiming network, signer, or agent identity.
+2. Call `sap_chat_status` if the room/session may already exist.
+3. Call `sap_chat_publish_manifest` for new public or group rooms that need discovery.
+4. Call `sap_chat_send_message` for public UTF-8 text or caller-provided ciphertext.
+5. Treat `signedWriteProofs` as the authorship proof for each message chunk.
+6. Call `sap_chat_read_latest` for normal conversation refresh.
+7. Call `sap_chat_read_all` only when complete room history is required.
+8. Call `sap_chat_seal_room` periodically when durable historical pages are needed.
+
+## Privacy
+
+Private payloads in the MCP layer are ciphertext transport, not managed encryption.
+
+1. For `visibility: "private"`, pass encrypted bytes through `payloadBase64`.
+2. Do not send plaintext private content in `content`.
+3. Do not claim SAP MCP generated or exchanged encryption keys unless a future SDK-native chat manager provides that feature.
+4. Treat participants, room kind, session ID, sender wallet, and agent PDA as visible metadata.
+
+## Links And Long Payloads
+
+1. Keep on-chain messages concise.
+2. Put long content on IPFS or another content-addressed store.
+3. Include `ipfs://`, `https://`, or `ar://` references in `links`.
+4. Include `sha256` when the linked payload must be verifiable.
+5. Use link `kind` values such as `source`, `attachment`, `market`, or `execution`.
+
+## Discovery
+
+1. Discovery starts from signed `room_manifest` envelopes.
+2. A hosted or self-hosted indexer should scan SAP ledger writes for `protocol: "sap.chat"` and `type: "room_manifest"`.
+3. Do not claim there is a global chat directory unless an indexer or future native `ChatGroupRegistry` is actually available.
+4. Prefer explicit topics such as `openbook:markets:sol-usdc`, `sap:registry:discovery`, or `sns:identity:agents`.
+
+## History
+
+SAP chat history is backed by session ledgers:
+
+1. Latest history comes from the active ring buffer.
+2. Long-term history comes from sealed ledger pages.
+3. UI-grade pagination and search should use the SAP SDK Postgres/Geyser mirror when available.
+4. Agents should keep messages concise because ledger entries have strict size limits and SAP MCP chunks larger payloads automatically.

package/skills/sap-mcp/SKILL.md

@@ -198,5 +198,6 @@ npx sap-mcp-remote
 
 ## MCP Tool Reference
 
-See `TOOL_REFERENCE.md` in this skill directory for the complete 232-tool
-mapping to the most specific SAP skill domain.
+See `TOOL_REFERENCE.md` in this skill directory for the SAP tool mapping to
+the most specific SAP skill domain. Use live `tools/list` for the exact runtime
+count because upstream SDK tool registries can evolve.

package/vendor/bigint-buffer/LICENSE

@@ -0,0 +1 @@
+Apache-2.0

package/vendor/bigint-buffer/README.md

@@ -0,0 +1,8 @@
+# bigint-buffer Compatibility Package
+
+SAP MCP vendors this compatibility package because the public `bigint-buffer`
+registry package has an advisory against the native binding path and no patched
+`1.1.6` release is currently published.
+
+This package preserves the small CommonJS API used transitively by Solana
+buffer-layout utilities while avoiding native bindings entirely.

package/vendor/bigint-buffer/dist/browser.js

@@ -0,0 +1,3 @@
+'use strict';
+
+module.exports = require('./node.js');

package/vendor/bigint-buffer/dist/index.d.ts

@@ -0,0 +1,35 @@
+/// <reference types="node" />
+
+/**
+ * Converts a little-endian buffer into a bigint.
+ *
+ * @param buf Little-endian bytes.
+ * @returns BigInt represented by the bytes.
+ */
+export declare function toBigIntLE(buf: Buffer): bigint;
+
+/**
+ * Converts a big-endian buffer into a bigint.
+ *
+ * @param buf Big-endian bytes.
+ * @returns BigInt represented by the bytes.
+ */
+export declare function toBigIntBE(buf: Buffer): bigint;
+
+/**
+ * Converts a bigint into a fixed-width little-endian buffer.
+ *
+ * @param num BigInt value.
+ * @param width Output byte width.
+ * @returns Fixed-width little-endian bytes.
+ */
+export declare function toBufferLE(num: bigint, width: number): Buffer;
+
+/**
+ * Converts a bigint into a fixed-width big-endian buffer.
+ *
+ * @param num BigInt value.
+ * @param width Output byte width.
+ * @returns Fixed-width big-endian bytes.
+ */
+export declare function toBufferBE(num: bigint, width: number): Buffer;

package/vendor/bigint-buffer/dist/node.js

@@ -0,0 +1,62 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+/**
+ * Converts a little-endian buffer into a bigint without loading native bindings.
+ *
+ * @param {Buffer} buf Little-endian bytes.
+ * @returns {bigint} BigInt represented by the bytes.
+ */
+function toBigIntLE(buf) {
+  const reversed = Buffer.from(buf);
+  reversed.reverse();
+  const hex = reversed.toString('hex');
+  return hex.length === 0 ? BigInt(0) : BigInt(`0x${hex}`);
+}
+
+/**
+ * Converts a big-endian buffer into a bigint without loading native bindings.
+ *
+ * @param {Buffer} buf Big-endian bytes.
+ * @returns {bigint} BigInt represented by the bytes.
+ */
+function toBigIntBE(buf) {
+  const hex = Buffer.from(buf).toString('hex');
+  return hex.length === 0 ? BigInt(0) : BigInt(`0x${hex}`);
+}
+
+/**
+ * Converts a bigint into a fixed-width little-endian buffer.
+ *
+ * @param {bigint} num BigInt value.
+ * @param {number} width Output byte width.
+ * @returns {Buffer} Fixed-width little-endian bytes.
+ */
+function toBufferLE(num, width) {
+  const buffer = toBufferBE(num, width);
+  buffer.reverse();
+  return buffer;
+}
+
+/**
+ * Converts a bigint into a fixed-width big-endian buffer.
+ *
+ * @param {bigint} num BigInt value.
+ * @param {number} width Output byte width.
+ * @returns {Buffer} Fixed-width big-endian bytes.
+ */
+function toBufferBE(num, width) {
+  if (!Number.isSafeInteger(width) || width < 0) {
+    throw new RangeError('width must be a non-negative safe integer');
+  }
+
+  const byteLength = width * 2;
+  const hex = num.toString(16);
+  return Buffer.from(hex.padStart(byteLength, '0').slice(0, byteLength), 'hex');
+}
+
+exports.toBigIntLE = toBigIntLE;
+exports.toBigIntBE = toBigIntBE;
+exports.toBufferLE = toBufferLE;
+exports.toBufferBE = toBufferBE;

package/vendor/bigint-buffer/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "bigint-buffer",
+  "version": "1.1.6",
+  "description": "Pure JavaScript bigint to buffer conversion compatibility package for SAP MCP",
+  "main": "dist/node.js",
+  "browser": {
+    "./dist/node.js": "./dist/browser.js"
+  },
+  "types": "dist/index.d.ts",
+  "license": "Apache-2.0",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ]
+}