# mizcausevic-dev/mcp-sentinel architecture

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

- Interactive diagram: https://gitdiagram.com/mizcausevic-dev/mcp-sentinel
- Repository: https://github.com/mizcausevic-dev/mcp-sentinel

## Overview

#### Purpose and principal workflow

MCP Sentinel is a Node.js/Express API for evaluating MCP server registrations, tool schemas, and tool invocations against governance and security checks, then exposing fleet posture and audit views. The documented main trigger is an agent or assistant making a tool call: it submits an invocation to the API, which validates the payload, scores prompt-injection and PII risk, and returns a decision. Platform teams and operators also submit registration and schema checks and read fleet views. The sampled implementation uses seeded in-memory data; it does not establish persistent storage or live polling.

#### Components

##### API and request boundary
- **Agent or assistant** — *External; path: null.* The README identifies an agent or assistant initiating a tool call and describes invocation validation as an inflight check.
- **Express API application** — `src/index.ts`. Creates the Express app, installs middleware, mounts route groups, serves health and Swagger endpoints, and listens when run as the main module.
- **Validation request contracts** — `src/schemas/validation-schemas.ts`. Zod schemas define and parse the registration, tool-schema, invocation, and security-scan request shapes used by the validation routes.
- **Governance validation routes** — `src/routes/validate.ts`. Exposes the validation endpoints, rejects invalid payloads, dispatches supported checks, and combines registration validation into a posture-check response.
- **API documentation** — `src/docs/swagger.ts`. The application mounts its OpenAPI specification at `/docs`; the spec’s contents were not sampled.

##### Governance evaluation
- **Registration posture evaluator** — `src/governance/server-validator.ts`. Scores authentication, OAuth scopes, tool capabilities, transport, and ownership, returning a status, findings, and recommended action.
- **Schema-drift evaluator** — `src/governance/schema-drift.ts`. The README describes comparing tool schemas with baselines for added or removed parameters and risk-flag or signature changes; source behavior was not sampled.
- **Invocation risk evaluator** — `src/governance/injection-detector.ts`. Scans invocation context, arguments, and result preview for injection and PII/credential signatures, adds latency risk, and returns a threshold-based verdict.
- **Combined security scanner** — `src/governance/security-scan.ts`. The README documents combined security scanning, and the route calls this module; its checks and internal flow were not sampled.
- **Policy lookup** — `src/governance/policy-engine.ts`. Lists and finds policies from the audit-data module; the sampled file does not show it participating in validation decisions.

##### Fleet visibility and state
- **Server route surface** — `src/routes/servers.ts`. The tree and README document server listing, individual server, and tool endpoints; route implementation was not sampled.
- **Audit, incident, policy, and dashboard routes** — `src/routes/audits.ts`. Serves audit, incident, and policy lists and computes a dashboard summary from fleet, audit, incident, and policy data.
- **Seeded server registry** — `src/data/servers.ts`. Defines server records and an in-memory registry, with a lookup helper.
- **Seeded governance records** — `src/data/audits.ts`. Defines in-memory audit, incident, and policy records; the samples are static data rather than evidence of runtime persistence.

##### Runtime configuration
- **Environment settings** — `src/config/env.ts`. Loads environment variables and provides defaults for the port, runtime mode, thresholds, polling intervals, and alert webhook URL; sampled code uses the mode, port, and injection threshold.

#### Relationships

- **Agent or assistant -> Express API application:** initiates an MCP tool-call validation request; the README names the actor and the API’s validation role.
- **Express API application -> Governance validation routes:** mounts the validation, security-scan, and posture-check route groups; the application wiring establishes this dispatch.
- **Governance validation routes -> Validation request contracts:** parses request bodies with the relevant Zod schemas and returns a 400 response for invalid payloads.
- **Governance validation routes -> Registration posture evaluator:** calls registration evaluation for server validation and posture checks; the result is mapped to the combined posture status.
- **Governance validation routes -> Schema-drift evaluator:** dispatches parsed schema-check requests for evaluation; the route call is sampled, while evaluator details are not.
- **Governance validation routes -> Invocation risk evaluator:** dispatches parsed invocation requests and returns the verdict; the evaluator reads the configured injection threshold.
- **Governance validation routes -> Combined security scanner:** dispatches parsed security-scan requests; scanner internals are not established.
- **Express API application -> API documentation:** mounts the OpenAPI specification in Swagger UI at `/docs`.
- **Express API application -> Server route surface:** mounts the server router under `/api/servers`; endpoint behavior is documented, but route implementation was not sampled.
- **Express API application -> Audit, incident, policy, and dashboard routes:** mounts these routes under their API prefixes.
- **Audit, incident, policy, and dashboard routes -> Seeded server registry:** reads server records to calculate fleet counts and average posture in the dashboard summary.
- **Audit, incident, policy, and dashboard routes -> Seeded governance records:** reads audit, incident, and policy arrays for list responses and dashboard totals.
- **Policy lookup -> Seeded governance records:** reads the policy array to list or find a policy.
- **Express API application -> Environment settings:** reads the port and runtime mode for startup, health output, and middleware configuration.

#### Coverage limits

The supplied source sample omits implementations for schema-drift evaluation, security scanning, server routes, and the OpenAPI specification. The README describes their intended behavior, but their detailed checks and runtime wiring beyond the sampled route calls or mounts could not be established. The excerpt also does not show persistence, ingestion/polling workers, or alert delivery.

Main entry points: [`src/index.ts`](https://github.com/mizcausevic-dev/mcp-sentinel/blob/main/src/index.ts) (Express API), [`src/routes/validate.ts`](https://github.com/mizcausevic-dev/mcp-sentinel/blob/main/src/routes/validate.ts) (Validation Routes), [`src/routes/audits.ts`](https://github.com/mizcausevic-dev/mcp-sentinel/blob/main/src/routes/audits.ts) (Audit and Dashboard Routes), [`src/data/audits.ts`](https://github.com/mizcausevic-dev/mcp-sentinel/blob/main/src/data/audits.ts) (Seeded Governance Records)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API Boundary"]
  node_express["Express API<br/>Express application"]
  node_contracts["Validation Contracts<br/>Zod schemas"]
  node_validate_routes["Validation Routes<br/>API routes"]
  node_swagger["API Documentation<br/>OpenAPI specification"]
end

subgraph group_governance["Governance Evaluation"]
  node_registration["Registration Evaluator<br/>Governance evaluator"]
  node_schema_drift["Schema Drift Evaluator<br/>Governance evaluator"]
  node_invocation["Invocation Risk Evaluator<br/>Governance evaluator"]
  node_security_scan["Security Scanner<br/>Governance evaluator"]
  node_policy_lookup["Policy Lookup<br/>Policy service"]
end

subgraph group_fleet["Fleet Visibility and State"]
  node_server_routes["Server Routes<br/>API routes"]
  node_audit_routes["Audit and Dashboard Routes<br/>API routes"]
  node_servers["Seeded Server Registry<br/>In-memory data"]
  node_records["Seeded Governance Records<br/>In-memory data"]
end

subgraph group_config["Runtime Configuration"]
  node_env["Environment Settings<br/>Configuration"]
end

node_agent(("Agent or Assistant<br/>External actor"))

node_agent -->|"submits tool call"| node_express
node_express -->|"mounts routes"| node_validate_routes
node_validate_routes -->|"parses payloads"| node_contracts
node_validate_routes -->|"evaluates registration"| node_registration
node_validate_routes -->|"dispatches check"| node_schema_drift
node_validate_routes -->|"dispatches invocation"| node_invocation
node_validate_routes -->|"dispatches scan"| node_security_scan
node_express -->|"mounts docs"| node_swagger
node_express -->|"mounts router"| node_server_routes
node_express -->|"mounts routes"| node_audit_routes
node_audit_routes -->|"reads server records"| node_servers
node_audit_routes -->|"reads governance records"| node_records
node_policy_lookup -->|"reads policies"| node_records
node_express -->|"reads settings"| node_env

click node_express "https://github.com/mizcausevic-dev/mcp-sentinel/blob/main/src/index.ts"
click node_contracts "https://github.com/mizcausevic-dev/mcp-sentinel/blob/main/src/schemas/validation-schemas.ts"
click node_validate_routes "https://github.com/mizcausevic-dev/mcp-sentinel/blob/main/src/routes/validate.ts"
click node_swagger "https://github.com/mizcausevic-dev/mcp-sentinel/blob/main/src/docs/swagger.ts"
click node_server_routes "https://github.com/mizcausevic-dev/mcp-sentinel/blob/main/src/routes/servers.ts"
click node_audit_routes "https://github.com/mizcausevic-dev/mcp-sentinel/blob/main/src/routes/audits.ts"
click node_registration "https://github.com/mizcausevic-dev/mcp-sentinel/blob/main/src/governance/server-validator.ts"
click node_schema_drift "https://github.com/mizcausevic-dev/mcp-sentinel/blob/main/src/governance/schema-drift.ts"
click node_invocation "https://github.com/mizcausevic-dev/mcp-sentinel/blob/main/src/governance/injection-detector.ts"
click node_security_scan "https://github.com/mizcausevic-dev/mcp-sentinel/blob/main/src/governance/security-scan.ts"
click node_policy_lookup "https://github.com/mizcausevic-dev/mcp-sentinel/blob/main/src/governance/policy-engine.ts"
click node_servers "https://github.com/mizcausevic-dev/mcp-sentinel/blob/main/src/data/servers.ts"
click node_records "https://github.com/mizcausevic-dev/mcp-sentinel/blob/main/src/data/audits.ts"
click node_env "https://github.com/mizcausevic-dev/mcp-sentinel/blob/main/src/config/env.ts"

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_express,node_contracts,node_validate_routes,node_swagger toneBlue
class node_registration,node_schema_drift,node_invocation,node_security_scan,node_policy_lookup toneAmber
class node_server_routes,node_audit_routes,node_servers,node_records toneMint
class node_env toneRose
class node_agent toneIndigo
```

## Components

### API Boundary

- [Express API](https://github.com/mizcausevic-dev/mcp-sentinel/blob/main/src/index.ts): Express application · `src/index.ts`
- [Validation Contracts](https://github.com/mizcausevic-dev/mcp-sentinel/blob/main/src/schemas/validation-schemas.ts): Zod schemas · `src/schemas/validation-schemas.ts`
- [Validation Routes](https://github.com/mizcausevic-dev/mcp-sentinel/blob/main/src/routes/validate.ts): API routes · `src/routes/validate.ts`
- [API Documentation](https://github.com/mizcausevic-dev/mcp-sentinel/blob/main/src/docs/swagger.ts): OpenAPI specification · `src/docs/swagger.ts`

### Governance Evaluation

- [Registration Evaluator](https://github.com/mizcausevic-dev/mcp-sentinel/blob/main/src/governance/server-validator.ts): Governance evaluator · `src/governance/server-validator.ts`
- [Schema Drift Evaluator](https://github.com/mizcausevic-dev/mcp-sentinel/blob/main/src/governance/schema-drift.ts): Governance evaluator · `src/governance/schema-drift.ts`
- [Invocation Risk Evaluator](https://github.com/mizcausevic-dev/mcp-sentinel/blob/main/src/governance/injection-detector.ts): Governance evaluator · `src/governance/injection-detector.ts`
- [Security Scanner](https://github.com/mizcausevic-dev/mcp-sentinel/blob/main/src/governance/security-scan.ts): Governance evaluator · `src/governance/security-scan.ts`
- [Policy Lookup](https://github.com/mizcausevic-dev/mcp-sentinel/blob/main/src/governance/policy-engine.ts): Policy service · `src/governance/policy-engine.ts`

### Fleet Visibility and State

- [Server Routes](https://github.com/mizcausevic-dev/mcp-sentinel/blob/main/src/routes/servers.ts): API routes · `src/routes/servers.ts`
- [Audit and Dashboard Routes](https://github.com/mizcausevic-dev/mcp-sentinel/blob/main/src/routes/audits.ts): API routes · `src/routes/audits.ts`
- [Seeded Server Registry](https://github.com/mizcausevic-dev/mcp-sentinel/blob/main/src/data/servers.ts): In-memory data · `src/data/servers.ts`
- [Seeded Governance Records](https://github.com/mizcausevic-dev/mcp-sentinel/blob/main/src/data/audits.ts): In-memory data · `src/data/audits.ts`

### Runtime Configuration

- [Environment Settings](https://github.com/mizcausevic-dev/mcp-sentinel/blob/main/src/config/env.ts): Configuration · `src/config/env.ts`

### Other components

- **Agent or Assistant**: External actor

## Connections

- Agent or Assistant → Express API: submits tool call
- Express API → Validation Routes: mounts routes
- Validation Routes → Validation Contracts: parses payloads
- Validation Routes → Registration Evaluator: evaluates registration
- Validation Routes → Schema Drift Evaluator: dispatches check
- Validation Routes → Invocation Risk Evaluator: dispatches invocation
- Validation Routes → Security Scanner: dispatches scan
- Express API → API Documentation: mounts docs
- Express API → Server Routes: mounts router
- Express API → Audit and Dashboard Routes: mounts routes
- Audit and Dashboard Routes → Seeded Server Registry: reads server records
- Audit and Dashboard Routes → Seeded Governance Records: reads governance records
- Policy Lookup → Seeded Governance Records: reads policies
- Express API → Environment Settings: reads settings