ContextSlim TypeScript SDK

High-performance M2M context middleware and x402 micropayment engine for AI Agents and MCP tools on Base.

ContextSlim prunes massive JSON payloads by up to 85%, enforces strict token budgets, and handles autonomous HTTP 402 EIP-712 micropayments—keeping agent execution fast, cost-effective, and deterministically within LLM context limits.

---

Proven E2E Benchmarks

Real-world test suite performance measured over live execution on Cloudflare KV + Base Sepolia:

MCP Tool / Operation	Input Payload	Output Payload	Reduction / Impact	Performance Metric
optimize_context	622 Tokens	94 Tokens	84.9% Token Saved	528 Tokens saved in array pruning
fetch_result (Targeted Path)	622 Tokens	9 Tokens	98.5% Savings	Instant extraction via JSONPath
Session Pass (2nd Query)	On-chain Auth	Cache Auth	70% Latency Drop	0.43s $\rightarrow$ 0.13s execution speed

---

Architecture & Protocol Flow

ContextSlim seamlessly sits between your AI Agent framework, the Model Context Protocol (MCP), and the Base blockchain:

+-------------------+       1. MCP Tool Call       +------------------------+
|  AI Agent / LLM   | ---------------------------> |  @contextslim/sdk      |
| (Claude / Cursor) | <--------------------------- |  (TS Engine Client)    |
+-------------------+     4. Pruned Payload        +------------------------+
                                                               |        ^
                                             2. x402 Payment   |        | 3. Optimized Data
                                                Challenge/Pass |        |    & Reference ID
                                                               v        |
                                                   +--------------------------------+
                                                   | ContextSlim Worker Engine      |
                                                   | (Cloudflare KV + Pruner Engine)|
                                                   +--------------------------------+
                                                                   |
                                                                   v (On-Chain Settlement)
                                                   +--------------------------------+
                                                   | Base Network (USDC / ERC-3009) |
                                                   +--------------------------------+

---

Installation

Install the agnostic SDK optimized for Node.js (v18+), Bun, Deno, and Cloudflare Workers:

npm install @contextslim/sdk ethers dotenv

---

MCP Client Configurations

1. Claude Desktop Integration

Add the following configuration to your claude_desktop_config.json file:

{
  "mcpServers": {
    "contextslim": {
      "command": "npx",
      "args": ["-y", "@contextslim/sdk"],
      "env": {
        "ENDPOINT_URL": "https://contextslim.friczero.com",
        "PRIVATE_KEY": "0x_YOUR_AGENT_PRIVATE_KEY"
      }
    }
  }
}

2. Cursor IDE (.cursor/mcp.json)

{
  "mcpServers": {
    "contextslim": {
      "url": "https://contextslim.friczero.com/message"
    }
  }
}

3. Smithery CLI

One-click installation via Smithery:

npx -y @smithery/cli install contextslim --client claude

---

30-Second Quickstart

This script initializes the client with an active Session Pass ($0.005 USDC), prunes a massive JSON payload, and retrieves specific fields with ultra-low latency:

import { ContextSlimClient } from "@contextslim/sdk";
import { Wallet } from "ethers";
import * as dotenv from "dotenv";

dotenv.config();

async function main() {
  // 1. Initialize Local Signer (Private key isolated in memory)
  const wallet = new Wallet(process.env.PRIVATE_KEY!);

  // 2. Instantiate ContextSlim Client
  const client = new ContextSlimClient({
    endpoint: process.env.ENDPOINT_URL || "https://contextslim.friczero.com",
    signer: wallet,
    allowanceBudget: 0.005, // Optional: Enables Session Pass to avoid signing every query
    maxTokenBudget: 1000,
  });

  // 3. Prune Massive Payload (optimize_context)
  const heavyPayload = {
    critical_alert: {
      severity: "CRITICAL",
      system: "database-cluster-primary",
      message: "Connection pool exhausted on port 5432",
    },
    system_status: { cpu_load: "88%", memory_used: "14.2GB" },
    logs: Array.from({ length: 100 }, (_, i) => `Log entry #${i + 1}: Activity sweep`),
  };

  console.log("Optimizing massive context...");
  const prep = await client.callTool("optimize_context", {
    data: heavyPayload,
    maxTokenBudget: 150,
  });

  const res = prep.result || {};
  const refId = res.toolResultReference?.referenceId || res.referenceId;
  console.log(`Reference Cached in KV: ${refId}`);
  console.log(`Saved Tokens: ${prep.metrics?.savedTokens}`);
  console.log(`Compression Ratio: ${prep.metrics?.reductionPercentage}`);

  // 4. Targeted Path Extraction (fetch_result)
  console.log("Retrieving only 'critical_alert.severity'...");
  const extracted = await client.callTool("fetch_result", {
    referenceId: refId,
    paths: ["critical_alert.severity"],
  });

  console.log("Result:", JSON.stringify(extracted?.result ?? {}, null, 2));
  // Returns only 9 tokens: { critical_alert: { severity: 'CRITICAL' } }
}

main().catch(console.error);

---

Advanced Signer Setup (Production & Enterprise)

While passing a raw ethers.Wallet initialized from an environment variable works for local development, production AI agents should avoid storing plain-text private keys in .env files.

ContextSlimClient accepts any standard ethers.Signer interface, allowing seamless integration with Hardware Security Modules (HSMs), Cloud Key Management Services (KMS), and Multi-Party Computation (MPC) infrastructure:

1. AWS KMS / Cloud HSM

Keep keys non-exportable inside dedicated cloud HSMs:

import { KmsSigner } from "aws-kms-ethers-signer";
import { ContextSlimClient } from "@contextslim/sdk";

const kmsSigner = new KmsSigner({
  keyId: "arn:aws:kms:us-east-1:123456789012:key/your-agent-key-id",
});

const client = new ContextSlimClient({
  endpoint: "https://contextslim.friczero.com",
  signer: kmsSigner, // Native Ethers Signer wrapping AWS KMS
});

2. Turnkey / Non-Custodial MPC Wallets

Isolate credentials for serverless agents or multi-tenant agent architectures:

import { TurnkeySigner } from "@turnkey/ethers";
import { ContextSlimClient } from "@contextslim/sdk";

const turnkeySigner = new TurnkeySigner({
  client: turnkeyClient,
  organizationId: process.env.TURNKEY_ORGANIZATION_ID!,
  signWith: process.env.TURNKEY_WALLET_ADDRESS!,
});

const client = new ContextSlimClient({
  endpoint: "https://contextslim.friczero.com",
  signer: turnkeySigner,
});

---

API Reference

new ContextSlimClient(options)

Option	Type	Default	Description
endpoint	string	Required	Base URL of the ContextSlim Worker (https://contextslim.friczero.com).
signer	ethers.Signer	Required	Ethers Signer implementation for ERC-3009/EIP-712 payment authorizations.
allowanceBudget	number	0	USDC budget to pre-approve a Session Pass (base price: $0.001 USDC/call; on-chain settlement triggers at $0.005 USDC).
maxTokenBudget	number	1000	Default response token limit.

---

client.callTool(name, params)

Unified invocation compatible with MCP JSON-RPC.

1. optimize_context Tool

Reduces complex JSON structures while preserving critical fields and inserting truncated reference markers (_slim).

• Parameters:

  • data (object, required) - Full JSON payload to optimize.
  • maxTokenBudget (number, optional) - Hard token limit for the response payload.

• Response:

{
  status: "success",
  result: {
    toolResultReference: { referenceId: "ref_ef17a253", expiresIn: "3600s" },
    // ... pruned payload
  },
  metrics: {
    savedTokens: "528",
    reductionPercentage: "84.9%",
    strategy: "recursive:arrays(47_items)"
  }
}

2. fetch_result Tool

Retrieves exact data subsets from a cached reference ID.

• Parameters:

  • referenceId (string, required) - ID returned by optimize_context.
  • paths (string[], optional) - Dot-notation field paths to extract (e.g., ["user.id", "items[0].price"]).

• Response:

{
  status: "success",
  referenceId: "ref_ef17a253",
  retrievedTokens: 9,
  result: { critical_alert: { severity: "CRITICAL" } }
}

---

Security & Resilience

• Cryptographic Isolation: EIP-712 / ERC-3009 x402 payment challenge signing happens strictly within your local process or designated KMS signer. No private keys or seed phrases ever leave your execution environment.
• Anti-Replay Protection: Every payment challenge issued by the HTTP 402 server includes time-bound single-use nonces. Reusing X-PAYMENT headers is strictly rejected.
• Session Pass Mechanism: Setting an allowanceBudget issues an encrypted session pass, amortizing on-chain verification and speeding up subsequent KV fetches to an average execution speed of 0.13 seconds.

---

License

This project is licensed under the MIT License.