Inspectra

Hybrid code audit system powered by GitHub Copilot and MCP.

Inspectra runs deterministic MCP tools across 12 audit domains, then performs a single structured synthesis pass with optional hotspot exploration to produce structured, scored, and actionable code quality reports.

Supported Languages

Full support (deterministic tools + conditional explorer)

Partial support (hotspot explorer only)

Full support = deterministic MCP tool scans (naming, file lengths, complexity, DRY, etc.) + conditional hotspot exploration. Partial support = conditional hotspot explorer only — no dedicated MCP tool scans. More languages on the roadmap.

Installation

# Clone the repository
git clone https://github.com/Fascinax/Inspectra.git
cd Inspectra

# Install dependencies
npm install

# Build the MCP server
npm run build

# Install globally
npm install -g .

Quick Start

Prerequisites

• Node.js 20+

• npm 10+

• GitHub Copilot with Custom Agents support

Option A — Global Setup (recommended, zero project footprint)

inspectra setup

This installs everything into your VS Code user directory:*

• MCP server registered in VS Code user settings

• Agents + prompts available globally in all projects

Then open any project in VS Code → Copilot Chat → type /audit.

No files are added to your projects.

Option A′ — Claude Code Setup

cd /path/to/my-project
inspectra setup --claude

This creates in the current directory:

• .mcp.json — Claude Code auto-connects to the Inspectra MCP server

• CLAUDE.md — project context with audit instructions, tool list, scoring model

• policies/ + schemas/ — scoring rules and contracts

Then open the project with Claude Code and ask to run an audit.

See docs/claude-code-setup.md for detailed instructions.

Option A″ — OpenAI Codex Setup

cd /path/to/my-project
inspectra setup --codex

This creates in the current directory:

• AGENTS.md — Codex reads this as project instructions (audit workflow, tools, scoring)

• .codex/config.toml — MCP server configuration (Codex auto-connects)

• policies/ + schemas/ — scoring rules and contracts

Then run codex "Run a full Inspectra audit on this project."

See docs/codex-setup.md for detailed instructions.

Option B — Per-project (symlinks, gitignored)

inspectra init /path/to/my-project

This creates symlinked Inspectra workflow assets in the target project (gitignored automatically):

• .github/prompts/ — audit prompt shortcuts (symlinked, gitignored)

• .vscode/mcp.json — MCP server auto-starts when the project opens

• policies/ + schemas/ — scoring rules and contracts (copied)

On Windows, directory junctions are used (no Developer Mode or elevation required). File symlinks are used on Unix.

Option C — Per-project (committed copies)

inspectra init /path/to/my-project --copy

Same as Option B but files are real copies committed with the repo. Useful for CI or when team members don't have Inspectra installed.

Run an Audit

Open the target project in VS Code, open Copilot Chat, and type:

• /audit : full audit (all 12 domains, Tier B hybrid workflow)

• /audit-pr : audit scoped to changed files

Usage

Running Audits

Full audit (all 12 domains, Tier B):

/audit

PR audit (only changed files):

/audit-pr

Domain-specific audit:

/audit-domain

Then specify the domain to audit in the prompt, for example: security, tests, architecture, observability.

Working with Reports

Generate HTML report:

inspectra render report.json --html

Export to PDF:

inspectra render report.json --pdf

Compare reports:

inspectra compare baseline.json current.json

View trends:

inspectra trend report1.json report2.json report3.json

CLI Commands

Environment Variables

Profile Selection

Profiles are auto-detected based on package.json and pom.xml. Explicit override:

{
  "inspectra": {
    "profile": "java-angular-playwright"
  }
}

Or via environment:

export INSPECTRA_PROFILE=java-backend

Project Structure

inspectra/
├─ .github/
│  ├─ agents/           # legacy benchmark/reference agent definitions
│  ├─ prompts/          # /audit, /audit-pr, /audit-domain, benchmark prompts
│  ├─ workflows/        # GitHub Actions CI/CD
│  └─ copilot-instructions.md
│
├─ mcp/src/             # MCP server (TypeScript, ES2022, Node 20+)
│  ├─ tools/            # Domain tool implementations (one file per domain)
│  ├─ register/         # Tool registration with input/output schemas
│  ├─ merger/           # Scoring engine, deduplication, merge
│  ├─ policies/         # YAML policy loader & scoring defaults
│  ├─ renderer/         # HTML, PDF, Markdown, SARIF renderers
│  └─ utils/            # Shared utilities (files, paths, project-config)
│
├─ schemas/             # JSON Schema 2020-12 contracts
├─ policies/            # Scoring rules, severity matrix & stack profiles
├─ docs/                # ADRs, guides, architecture docs
├─ examples/            # Sample findings & reports
├─ scripts/             # Dev & CI utility scripts
├─ Makefile             # Unified command runner
└─ bin/init.mjs         # CLI entry point

Docker

MCP Server

docker compose up inspectra

Audit Domains

Scoring Model

• Domain scores: 0–100 (100 = no issues)

• Overall score: Weighted average across all audited domains (weights in policies/scoring-rules.yml)

• Grades: A (90+), B (75+), C (60+), D (40+), F (<40)

Make Commands

npm Scripts

Release Checklist

Before publishing a new version:

1. Bump the version in package.json and update CHANGELOG.md

2. Run npm run release:check

3. Create a GitHub release tag matching the package version, for example v0.7.0

4. Ensure the NPM_TOKEN repository secret is configured

5. Publish via the release workflow in .github/workflows/release.yml

The release workflow builds, tests, packs the artifact, publishes with npm provenance, and attaches the tarball to the GitHub release.

Testing

# Run the full test suite
npm test

# Watch mode for development
npm run test:watch

# Generate coverage report
npm run test:coverage

Tests are written with Vitest and live alongside source files in mcp/src/__tests__/.

Extending

• Contributing guide: See CONTRIBUTING.md

• Release notes: See CHANGELOG.md

• Add a tool: See docs/adding-a-tool.md

• Architecture guide: See docs/architecture.md

• Output formats: See docs/output-format.md

• Scoring model: See docs/scoring-model.md

• Roadmap: See docs/roadmap.md

• Add a domain: Add tools in mcp/src/tools/, expose them via prompts, and update scoring weights

• Add a profile: Create a YAML file in policies/profiles/

Available Profiles

Tech Stack

• TypeScript (ES2022, Node 20+) — MCP server

• Zod — Runtime type validation

• JSON Schema 2020-12 — Output contracts

• MCP SDK — Tool registration and transport

• YAML — Policies and profiles

License

MIT