English | 한국어

my-nexus

my-nexus is an open-source starter for running Nexus Repository as an internal package hub and querying package usage through AI tools.

It includes:

• Nexus repository configuration-as-code through nexusctl.
• An integrated web server for dashboard, approvals, API, scheduler, and MCP HTTP.
• A read-only stdio MCP server for local AI clients.
• Collectors for Nexus request.log and CycloneDX/SPDX SBOM files.
• Docker Compose examples for Nexus, PostgreSQL, and the integrated server.

Why this exists

Nexus can tell you what was stored and downloaded. It cannot, by itself, prove which production system is currently running a vulnerable dependency. This project adds the missing inventory layer by combining:

• Nexus REST API component metadata.
• Nexus request.log download history.
• SBOMs from CI/CD.
• Runtime deployment inventory from Kubernetes, VM, or release pipelines.
• OSV/NVD vulnerability data.

The MCP server then exposes safe, read-only tools so an AI assistant can answer questions such as:

Is CVE-2021-44228 affecting us? Who downloaded it, which systems run it, and who owns them?

Quick start

Install dependencies:

pnpm install

Build:

pnpm build

Validate the example configuration:

pnpm dev:validate

Create starter inventory files:

node dist/nexusctl/main.js --config config/my-nexus.example.yaml init-data

Run the integrated web server:

node dist/server/main.js --config config/my-nexus.example.yaml

Open http://127.0.0.1:8787.

Run the MCP server from an MCP client using stdio:

node dist/nexus-mcp/main.js --config config/my-nexus.example.yaml

Main commands

nexusctl validate --config config/my-nexus.example.yaml
nexusctl plan --config config/my-nexus.example.yaml
nexusctl apply --config config/my-nexus.example.yaml --dry-run
nexusctl sync-components --config config/my-nexus.example.yaml
my-nexus-log-collector --config config/my-nexus.example.yaml --file /path/to/request.log
my-nexus-sbom-ingestor --config config/my-nexus.example.yaml --file sbom.json --system billing-api --as-deployment

MCP tools

• lookup_cve: resolve a CVE or advisory through configured vulnerability sources.
• find_affected_components: match a CVE against indexed components, SBOMs, deployments, and downloads.
• find_download_history: search Nexus request-log-derived download events.
• find_running_systems: find deployed systems for a purl or CVE.
• resolve_owner: resolve owner metadata by owner reference or system.
• generate_impact_report: produce a markdown incident impact report.
• inventory_summary: summarize indexed inventory.
• request_library_approval: create a library approval request.
• decide_library_approval: approve, reject, or cancel a request.
• list_library_approvals: list requests and current status.
• get_library_history: show package approval, download, SBOM, deployment, and component history.
• summarize_library_risk: query known OSV vulnerabilities for a package.

Configuration

Copy .env.example and config/my-nexus.example.yaml, then change values for your environment. Secrets are referenced by environment variable name instead of being stored in YAML.

Repository names, upstream URLs, blob store names, ports, and ownership defaults are all configuration-driven.

Data model

The starter uses append-only JSONL files under dataDir. This is intentional for local and small team deployments because it is auditable and easy to inspect. For larger deployments, keep the MCP tool contract and replace the FileInventoryStore with PostgreSQL or OpenSearch.

Primary record kinds:

• component
• download
• sbom
• deployment
• owner
• library-approval-request
• library-approval-decision
• library-history-event

Package identity uses Package URL (purl) wherever possible.

Security posture

• MCP tools are read-only by default.
• Mutable actions, such as ticket creation or quarantine, should be added as separate tools with explicit authorization.
• The AI assistant should summarize and correlate evidence, not invent vulnerability matches.
• All package matching is based on normalized inventory plus OSV/NVD data.
• Keep MCP access inside the trusted network or behind an authenticated gateway.

Docs

• Architecture
• Operations
• Native install
• Windows install
• MCP client example