@curatedmcp/tokenshield-core 0.2.0 → 0.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +93 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
# @curatedmcp/tokenshield-core
|
|
2
|
+
|
|
3
|
+
**The proxy engine behind [TokenShield](https://www.npmjs.com/package/@curatedmcp/tokenshield).** Anthropic API-layer middleware with token accounting, conversation dedup, and response cache.
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/@curatedmcp/tokenshield-core)
|
|
6
|
+
[](https://github.com/oneprofile-dev/tokenshield/blob/main/LICENSE)
|
|
7
|
+
|
|
8
|
+
> **You probably want [`@curatedmcp/tokenshield`](https://www.npmjs.com/package/@curatedmcp/tokenshield) instead.** That's the CLI. This package is the embeddable engine — use it if you're integrating TokenShield directly into another Node server.
|
|
9
|
+
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
## Install
|
|
13
|
+
|
|
14
|
+
```bash
|
|
15
|
+
npm install @curatedmcp/tokenshield-core
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
## What's in the box
|
|
19
|
+
|
|
20
|
+
- **`Pipeline`** — middleware runner with fail-open semantics and per-processor circuit breakers
|
|
21
|
+
- **`conversationDedup`** — content-hash `tool_result` blocks; replace 2nd+ with deterministic pointer stubs
|
|
22
|
+
- **`responseCache`** — LRU+TTL cache for `temperature === 0 && stream === false` requests
|
|
23
|
+
- **`anthropic`** — provider adapter (URL matching, SSE usage parsing, message conversion)
|
|
24
|
+
- **`Ledger`** — SQLite-backed request log using Node 22's built-in `node:sqlite` (zero native deps)
|
|
25
|
+
- **`dollarsFor()`** — accurate pricing math across all Anthropic models (Opus 4.7, Sonnet 4.6, Haiku 4.5, …)
|
|
26
|
+
|
|
27
|
+
## Minimal example
|
|
28
|
+
|
|
29
|
+
```ts
|
|
30
|
+
import { Pipeline, conversationDedup, anthropic } from "@curatedmcp/tokenshield-core";
|
|
31
|
+
|
|
32
|
+
const pipeline = new Pipeline({
|
|
33
|
+
processors: [conversationDedup],
|
|
34
|
+
enabled: new Set(["conversation-dedup"]),
|
|
35
|
+
});
|
|
36
|
+
|
|
37
|
+
const conv = anthropic.toConversation(anthropicMessagesRequest);
|
|
38
|
+
const result = pipeline.run(conv, {
|
|
39
|
+
providerId: "anthropic",
|
|
40
|
+
conversationFingerprint: "...",
|
|
41
|
+
inboundBytes: 12_345,
|
|
42
|
+
});
|
|
43
|
+
|
|
44
|
+
const compressedRequest = anthropic.applyConversation(anthropicMessagesRequest, result.conversation);
|
|
45
|
+
// → send compressedRequest to api.anthropic.com
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
## Provider adapter interface
|
|
49
|
+
|
|
50
|
+
If you want to add OpenAI, Gemini, or a custom provider, implement:
|
|
51
|
+
|
|
52
|
+
```ts
|
|
53
|
+
interface Provider {
|
|
54
|
+
id: "anthropic" | "openai" | "gemini" | string;
|
|
55
|
+
matches(url: URL, headers: Record<string, string>): boolean;
|
|
56
|
+
parseUsageFromJson(body: unknown): { usage: UsageCounts; model: string | null };
|
|
57
|
+
parseUsageFromSSE(event: SSEEvent, acc: UsageAccumulator): void;
|
|
58
|
+
extractModel(requestBody: unknown): string;
|
|
59
|
+
toConversation(requestBody: unknown): Conversation | null;
|
|
60
|
+
applyConversation(requestBody: unknown, conv: Conversation): unknown;
|
|
61
|
+
}
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
OpenAI lands in v1.1, Gemini in v1.2 — or send a PR.
|
|
65
|
+
|
|
66
|
+
## Privacy guarantees
|
|
67
|
+
|
|
68
|
+
- All work happens in-process. Nothing leaves the host that calls this library.
|
|
69
|
+
- No network I/O except the upstream provider call you make yourself.
|
|
70
|
+
- The optional ledger writes to a SQLite file you control (`~/.tokenshield/ledger.db` by default).
|
|
71
|
+
|
|
72
|
+
## Architecture & full docs
|
|
73
|
+
|
|
74
|
+
This is the engine. For the full CLI, dashboard, integrations, and end-user docs, see:
|
|
75
|
+
|
|
76
|
+
- **CLI:** [`@curatedmcp/tokenshield`](https://www.npmjs.com/package/@curatedmcp/tokenshield)
|
|
77
|
+
- **Source:** [github.com/oneprofile-dev/tokenshield](https://github.com/oneprofile-dev/tokenshield)
|
|
78
|
+
- **Whitepaper:** [docs/whitepaper.md](https://github.com/oneprofile-dev/tokenshield/blob/main/docs/whitepaper.md)
|
|
79
|
+
- **Website:** [curatedmcp.com/tokenshield](https://curatedmcp.com/tokenshield)
|
|
80
|
+
|
|
81
|
+
## Part of the CuratedMCP control plane
|
|
82
|
+
|
|
83
|
+
TokenShield is one of three products at **[curatedmcp.com](https://curatedmcp.com)** — the MCP governance control plane for engineering organizations:
|
|
84
|
+
|
|
85
|
+
- 🛡️ **TokenShield** — cut your Claude Code bill 40–70%
|
|
86
|
+
- 🔍 **[MCP Auditor](https://curatedmcp.com/auditor)** — static analysis for MCP server security
|
|
87
|
+
- 📊 **[Sentinel](https://curatedmcp.com/sentinel)** — runtime anomaly detection
|
|
88
|
+
|
|
89
|
+
[Start an enterprise pilot →](https://curatedmcp.com/enterprise/pilot)
|
|
90
|
+
|
|
91
|
+
## License
|
|
92
|
+
|
|
93
|
+
MIT — see [LICENSE](https://github.com/oneprofile-dev/tokenshield/blob/main/LICENSE).
|