<div align="center">

# 🛡️ AdaLab
### Automated Security & Conformance Benchmark Engine for Model Context Protocol (MCP) & AI Agents

[![AdaLab Verified](https://adalab.cc/api/badge/rexchou/adalab)](https://adalab.cc/audit/rexchou/adalab)
[![GitHub Action](https://github.com/rexchou/adalab/actions/workflows/daily-scanner.yml/badge.svg)](https://github.com/rexchou/adalab/actions/workflows/daily-scanner.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-emerald.svg)](LICENSE)
[![Next.js](https://img.shields.io/badge/Next.js-16-black.svg)](https://nextjs.org)

**[Website](https://adalab.cc)** • **[Directory](https://adalab.cc/directory)** • **[Submit Tool](https://adalab.cc/submit)** • **[CI/CD Docs](https://adalab.cc/docs/github-action)**

</div>

---

## 📌 Overview

**AdaLab** (`adalab.cc`) is the continuous security scanner and benchmark engine designed for the Model Context Protocol (MCP) ecosystem. Traditional SAST tools fail to detect AI-native vulnerabilities such as prompt injections, tool parameter hallucinations, and unbounded agent shell execution.

AdaLab performs static AST analysis, protocol schema validation, and guardrail fuzzing to give developers and security teams instant clarity on their agent security posture.

---

## ⚡ Core Capabilities

- **🛡️ Prompt Injection Defense**: Detects unescaped parameter interpolations in system instructions that expose agents to behavioral hijacking.
- **🔒 Tool Boundary Containment**: Flags unconstrained `child_process.exec`, `eval`, or unsanitized file system operations inside MCP handlers.
- **🔑 Secret & Token Leak Scanner**: Intercepts exposed API keys (`sk-`, `ghp_`, cloud tokens) before deployment.
- **📐 JSON-RPC 2.0 Conformance**: Validates `inputSchema` specifications against official MCP requirements to prevent runtime model crashes.
- **🏷️ Dynamic SVG Verification Badges**: Real-time Shields.io-compatible badges for open-source repositories to embed in `README.md`.

---

## 🚀 Quickstart: GitHub Actions CI/CD Gate

Add AdaLab to your continuous integration pipeline to block vulnerable code before pull requests are merged.

Create `.github/workflows/adalab-security.yml` in your repository:

```yaml
name: AdaLab Security Gate

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  mcp-audit:
    name: Verify MCP & Prompt Injection Security
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Code
        uses: actions/checkout@v4

      - name: Run AdaLab Security Audit
        run: |
          curl -s -X POST https://adalab.cc/api/scan \
            -H "Content-Type: application/json" \
            -d '{"repo": "${{ github.repository }}"}' \
            --fail-with-body
```

---

## 🔌 Run as an MCP Server (Claude Desktop, Cursor, Cline)

AdaLab operates as a native Model Context Protocol (MCP) server over standard input/output (stdio), providing real-time security auditing directly to your coding assistant.

Add to your `claude_desktop_config.json` or Cursor MCP settings:

```json
{
  "mcpServers": {
    "adalab": {
      "command": "node",
      "args": ["bin/cli.mjs", "mcp"]
    }
  }
}
```

### Supported MCP Tools:
- `scan_code_security`: Deep AST analysis of local server repositories for injection attack surfaces and shell leaks.
- `fuzz_prompt_injection`: Fuzz test system instructions against prompt injection vectors.
- `get_verification_badge`: Automatically generate Shields badges and verification URLs for your MCP repo.

---

## 🏷️ Embed Verification Badge in README

Add live verification status to your project's `README.md`:

```markdown
[![AdaLab Verified](https://adalab.cc/api/badge/OWNER/REPO)](https://adalab.cc/audit/OWNER/REPO)
```

Example Badge Output:

![AdaLab Badge Sample](https://adalab.cc/api/badge/modelcontextprotocol/servers)

---

## 🛠️ API Reference

### 1. Trigger Security Audit
```bash
POST /api/scan
Content-Type: application/json

{
  "repo": "modelcontextprotocol/servers"
}
```

### 2. Live Dynamic SVG Badge
```bash
GET /api/badge/[owner]/[repo]
Accept: image/svg+xml
```

### 3. Public Interactive Report
```bash
GET /audit/[owner]/[repo]
```

---

## 💻 Local Development

```bash
# Clone repository
git clone https://github.com/rexchou/adalab.git
cd adalab

# Install dependencies (pnpm or bun)
pnpm install

# Run local development server
pnpm dev

# Run automated batch scanner
bun scripts/batch-scanner.ts
```

Open [http://localhost:3000](http://localhost:3000) to view the live diagnostic terminal.

---

## 📄 License

MIT © [AdaLab Engine](https://adalab.cc)