# eepstein201/jev-mcp architecture

> Architecture diagram of the GitHub repository eepstein201/jev-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/eepstein201/jev-mcp
- Repository: https://github.com/eepstein201/jev-mcp

## Overview

Jev MCP is a local-model MCP server for typed evaluation and task routing. An MCP client submits a tool request to the server, which dispatches evaluation through a hybrid provider: Kev handles confident, smaller decisions, while uncertain or large-context requests escalate to the local smart-model daemon. The server also exposes repository scanning and semantic chunking, prompt linting, context compaction, and router management. The README documents additional ML workflows, but their implementation is not established by the sampled source, so they are not expanded into inferred components.

Main entry points: [`src/jev_mcp/server.py`](https://github.com/eepstein201/jev-mcp/blob/main/src/jev_mcp/server.py) (MCP Tool Server), [`src/jev_mcp/daemon_provider.py`](https://github.com/eepstein201/jev-mcp/blob/main/src/jev_mcp/daemon_provider.py) (Smart Daemon Provider), [`src/jev_mcp/routing_provider.py`](https://github.com/eepstein201/jev-mcp/blob/main/src/jev_mcp/routing_provider.py) (Hybrid Router), [`src/jev_mcp/kev_provider.py`](https://github.com/eepstein201/jev-mcp/blob/main/src/jev_mcp/kev_provider.py) (Kev Provider)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["MCP Entry"]
  node_server["MCP Tool Server<br/>[server.py]"]
  node_lint["Decision Linter<br/>[linter.py]"]
  node_cli["Linter CLI<br/>[cli_linter.py]"]
end

subgraph group_routing["Evaluation Engines"]
  node_question["Typed Questions<br/>[provider.py]"]
  node_router["Hybrid Router"]
  node_kev["Kev Provider<br/>[kev_provider.py]"]
  node_daemon["Smart Daemon Provider<br/>[daemon_provider.py]"]
  node_provider["Provider Contract<br/>[provider.py]"]
end

subgraph group_repo["Repository Tools"]
  node_scanner["Repository Scanner<br/>[scanner.py]"]
  node_chunker["Semantic Chunker<br/>[chunker.py]"]
end

subgraph group_safety["Policy and Configuration"]
  node_security["Payload and Path Safety<br/>[security.py]"]
  node_config[("Router Configuration<br/>[router_config.py]")]
end

node_client(("MCP Client"))
node_fastservice["Kev Local Service"]
node_smartservice["MLX Local Service"]

node_client -->|"calls tools"| node_server
node_server -->|"evaluates"| node_router
node_router -->|"evaluates first"| node_kev
node_router -->|"escalates uncertain"| node_daemon
node_kev -->|"posts evaluations"| node_fastservice
node_daemon -->|"posts evaluations"| node_smartservice
node_kev -->|"uses contract"| node_provider
node_daemon -->|"uses transport"| node_provider
node_router -->|"implements contract"| node_provider
node_server -->|"checks prompts"| node_lint
node_cli -->|"runs lint"| node_lint
node_server -->|"scans repositories"| node_scanner
node_server -->|"extracts code chunks"| node_chunker
node_server -->|"sanitizes and guards paths"| node_security
node_server -->|"manages router settings"| node_config
node_daemon -->|"loads temperature"| node_config
node_daemon -->|"sanitizes payloads"| node_security
node_kev -->|"sanitizes payloads"| node_security

click node_server "https://github.com/eepstein201/jev-mcp/blob/main/src/jev_mcp/server.py"
click node_question "https://github.com/eepstein201/jev-mcp/blob/main/src/jev_mcp/provider.py"
click node_router "https://github.com/eepstein201/jev-mcp/blob/main/src/jev_mcp/routing_provider.py"
click node_kev "https://github.com/eepstein201/jev-mcp/blob/main/src/jev_mcp/kev_provider.py"
click node_daemon "https://github.com/eepstein201/jev-mcp/blob/main/src/jev_mcp/daemon_provider.py"
click node_lint "https://github.com/eepstein201/jev-mcp/blob/main/src/jev_mcp/linter.py"
click node_cli "https://github.com/eepstein201/jev-mcp/blob/main/src/jev_mcp/cli_linter.py"
click node_scanner "https://github.com/eepstein201/jev-mcp/blob/main/src/jev_mcp/scanner.py"
click node_chunker "https://github.com/eepstein201/jev-mcp/blob/main/src/jev_mcp/chunker.py"
click node_security "https://github.com/eepstein201/jev-mcp/blob/main/src/jev_mcp/security.py"
click node_config "https://github.com/eepstein201/jev-mcp/blob/main/src/jev_mcp/router_config.py"
click node_provider "https://github.com/eepstein201/jev-mcp/blob/main/src/jev_mcp/provider.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server,node_lint,node_cli,node_client toneBlue
class node_question,node_router,node_kev,node_daemon,node_provider toneAmber
class node_scanner,node_chunker toneMint
class node_security,node_config toneRose
class node_fastservice,node_smartservice toneIndigo
```

## Components

### MCP Entry

- [MCP Tool Server](https://github.com/eepstein201/jev-mcp/blob/main/src/jev_mcp/server.py): `src/jev_mcp/server.py`
- [Decision Linter](https://github.com/eepstein201/jev-mcp/blob/main/src/jev_mcp/linter.py): `src/jev_mcp/linter.py`
- [Linter CLI](https://github.com/eepstein201/jev-mcp/blob/main/src/jev_mcp/cli_linter.py): `src/jev_mcp/cli_linter.py`

### Evaluation Engines

- [Typed Questions](https://github.com/eepstein201/jev-mcp/blob/main/src/jev_mcp/provider.py): `src/jev_mcp/provider.py`
- [Hybrid Router](https://github.com/eepstein201/jev-mcp/blob/main/src/jev_mcp/routing_provider.py): `src/jev_mcp/routing_provider.py`
- [Kev Provider](https://github.com/eepstein201/jev-mcp/blob/main/src/jev_mcp/kev_provider.py): `src/jev_mcp/kev_provider.py`
- [Smart Daemon Provider](https://github.com/eepstein201/jev-mcp/blob/main/src/jev_mcp/daemon_provider.py): `src/jev_mcp/daemon_provider.py`
- [Provider Contract](https://github.com/eepstein201/jev-mcp/blob/main/src/jev_mcp/provider.py): `src/jev_mcp/provider.py`

### Repository Tools

- [Repository Scanner](https://github.com/eepstein201/jev-mcp/blob/main/src/jev_mcp/scanner.py): `src/jev_mcp/scanner.py`
- [Semantic Chunker](https://github.com/eepstein201/jev-mcp/blob/main/src/jev_mcp/chunker.py): `src/jev_mcp/chunker.py`

### Policy and Configuration

- [Payload and Path Safety](https://github.com/eepstein201/jev-mcp/blob/main/src/jev_mcp/security.py): `src/jev_mcp/security.py`
- [Router Configuration](https://github.com/eepstein201/jev-mcp/blob/main/src/jev_mcp/router_config.py): `src/jev_mcp/router_config.py`

### Other components

- **MCP Client**
- **Kev Local Service**
- **MLX Local Service**

## Connections

- MCP Client → MCP Tool Server: calls tools (evidence: `README.md`)
- MCP Tool Server → Hybrid Router: evaluates (evidence: `src/jev_mcp/server.py`)
- Hybrid Router → Kev Provider: evaluates first (evidence: `src/jev_mcp/routing_provider.py`)
- Hybrid Router → Smart Daemon Provider: escalates uncertain (evidence: `src/jev_mcp/routing_provider.py`)
- Kev Provider → Kev Local Service: posts evaluations (evidence: `src/jev_mcp/kev_provider.py`)
- Smart Daemon Provider → MLX Local Service: posts evaluations (evidence: `src/jev_mcp/daemon_provider.py`)
- Kev Provider → Provider Contract: uses contract (evidence: `src/jev_mcp/kev_provider.py`)
- Smart Daemon Provider → Provider Contract: uses transport (evidence: `src/jev_mcp/daemon_provider.py`)
- Hybrid Router → Provider Contract: implements contract (evidence: `src/jev_mcp/routing_provider.py`)
- MCP Tool Server → Decision Linter: checks prompts (evidence: `src/jev_mcp/server.py`)
- Linter CLI → Decision Linter: runs lint (evidence: `src/jev_mcp/cli_linter.py`)
- MCP Tool Server → Repository Scanner: scans repositories (evidence: `src/jev_mcp/server.py`)
- MCP Tool Server → Semantic Chunker: extracts code chunks (evidence: `src/jev_mcp/server.py`)
- MCP Tool Server → Payload and Path Safety: sanitizes and guards paths (evidence: `src/jev_mcp/server.py`)
- MCP Tool Server → Router Configuration: manages router settings (evidence: `src/jev_mcp/server.py`)
- Smart Daemon Provider → Router Configuration: loads temperature (evidence: `src/jev_mcp/daemon_provider.py`)
- Smart Daemon Provider → Payload and Path Safety: sanitizes payloads (evidence: `src/jev_mcp/daemon_provider.py`)
- Kev Provider → Payload and Path Safety: sanitizes payloads (evidence: `src/jev_mcp/kev_provider.py`)
