<div align="center">
  <h1>Interlock</h1>
  <p><strong>A zero-trust Model Context Protocol (MCP) server that gives AI agents native, governed access to desktop CAD, EDA, and SPICE tools.</strong></p>

  [![Python 3.11+](https://img.shields.io/badge/Python-3.11%2B-blue.svg?style=flat-square&logo=python&logoColor=white)](https://www.python.org/)
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](LICENSE)
  [![MCP 2025-06-18](https://img.shields.io/badge/MCP-2025--06--18-orange.svg?style=flat-square)](https://modelcontextprotocol.io)
  [![Status: Beta](https://img.shields.io/badge/Status-Beta-yellow.svg?style=flat-square)](https://github.com/IamOumarIbrahim/interlock-mcp)
</div>

<br />

> [!IMPORTANT]
> **Zero-Trust Safety Boundary**: Interlock runs entirely on your local machine. Every mutating action is deny-by-default, staged against a shadow copy, and diffed in domain-real terms before committing to disk.

```json
// Add to Claude Desktop configuration (claude_desktop_config.json)
{
  "mcpServers": {
    "interlock": {
      "command": "uvx",
      "args": ["interlock-mcp", "serve", "--policy", "/path/to/interlock.policy.yaml"]
    }
  }
}
```

<br />

## Repository About & Topics

### About
A zero-trust Model Context Protocol (MCP) server that gives AI agents native, governed access to the CAD, EDA, and SPICE tools already installed on your machine.

### Topics / Tags
`mcp` · `model-context-protocol` · `zero-trust` · `cad` · `eda` · `spice` · `freecad` · `kicad` · `ngspice` · `ltspice` · `fusion360` · `governance` · `security` · `python`

---

## Table of Contents
- [What is Interlock?](#what-is-interlock)
- [Key Features](#key-features)
- [System Architecture](#system-architecture)
- [Mathematical / Technical Formulation](#mathematical--technical-formulation)
- [Setup & Installation](#setup--installation)
- [Connecting to AI Clients](#connecting-to-ai-clients)
- [How to Use](#how-to-use)
- [Reference Tables](#reference-tables)
- [Benchmarks / Comparisons](#benchmarks--comparisons)
- [Scope & Limitations](#scope--limitations)
- [File Structure](#file-structure)
- [Troubleshooting](#troubleshooting)
- [Deployment & GitHub Release](#deployment--github-release)
- [Security Policy](#security-policy)
- [Code of Conduct](#code-of-conduct)
- [Contributing](#contributing)
- [License](#license)
- [Acknowledgments](#acknowledgments)

---

## What is Interlock?

Interlock sits between an MCP client (Claude Desktop, Claude Code, or any MCP host) and desktop engineering software (FreeCAD, KiCad, ngspice). It exposes one normalized MCP interface so an agent can sketch parts, route PCBs, or run SPICE simulations without ungoverned, destructive access.

Instead of granting raw macro or IPC access, Interlock enforces policy governance:
- **Deny-by-Default Grants**: Capabilities remain disabled until explicitly enabled in `interlock.policy.yaml`.
- **Git-Style Staging**: Mutating tool calls operate on a shadow copy; live files remain untouched until an explicit commit.
- **Domain-Aware Diffing**: Outputs structural deltas (solids/volume for CAD, nets/tracks for EDA, elements for SPICE) rather than text or binary diffs.

---

## Key Features

- **Non-Downgradable Destructive Tier**: `destructive`-tier capabilities (e.g. `cad.delete_feature`, `eda.delete_track`, `fs.write_file`) are strictly `approval-required`. Policy loading fails if set to `auto`.
- **Local-First Processing**: Sockets, subprocesses, and file operations remain 100% local on host hardware.
- **SQLite Audit Store**: Every tool call, domain diff, timestamp, decision, and SHA-256 diff hash is logged to `.interlock/audit.db`.
- **In-Chat Approval & CLI Fallback**: Inline review via `elicitation/create` or terminal fallbacks (`interlock approve <session-id>`, `interlock reject <session-id> --reason "..."`).
- **Path Scoping**: Restricts access strictly inside `project_root`. Deny rules (`file_scope.deny`) take precedence over allow rules.

---

## System Architecture

Interlock proxies communication between MCP clients and local engineering binaries:

```mermaid
graph TD
    Client["MCP Client (Claude Desktop / CLI)"] -->|JSON-RPC 2.0 stdio/HTTP| PolicyEngine["Interlock Policy Engine"]
    PolicyEngine -->|Policy Check| DiffEngine["Sandbox & Diff Engine"]
    DiffEngine -->|Log Event & Hash| AuditStore[("SQLite Audit Store .interlock/audit.db")]
    DiffEngine -->|Staged Automation| Adapters["Adapter Layer (FreeCAD / KiCad / ngspice / Workspace)"]
    Adapters -->|Local Sockets & SCLI| LocalTools["Host Engineering Tools & Files"]

    classDef default fill:#0f172a,stroke:#3b82f6,stroke-width:2px,color:#fff;
    classDef process fill:#1e1b4b,stroke:#a855f7,stroke-width:2px,color:#fff;
    class PolicyEngine,DiffEngine process;
```

> [!NOTE]
> **Security Boundary**: Downstream tool capabilities are categorized by risk tier in adapter manifests (`safe`, `mutating`, `destructive`). Risk tiers are enforced independently by Interlock's policy engine.

---

## Mathematical / Technical Formulation

### 1. Sallen-Key Low-Pass Filter Cutoff Frequency
Interlock validates analog SPICE simulation results against the theoretical closed-form cutoff equation:

$$f_c = \frac{1}{2 \pi \sqrt{R_1 R_2 C_1 C_2}}$$

*Where:*
- $f_c$ — Cutoff frequency in Hertz (Hz)
- $R_1, R_2$ — Filter resistor values in Ohms ($\Omega$)
- $C_1, C_2$ — Filter capacitor values in Farads (F)

When $R_1 = R_2 = R$ and $C_1 = C_2 = C$:

$$f_c = \frac{1}{2 \pi R C}$$

*Verification Target*: Simulated AC sweep cutoff frequency must be within **2%** of theoretical target frequency.

---

## Setup & Installation

### Option A: 1-Click Setup with `uv` or `pip`
```bash
# Recommended
uv tool install interlock-mcp

# Or with pip
pip install interlock-mcp
```

### Option B: From Source
```bash
git clone https://github.com/IamOumarIbrahim/interlock-mcp.git
cd interlock-mcp
pip install -e .
```

**Verification Command**:
```bash
interlock doctor
```
*Expected Output*:
```text
Interlock v0.4.2 — environment check

  ✓ python      3.12.3
  ✓ freecad     FreeCAD 1.0.1 found at /usr/bin/freecadcmd
  ✓ kicad       KiCad 9.0.2 — IPC API reachable on /tmp/kicad/api.sock
  ✗ ngspice     binary not found on PATH
  ✓ workspace   C:\Dev\interlock is readable and writable

1 adapter needs attention — run `interlock doctor --fix` for platform-specific install instructions.
```

---

## Connecting to AI Clients

1. Open your Claude Desktop configuration file:
   - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
   - **Linux**: `~/.config/Claude/claude_desktop_config.json`
2. Add Interlock to `mcpServers`:
```json
{
  "mcpServers": {
    "interlock": {
      "command": "uvx",
      "args": [
        "interlock-mcp",
        "serve",
        "--policy",
        "/path/to/project/interlock.policy.yaml"
      ]
    }
  }
}
```

---

## How to Use

1. Initialize policy configuration in your project root:
```bash
interlock init
```
2. Verify environment health:
```bash
interlock doctor
```
3. Approve or reject staged agent actions:
```bash
# Approve staged session
interlock approve 8f2c-af31

# Reject staged session with reason
interlock reject 8f2c-af31 --reason "Untrusted footprint modification"
```
4. View audit logs and replay sessions:
```bash
interlock audit tail
interlock audit show 8f2c-af31
interlock audit replay 8f2c-af31 --adapter kicad
```

---

## Reference Tables

### Configuration Schema (`interlock.policy.yaml`)

| Field | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `project_root` | string | `./` | Root directory allowed for file operations |
| `default_mode` | string | `approval-required` | Default mode for unlisted capabilities (`auto` \| `approval-required`) |
| `adapters.<name>.enabled` | boolean | `true` | Enable/disable adapter |
| `adapters.<name>.capabilities` | map | `{}` | Capability permission mapping (`auto` \| `approval-required`) |
| `file_scope.allow` | list | `["**"]` | Allowed glob paths relative to `project_root` |
| `file_scope.deny` | list | `["vendor/**", "**/*.lic"]` | Denied glob paths (overrides allow rules) |
| `approval.channel` | string | `elicitation` | Channel (`elicitation` \| `cli` \| `both`) |
| `approval.timeout_s` | integer | `600` | Approval request timeout in seconds |
| `audit.path` | string | `.interlock/audit.db` | SQLite audit database location |

### Environment Variables

| Variable | Default | Purpose |
| :--- | :--- | :--- |
| `INTERLOCK_POLICY_PATH` | `./interlock.policy.yaml` | Path to active policy file |
| `INTERLOCK_AUDIT_DB` | `.interlock/audit.db` | Override SQLite audit database path |
| `INTERLOCK_LOG_LEVEL` | `info` | Logging verbosity (`debug` \| `info` \| `warn` \| `error`) |
| `INTERLOCK_APPROVAL_TIMEOUT_S` | `600` | Override approval timeout |
| `INTERLOCK_NO_COLOR` | unset | Disable ANSI colors in output |

---

## Benchmarks / Comparisons

| Capability / Metric | Direct Tool Automation | Generic MCP Gateway | **Interlock** |
| :--- | :---: | :---: | :---: |
| Domain CAD/EDA/SPICE State | Yes | No | **Yes** |
| Blocks Destructive Calls | No | Generic rules only | **Yes** |
| Domain-Real Diffs | No | No | **Yes** |
| 100% Local (No Cloud Relay) | Yes | Cloud-hosted | **Yes** |
| Standard MCP Protocol | Script-specific | Yes | **Yes** |

---

## Scope & Limitations

- **Application Security Boundary**: Interlock does not sandbox underlying binaries (FreeCAD, KiCad, ngspice); it inherits their real system privileges.
- **Semantic Engineering Decisions**: Interlock enforces capability permissions and risk policy, not whether a specific CAD parameter is good engineering practice.
- **Export Control Compliance**: Audit logs provide full session traceability; compliance policies (ITAR/EAR) must pair Interlock with organizational host controls.

---

## File Structure

```
interlock-mcp/
├── src/interlock/
│   ├── adapters/          - Adapter implementations (FreeCAD, KiCad, ngspice, workspace, LTspice, Fusion 360)
│   ├── audit.py           - SQLite audit store (.interlock/audit.db)
│   ├── cli.py             - Click CLI commands (init, doctor, serve, approve, reject, audit)
│   ├── diff.py            - Domain-aware diffing engine
│   ├── math_utils.py      - Sallen-Key low-pass filter equations & verification
│   ├── policy.py          - Zero-trust PolicyEngine & rule enforcement
│   └── server.py          - MCP Server implementation
├── tests/                 - Pytest suite (100% pass rate)
├── interlock.policy.yaml  - Default policy configuration
├── pyproject.toml         - Build configuration & dependencies
├── REQUIREMENTS.md        - Extracted specification checklist
└── VERIFICATION.md        - Verification matrix & test evidence
```

---

## Troubleshooting

| Issue | Root Cause | Resolution |
| :--- | :--- | :--- |
| `ngspice binary not found` | `ngspice` not on system `PATH` | Run `interlock doctor --fix` and install `ngspice` via OS package manager |
| `Security Violation: Capability ... cannot be set to auto` | Policy file maps `destructive` capability to `auto` | Set capability permission to `approval-required` in `interlock.policy.yaml` |
| `Path ... outside project root` | Agent attempted path traversal outside `project_root` | Move target file under `project_root` or update `project_root` in policy file |
| `Path ... matches deny rule` | File path matched pattern in `file_scope.deny` | Adjust `file_scope.deny` patterns in policy file if access is intended |

---

## Deployment & GitHub Release

### Automated CI/CD & Deployment
Interlock uses GitHub Actions (`.github/workflows/deploy.yml`) for automated testing, linting, packaging, and GitHub Releases upon tag creation.

```bash
# Tag a release
git tag -a v0.4.2 -m "Release v0.4.2"
git push origin v0.4.2
```

---

## Security Policy

Security issues are taken seriously. See [`SECURITY.md`](SECURITY.md) for vulnerability reporting procedures.

---

## Code of Conduct

We are committed to providing a welcoming community. See [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md).

---

## Contributing

Contributions and new adapters are welcome! See [`CONTRIBUTING.md`](CONTRIBUTING.md) and [`docs/writing-an-adapter.md`](docs/writing-an-adapter.md) for details.

---

## License

MIT © 2026 [Interlock Maintainers](https://github.com/IamOumarIbrahim)

---

## Powered By

[Model Context Protocol](https://modelcontextprotocol.io) · [FreeCAD](https://www.freecad.org/) · [KiCad](https://www.kicad.org/) · [ngspice](https://ngspice.sourceforge.io/)

<div align="center">

If Interlock keeps your engineering tools safe, starring the repo helps others find it!

</div>