SpectraMCP

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

// 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"]
    }
  }
}

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

Related MCP server: sionna-mcp

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;

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 A: Quick 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 0.78s

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

Benchmarks & Comparisons

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

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