# DefAudit MCP

A small Python MCP server that lets Claude Code, Antigravity, and other MCP clients work with an existing [DefAudit](https://defaudit.com/) installation.

Available tools:

- `list_projects` — list active projects and the latest scan for each one.
- `start_scan` — start a scan on an existing project and optional branch.
- `list_scans` — list recent project scans.
- `get_scan` — read status, progress, timestamps, and severity totals.
- `get_scan_results` — read all findings, including their current disposition.
- `mark_false_positive` — mark a finding and its matching project-wide fingerprint as false positive.
- `unmark_false_positive` — remove that false-positive mark.

## Prerequisites

- Python 3.10 or newer.
- `pipx` (`python3 -m pip install --user pipx`).
- A DefAudit installation that includes the `/api/mcp/v1` API.
- A personal app token from **Settings → Profile → Personal app token**. Copy the secret when it is created; DefAudit stores only its hash and cannot display it again.

The token acts as its owner. Viewers can read projects and scans, users can also start scans, and managers/administrators can additionally mark or restore false positives. Disabling the account or token revokes access immediately.

## Quick install: Claude Code

Replace the URL and token, then run:

```bash
claude mcp add --scope user \
  defaudit \
  -e DEFAUDIT_URL=https://defaudit.example.com \
  -e DEFAUDIT_APP_TOKEN=defa_pat_REPLACE_ME \
  -- pipx run --spec git+https://github.com/intellisoftalpin/defaudit-mcp.git defaudit-mcp
```

Verify the connection:

```bash
claude mcp get defaudit
```

## Quick install: Antigravity (formerly Gemini)

Replace the URL and token, then run:

```bash
antigravity --add-mcp '{"name":"defaudit","command":"pipx","args":["run","--spec","git+https://github.com/intellisoftalpin/defaudit-mcp.git","defaudit-mcp"],"env":{"DEFAUDIT_URL":"https://defaudit.example.com","DEFAUDIT_APP_TOKEN":"defa_pat_REPLACE_ME"}}'
```

Alternatively, open **Agent → MCP Servers → Manage MCP Servers → View raw config**, then add this server to `mcpServers`:

```json
{
  "mcpServers": {
    "defaudit": {
      "command": "pipx",
      "args": [
        "run",
        "--spec",
        "git+https://github.com/intellisoftalpin/defaudit-mcp.git",
        "defaudit-mcp"
      ],
      "env": {
        "DEFAUDIT_URL": "https://defaudit.example.com",
        "DEFAUDIT_APP_TOKEN": "defa_pat_REPLACE_ME"
      }
    }
  }
}
```

On Linux, the raw configuration file is normally `~/.gemini/antigravity/mcp_config.json`. Restart the MCP server from the Antigravity MCP manager after saving.

## Local development

```bash
git clone https://github.com/intellisoftalpin/defaudit-mcp.git
cd defaudit-mcp
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e '.[test]'
pytest
```

Run the stdio server directly:

```bash
DEFAUDIT_URL=https://defaudit.example.com \
DEFAUDIT_APP_TOKEN=defa_pat_REPLACE_ME \
defaudit-mcp
```

Optional environment variables:

| Variable | Default | Meaning |
|---|---:|---|
| `DEFAUDIT_TIMEOUT` | `30` | HTTP timeout in seconds. |
| `DEFAUDIT_VERIFY_TLS` | `true` | Set to `false` only for a trusted development instance using a self-signed certificate. |

## Security

- Treat `DEFAUDIT_APP_TOKEN` like a password; never commit it.
- Prefer a dedicated least-privilege DefAudit user for automation.
- The server communicates over stdio and writes no protocol messages to stdout outside the MCP SDK.
- False-positive changes require a reason and are recorded in the DefAudit audit log.

## License

MIT