Ketan-OS MCP Server

README.md

# Ketan-OS 🪔 (केतन)
### The Transactional Runtime for AI Agents

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
[![Tests](https://img.shields.io/badge/tests-38%20passed-brightgreen.svg)](tests/)

[![MCP](https://img.shields.io/badge/Claude%20Code-FastMCP%20Ready-blueviolet.svg)](ketan/mcp/server.py)
[![ketan-os MCP server](https://glama.ai/mcp/servers/umang-algo/ketan-os/badges/score.svg)](https://glama.ai/mcp/servers/umang-algo/ketan-os)
[![M8ven Score](https://m8ven.ai/badge/mcp/umang-algo-ketan-os-1k4rg0)](https://m8ven.ai/mcp/umang-algo-ketan-os-1k4rg0)

---

## 🔱 Origin & Philosophy

> *"Aham ātmā guḍākeśa sarva-bhūtāśaya-sthitaḥ"*  
> — **Bhagavad Gita, Chapter 10, Verse 20**  
>  
> *"I am the Self, O Gudakesha, seated in the hearts of all beings.  
> I am the beginning, the middle, and the end of all beings."*  

**Ketan (केतन)** literally means *Banner, Beacon, or Dwelling* in Sanskrit — the fixed, unmovable point of reference from which all navigation begins.

AI agents perform complex, multi-step actions across files, commands, and external tools — but they lack **transaction semantics**. When an agent writes a malformed file, executes a destructive shell command, or acts on stale assumptions, standard agent frameworks have no rollback mechanism.

**Ketan-OS provides the transactional substrate for AI agents**:
```text
BEGIN  →  WAL JOURNAL  →  VERIFY  →  SANDBOX EXEC  →  COMMIT / ROLLBACK / COMPENSATE
```

By wrapping tool execution in content-addressed state snapshotting, durable WAL journal persistence, container sandbox isolation, pre-flight assertion guards, causal execution provenance, and prompt contradiction pruning, Ketan-OS makes agent tool execution safe, reversible, and debuggable.

---

## 🌟 Core Architectural Subsystems

| Subsystem | Component | What Ketan-OS Does |
|:---|:---|:---|
| **1. Transactional Workspace Recovery** | `KetanShadowFS` | Takes incremental, content-addressed workspace snapshots using SHA-256 blob deduplication (`blobs/<sha256>`). Reverts tracked regular workspace files to clean checkpoints. |
| **2. Durable Write-Ahead Journal (WAL)** | `TransactionJournal` | Synchronously appends transaction events (`TX_BEGIN`, `TX_COMMIT`, `TX_ROLLBACK`) to `.ketan/journal.jsonl` on disk so transactions survive process crashes & SIGKILL. |
| **3. Execution Sandbox Engines** | `LocalProcessSandbox` & `DockerContainerSandbox` | Provides isolated tool execution backends. Enforces strict canonical path confinement locally or runs commands in isolated Docker containers. |
| **4. System Compensation Drivers** | `GitCompensationDriver` & `SQLCompensationDriver` | Executes registered inverse operations (`git revert`, inverse SQL `DELETE` queries) to compensate non-filesystem mutations during rollback. |
| **5. Multi-Layer Pre-Flight Guards** | `InvariantVerifier` | Enforces strict workspace canonical path isolation (`is_relative_to(workspace_root)`), blocks symlink traversal escapes, checks Python AST syntax, and filters destructive shell patterns. |
| **6. Causal Execution Provenance DAG** | `KetanTraceGraph` | Records tool calls, checkpoints, failures, and rollbacks into a directed acyclic graph (DAG). On failure, automatically traverses the DAG backwards to explain the execution lineage. |
| **7. State Belief & Fact Store** | `EpistemicBeliefEngine` | Tracks factual assertions about workspace state. Uses type coercion (`_values_are_equivalent`) to prevent false positives and auto-prunes contradicted prompt assumptions. |

---


## 🛡️ Side-Effect Reversibility Matrix

Ketan-OS tracks tool operations across three distinct transaction recovery tiers:

| System / Target | Reversibility Tier | Recovery Strategy |
|:---|:---:|:---|
| **Local Workspace Files** | `REVERSIBLE` | Automatic content-addressed state rollback via `KetanShadowFS` |
| **Git Repositories** | `REVERSIBLE` | Automated workspace restore / branch checkpoint reversion |
| **PostgreSQL / SQL Databases** | `COMPENSATABLE` | Inverse transaction query or registered compensation handler |
| **S3 / Blob Storage** | `COMPENSATABLE` | Object versioning rollback or compensation handler |
| **GitHub / AWS / Infrastructure** | `COMPENSATABLE` | Registered API inverse call (e.g. close issue, delete resource) |
| **External Network APIs / Email** | `IRREVERSIBLE` | Pre-execution policy check & counterfactual failure hint |

---

## 📜 Formal Ketan-OS Transaction Protocol Specification

Ketan-OS formally defines the execution boundary around agent actions across four authoritative layers:

| Component Layer | Persistent Storage | Role & Guarantee |
|:---|:---|:---|
| **Write-Ahead Log (WAL)** | `.ketan/journal.jsonl` | **Authoritative Transaction State Log** — Synchronous `fsync()` record of all `BEGIN`, `EFFECT`, `COMMIT`, `ROLLBACK`, and `RECOVERED` events. |
| **Dual-Ledger Index** | `.ketan/ledger.jsonl` | **Checkpoint Index & Turn History** — $O(1)$ append-only index mapping `state_root_hash`, prompt stacks, and tool call records across steps. |
| **Workspace State Engine** | `.ketan/snapshots/<id>/manifest.json` + `.ketan/blobs/` | **Content-Addressed State Store** — Incremental workspace snapshots with JSON manifests and deduplicated file blobs. |
| **Effect Contract Engine** | `Effect(pre, action, post, inverse)` | **Observable System Mutation Contract** — Captures preconditions, postconditions, and compensation conflict detection. |

```text
              AGENT TRANSACTION LIFECYCLE
                         │
                         ▼
        ┌──────────────────────────────────┐
        │  WAL Journal (.ketan/journal)   │
        │  TX_BEGIN → TX_EFFECT → COMMIT   │
        └────────────────┬─────────────────┘
                         │
        ┌────────────────┴─────────────────┐
        │  Dual-Ledger (.ketan/ledger)    │
        │  Hash-Chained State Commitment   │
        └────────────────┬─────────────────┘
                         │
        ┌────────────────┴─────────────────┐
        │  ShadowFS (.ketan/snapshots)    │
        │  Manifest & Blob Storage         │
        └────────────────┬─────────────────┘
                         │
        ┌────────────────┴─────────────────┐
        │  Effect Contract Engine          │
        │  Pre/Postcondition Verification  │
        └──────────────────────────────────┘
```

---



## 🏗️ System Architecture

```mermaid
graph TD
    subgraph AgentLayer [" 🤖 Agent Execution Layer "]
        LLM["LLM Agent Loop
        OpenAI • Claude • LangGraph • AutoGen"]
        MCP["🔌 FastMCP Server
        Claude Code Integration"]
        Wrapper["🛡️ KetanAgentWrapper
        Tool Call Interceptor"]
        LLM -->|Tool Call| Wrapper
        MCP -->|Safe Tool Execution| Wrapper
    end

    subgraph CoreEngine [" 🪔 Ketan-OS Transactional Substrate "]
        Harness["🪔 KetanHarness
        Thread-Safe Coordinator"]

        subgraph WALJournal [" Durable WAL Journal "]
            Journal["📝 TransactionJournal
            .ketan/journal.jsonl Persistence"]
        end

        subgraph PreFlight [" Pre-Flight Guard Layer "]
            Verifier["🛡️ InvariantVerifier
            Canonical Path Confinement
            Symlink Guard + AST & Safety Rules"]
        end

        subgraph Sandboxes [" Execution Sandbox Engines "]
            Sandbox["📦 Local / Docker Sandbox Engine
            Path Confinement & Container Isolation"]
        end

        subgraph StorageLedger [" Dual-Ledger Substrate "]
            Ledger["📋 KetanLedger
            Checkpoint & Reversibility Registry"]
            ShadowFS["💾 KetanShadowFS
            Content-Addressed Workspace Recovery"]
            Ledger --> ShadowFS
        end

        subgraph Cognition [" State Belief Layer "]
            Epistemic["🧠 EpistemicBeliefEngine
            Runtime Fact Store &
            Prompt Contradiction Pruning"]
        end

        subgraph CTGSubsystem [" Causal Provenance Engine "]
            CTG["🧬 KetanTraceGraph
            Causal Execution Provenance DAG"]
            RCA["🔍 Provenance Analyzer
            Execution Lineage Explanation"]
            CTG --> RCA
        end

        subgraph TimeTravel [" Transaction Recovery & Compensation "]
            Rollback["⏱️ Rollback Controller
            Workspace State Reversion"]
            CompDrivers["🔄 System Compensation Drivers
            Git & SQL Inverse Actions"]
            Counterfactual["💡 Counterfactual Engine
            Diagnostic Hint Injector"]
            Rollback --> CompDrivers
            CompDrivers --> Counterfactual
        end
    end

    Wrapper -->|"① Intercept"| Harness
    Harness -->|"② WAL Record TX_BEGIN"| Journal
    Journal -->|"③ Pre-flight"| Verifier
    Verifier -->|"④ Pre-Flight Pass"| Epistemic
    Epistemic -->|"⑤ Checkpoint"| ShadowFS
    ShadowFS -->|"⑥ Sandbox Exec"| Sandbox
    Sandbox -->|"⑦ Execute Tool"| Execution["⚙️ Tool Execution"]

    Verifier -.->|Path / Syntax / Safety Fail| Rollback
    Execution -->|Crash / Exception| Rollback

    Execution -->|Success| Commit["🟢 WAL Commit & Record"]
    Commit --> CTG
    Commit --> Ledger

    Rollback -->|"⑧ Revert Workspace"| ShadowFS
    Rollback -->|"⑨ Execute Compensations"| CompDrivers
    Rollback -->|"⑩ Record Failure Node"| CTG
    Counterfactual -->|"⑪ Inject Hint"| LLM

    classDef agent    fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px,color:#1e1b4b
    classDef core     fill:#e0f2fe,stroke:#0284c7,stroke-width:2px,color:#0c4a6e
    classDef storage  fill:#d1fae5,stroke:#059669,stroke-width:2px,color:#064e3b
    classDef rollback fill:#ffe4e6,stroke:#e11d48,stroke-width:2px,color:#881337
    classDef ctg      fill:#fef3c7,stroke:#d97706,stroke-width:2px,color:#78350f
    classDef exec     fill:#f0fdf4,stroke:#16a34a,stroke-width:2px,color:#14532d

    class LLM,Wrapper,MCP agent
    class Harness,Verifier,Epistemic,Journal,Sandbox core
    class Ledger,ShadowFS storage
    class Rollback,CompDrivers,Counterfactual rollback
    class CTG,RCA ctg
    class Execution,Commit exec
```


---

## ⚡ Quickstart

```python
from ketan import KetanHarness, KetanAgentWrapper

# 1. Initialize Ketan-OS for your project workspace
harness = KetanHarness(workspace_dir="./my_project")
wrapper = KetanAgentWrapper(harness)

# 2. Wrap any tool with transactional protection
def write_code(args):
    with open(args["filepath"], "w") as f:
        f.write(args["content"])
    return "File written"

safe_write = wrapper.wrap_tool("write_file", write_code)

# 3. Execute — Ketan-OS handles snapshot, pre-flight, rollback automatically
result = safe_write(
    tool_args={"filepath": "main.py", "content": "def run():\n    return 42\n"},
    prompt_stack=[{"role": "user", "content": "Create main function"}]
)
print(result)
# → {"success": True, "result": "File written", "hint": ""}
# If content had a syntax error → {"success": False, "hint": "Fix SyntaxError on line 1..."}
# → workspace auto-rolled back cleanly
```

---

## 🔌 Claude Code FastMCP Integration

Ketan-OS ships a ready-to-use **FastMCP server** that gives Claude Code native tools for safe, transactional, auditable agentic coding.

### 1. Install

```bash
git clone https://github.com/umang-algo/ketan-os.git
cd ketan-os
uv pip install -e .
```

### 2. Configure Claude Code

Add to `~/.claude/claude.json`:

```json
{
  "mcpServers": {
    "ketan-os": {
      "command": "python",
      "args": ["-m", "ketan.mcp.server", "--workspace", "/absolute/path/to/your/project"]
    }
  }
}
```

---

## 🧪 Running Tests & Benchmarks

```bash
# Run unit test suite
uv run pytest tests/

# Run performance benchmark suite
uv run python examples/benchmark_ketan_performance.py
```

---

## 📜 License

MIT License. Copyright (c) 2026 umang-algo.

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.1/5.0

Scored 2026-08-02 20:35 across 15 tools

Disambiguation4/5

Most tools are clearly distinct: snapshotting, rollback, safe file writes, safe bash, invariant checks, CTG, beliefs, and file operations all target unique actions. The only overlap is between get_status and session_summary, both providing session state, but at different detail levels (quick report vs comprehensive markdown), so agents can distinguish them with care.

Naming Consistency4/5

All tools share the ketan_ prefix and use snake_case, with a dominant verb_noun pattern (get_status, list_files, write_file_safe). Minor deviations include one-word verbs (snapshot, rollback) and session_summary lacking a verb, but the pattern is predictable and readable overall.

Tool Count4/5

With 15 tools, the server sits at the upper edge of the well-scoped range. Each tool earned its place in the workspace-protection workflow, though get_status and session_summary are slightly redundant, making the count marginally heavier than necessary.

Completeness4/5

The tool surface covers the full lifecycle: initialization, atomic snapshots, rollback, guarded mutations, invariant checks, causal tracing, failure explanation, and belief tracking. Minor gaps exist, such as no explicit checkpoint deletion or belief retraction, but these are workaroundable and do not block core workflows.

Maintenance

ActivityMaintained

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers