mcp-osiris 0.1.0__tar.gz

mcp_osiris-0.1.0/.gitignore

@@ -0,0 +1,37 @@
+# Environnement virtuel isolé
+.venv/
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+
+# Outils
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+coverage.xml
+htmlcov/
+
+# Données runtime (conservées localement, non versionnées)
+data/*
+!data/.gitkeep
+
+# Secrets
+.env
+.env.*
+
+# Packaging / publication
+node_modules/
+*.egg-info/
+dist/
+npm/*.tgz
+
+# Sauvegardes et logs locaux (jamais dans la distribution)
+*.bak*
+_backup_*/
+_livetest/
+*.log
+

mcp_osiris-0.1.0/AGENTS.md

@@ -0,0 +1,118 @@
+# AGENTS.md — OSIRIS
+
+## ⛔ Règle de périmètre — PRIORITÉ ABSOLUE
+
+**Ce projet est 100% AUTONOME. Ne jamais toucher aux autres projets de l'utilisateur.**
+
+Interdits absolus, sans exception ni autorisation implicite :
+
+- ❌ Modifier, refactorer, restructurer, migrer, renommer ou supprimer un autre projet
+- ❌ `pip install` d'un autre projet de l'utilisateur (ex. `loom-mcp`) ou dépendance par chemin
+- ❌ `import` d'un module d'un autre projet
+- ❌ Référencer un chemin absolu vers un autre dossier de projet
+- ❌ Partager une base de données, un schéma ou un fichier avec un autre projet
+- ❌ Proposer ou appliquer une « absorption », « fusion » ou « migration » d'un autre projet
+- ❌ Modifier la configuration MCP globale (`C:\Users\Tech\.minimax\mcp.json`) sans accord explicite
+
+Projets existants protégés : `D:\Loom`, `D:\AI-Stack` (SuperLocalMemory),
+`D:\CacheForge`, `D:\IcyCache`, `D:\MCP`, `D:\MCP_TEST` — et tout autre dossier
+du disque hors de `D:\MCP-Osiris`.
+
+**Zone d'écriture autorisée : `D:\MCP-Osiris` uniquement.**
+
+L'inspection **en lecture seule** d'un projet existant doit être **demandée**,
+jamais présumée. En cas de doute, demander avant de lire.
+
+---
+
+## Ce qui est autonome ici
+
+Tout le code est écrit from scratch dans `src/osiris/`. Les seules dépendances
+autorisées sont des **paquets PyPI publics** : `mcp`, `fastmcp`, `pydantic`,
+`httpx`, `PyYAML`, `rich`, `tiktoken`.
+
+| Besoin | Implémentation locale |
+|---|---|
+| Comptage de tokens | `core/tokens.py` (tiktoken, repli heuristique) |
+| Stockage des refs | `core/refs.py` (SQLite local, content-addressed) |
+| Masquage des secrets | `core/redact.py` (avant le hash) |
+| Lecture de fichiers | `core/fileops.py` (sandbox, racines autorisées) |
+| Mémoire typée | `core/memory.py` + `core/task_state.py` |
+| Journal / checkpoints | `core/events.py` |
+| Coût / économies | `core/ledger.py` |
+| Cache / drift | `core/prefix.py` |
+| Filtrage serveur des payloads | `core/query.py` (grep, range, outline, aggregate, jsonl) |
+| Compaction (trim/compact/clear) | `core/compaction.py` |
+| Pression contexte | `core/pressure.py` |
+| Anti-boucle | `core/loopguard.py` |
+| Invariants | `core/invariants.py` |
+| Handoff | `core/handoff.py` |
+
+---
+
+## Invariants du produit (à ne pas casser)
+
+1. **Le prune déplace, il ne supprime jamais.** Il n'existe aucun chemin de code
+   qui supprime un payload. C'est ce qui rend la preuve LOSSLESS possible.
+2. **Les décisions et les contraintes sont append-only, et leur réécriture est
+   détectée.** Elles vivent dans la queue (`tail_hash`), pas dans le head :
+   les ajouter ne doit **jamais** déclencher un drift critique (le prefixe
+   cache est intact). Réécrire un élément épinglé est détecté par comparaison
+   des collections elles-mêmes (`core/prefix.py::rewritten_pins`) et signalé
+   comme rupture **sémantique** (`verdict: critical`, `cause: pinned_rewrite`,
+   `semantic_break: true`). Le cache n'est pas invalidé, l'état de la tâche si.
+   *Avant correction, les contraintes étaient dans le head et la réécriture
+   d'une décision n'était pas détectée du tout : l'invariant n°2 était
+   documentaire, pas implémenté.*
+3. **L'agent ne calcule jamais de hash.** Il transmet les arguments bruts ;
+   OSIRIS canonicalise et digeste.
+4. **Les réponses des outils restent courtes.** Garde-fou dans
+   `tests/test_mcp_tools.py` : `plan` < 260 tokens, `observe` < 110,
+   `checkpoint` < 110. OSIRIS ne doit pas devenir un consommateur de contexte.
+5. **Le surcoût d'OSIRIS est mesuré** (ledger kind `overhead`) et le gain net
+   est exposé dans le rapport. Si le net est négatif, `osiris.plan` prévient
+   l'agent.
+6. **Aucun prix provider n'est codé en dur** : la table de prix vient de
+   `~/.osiris/pricing.json`.
+7. **Le TTL du cache est un paramètre**, pas une dépendance provider. Le TTL
+   est **déterministe** : `P(cache_mort)` est un seuil (0 avant, 1 après), pas
+   une rampe `Δt/TTL`.
+8. **Déplacé ≠ gagné.** `tokens_moved` = payload déplacé vers un ref ;
+   `tokens_saved` = tokens dont la sortie du contexte est **prouvée** par
+   l'accusé de réception de l'agent (`observe(kind="dropped")`). Invariant
+   garanti par un test : `tokens_saved ≤ tokens_in`.
+9. **Le tableau `tools` exposé ne change pas** (6 outils, ou 1 en mode
+   `OSIRIS_DISPATCH_ONLY=1`) : il fait partie du prefixe mis en cache.
+10. **Un serveur MCP ne peut pas compacter la fenêtre de l'hôte** : OSIRIS
+    fournit les artefacts (`compact`/`trim`/`clear`, resources), la réduction
+    reste une décision de l'hôte.
+
+---
+
+## Environnement
+
+- Venv : `D:\MCP-Osiris\.venv` (CPython 3.12.10, via `uv`)
+- Interpréteur : `.venv\Scripts\python.exe`
+- Ne jamais installer dans le Python système.
+- `OSIRIS_HOME` par défaut : `~/.osiris`. Pour un essai isolé :
+  `OSIRIS_HOME=D:\MCP-Osiris\data\home`.
+
+## Commandes
+
+```powershell
+.venv\Scripts\python.exe -m pytest tests -q         # 76 tests
+.venv\Scripts\python.exe -m ruff check src tests bench scripts
+.venv\Scripts\python.exe -m osiris health
+.venv\Scripts\python.exe scripts\smoke_stdio.py     # E2E stdio
+.venv\Scripts\python.exe bench\run_bench.py         # benchmark + rentabilité
+```
+
+## Cycle de développement
+
+1. Modifier dans `src/osiris/`.
+2. `pytest` doit rester vert (76 tests) et `ruff check` propre.
+3. Si le comportement des outils change : mettre à jour `README.md` (section
+   correspondante) et `tests/test_mcp_tools.py`.
+4. Ne jamais casser la preuve LOSSLESS (`tests/test_audit.py`).
+5. Ne jamais publier un chiffre qui ne sort pas de `bench/run_bench.py` : le
+   README §12 est regénéré depuis la sortie réelle, pas recopié.

mcp_osiris-0.1.0/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-10-31
+
+First public release.
+
+### Added
+
+- **6 MCP tools** (`plan`, `precheck`, `observe`, `recall`, `checkpoint`, `handoff`),
+  stable table (invariant: the exposed tool array never changes, it is part of
+  the cached prefix).
+- **Server-side payload filtering** (`recall(op=…)`): `grep`, `range`, `head`,
+  `tail`, `outline`, `aggregate`, `jsonl` — the agent only pays for the slice
+  it selects, not for the whole payload.
+- **Honest ledger**: `tokens_moved` (payload relocated to a ref) is tracked
+  separately from `tokens_saved` (proved by the agent's withdrawal
+  acknowledgement or by a measured filtered access). Enforced invariant:
+  `tokens_saved ≤ tokens_in + tokens_moved`.
+- **Cache-aware pruning**: the prune moves, never deletes; `cache_mort_probability`
+  is a threshold (0 before TTL, 1 after), and the elapsed time is measured from
+  the event journal.
+- **Append-only decision/constraint queue** with rewrite detection
+  (`verdict: critical`, `cause: pinned_rewrite`, `semantic_break: true`).
+- **LoopGuard** (duplicate and loop protection), **precheck** (invariants,
+  budget, duplicate refusal with `suggest_alternative`).
+- **Context pressure** (`plan(mode="status")`), **reversible compaction**
+  (`checkpoint(mode="compact"|"trim"|"clear")`).
+- **MCP resources** (`osiris://task/{task_id}/manifest`, `osiris://task/{task_id}/status`,
+  `osiris://ref/{ref}`) and the `osiris/task-resume` prompt.
+- **Control Plane dashboard** (`osiris-dashboard`): live KPIs, ledger, integrity.
+- **Verified benchmarks** (`bench/run_bench.py`): the README §10 table is
+  regenerated from the real bench output, never hand-written.
+
+### Notes
+
+- Measured on the reference machine: +15 % (800 tok prompt) to +71 % (20 000 tok
+  prompt) net context reduction; access cost 1 019 tokens of tool schemas.
+- A server-side filter cannot replace an LLM, and an MCP server cannot shrink
+  the host's context window retroactively: OSIRIS provides the artefacts, the
+  host decides.

mcp_osiris-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Malik Belkacemi (MLKBLK-IT)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_osiris-0.1.0/PKG-INFO

@@ -0,0 +1,384 @@
+Metadata-Version: 2.5
+Name: mcp-osiris
+Version: 0.1.0
+Summary: OSIRIS — context engine cache-aware pour agents IA (serveur MCP local, provider-agnostic).
+Project-URL: Homepage, https://github.com/MlkBlk-IT/osiris
+Project-URL: Repository, https://github.com/MlkBlk-IT/osiris
+Project-URL: Issues, https://github.com/MlkBlk-IT/osiris/issues
+Project-URL: Changelog, https://github.com/MlkBlk-IT/osiris/blob/main/CHANGELOG.md
+Author: Malik Belkacemi
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,context-engine,cost,mcp,memory,osiris,prompt-cache
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Requires-Dist: fastmcp>=2.0.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp>=1.2.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: tiktoken>=0.7.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.5.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/MlkBlk-IT/osiris/main/docs/mlkblk-banner-v2.svg" width="100%" alt="OSIRIS — Cache-aware context engine & state governor for AI agents" />
+</p>
+
+# OSIRIS
+
+**Cache-aware context engine & state governor for AI agents.** Standard MCP server, local-first, independent of any model provider.
+
+> OSIRIS makes AI agents cheaper, faster, and more reliable: fewer tokens, fewer loops, zero unnecessary tools, and zero loss of context.
+
+OSIRIS does not replace your other MCP servers (filesystem, Git, GitHub, shell, browser…). It **coexists** alongside them and drastically cuts what they cost in prompt context.
+
+---
+
+## 1. The Core Architectural Constraint
+
+An MCP server **never sees** the final prompt assembled by the client host. It only sees what the agent sends to it. Therefore, OSIRIS cannot:
+
+| What we would want | What a standard MCP server can actually do |
+|---|---|
+| Write directly into the prompt | Produce canonical state and **have the agent carry it** |
+| Erase past conversation turns | Decide what to externalize **for future turns** |
+| Hide another MCP server's tools | **Recommend** via Tool Compass |
+| Hard-cap prompt tokens | Block an **action** (invariants, budget enforcement) |
+
+The promise is honest: OSIRIS provides **stable state and an enforceable safety contract**, not a client prompt builder.
+
+---
+
+## 2. Sealed Manifest — The Core Design
+
+`osiris.plan` returns a deterministic block (~120 tokens) that the agent carries at a fixed position in its context window:
+
+```text
+OSIRIS/1 task=7c3f obj="fix PowerShell profile bug" plan=3/7
+inv=4 files=6 refs=9 dec=2 budget=ok
+SEAL=sha256:3f9a1c…c21b
+```
+
+The `SEAL` is a SHA256 digest of stable zones. The agent passes it on every turn to `osiris.observe`: OSIRIS recomputes and detects any state drift immediately.
+
+**This is OSIRIS's passive transport**: even if the agent stops calling tools, it carries the essential state cleanly.
+
+### Three Hashes Because Prompt Cache is Prefix-Based
+
+```
+head_hash   = sha256(system_head ‖ rules)                       immutable
+zoneB_hash  = sha256(objective ‖ global_plan ‖ tool_contract)   quasi-stable
+tail_hash   = sha256(constraints ‖ pinned_decisions)           append-only
+prefix_hash = sha256(head_hash ‖ zoneB_hash)                   ← cached prefix
+zoneA_hash  = sha256(head_hash ‖ tail_hash)                    ← full ZONE A
+```
+
+| Change | Verdict | Cache Cost |
+|---|---|---|
+| `head_hash` | **CRITICAL DRIFT** | Full re-prefill |
+| `zoneB_hash` | Minor drift | Re-prefill delta only |
+| `tail_hash` (append) | **Normal growth** | Re-prefill delta only |
+| Pinned item **rewritten** | **CRITICAL DRIFT (semantic)** | Cache intact, task state corrupted |
+
+> **Appending** a constraint or decision changes `tail_hash` but **not** `prefix_hash`: the prompt cache holds, only the new tokens are prefilled.
+>
+> **Rewriting** a pinned decision is explicitly caught: OSIRIS checks collection identity, flagging a semantic break (`semantic_break: true`, `cause: pinned_rewrite`).
+
+---
+
+## 3. The 6 MCP Tools
+
+Access footprint: **1,019 tokens** of schemas and descriptions in model context (measured via `bench/run_bench.py`). Paid on task start, amortized across the session — pays off on the very first turn with ≥800 token payloads.
+
+| Tool | Role | Typical Response |
+|---|---|---|
+| `osiris.plan` | Start / update / resume / status of a task; produces sealed manifest | ~160 tok |
+| `osiris.precheck` | Authorize or deny an action (invariants, budget, deduplication) | ~70 tok |
+| `osiris.observe` | Log actions, loop detection, offload large data, update memory | ~50 tok |
+| `osiris.recall` | Rehydrate refs (**server-side filtered**: grep, range, outline) | variable |
+| `osiris.checkpoint` | Snapshot, resume, completion report, reversible compaction | ~80 tok |
+| `osiris.handoff` | Executable delegation contracts and structured results | ~200 tok |
+
+`osiris.observe` combines logging, loop protection, payload externalization, memory registry, and automated pruning in a single call so the agent always reports back seamlessly.
+
+### Extended Operations
+
+| Call | Behavior |
+|---|---|
+| `osiris.observe(kind="dropped", result=<ref>)` | **Drop receipt**: agent confirms payload was evicted from prompt → token savings are **proven** and credited |
+| `osiris.observe(kind="head"\|"contract", result=…)` | Records system prompt head / client contract and detects cache-busting volatile tokens (timestamps, UUIDs) |
+| `osiris.recall(op="grep"\|"range"\|"head"\|"tail"\|"outline"\|"aggregate"\|"jsonl")` | **Server-side filtering**: only requested matches enter the context window |
+| `osiris.plan(mode="status")` | Context pressure breakdown (measured vs declared vs unknown) |
+| `osiris.checkpoint(mode="compact"\|"trim"\|"clear")` | Reversible session compaction preparation |
+| `osiris.precheck` → `suggest_alternative` | Active collision resolution for duplicate operations |
+
+### Resources & Prompts
+
+- `osiris://task/{task_id}/manifest` — Active zones, drift status, objective
+- `osiris://task/{task_id}/status` — Real-time context pressure
+- `osiris://ref/{ref}` — Raw byte content of any referenced payload
+- Prompt `osiris/task-resume` — Clean agent recovery template after crashes
+
+---
+
+## 4. Architecture
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│  Agent (Claude Code, Cursor, MiniMax Code, Codex, Cline…)   │
+│  Context: system │ tools │ OSIRIS MANIFEST │ history         │
+└───────────────────────────┬──────────────────────────────────┘
+                            │  MCP stdio — 6 tools, ~1,019 tok schema
+                            ▼
+┌──────────────────────────────────────────────────────────────┐
+│  osiris-mcp  (server.py)                                     │
+│  plan · precheck · observe · recall · checkpoint · handoff   │
+└───────────────────────────┬──────────────────────────────────┘
+                            │
+┌───────────────────────────▼──────────────────────────────────┐
+│  core/                                                        │
+│   task_state  Typed TaskState (objective, plan, decisions)    │
+│   memory     Typed memory registry by kind and scope         │
+│   refs       Content-addressed store (verified on read)      │
+│   prefix     Zones, 3-hash system, drift, PrefillPlan        │
+│   prune      Reversible externalization, 4 modes             │
+│   query      Server-side payload filtering (grep, range...)  │
+│   compaction trim / compact / clear (lossless)               │
+│   pressure   Context pressure metrics & tracking             │
+│   loopguard  Fingerprinting, 5 loop patterns detection       │
+│   invariants TOML rule engine (guard rails)                  │
+│   compass    Tool Compass (dynamic relevance scoring)        │
+│   handoff    Executable agent delegation contracts           │
+│   events     Append-only event journal + checkpoints         │
+│   ledger     Tokens / cost / savings / OSIRIS overhead       │
+│   fileops    Sandboxed file inspection (roots, size limits)  │
+│   redact     Secret scrubbing before any hashing             │
+│   policy     Budget policies & token enforcement             │
+└───────────────────────────┬──────────────────────────────────┘
+                            ▼
+        ~/.osiris/osiris.db  +  ~/.osiris/reports/
+```
+
+---
+
+## 5. Memory Model
+
+Deterministic, typed, content-addressable memory — **not** an opaque vector database.
+
+```
+TaskState
+├── objective      immutable
+├── constraints[]  append-only
+├── decisions[]    append-only, pinned verbatim
+├── plan           completed / active / remaining steps
+├── files{}        path, SHA-256 hash, mtime, last access, ref
+├── tool_results{} cache_key, ref, size, token cost, TTL
+├── failures{}     error signature, tool, args hash, attempts, lesson
+├── lessons[]      general behavioral rules learned
+├── handoffs{}     cross-agent delegation contracts
+└── budget         estimated vs consumed tokens and cost
+```
+
+Scopes: `task` → `project` → `agent` → `global`.
+
+---
+
+## 6. Cache-Aware Pruning
+
+**Security Invariant: Pruning moves payload data to content-addressed refs (`mem://sha256:…`). It NEVER deletes.**
+
+```
+ZONE_A_pruning_cost = pruned_tokens
+ZONE_C_or_D_pruning_cost = 0                      ← always zero cost
+net_savings = pruned_tokens − (prefix_tokens × P(cache_dead) × prefix_pruned)
+```
+
+| Mode | Trigger | Evicts | Cache Impact | Use Case |
+|---|---|---|---|---|
+| `cache_ttl` (default) | `Δt > TTL` | C/D, and A/B only if cache expired | Neutral | **Recommended default** |
+| `conservative` | Very high threshold | Working zone (C/D) only | Zero | High-cost API models |
+| `balanced` | Moderate threshold | C/D + cold historical turns | Zero | Standard agent workflows |
+| `aggressive` | Low threshold | Everything rehydratable | Minor prefill risk | Fast local LLMs |
+
+---
+
+## 7. LoopGuard Protection
+
+```
+fingerprint = sha256(tool ‖ canonical_args ‖ result_signature)
+```
+
+| Detection | Trigger Signal | Verdict |
+|---|---|---|
+| Exact duplicate | Identical fingerprint | `suggest_alternative` |
+| Repeated failure | Same error signature (≥3 times) | `block` + `required_action` |
+| Loop pattern | Same error across varying args | `warn` |
+| Oscillation | Alternating A/B/A/B pattern | `warn` |
+| Runaway | N calls with zero state progress | `warn` / `block` |
+
+---
+
+## 8. Invariants (Guard Rails)
+
+Define project safety rules in `.osiris/invariants.toml`:
+
+```toml
+[[invariant]]
+id = "tests-before-commit"
+when = { tool = "git.commit" }
+require = { state = "tests_passed" }
+message = "Cannot commit while tests are failing"
+
+[[invariant]]
+id = "no-test-edit"
+when = { path_glob = "tests/**" }
+verdict = "block"
+message = "Modifying test suites requires explicit approval"
+```
+
+---
+
+## 9. Lossless Verification & Non-Loss Proof
+
+OSIRIS guarantees full auditability for offloaded data:
+
+1. **Self-verifying refs**: `mem://sha256:<hash>`. Reads re-verify data integrity against the hash before returning.
+2. **Zero deletion paths**: data is relocated to the local store, never pruned permanently.
+3. **Reproducible audit**:
+   ```bash
+   python -m osiris audit --task <task_id>
+   ```
+   Outputs cryptographic proof of non-loss:
+   ```json
+   {"lossless": true, "items_externalized": 14, "items_verified": 14, "items_missing": 0, "integrity_violations": []}
+   ```
+
+---
+
+## 10. Verified Benchmarks
+
+Real measurements from `python bench\run_bench.py` running an automated coding workflow:
+
+| Payload Size | Baseline Context | Fixed OSIRIS | Adaptive OSIRIS | Net Improvement | OSIRIS Mode | Overhead |
+|---|---|---|---|---|---|---|
+| **200 tok** | 1,583 | 2,687 | **1,651** | **−4.30%** | bystander | 34 tok |
+| **800 tok** | 3,851 | 3,755 | **3,261** | **+15.32%** | light | 1,810 tok |
+| **2,000 tok** | 9,015 | 5,229 | **5,233** | **+41.95%** | standard | 2,492 tok |
+| **5,000 tok** | 20,979 | 8,171 | **8,168** | **+61.07%** | standard | 2,439 tok |
+| **20,000 tok** | 82,135 | 23,427 | **23,440** | **+71.46%** | full | 2,422 tok |
+
+- **Access Cost**: 1,019 tokens of schemas, amortized across session tasks.
+- **Session Net Gate**: PASS (Worst-case net across full suite: **+951 tokens**).
+- **At 20,000 tokens**: **+71.46% net savings** on context usage.
+
+---
+
+## 11. Quick Start
+
+```powershell
+cd D:\MCP-Osiris
+uv venv --python 3.12 .venv
+uv pip install --python .venv\Scripts\python.exe -e ".[dev]"
+```
+
+### CLI Verification
+
+```powershell
+.venv\Scripts\python.exe -m pytest tests -q        # Run test suite (76 passed)
+.venv\Scripts\python.exe -m ruff check src tests    # Code linting
+.venv\Scripts\python.exe -m osiris health           # Server health check
+.venv\Scripts\python.exe -m osiris audit --task t_1 # Cryptographic non-loss proof
+.venv\Scripts\python.exe bench\run_bench.py         # Reproduce benchmarks
+```
+
+### Registration as MCP Server
+
+Add to your client configuration (`mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "osiris": {
+      "command": "D:\\mcp-osiris\\.venv\\Scripts\\python.exe",
+      "args": ["-m", "osiris"],
+      "env": {
+        "OSIRIS_HOME": "C:\\Users\\Tech\\.osiris",
+        "OSIRIS_ROOTS": "D:\\mcp-osiris"
+      }
+    }
+  }
+}
+```
+
+---
+
+## 12. Installation
+
+### From PyPI (recommended)
+
+```bash
+pip install mcp-osiris          # or: uv pip install mcp-osiris
+mcp-osiris                      # runs the MCP server on stdio
+osiris health                   # CLI verification
+osiris-dashboard --port 8770    # Control Plane (dashboard)
+```
+
+### From npm (no Python setup)
+
+```bash
+npx -y osiris-mcp
+```
+
+The npm package is a stdio launcher. It resolves the Python runtime in this
+order — `OSIRIS_PYTHON` → `uvx` → `python3` → `python` — and runs the PyPI
+package `mcp-osiris`.
+
+### From source
+
+```powershell
+git clone https://github.com/MlkBlk-IT/osiris.git
+cd osiris
+uv venv --python 3.12 .venv
+uv pip install --python .venv\Scripts\python.exe -e ".[dev]"
+```
+
+### MCP client configuration
+
+```json
+{
+  "mcpServers": {
+    "osiris": {
+      "command": "npx",
+      "args": ["-y", "osiris-mcp"],
+      "env": {
+        "OSIRIS_HOME": "~/.osiris",
+        "OSIRIS_ROOTS": "/path/to/project"
+      }
+    }
+  }
+}
+```
+
+| Variable | Default | Role |
+|---|---|---|
+| `OSIRIS_HOME` | `~/.osiris` | SQLite database, reports, caches |
+| `OSIRIS_ROOTS` | *(empty)* | Roots allowed for file reading (`;` separated) |
+| `OSIRIS_CACHE_TTL_S` | `300` | Cache TTL (seconds) |
+| `OSIRIS_PRUNE_THRESHOLD_TOKENS` | `40000` | Prune threshold |
+| `OSIRIS_DISPATCH_ONLY` | `0` | `1` → exposes only `osiris.call` |
+
+---
+
+## License
+
+MIT © 2026 Malik Belkacemi (MLKBLK-IT)