# DepGuard MCP Server

[![CI](https://github.com/foudhilriahi/DepGuard/actions/workflows/ci.yml/badge.svg)](https://github.com/foudhilriahi/DepGuard/actions/workflows/ci.yml)
[![Pages](https://github.com/foudhilriahi/DepGuard/actions/workflows/pages.yml/badge.svg)](https://github.com/foudhilriahi/DepGuard/actions/workflows/pages.yml)
[![Proof Artifact](https://github.com/foudhilriahi/DepGuard/actions/workflows/proof-artifact.yml/badge.svg)](https://github.com/foudhilriahi/DepGuard/actions/workflows/proof-artifact.yml)
[![Docker Publish](https://github.com/foudhilriahi/DepGuard/actions/workflows/publish-docker.yml/badge.svg)](https://github.com/foudhilriahi/DepGuard/actions/workflows/publish-docker.yml)
[![GHCR](https://img.shields.io/badge/GHCR-package-blue?logo=docker)](https://github.com/foudhilriahi/DepGuard/pkgs/container/depguard)
[![Live Proof](https://img.shields.io/badge/Live-Proof-success?logo=github)](https://foudhilriahi.github.io/DepGuard/)

DepGuard is a production MCP server for real-time dependency risk checks while coding.

It checks package updates against:
- OSV vulnerabilities (CVE/GHSA)
- npm package deprecations
- local cache for fast repeated lookups

## Status

- Docker image: `ghcr.io/foudhilriahi/depguard:latest`
- Multi-arch publish: `linux/amd64`, `linux/arm64`
- GitHub Pages live proof: `https://foudhilriahi.github.io/DepGuard/`

---

## 1) Fastest way to use DepGuard (Docker + MCP)

Add this to your MCP client config:

```json
{
  "mcpServers": {
    "depguard": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "CACHE_TTL_SECONDS=86400",
        "-e",
        "DEPGUARD_CACHE_PATH=/data/cache.sqlite",
        "-v",
        "depguard-cache:/data",
        "ghcr.io/foudhilriahi/depguard:latest"
      ]
    }
  }
}
```

Restart your AI IDE/CLI after saving config.

### Available MCP tools

- `check_package`
- `check_packages_bulk`
- `scan_package_json`
- `get_cached_result`

---

## 2) Real online proof (no mocks)

### Live proof page

GitHub Pages app in `docs/` performs real browser calls to:
- `https://api.osv.dev/v1/querybatch`
- `https://registry.npmjs.org/<package>`

### CI proof artifact

`docs/proof/latest.json` is generated by running **actual DepGuard core logic** in CI:
- workflow: `.github/workflows/proof-artifact.yml`
- script: `scripts/generate-proof.mjs`

This is not simulation data.

---

## 3) How to test Docker image online (without local Docker)

Use GitHub Actions manual workflow:

- Workflow: `.github/workflows/docker-smoke.yml`
- Trigger: **Actions → Docker Smoke Test (GHCR) → Run workflow**

It validates:
1. image can be pulled from GHCR
2. manifest inspection works
3. container runtime works (`node --version`)
4. MCP entrypoint file exists (`/app/dist/index.js`)

So you can prove your container works even without Docker installed locally.

---

## 4) GitHub Pages setup

Use workflow-based Pages deploy for consistency:

1. GitHub repo → **Settings → Pages**
2. Source: **GitHub Actions**
3. Keep `.github/workflows/pages.yml` enabled

---

## 5) Local dev (optional)

```bash
npm install
npm run test
npm run build
npm run dev
```

---

## 6) Environment variables

- `CACHE_TTL_SECONDS` (default `86400`)
- `DEPGUARD_CACHE_PATH` (default `.depguard-cache.sqlite`)
- `DEPGUARD_HTTP_TIMEOUT_MS` (default `7000`)
- `DEPGUARD_HTTP_RETRIES` (default `2`)
- `DEPGUARD_HTTP_RETRY_DELAY_MS` (default `250`)

---

## 7) CI/CD workflows in this repo

- `ci.yml` → tests + build
- `pages.yml` → deploys `docs/` to GitHub Pages
- `proof-artifact.yml` → refreshes real proof JSON
- `publish-docker.yml` → publishes multi-arch GHCR image
- `docker-smoke.yml` → manual online container verification