<div align="center">
  <h1>🛡️ Gibwork Sentinel</h1>
  <p><strong>Autonomous Bounty Discovery CLI & Model Context Protocol (MCP) Server for Solana's Gibwork Protocol</strong></p>
</div>

---

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.8-blue?logo=typescript)](https://www.typescriptlang.org/)
[![Model Context Protocol](https://img.shields.io/badge/MCP-Standard-orange?logo=anthropic)](https://modelcontextprotocol.io/)
[![Solana](https://img.shields.io/badge/Solana-Mainnet--Beta-black?logo=solana)](https://solana.com)

**Gibwork Sentinel** is a developer automation utility, interactive terminal tool, and native **Model Context Protocol (MCP) Server** designed to bridge the **Gibwork Solana Bounty Protocol** (`gib.work`) with autonomous AI agents (Claude, Cursor, Antigravity, OpenCode) and terminal power users.

It eliminates the friction of web-app browsing by providing automated bounty discovery, on-chain Solana escrow verification, and automated project workspace scaffolding.

---

## 🚀 Key Features

- **⚡ Fast Terminal CLI (`gib-sentinel`)**: Real-time filtering across active Gibwork bounties by payout amount (USDC/SOL), category, and status.
- **🤖 Native Model Context Protocol (MCP) Server**: Enables LLM agents to autonomously discover tasks, read deliverable specifications, and verify escrow parameters via standard MCP tools.
- **🔒 On-Chain Solana Escrow Verification**: Directly queries Solana Mainnet JSON-RPC to verify that advertised bounty token mints (e.g. SPL USDC `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v`) exist and are valid before committing development hours.
- **📁 Automated Workspace Scaffolding**: Automatically creates an isolated project directory with task metadata, deliverable checklists (`DELIVERABLE_SPEC.md`), and PR templates for any claimed bounty.

---

## 📦 Installation & Setup

### Prerequisites
- Node.js `>= 18.0.0`
- npm or pnpm

### Global Installation (or Run with npx)
```bash
git clone https://github.com/TomerGamerTV/gibwork-sentinel.git
cd gibwork-sentinel
npm install
npm run build
npm link
```

---

## 🛠️ CLI Usage Guide

### 1. List Open Bounties
Discover all open bounties funded on Solana:
```bash
gib-sentinel list
```

Filter by minimum reward amount and token:
```bash
# Bounties paying >= 100 USDC
gib-sentinel list --min 100 --token USDC

# Filter by category
gib-sentinel list --category Development
```

Output as machine-readable JSON:
```bash
gib-sentinel list --json
```

### 2. Inspect Bounty Requirements
Fetch full requirements, deadline, and creator metadata:
```bash
gib-sentinel inspect 1052f22d-3f87-4b1d-b0d7-71a60679e7fa
```

### 3. Verify On-Chain Solana Escrow
Cross-validate the token mint and escrow contract parameters on Solana Mainnet:
```bash
gib-sentinel verify 1052f22d-3f87-4b1d-b0d7-71a60679e7fa
```

Sample output:
```text
Verifying on-chain parameters for task 1052f22d-3f87-4b1d-b0d7-71a60679e7fa...

--- Solana Escrow & Mint Verification ---
Network:      Solana Mainnet-Beta
Token Mint:   EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
Token Symbol: USDC
Status:       VERIFIED_ON_CHAIN
Notes:        Canonical USDC (USD Coin)
-----------------------------------------
```

### 4. Scaffold Development Workspace
Automatically scaffold an isolated deliverable environment:
```bash
gib-sentinel scaffold 1052f22d-3f87-4b1d-b0d7-71a60679e7fa
```

Creates:
```text
bounty_workspaces/gibwork-developer-hackathon-bounty-1052f22d/
├── task_metadata.json
├── DELIVERABLE_SPEC.md
└── PULL_REQUEST_TEMPLATE.md
```

---

## 🤖 Model Context Protocol (MCP) Integration

Gibwork Sentinel exposes 4 native MCP tools for autonomous AI agents:

| Tool Name | Description | Arguments |
| :--- | :--- | :--- |
| `gibwork_list_bounties` | List and filter active bounties from Gibwork | `minAmount`, `token`, `category`, `search` |
| `gibwork_get_bounty_details` | Get complete description and requirements | `taskId` (UUID) |
| `gibwork_verify_escrow` | Verify on-chain Solana mint & escrow parameters | `taskId` (UUID) |
| `gibwork_scaffold_workspace` | Scaffold local development directory | `taskId` (UUID), `outputDir` |

### Configuration for Claude Desktop / Cursor / Antigravity

Add the following to your MCP settings configuration:

```json
{
  "mcpServers": {
    "gibwork-sentinel": {
      "command": "node",
      "args": ["/path/to/gibwork-sentinel/dist/mcp-server.js"]
    }
  }
}
```

---

## 🏛️ Architecture & Data Flow

```text
+---------------------+        +-------------------------+
|   Terminal User     |        |   Autonomous AI Agent   |
|   (gib-sentinel)    |        |   (Claude / Cursor MCP) |
+----------+----------+        +------------+------------+
           |                                |
           +---------------+----------------+
                           |
                           v
              +--------------------------+
              |    Gibwork Sentinel      |
              |    Core Engine           |
              +-------------+------------+
                            |
            +---------------+---------------+
            |                               |
            v                               v
+-----------------------+       +------------------------+
|  Gibwork Explore API  |       |   Solana Mainnet RPC   |
|  (api.gib.work)       |       |   (Token Mint Verify)  |
+-----------------------+       +------------------------+
```

---

## 📄 License

MIT License. Authored by **Tomer** ([@TomerGamerTV](https://github.com/TomerGamerTV)).