# Deterministic Logic Evaluation MCP Toolkit (`deterministic-logic-mcp`)

A Model Context Protocol (MCP) server providing high-performance, deterministic logic evaluation tools for AI assistants and automated systems.

## Features & Logic Engines

1. **Propositional Logic & AST Evaluator**: Parse and evaluate boolean expressions with full variable mapping. Supports `&&`, `||`, `!`, `^` (XOR), `=>` (IMPLIES), `<=>` (IFF), and custom operator notation.
2. **Truth Table Generator**: Compute complete $2^N$ truth tables, check tautologies, contradictions, and satisfiability.
3. **DPLL SAT Solver**: Convert formulas to Conjunctive Normal Form (CNF) and find satisfying variable assignments or prove UNSAT.
4. **JSON Logic Rule Engine**: Deterministic evaluation of structured rules (boolean, arithmetic, comparison, array filters/maps, conditional branching) against JSON datasets.
5. **Decision Table Engine**: Grid-based rule evaluation with support for wildcards, `first_match`, `all_matches`, and `strict_single_match` (determinism verification).
6. **State Machine Analyzer & Verifier**: Check Finite State Machines (FSMs) for determinism, deadlocks, unreachable states, and state reachability path extraction.

---

## 🛠️ MCP Tools Reference

| Tool Name | Description | Key Arguments |
|---|---|---|
| `evaluate_boolean` | Evaluates a boolean logic expression with variable values | `expression`, `env` |
| `generate_truth_table` | Generates full truth table & computes Tautology / Contradiction | `expression`, `maxVariables` |
| `solve_sat` | DPLL SAT solver returning satisfying variable assignment or UNSAT | `expression` |
| `evaluate_json_logic` | Evaluates JSON logic rules against context JSON data | `rule`, `data` |
| `evaluate_decision_table` | Evaluates matrix decision table rules with determinism checks | `rows`, `inputs`, `mode` |
| `analyze_state_machine` | Checks FSM for determinism, deadlocks, and unreachable states | `initialState`, `transitions`, `terminalStates` |
| `verify_state_reachability` | Finds shortest execution path to target state in FSM | `initialState`, `transitions`, `targetState` |
| `simulate_state_machine` | Simulates an input sequence through an FSM step-by-step | `initialState`, `transitions`, `inputSequence` |

---

## 🚀 Quickstart & Setup

### Building Locally

```bash
npm install
npm run build
npm test
```

### Configuring in MCP Clients (e.g. Claude Desktop, Cursor, AGY)

Add the following to your `mcpServers` configuration file (e.g. `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "deterministic-logic": {
      "command": "node",
      "args": ["/home/mrovkill/Projects/deterministic-logic/dist/index.js"]
    }
  }
}
```

Or run directly via `npx` / `tsx`:

```json
{
  "mcpServers": {
    "deterministic-logic": {
      "command": "npx",
      "args": ["tsx", "/home/mrovkill/Projects/deterministic-logic/src/index.ts"]
    }
  }
}
```

---

## 💡 Example Tool Usage

### 1. Truth Table Generation
**Input:** `expression = "A => (B => A)"`  
**Output:** `isTautology = true`, `isSatisfiable = true`, `truthTable` rows showing all evaluated combinations.

### 2. DPLL SAT Solving
**Input:** `expression = "(A || B) && (!A || B) && (!B)"`  
**Output:** `satisfiable = false` (UNSAT).

### 3. JSON Logic Rule Execution
**Input:**
```json
{
  "rule": {
    "and": [
      { ">": [{ "var": "user.age" }, 18] },
      { "in": [{ "var": "user.role" }, ["admin", "editor"]] }
    ]
  },
  "data": { "user": { "age": 25, "role": "admin" } }
}
```
**Output:** `result = true`.

---

## 📄 License

MIT