Inspectra

Inspectra

[](https://github.com/Fascinax/Inspectra/actions/workflows/validate-config.yml) [](https://www.npmjs.com/package/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](docs/roadmap.md).

---

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](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](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

| Command | Description | | --------- | ------------- | | inspectra setup | Global setup (VS Code user settings) | | inspectra setup --claude | Claude Code setup (current directory) | | inspectra setup --codex | OpenAI Codex setup (current directory) | | inspectra init | Per-project setup with symlinks | | inspectra init --copy | Per-project setup with copies | | inspectra doctor | Diagnose installation issues |

Environment Variables

| Variable | Default | Description | | ---------- | --------- | ------------- | | INSPECTRA_LOG_LEVEL | info | Log verbosity (debug, info, warn, error) | | INSPECTRA_PROFILE | generic | Active policy profile | | NODE_ENV | production | Runtime environment |

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

| Domain | Tool Group | MCP Tools | Prefix | | -------- | ------------ | ----------- | -------- | | Security | Security scan | inspectra_scan_secrets, inspectra_check_deps_vulns, inspectra_run_semgrep, inspectra_check_maven_deps | SEC- | | Tests | Test audit | inspectra_parse_coverage, inspectra_parse_test_results, inspectra_detect_missing_tests, inspectra_parse_playwright_report, inspectra_detect_flaky_tests | TST- | | Architecture | Architecture audit | inspectra_check_layering, inspectra_analyze_dependencies, inspectra_detect_circular_deps | ARC- | | Conventions | Conventions audit | inspectra_check_naming, inspectra_check_file_lengths, inspectra_check_todos, inspectra_parse_lint_output, inspectra_detect_dry_violations | CNV- | | Performance | Performance audit | inspectra_analyze_bundle_size, inspectra_check_build_timings, inspectra_detect_runtime_metrics | PRF- | | Documentation | Documentation audit | inspectra_check_readme_completeness, inspectra_check_adr_presence, inspectra_detect_doc_code_drift | DOC- | | Tech debt | Tech-debt audit | inspectra_analyze_complexity, inspectra_age_todos, inspectra_check_dependency_staleness | DEBT- | | Accessibility | Accessibility audit | inspectra_check_a11y_templates | ACC- | | API Design | API design audit | inspectra_check_rest_conventions | API- | | Observability | Observability audit | inspectra_check_observability | OBS- | | i18n | i18n audit | inspectra_check_i18n | INT- | | UX Consistency | UX consistency audit | inspectra_check_ux_consistency | UX- |

---

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

| Command | Description | | --------- | ------------- | | make bootstrap | Full setup: install, build, test | | make build | Build the MCP server | | make test | Run unit tests | | make validate | Validate schemas + lint prompts | | make smoke | Smoke test the MCP server | | make init TARGET=/path | Copy agents into a project | | make help | List all commands |

npm Scripts

| Script | Description | | -------- | ------------- | | npm run build | Compile the MCP server (TypeScript → mcp/dist/) | | npm test | Run the Vitest suite | | npm run test:watch | Run tests in watch mode | | npm run test:coverage | Run tests with V8 coverage report | | npm run lint | TypeScript type-check + ESLint | | npm run lint:fix | Auto-fix ESLint violations | | npm run format | Format source with Prettier | | npm run format:check | Check Prettier formatting (CI-safe) | | npm run release:check | Run the npm publication preflight (npm publish --dry-run) |

---

Release Checklist

Before publishing a new version:

1. Bump the version in [package.json](package.json) and update [CHANGELOG.md](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](.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](CONTRIBUTING.md)
• Release notes: See [CHANGELOG.md](CHANGELOG.md)
• Add a tool: See [docs/adding-a-tool.md](docs/adding-a-tool.md)
• Architecture guide: See [docs/architecture.md](docs/architecture.md)
• Output formats: See [docs/output-format.md](docs/output-format.md)
• Scoring model: See [docs/scoring-model.md](docs/scoring-model.md)
• Roadmap: See [docs/roadmap.md](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

| Profile | Stack | | --------- | ------- | | generic | Any project (conservative defaults) | | java-angular-playwright | Java + Angular + Playwright full-stack | | java-backend | Java backend (Quarkus / Spring Boot) | | angular-frontend | Angular SPA (TypeScript) |

---

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

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Fascinax
• Source: Fascinax/Inspectra
• License: MIT

Install and usage instructions live in the source repository linked above.