IcyLoom
Acts as a local OpenAI-compatible gateway (exposing /v1/chat/completions, /v1/models, /v1/embeddings) placed in front of upstream LLM providers, so any OpenAI-style client can point its base_url at IcyLoom and get prompt normalisation, exact-hash caching (identical requests served with zero upstream tokens), and per-request token accounting through the ledger.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
IcyLoom
One MCP server. One SQLite file. One ledger that tells you what it actually saved.
IcyLoom V2 — the MCP Tool Gateway
What's new — 2026-11-04 — V2.2.0 (fail-closed, honest status)
Change | What it means |
Unknown tools are denied | A tool absent from the registry used to be allowed with |
| One single decision point for both. A reader asking for a destructive tool gets |
|
|
Real per-server status |
|
Drift noise gone | Schemas are normalized before hashing ( |
Cache metrics are real |
|
A live economy metric | The toolbar shows a number that moves — |
The economy is counted once | Disjoint domains only — cache LLM, compression, tools, tool-cache. The previous formula counted the same compression twice, so the toolbar and the registry card disagreed. They now agree, and |
Catalogue: 102 server entries | 18 active, 84 dormant in the catalogue, listed with a real per-server Tester and a pager (25 per page); the dormant ones stay disabled until enabled. |
What's new — 2026-11-04 — V2.1.0 (trust signals)
Change | What it means |
The gateway reads what the servers declare | The MCP annotations ( |
A changed tool definition is journalised | Every definition is hashed (description, schemas, annotations). A change lands in |
Structured results are checked | The |
Results are scanned for injections | Instruction override, role hijack, credential leak, forged tool call, hidden markup: a flagged result is served with an |
Two new meta-tools |
|
The console shows the trust signals | A new Trust signals panel in the Gateway V2 view: what the downstream servers declare, the definition drift, and the results that were flagged. |
A new mark, visible in the console | The ink-and-paper identity is kept, the palette turns bluer (blue warp threads, violet weft). The mark now shows at 132 px in the console hero instead of hiding in the favicon. |
What's new — 2026-11-03
Change | What it means |
The system tray ships with the package | The gateway starts with your session — one click from the tray, no terminal juggling. |
Agent clients are read-only and keep their own roots | An agent cannot reach outside the project roots it declares; a write outside them is refused outright. |
Downstream MCP servers get a usable environment | An empty environment used to kill |
Every active server is indexed at startup | SQLite and the others were missing from the registry; the FastMCP lifespan now receives the server, so a refresh actually starts. |
The registry accepts the real |
|
Dashboard rebuilt | Window mask, cropped relief/topo, honest axes, legends, tooltips, ranked cache chart. |
Figures republished from a real measurement | 194 tools across 14 servers, real tokens (tiktoken), gain per domain. The numbers below are the measured ones. |
V2.0.0 is released (release notes). V2 turns a pile of MCP servers into one governed gateway: every tool catalogued, the right tool selected from a plain-language request, permissions enforced, context compressed, every decision logged.
194 tools · 14 servers · 21 MCP tools · zero embeddings · 127.0.0.1 only
V1 solved the cost problem: it cached LLM answers, compressed a context drawer, relayed tools. It did not solve the control problem — a client that could see every downstream tool could also use every downstream tool. V2 is the missing half.
V1 | V2 | |
Tools | relayed, opaque | catalogued — schema, intent, side effects, scope, risk |
Selection | the client picks | the gateway picks, from a natural-language request |
Permissions | one global switch | roles, rules, approvals, project scope |
Context | raw tool schemas | compressed schemas and results |
Trail | token ledger | token ledger + decision audit |
Install | pip + config | pip + config — still no embeddings, no GPU, no external service |
Eight meta-tools
The agent talks to the gateway, not to 194 individual tools.
Meta-tool | What it does |
| Finds the tools matching an intent written in 12 languages. Lexical index (SQLite FTS5/BM25), no embeddings. |
| The compressed contract of one tool — what the agent actually sees. |
| Runs one downstream tool through policy, cache and compression. |
| Chains several calls inside a sandboxed Python script. |
| The policy in force: roles, scopes, approval rules. |
| Tokens per category, registry, audit — the observability view. |
| Definition drift: a downstream tool changed — schema, description, behaviour. |
| The decision the policy would take, without executing anything. |
21 tools in total (13 from V1 + these 8). A destructive action without confirm=true is refused with no side effect.
The six pillars
The registry is the source of truth — every tool described once (schema, domain, intent, side effects, security level, scope, owner, risk), in the same SQLite file as everything else.
Selection that understands the request — FTS5 narrows the candidates, Python scores them, and the request is translated into the canonical concepts first, so a French sentence reaches the English-named tool that answers it.
Policy, roles and approvals —
reader/writer/operator/admin, rulesallow/deny/approval, most specific rule wins. A destructive effect always needs an approval; a write outside the project roots is refused outright.Compression that keeps the prompt small — schemas and results are compressed, property order is preserved (reordering would invalidate the provider's prompt cache), secrets are detected on the way through, and the raw result stays retrievable by
result_ref.Observability and audit — every decision is written to
tool_audit: actor, role, intent, tool, decision, reason, compression applied, tokens saved.Trust signals — the server's declarations are read, not assumed — the MCP annotations (
readOnlyHint,destructiveHint…) complete the side-effect classification (they can only escalate it, never lower it), a changed tool definition is journalised intool_drift, a structured result is checked against its declaredoutputSchema, and a result that tries to inject instructions into the model is flagged instead of being served silently.
Benchmarks — measured, not claimed
Measured on the development instance (Windows 11, i7 vPro, no GPU) against a live stack of 14 real MCP servers, after a 46-call load pass through the gateway:
Metric | Value |
Tools indexed | 194 across 14 servers |
Read-only / write / destructive | 134 (69.1 %) / 45 (23.2 %) / 15 (7.7 %) |
Decisions traced | 58 — 40 allowed, 17 approvals, 1 refused (outside project scope) |
Tokens saved by tool compression | 118 654 — real tokens (tiktoken) |
Tokens measured (window) | 837 431 — 812 407 in tool schemas, 25 024 in tool results |
Test suite | 20 mission tests (one per finding) + full suite green, exit code 0 |
The console was then put under load in the same run — 40 real calls through the gateway (10 prompts × 4), no mock:
Metric | Value |
Calls through the gateway | 40 — 0 error, 10 distinct prompts |
Served from IcyLoom's own cache | 30 — ~215 ms each, 0 token spent |
Real generations (upstream miss) | 10 — p50 6.2 s, p95 10.4 s |
Hit rate on the console window | 78.5 % — 102 hits / 28 misses (13 errors excluded) |
Tokens avoided | 373 190 — cache 20 250 + compression 234 286 + tools 118 654 |
Gain on the window | 48.4 % — 373 190 avoided / (398 367 paid + 373 190 avoided) |
Local cache after the run | 8 entries, 4 reuses each |
Ledger rows | 623 |
Every figure above is read from the SQLite file the console itself reads — the same file you can open.
End-to-end run against the real MCP server over stdio, no mocks:
TOOLS=19 META_OK=True
lis un fichier du depot -> github.get_file_contents | desktop-commander.read_file | filesystem.read_file
supprime un fichier -> github.delete_file | local-rag.delete_file | basic-memory.delete_note
cree un ticket github -> github.issue_write | memory.create_entities | github.add_issue_comment
read_file README.md -> ok=True, real content returned
write_file -> ok=True, file really written
github.delete_file (no confirm) -> error=approval_required, call never reached the server
run_tool_script -> ok=True, sandboxed
policy: role=reader env=dev roots=[] (client-declared roots only)Gateway V2 view of the console: five KPIs with success badges, three charts, the registry, the policy in force and the decision audit — all live.
Release status
V2.2.0 is on main (changelog). It adds: registry, lexical selection in 12 languages, the six meta-tools, roles and approvals, compression, the sandbox, the audit trail, the console view, the system tray icon, the trust signals (MCP annotations, definition drift, structured-output verification, untrusted-content detection) with two extra meta-tools, tool_drift and tool_simulate, a new Trust signals panel in the console, a fail-closed relay (an unknown tool is denied by default), real per-server status, a catalogue of 102 server entries (18 active, 84 dormant) with a pager and a real per-server Tester — and a live economy metric in the toolbar: GET /api/live re-queries SQLite every second and sums disjoint domains, so the headline and the registry card always agree.
Full announcement: ANNOUNCEMENT.md · Session log: progress.md
A hybrid gateway for local and cloud LLM workflows that puts an LLM cache, a compressed context drawer and an MCP tool relay behind one MCP server, one configuration file and one SQLite database.
IcyLoom is a standalone project: no imports, links or paths to any other project. The code is written from scratch; the only files taken from elsewhere are data (normalisation rules, a tool registry), because the cache hash depends on them.
Cache | Every prompt normalised, hashed and stored. A hit is a zero-token answer. |
Context drawer | Sources filed, chunked, anchored, invariants checked — compressed on demand, opt-in. |
Tool relay | Downstream MCP servers, cached by canonical signature, deny by default. |
Registry |
|
Console | A hand-drawn web console on |
Privacy | Binds |
The numbers are real. A cache hit is counted as avoided, a miss is counted as paid with the upstream's own usage figures — never estimated. The 35 % threshold is read straight from the ledger.
Overview: the unified registry, five live KPIs, calls per bucket, latency, outcomes, models, upstreams. Captured on the live development instance: every tile is a real call read from SQLite.
Hermes Agent Plugin (Catalog Ready)
IcyLoom is packaged as a Hermes Agent plugin — installable by name once listed in the plugin catalog:
# After catalog merge (pending PR)
hermes plugins install icyloomThe plugin declares 21 MCP tools and runs the full gateway stack (ports 8150-8153).
See plugin.yaml for the manifest and __init__.py for the entrypoint.
Quick start (Standalone)
Five minutes, on a clean machine. No GPU is required, no provider lock-in is imposed, and no cloud account is needed for local mode. Route to local or cloud upstreams when configured.
Option 1: PyPI (Python)
pip install icyloom
# or with pipx (recommended for CLI tools):
pipx install icyloomOption 2: NPM (Node.js wrapper)
npm install -g icyloom
# Requires Python 3.11+ — the wrapper delegates to PythonLinux / macOS
python3 -m venv venv
source venv/bin/activate
python -m pip install --upgrade pip
pip install icyloom
icyloom init
icyloom doctor
icyloom tray --install-autostart
# in a second terminal
icyloom serve
icyloom check --transport allWindows (PowerShell)
py -3.12 -m venv venv
.\venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install icyloom
icyloom init
icyloom doctor
# the system tray icon — starts with your session
icyloom tray --install-autostart
# in a second terminal
icyloom serve
icyloom check --transport allPinned to a specific release (git required):
python -m pip install "icyloom @ git+https://github.com/MlkBlk-IT/icy-loom.git@v2.2.2"Expected output of icyloom check: 21/21 vérifications réussies.
icyloom check plays the role of the client: it starts the server, connects,
lists the 13 tools and calls them (ctx_store, ctx_search, ctx_verify,
cache, ledger, proxy_info). It tests the three transports (stdio,
streamable-HTTP, SSE) and prints 21/21 vérifications réussies when all is
well. If HTTP or SSE fails, the stack is not running (icyloom serve); the
stdio mode, on the other hand, is self-contained — it is the one Claude
Code and Cursor use.
Then plug IcyLoom into your MCP client:
icyloom client --target cursor --install # writes the config on your machine
icyloom client --target claude # prints the block to pasteTargets: cursor, claude (Desktop), claude-code, windsurf, codex,
json (raw block).
icyloom.yaml single configuration (Pydantic)
src/icyloom/data/ externalised data, shipped inside the package (JSON)
var/icyloom.db single SQLite database (WAL)
HTTP gateway :8150 MCP server (one build function)
/v1/chat/completions stdio dedicated process
/v1/messages streamable-HTTP :8151
/v1/models, /v1/embeddings SSE :8152
/{upstream}/v1/... 13 tools, one surface
cache -> routing -> upstream
admin API + dashboard :8153
gateway, MCP and admin all write to one database and one ledgerOutside a repository checkout, nothing is written inside site-packages: the
configuration, the database and the logs go to the user data directory —
%LOCALAPPDATA%\icyloom on Windows, $XDG_DATA_HOME/icyloom (or
~/.local/share/icyloom) on Linux and macOS. Override it with
ICYLOOM_DATA_DIR.
Related MCP server: mcplex
The system tray
The icon is part of the package: on Windows pip install icyloom already
brings it in, nothing extra to install. It starts the stack, opens the
console, shows the state of the four services, writes the MCP configuration of
your clients in one click, and can start with your session.
icyloom tray # launch the icon
icyloom tray --install-autostart # start it with Windows
icyloom tray --status # stack, services, autostartFull guide: docs/INSTALL.md · docs/TRAY.md
Status & known limitations
This section is the honest summary. Raw measurements live in
docs/archive/PROGRESS.md.
Area | Status |
Installation from a wheel on a clean machine | Verified. |
Test suite | 223 tests collected by pytest ( |
Cache round trip (miss then hit) | Verified by an automated test: the first request calls the upstream, the identical second request does not, the served response is identical, and the ledger records both |
Tool relay | Verified by an automated test against a real MCP stdio server: the tool is reached, it answers, and the second identical call is served from the cache |
Tool-result cache correctness (stale hits, replayed writes, cached errors, loop detection) | Verified. Synthetic harness: 0 stale hits out of 140 (before the fix: 425 out of 436). Real |
Gateway latency | p50 13.5 ms (MISS) and 10.7 ms (HIT); p95 about 16 ms against a 200 ms budget |
Latency gain on a slow tool | One real |
Token savings on tool calls | Not delivered and not measured. A tool-cache hit is ledgered with 0 tokens saved |
Context compression | Opt-in, off by default. |
Python versions | 3.11, 3.12, 3.13 supported. Python 3.14 is not in the supported range yet |
The "50 percent tokens saved" printed by tests/proof_e2e.py is true by construction: that test sends every request twice. It is not a traffic figure and must not be quoted as one.
Getting started
icyloom doctor # diagnostics
icyloom serve # gateway + MCP + admin
icyloom mcp --transport stdio # for an MCP client
icyloom gateway # gateway only (8150)
icyloom admin # admin API only (8153)
icyloom paths # every resolved pathAn MCP client connects with a single entry, for example:
{ "mcpServers": { "icyloom": { "command": "/path/to/venv/bin/python",
"args": ["-m", "icyloom", "mcp", "--transport", "stdio"] } } }An LLM client points its base_url at http://127.0.0.1:8150/v1.
icyloom doctor also probes each enabled upstream (/models) and checks that the tool-server executables are on the PATH. A missing upstream or a missing tool executable is a warning, not a failure: a default installation has neither, and still works. When server.remote_access_token is set, every admin and gateway route except /health requires it, and a non-loopback server.host is refused without one.
The tool cache
IcyLoom relays calls to downstream MCP servers and can cache their results. The rules:
Deny by default. Only tools set to
truein a server'scache_toolsare ever replayed from the cache. There is no guessing from the tool name. A server withcache_enabled: trueand nocache_toolscaches nothing.State epoch per server. Any call that is not cacheable (a possible write) advances that server's epoch. The epoch is part of the cache key, so a read cached before a write is never served after it. The epoch also carries a boot token: the cache does not survive a relay restart, because the server may have changed while the relay was down.
Errors are never cached. A result flagged
is_erroris not stored.Schema-guided canonicalisation. A near-identical call is recognised only according to the tool's
inputSchema: integer, number and boolean parameters, and path-like string parameters. Without a schema, only an exactly identical call matches. Never: case changes, whitespace folding inside strings, reordering of lists. Schemas are loaded whenlist_toolsis called.The loop guard counts cache hits. A loop answered from the cache is still a loop: the 5th identical call within the window is blocked.
A batch stops at the first error. The remaining calls are reported as
skipped_after_error.
tool_proxy:
servers:
- name: fetch
command: uvx
args: ["mcp-server-fetch@2026.10.10"]
cache_enabled: true
ttl_seconds: 3600 # protects against changes made outside the relay
cache_tools:
fetch: true # explicit allowlist: nothing else is cachedThe TTL is the only protection against a downstream server whose state changes outside the relay. Choose it per server.
Loading tools fast
Two things make the relay quick to use, both verified by tools\proof_tools.py:
One live session per downstream server. The server process stays alive between calls instead of being respawned for every call. The session lives in its own thread and its own event loop, because the MCP SDK opens a stdio session inside an anyio task group that must be entered and left in the same task. Measured on a local server: the first call costs ~840 ms (process start), the next ones ~21 ms — 40× faster.
The tool catalogue is cached and searchable.
proxy_info(what="tools", server=…)lists the tools of a server and keeps the result (with theinputSchema) in memory;proxy_info(what="search", query=…)then finds a tool by name or description — "git" findsgit_log, "file" findsread_file. The catalogue is also loaded automatically on the first call to an unknown tool, because the schema is what makes the near-identical recognition possible.
.\.venv\Scripts\python.exe tools\proof_tools.py # 14 checks: near-hit, no false hit, reuse, searchThe schema-guided merge is deliberately conservative: limit: 10 and limit: "10" are one and the same call (the schema declares an integer), but " 8150 " and "8150" are not merged (a string is a value — the downstream tool answered "unknown port" for the padded one).
The console (dashboard)
A web console, served by the admin API, shows all metrics with matching charts:
http://127.0.0.1:8153/dashboard (alias: http://127.0.0.1:8153/).\.venv\Scripts\python.exe -m icyloom dashboard # URL + current state
.\.venv\Scripts\python.exe -m icyloom dashboard --serve # serve the console
The console on a demo database seeded by tools/seed_demo.py (synthetic traffic) — not production data.
Reading the console
Every chart is live and interactive:
hover a bar, a point or a slice → the values appear in a tooltip;
click a point → the tooltip is pinned, and it survives the 2-second refresh;
click a legend label → that series is hidden, or shown again;
the window selector (1 h / 24 h / 7 d / 14 d) re-reads the database on the spot.
One console, two consoles fused
The console is the merge of the IcyCache console and the Loom dash, rebuilt on the
unified registry v_token_ledger and drawn in the rough-sketch style (warm paper, brown
ink, hand-drawn strokes, hatched fills, stickers, doodles).
It is an application shell, not a long scrollable page: a side panel on the left switches the view, and the content area only ever renders the view you are on.
View | Fused from | Content |
Overview | IcyCache + Loom | 5 KPIs with sparklines, the unified registry card (tokens paid / avoided / baseline, latency avoided, 35 % threshold), calls per bucket, latency p50/p95, hit/miss donut, per-model breakdown, upstreams & clients |
Activity | IcyCache | 3D traffic mountain (day × hour, drag to rotate), topographic map with isolines, hourly traffic table, latest requests |
Economy | IcyCache + Loom | 14-day curve (paid vs avoided, hatched area, dashed average, circled record), gain gauge against the 35 % line, split of the baseline per domain, economy per day |
Cache | IcyCache | most reused entries (hatched pseudo-3D bars), searchable table of every stored prompt (hash, model, provider, hits) |
Context | Loom | sessions, sources, chunks, invariants, anchors, redactions, stored sources table, sources per session |
Tools | Loom | downstream MCP servers, calls per tool, tool cache (entries, bytes, latency avoided), per-tool breakdown |
Audit | Loom | live LLM journal and tool journal, both searchable |
Guide | IcyCache Help | request-path diagram, how to read the metrics, the 13 MCP tools, shortcuts & tips, live system state |
The side panel carries the eight views (each with its own live counter), the system
actions — Pause / Refresh / Export / Compact, which really act — and a live status card
(calls, hit rate, tokens avoided, gain, ledger rows, database size). A toolbar above the
content shows the current view, the LIVE state, the measured request rate and the event
count; the control bar holds the analysis window (1 h / 24 h / 7 d / 14 d — it really
changes the query), a Reconnect button and the live database pills.
Every button is wired to a real action: Pause freezes the figures (the polling stops, the
pill turns PAUSED), Refresh and Reconnect re-query the admin API, Export downloads the
exact JSON the page is drawing, Compact shrinks the layout for a laptop screen. Keyboard
shortcuts: 1…8 switch view, R refreshes, P pauses, E exports, C compacts.
The eight views: Activity (3D mountain + topo map), Economy (curve, gauge, split),
Cache (entries, ranking), Guide (path of a request). Context, Tools and Audit complete
the set — see docs/screenshots/.
Everything is computed in real time; no value is frozen in the page:
/api/dashboardis polled every 2 s; the server keeps the snapshot fresh in a background thread, so the answer is instant (≈ 10 ms) even on a busy base;requests/min is computed between two real samples and smoothed;
each value is interpolated toward its new target, so counters scroll instead of jumping;
the window and the pause button apply immediately;
every timestamp is UTC — one single clock, from the SQLite defaults to the charts.
The data comes from a single read-only route:
GET /api/dashboard -> { kpi, config, registry, surface, series, breakdown, tables, context, recent, db }registry is the unified v_token_ledger (cache + compression + tool tax, all in tokens),
surface is the day × hour traffic grid behind the 3D mountain and the map, series holds
the time series (per hour over 24 h, per day over 14 d). GET /api/gateway relays the
gateway's live state (circuits, upstreams) from port 8150 so the page stays on a single origin.
The console is self-contained: one HTML file, hand-written SVG charts and a hand-written
sketch engine (no rough.js, no framework), no external dependency, no CDN, no network call
except /api/dashboard. The tokens shown are the real tokens reported by the upstream.
Reference screenshots (1440 × 960) live in docs/screenshots/:
overview, activity, economy, cache, context, tools, audit, guide.
The logo is src/icyloom/static/logo.svg — the same file is
served by the console at http://127.0.0.1:8153/assets/logo.svg. The mark is the flame of the old logo, now extruded in 3D: ink hatching on top,
hatched side faces, a bevelled light edge and a cast shadow on the paper.
Demo data set (fake data, isolated stacks, ports 8150-8154):
.\.venv\Scripts\python.exe tools\seed_demo.py # continuous traffic, about 4 req/s
.\.venv\Scripts\python.exe tools\check_js.py # JavaScript syntax check of the consoleThe functional test campaign
Re-run on 2026-10-28 with the current code: 88/88 checks green (report in var\campaign-report.json).
A hermetic campaign that exercises every layer on an isolated stack (ports 8160-8164, temporary database), with entirely different inputs: 24 distinct prompts, 6 distinct documents, 3 distinct markers, 3 distinct tool calls:
.\.venv\Scripts\python.exe tools\campaign.py # report + var\campaign-report.jsonIt covers the cache (variants, anti-collision, key scope), the ledger (real tokens, gain), the context drawer (byte-exact, invariants, discriminating search, isolated sessions), the tool relay, the gateway formats (OpenAI, Anthropic, SSE streaming), MCP HTTP/SSE parity, the safeguards (confirmation, concurrency) and the consistency of the console with the database. Output: one verdict per check and a non-zero exit code at the first failure.
Two blocks play the role of an agent doing real work:
N, agentic work: the agent looks up its spec in the drawer, files a real document, asks 8 really different requests (plan, risks, test, talk, threat, rollback, measure, strategy), iterates one request ("v1" then "v2"), then calls 6 distinct downstream tools and closes with an invariants check.
O, anti-mixing: interleaved requests and tools, purge, replay.
To prove that a hit returns the right answer, the campaign uses tools/echo_upstream.py: the upstream returns the fingerprint of the request it received (echo:<sha256>). An answer served from the cache therefore carries the fingerprint of its own request, never another one's.
The 21 tools
V2 — the meta-tools (gateway)
Tool | Role | Destructive action |
| selects the tools matching an intent (12 languages, lexical index) | none |
| compressed contract of one tool | none |
| runs one downstream tool through policy, cache, compression | yes, needs |
| chains calls in a sandboxed script | yes, needs |
| the policy in force: roles, scopes, approval rules | none |
| tokens per category, registry, audit | none |
| definition drift: a downstream tool changed (schema, description, behaviour) | none |
| the decision the policy would take — no side effect | none |
V1 — the base tools
Tool | Role | Destructive action |
|
|
|
| relay to downstream MCP servers, in a batch (stops at the first error) | none |
|
| none |
| purge the tool cache | yes, needs |
|
| none |
| re-reads the original bytes (byte-exact) | none |
| search the drawer | none |
| proof that no invariant was lost | none |
| loss and fidelity check | none |
|
| none |
|
|
|
|
|
|
|
| none |
Every tool carries ToolAnnotations (read-only, destructive, idempotent, open-world). A destructive action without confirm=true is refused with no side effect.
Capability map: tools and routes
(Capabilities from spec section 5. ✔ = covered and tested · ◐ = partly covered · ✘ = not implemented, announced)
Cache and network
# | Capability | Where |
A1 | OpenAI |
|
A2 | Anthropic |
|
A3 |
|
|
A4 | routing |
|
A5 | priority: URL prefix > header > body > default, plus |
|
A6 | canonical normalisation + hash |
|
A7 | LLM cache (TTL, LRU, cap) |
|
A8 | semantic cache (Qdrant) | ✘ opt-in, not implemented (config and cache key ready) |
A9 | real tokens (never estimated on the upstream side) |
|
A10 | prefix cache | ◐ |
A11 | tool relay (single + batch) |
|
A12 | tool cache: per-server TTL, deny-by-default allowlist, state epoch, no cached errors, schema-guided canonicalisation |
|
A13 | loop guard (counts cache hits) |
|
A14 | resilient pool: drain, recycle, retry |
|
A15 | circuit breaker with real re-arming |
|
A16 | WebSocket | ✘ not implemented |
A17 | REST API (health, status, metrics, cache-clear, tools, ledger...) |
|
A18 | HTML dashboard |
|
A19 | stdio / SSE / streamable-HTTP transports |
|
A20 | tool registry, assertion |
|
A21 | IcyCache's 11 tool-relay tools | merged into the 13 ( |
A22 | CLI |
|
A23 | cache warm-up ( | ✘ not implemented |
A24 | stdout = pure JSON-RPC, logs on stderr, UTF-8 forced |
|
Context
# | Capability | Where |
B1 | 17 context tools | merged into the 13 ( |
B2 | 3 profiles, |
|
B3 | invariants (numbers, paths, URLs, versions, fingerprints, ports, dates, constraints) |
|
B4 |
|
|
B5 | FTS5 drawer + search |
|
B6 | UUIDv7 sessions, TTL, isolation, purge |
|
B7 | cross-session transfer |
|
B8 | database / column encryption | ✘ not implemented |
B9 | secret redaction before storage |
|
B10 | fail-closed sandbox |
|
B11 | rate limiting |
|
B12 | JSONL audit + rotation |
|
B13 | auto-store of a tool output | ✘ not implemented (threshold exposed in the config) |
B14 | FAISS vector index | ✘ opt-in, not implemented |
B15 | admin CLI (health, stats, sessions, vacuum, purge) |
|
B16 | dashboard |
|
The ledger
A single ledger_entries table records everything that costs and everything that saves: LLM calls (real upstream tokens), cache hits, context compression, tool calls. The 35 % threshold is readable there continuously:
tokens saved / (tokens paid + tokens saved)The tokens of an LLM cache hit are the real tokens measured on the original call: they are never estimated. Compression tokens come from the local counter (tiktoken if available, otherwise an estimator), and the counter used is recorded in every entry.
Tool path: a tool-cache hit is ledgered with saved_latency_ms and the tokens actually spared (tool_tokens_saved, measured by the local counter on the cached payload). A tool-cache hit therefore saves latency and tokens: the model never re-encodes a result it already has.
Known limitations
Tool-call token savings are measured by a local counter, not by the upstream API: exact with
tiktokeninstalled, estimated otherwise. The counter used is recorded on every ledger entry. See the Status section.Compression quality is not proven. In a prototype run on a real model (carried over from earlier notes, details in
PROGRESS.md), estimated prompt tokens dropped by about 84 to 92 percent, but the model answered incorrectly: the anchor keeps only a header, the invariants and the first 800 characters, so a key line in the middle of a log was lost. Compression therefore stays opt-in; "strict" guarantees that the invariants are kept, not that the text the model sees is unchanged.The gateway cache uses one slot per key shared by JSON and streaming responses, so a streamed request can miss a hit created by the JSON one.
An upstream
ReadTimeoutduring streaming is not caught ingateway.py(around line 578) and can end a client run.The tool-cache epoch is verified on a synthetic server; a real server with both reads and writes has not been tested yet.
Downstream state that changes outside the relay is only covered by the TTL.
Design decisions
One MCP server, two HTTP processes.
mcp>=1.2,<2exposes one transport per instance: HTTP and SSE are therefore two instances built by the same function (build_server), which guarantees an identical tool surface. stdio stays a dedicated process.Own environment variables.
ICYLOOM_CONFIG,ICYLOOM_HOME,ICYLOOM_STATE_DIR. The historical names from other projects are not reused: the project is independent.Ports 8150-8153 strictly reserved, bound to
127.0.0.1; tests run on 8154-8159.One transaction per request. Cache, LLM journal and ledger are written in one transaction: three successive transactions cost about 20 ms per request, more than the gain from the cache.
Circuit breaker really re-armed: after
reset_secondsthe state becomes half-open and one probe is allowed.Upstream failover: a failing upstream no longer permanently excludes the others; the priority is never mutated during a call.
Compression off by default,
strictprofile, never lossy implicitly.Fail-closed sandbox: without an allowed directory, no command is run.
Tool cache: deny by default, with a per-server state epoch (see The tool cache).
No git repository for now: the licence is still undecided, so the project is not published. The safety net is a folder copy.
Cache hash compatibility
The normalisation engine follows the reference semantics (NFKD, lowercase, Aho-Corasick rules, number-words, diacritics, sentence punctuation). Operators are kept (12+2 is not 1+22), and volatile fields (stream, user, metadata) are excluded from the key.
Measured on the historical cache (read-only): 70 % of normalised texts coincide. The remaining 30 % were written by an earlier version of the engine that removed :, /, +, * and did not convert numbers to words. Those entries are already incompatible with the reference engine; honouring them would break compatibility with the current engine. tests/test_normalize.py measures this agreement and checks the equivalence between the fast engine and an independent naive implementation.
Tests
.\.venv\Scripts\python.exe -m pytest tests\ -q # 223 tests collected
.\.venv\Scripts\python.exe tests\proof_e2e.py # end-to-end proof
.\.venv\Scripts\python.exe tests\test_cache_correctness.py # stale-hit measurement (prints a report)
.\.venv\Scripts\python.exe tests\real_mcp_fetch.py # real MCP server; needs uvx and Internetproof_e2e.pystarts a fake upstream on 8154, launches the stack on 8150-8153, checks the 4 services, verifies the tool list over HTTP and SSE, then measures latency over 200 requests (direct / MISS / HIT) and the ledger gain. Its "50 %" gain is by construction (every request is sent twice).test_cache_correctness.pyruns a stateful fake tool server under interleaved reads and writes and compares every cached answer with the server's true state. Run it as a script to get the numbers, or through pytest for strict thresholds (zero stale hits).real_mcp_fetch.pydrives the realmcp-server-fetchthrough the relay: schema capture, MISS then HIT, integer canonicalisation, no merge across different URLs, a real error never replayed.Tests use a temporary database and never touch
var\icyloom.db. SetICYLOOM_TEST_PORTto run the suite while a stack occupies 8154.
Layout
D:\ICY-LOOM\
├── icyloom.yaml single configuration
├── pyproject.toml package (requires-python >=3.11,<3.14)
├── LICENSE MIT
├── README.md
├── PROGRESS.md what is proven, what is not, what is next
├── MERGE_PLAN.md the merge plan (IcyCache + Loom -> IcyLoom)
├── RESEARCH.md the research notes behind the choices
├── ICYLOOM_PROMPT.md the original brief
├── docs\
│ ├── INSTALL.md installation, configuration, start, troubleshooting
│ ├── TRAY.md the system tray icon, end to end
│ ├── logo.png the mark (source: src\icyloom\static\logo.svg)
│ └── screenshots\ the eight console views
├── data\
│ ├── normalization_rules.json 1122 rules (data)
│ └── tools_registry.json 100 anchors (data)
├── src\icyloom\
│ ├── cli.py doctor / paths / version / config / serve / ...
│ ├── config.py Pydantic models of the single configuration
│ ├── paths.py path resolution (no hard-coded path)
│ ├── logsetup.py logs on stderr, UTF-8 forced
│ ├── db.py single database: schema, WAL, additive migrations
│ ├── normalize.py normalisation + cache key
│ ├── cache.py LLM cache (TTL, LRU)
│ ├── upstream.py multi-upstream routing
│ ├── pool.py HTTP pool: drain -> recycle -> retry
│ ├── breaker.py circuit breaker with real re-arming
│ ├── gateway.py OpenAI/Anthropic HTTP gateway
│ ├── admin.py admin API + metrics + console + /assets/logo.svg
│ ├── dashboard.py metrics aggregate (read-only snapshot)
│ ├── static\ web console (HTML + SVG, self-contained) + logo.svg
│ ├── mcpserver.py single FastMCP instance + 13 tools
│ ├── toolproxy.py tool relay + cache (deny-by-default, epoch) + loop guard
│ ├── ledger.py single economic journal
│ ├── tokenizer.py local token counter (tiktoken or estimator)
│ ├── migrate.py additive migration (sources read-only)
│ ├── runner.py combined launcher
│ ├── tray.py system tray icon (Windows / macOS / Linux)
│ ├── autostart.py start-with-session (registry / XDG / LaunchAgent)
│ └── context\ drawer, anchors, invariants, verification, sandbox...
├── tools\
│ ├── seed_demo.py demo data set (real traffic, isolated stack)
│ ├── spread_demo.py deterministic time-spreading of the demo events
│ ├── campaign.py hermetic functional campaign (88 checks)
│ ├── check_js.py JavaScript syntax check of the console
│ ├── fake_mcp_server.py fake downstream MCP server (relay target)
│ ├── run_fake_upstream.py fake OpenAI/Anthropic upstream
│ └── proof_tools.py, report_live.py, report_tools.py, diag_norm.py, ...
├── scripts\
│ └── install-windows.ps1 one-shot install: venv, package, tray, clients
└── tests\ test suite, end-to-end proof, correctness harness, real-server testProject map
Everything points at everything else:
Document | What it answers |
What IcyLoom is, how to run it, what it measures | |
How to install it, configure it, start it, wire the MCP clients | |
How the system tray icon behaves, and how to make it start with your session | |
What is proven, what is not, what is next | |
How IcyCache and Loom were merged into one project | |
The research behind the technical choices | |
The original brief this project answers | |
MIT | |
The mark (source: | |
The eight console views, 1440 × 960 |
The console is the living version of this README: it reads the same
v_token_ledger the ledger section describes, through the same
GET /api/dashboard route.
License
MIT — see LICENSE.
Copyright (c) 2026 Malik Belkacemi.
Ownership and license
Project origin and evidence · License
Original project and documentation by Malik Belkacemi · MLKBLK-IT · © 2026
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
LLM cost optimization gateway, repo token-waste auditor & model arbitrage MCP server.
MCP gateway: one connection for your AI apps, with tool policies, PII redaction and audit logs.
AI Reasoning Cache & Consensus Layer with 11 MCP tools via Streamable HTTP.
Private-by-default, local-first memory/context/task orchestrator for MCP apps and agents.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceMCPGate aggregates multiple MCP servers into a single unified endpoint, enabling centralized tool management with granular filtering, automatic namespacing, and observability. Features a real-time web dashboard and optional PostgreSQL-backed audit trails for monitoring and controlling AI tool access across local and remote deployments.Apache 2.0
- AlicenseAqualityBmaintenanceSemantic tool-routing gateway for MCP servers that cuts 70-90% of context tokens, with RBAC, API-key auth, response caching, hot-reload config, and a real-time observability dashboard.313MIT
- AlicenseNot gradedqualityCmaintenanceSelf-hosted MCP gateway that applies deterministic, compiled policy to tool discovery, invocation, and outbound data flow, with no model in the enforcement path. Every decision emits a hash-chained receipt sealed with Ed25519 and verifiable using public keys only.Apache 2.0
- AlicenseNot gradedqualityDmaintenanceA local-first MCP server that reduces LLM token usage by intercepting, deduplicating, compressing, and optimizing MCP tool calls and responses.8 npmMIT