SpectraMCP

<div align="center"> <h1>Governed Tool Access for AI Agents</h1> <p><strong>Zero-trust MCP servers for RF/SDR/radar DSP and CAD/EDA/SPICE — plus fleet-wide observability across every session that touches them.</strong></p>

</div>

<br />

[!TIP] GitHub About Section: Unified zero-trust MCP servers for RF/SDR/radar DSP and CAD/EDA/SPICE — plus fleet-wide observability across every session that touches them.

Repository Topics / Tags: mcp · model-context-protocol · sdr · radar-dsp · rf-signals · cad · eda · spice · zero-trust · observability · agent-governance · fastmcp · python

[!NOTE] Unified Repository: This single repository consolidates and supersedes SpectraMCP, Interlock, and AgentPulse into one unified codebase containing all domain MCP servers, governance policy engines, and fleet observability watchers.

Component	Role	Location in Repo
SpectraMCP	Domain server — RF signal processing, SDR capture, radar DSP	spectramcp/
Interlock	Domain server — zero-trust governance for CAD / EDA / SPICE tools	interlock/
AgentPulse	Cross-cutting layer — fleet observability watching active sessions	agentpulse/

# Quickstart — Run in 30 seconds
pip install -e .
python agentpulse.py --watch --minimized

<!-- mcp-name: spectramcp -->

// Add directly to client configuration (e.g. claude_desktop_config.json)
{
  "mcpServers": {
    "spectramcp": {
      "command": "uvx",
      "args": ["spectramcp"]
    },
    "interlock": {
      "command": "uvx",
      "args": ["interlock-mcp", "serve", "--policy", "/path/to/interlock.policy.yaml"]
    }
  }
}

<br />

Table of Contents

• What is Governed Tool Access for AI Agents?
• Key Features
• System Architecture
• Pillar Summary
• Mathematical & Technical Formulation
• Setup & Installation
• Connecting to AI Clients
• How to Use
• Reference Tables
• Benchmarks & Comparisons
• Scope & Limitations
• File Structure
• Troubleshooting
• Security Policy
• Code of Conduct
• Contributing
• Deployment & GitHub Releases
• License & Author

---

What is Governed Tool Access for AI Agents?

An AI agent that can write a DSP script still cannot see a spectrum. An agent with raw macro access to a CAD file can delete features that should not be removed. Governed tool access solves this by providing structured, agent-callable primitives rather than raw macro or IPC access.

This unified repository replaces three previously separate tools with a single consolidated stack:

• SpectraMCP: Exposes spectral analysis and radar DSP primitives (FFTs, STFT spectrograms, 2D Range-Doppler processing, CA-CFAR detection, MVDR beamforming, Kalman tracking) as stdio MCP tools.
• Interlock: Enforces deny-by-default policy over FreeCAD, KiCad, and ngspice with non-downgradable destructive capability approval and SHA-256 diff logging.
• AgentPulse: Tails agent transcripts (JSONL) and audit logs via psutil to detect crash-looping, idle-while-alive states, and token consumption without process ownership.

---

Key Features

• Standardized Domain MCP Servers: 13 RF/radar DSP primitives in SpectraMCP running hardware-free on .wav, .iq, .sigmf-data, and .npy files.
• Zero-Trust Governance: Interlock enforces default-deny governance where destructive capabilities (cad.delete_feature, eda.delete_track, fs.write_file) require explicit human approval.
• Shadow Copy Diffing: Mutating operations run against temporary shadow copies, computing volume, net, and SPICE element diffs logged with SHA-256 hashes to SQLite.
• Fleet Observability Watcher: AgentPulse tracks active Claude Code, Cursor, Codex, Kimi, Aider, and Gemini CLI sessions for crash loops (3+ in 120s) and idle states (>300s).
• Local Dashboard & Desktop Alerts: Serves live fleet dashboard at localhost:8420 with desktop toast alerts—100% local, zero cloud relays.

---

System Architecture

The workflow architecture connects coding agents to domain MCP servers and observability layers:

graph TD
    Agent["AI Agent — Claude Code / Cursor CLI / Antigravity"]

    Agent -->|MCP stdio| Spectra["SpectraMCP<br/>RF / SDR / Radar DSP"]
    Agent -->|MCP stdio / HTTP| Interlock["Interlock<br/>CAD / EDA / SPICE"]

    Agent --> AgentLog[("agent session log")]
    Interlock --> AuditDB[("interlock audit.db")]

    Pulse["AgentPulse<br/>fleet watcher"] -.->|native adapter, read-only| AgentLog
    Pulse -.->|generic adapter, read-only| AuditDB

    Pulse --> Dash["dashboard — localhost:8420"]
    Pulse --> Toast["desktop toast alerts"]

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

[!NOTE] Attach-Only Observability: AgentPulse never spawns or controls agent processes. It tails session logs and SQLite audit records in read-only mode.

---

Pillar Summary

SpectraMCP — RF Signal Processing, SDR & Radar DSP

Exposes spectral analysis and radar DSP primitives (FFTs, STFT spectrograms, 2D Range-Doppler processing, CA-CFAR detection, MVDR/Capon beamforming, Kalman tracking) as callable stdio tools. Runs hardware-free on .wav, .iq, .sigmf-data, and .npy files, with automatic hardware capture fallback.

Interlock — Zero-Trust CAD / EDA / SPICE Governance

Sits between an MCP client and FreeCAD, KiCad, and ngspice, enforcing deny-by-default policy. Destructive capabilities (cad.delete_feature, eda.delete_track, fs.write_file) are non-downgradable and require approval. Mutating calls run against a shadow copy and generate domain diffs with SHA-256 audit hashes.

AgentPulse — Fleet Observability

Attaches to running agent sessions via psutil and tails session transcripts for crash-looping (3+ restarts in 120s), idle states (>300s), and token costs against configurable pricing tables. Serves a local dashboard at localhost:8420.

---

Mathematical & Technical Formulation

1. CA-CFAR Detection Threshold

Cell-Averaging Constant False Alarm Rate (CA-CFAR) calculates detection threshold $T$ over $N_C = 2 N_{\text{train}}$ training cells for target probability of false alarm $P_{FA}$:

$$\alpha = N_C \left( P_{FA}^{-1/N_C} - 1 \right)$$

$$T = \alpha \cdot \bar{P}_{\text{noise}}$$

Where:

• $\alpha$ — Multiplicative threshold factor.
• $N_C$ — Total number of training cells ($2 \times \text{num_train}$).
• $\bar{P}_{\text{noise}}$ — Average power across lead/lag training windows.

2. MVDR / Capon Beamforming

Minimum Variance Distortionless Response computes spatial power spectrum $P_{MVDR}(\theta)$:

$$P_{MVDR}(\theta) = \frac{1}{\mathbf{a}^H(\theta) \mathbf{R}^{-1} \mathbf{a}(\theta)}$$

Where:

• $\mathbf{R}$ — Array covariance matrix.
• $\mathbf{a}(\theta)$ — Steering vector for angle $\theta$.

3. Sallen-Key Active Filter Cutoff Frequency

Low-pass Sallen-Key active filter cutoff frequency $f_c$:

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

Where:

• $R_1, R_2$ — Resistor values in Ohms.
• $C_1, C_2$ — Capacitor values in Farads.

4. Per-Turn Token Cost Calculation

Session token consumption cost in USD:

$$\text{Cost} = \frac{\text{PromptTokens} \times \text{PromptRate} + \text{CompletionTokens} \times \text{CompletionRate}}{1,000,000}$$

---

Setup & Installation

Option 0: 1-Click Auto Setup (Windows — Claude Desktop)

Double-click setup_claude_config.bat (or run in cmd):

setup_claude_config.bat

Automatically installs Python package dependencies and configures spectramcp and interlock across all local Claude Desktop configuration files, Windows Store apps, and MultiProfile instances.

Option A: Manual Installation

git clone https://github.com/IamOumarIbrahim/governed-agent-mcp-stack.git
cd governed-agent-mcp-stack
pip install -e .

Option B: Verification Command

py -m pytest -v

Expected Output: 13 passed in 2.26s

---

Connecting to AI Clients

1. Open your client's configuration file:
   • Claude Desktop: %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
2. Add the MCP server entry:

{
  "mcpServers": {
    "spectramcp": {
      "command": "uvx",
      "args": ["spectramcp"]
    },
    "interlock": {
      "command": "uvx",
      "args": ["interlock-mcp", "serve", "--policy", "/path/to/interlock.policy.yaml"]
    }
  }
}

3. Restart the client and confirm the registered tools appear in the interface.

---

How to Use

1. Launch AgentPulse in background watch mode:

python agentpulse.py --watch --minimized

2. Start Interlock with zero-trust policy enforcement:

python -m interlock.cli serve --policy interlock.policy.yaml

3. Open http://localhost:8420 in your web browser to view the fleet dashboard.

---

Reference Tables

Configuration Schema Reference

System	Parameter	Type	Default	Description
Interlock	default_action	string	deny	Fallback policy for unspecified capabilities
Interlock	capabilities	map	{}	Capability permission mapping (auto/approval-required/deny)
AgentPulse	crash_loop_threshold	int	3	Restart count triggering crash-loop alarm in window
AgentPulse	crash_loop_window_seconds	int	120	Window size for crash detection in seconds
AgentPulse	idle_threshold_seconds	int	300	Inactivity threshold in seconds triggering idle signal
AgentPulse	dashboard_port	int	8420	Local WebSocket dashboard port

---

Benchmarks & Comparisons

Dimension	Raw Script / Macro Access	Governed Agent MCP Stack
Access Control	Unrestricted file system & IPC permissions	Zero-trust deny-by-default with non-downgradable approval
Auditability	None or ad-hoc log files	SQLite audit trail with SHA-256 diff hashing
DSP Capability	One-off script execution	13 standardized agent-callable primitives
Observability	Terminal window hunting	Unified local dashboard at localhost:8420

---

Scope & Limitations

• Hardware Dependency: Live SDR captures require attached hardware (RTL-SDR, HackRF, SoapySDR); offline mode runs on .wav, .iq, .sigmf-data, .npy.
• Local Scope: Dashboard and audit database are local-only on-host to preserve zero-cloud privacy guarantees.

---

File Structure

governed-agent-mcp-stack/
├── spectramcp/            - RF/SDR/radar DSP MCP server package
│   ├── spectral.py        - FFT, STFT, spectrogram processing
│   ├── radar.py           - 2D Range-Doppler, CA-CFAR, MVDR, Kalman tracking
│   ├── io.py              - File reader (.wav, .iq, .sigmf-data, .npy) & hardware fallback
│   └── server.py          - FastMCP server exposing 13 tools
├── interlock/             - Zero-trust CAD/EDA/SPICE governance package
│   ├── policy.py          - Policy engine enforcing default-deny & destructive guards
│   ├── diff.py            - Shadow copy engine & domain diff generator
│   ├── audit.py           - SQLite audit store with SHA-256 hashing
│   └── math_utils.py      - Sallen-Key active filter validation
├── agentpulse/            - Fleet observability package
│   ├── scanner.py         - psutil agent process scanner
│   ├── rules.py           - Crash-loop, idle-while-alive, and token cost rules
│   └── dashboard.py       - FastAPI/Uvicorn local dashboard server (port 8420)
├── agentpulse.py          - Standalone CLI runner script
├── tests/                 - Pytest unit verification suite (13/13 passing)
├── claude_desktop_config.json - MCP desktop integration template
├── interlock.policy.yaml  - Governance policy file
├── agentpulse.yaml        - Watcher & pricing configuration
├── pyproject.toml         - Python project dependencies manifest
├── REQUIREMENTS.md        - Extracted specification checklist
├── VERIFICATION.md        - README cross-check proof matrix
├── SECURITY.md            - Security vulnerability policy
├── CODE_OF_CONDUCT.md     - Community standards & pledge
├── CONTRIBUTING.md        - Development & PR guidelines
└── LICENSE                - MIT License

---

Troubleshooting

Symptom	Root Cause	Resolution
SpectraMCP live capture fails	No SDR hardware attached	System automatically falls back to file-based processing (.wav, .iq, .sigmf-data, .npy)
Interlock blocks destructive operation	Operation set to approval-required	Approve operation via MCP elicitation prompt; shadow diff logged to .interlock/audit.db
AgentPulse process not detected	Agent process name or PID transient	Process scanner safely retries on next scanning cycle without crashing

---

Security Policy

Please review SECURITY.md for details on supported versions and vulnerability reporting procedures.

---

Code of Conduct

Please review CODE_OF_CONDUCT.md for our community standards and enforcement policies.

---

Contributing

Please review CONTRIBUTING.md for instructions on setting up your environment and submitting pull requests.

---

Deployment & GitHub Releases

Releases are published automatically via GitHub Actions upon tagging:

git tag -a v1.0.0 -m "Release v1.0.0"
git push origin v1.0.0

GitHub Release artifacts include packaged wheel files and standalone policy/config templates.

---

License & Author

MIT License © 2026 Oumar Ibrahim.

Powered By: NumPy · SciPy · FastMCP · FastAPI · psutil · Uvicorn