@gblin-protocol/mcp-server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GBLIN Protocol
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,213 @@
+# GBLIN MCP Server
+
+> **Treasury standard for AI agents on Base mainnet.** A Model Context Protocol (MCP) server that lets autonomous agents hold capital in GBLIN — a diversified, Crash-Shield-protected on-chain index — and Just-In-Time swap to USDC the millisecond they need to pay an [x402](https://docs.cdp.coinbase.com/x402/welcome) invoice.
+
+[![npm](https://img.shields.io/npm/v/@gblin-protocol/mcp-server.svg)](https://www.npmjs.com/package/@gblin-protocol/mcp-server)
+[![CI](https://github.com/gblinproject/GBLIN-MCP/actions/workflows/ci.yml/badge.svg)](https://github.com/gblinproject/GBLIN-MCP/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Base Mainnet](https://img.shields.io/badge/network-Base%20mainnet-0052FF)](https://basescan.org/address/0x38DcDB3A381677239BBc652aed9811F2f8496345)
+
+📖 **Full documentation and Quick Start:** [gblin.digital/agents](https://gblin.digital/agents)
+
+---
+
+## Why this exists
+
+AI agents today hold their working capital in **USDC**. USDC sits flat: zero yield, full inflation exposure.
+
+**GBLIN** is an on-chain index on Base (45% cbBTC + 45% WETH + 10% USDC) with an algorithmic Crash Shield that auto-rebalances toward USDC when a basket asset drops >20%. Agents holding GBLIN earn basket appreciation while keeping the ability to settle x402 invoices instantly via native one-tx atomic swaps.
+
+This server exposes that capability to any LLM agent through the standard MCP protocol.
+
+---
+
+## Quick start
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json` (on Windows: `%APPDATA%\Claude\claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "gblin": {
+      "command": "npx",
+      "args": ["-y", "@gblin-protocol/mcp-server"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop. The 5 GBLIN tools appear in the tool picker.
+
+### Windsurf / Cursor
+
+Add to `~/.codeium/windsurf/mcp_config.json` (Windsurf) or the equivalent Cursor MCP config:
+
+```json
+{
+  "mcpServers": {
+    "gblin": {
+      "command": "npx",
+      "args": ["-y", "@gblin-protocol/mcp-server"],
+      "env": {
+        "GBLIN_RPC_URL": "https://base-rpc.publicnode.com"
+      }
+    }
+  }
+}
+```
+
+Refresh MCP servers from the IDE settings (or restart). The tools become callable inline.
+
+### Coinbase AgentKit (TypeScript)
+
+```ts
+import { MCPClient } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+
+const transport = new StdioClientTransport({
+  command: "npx",
+  args: ["-y", "@gblin-protocol/mcp-server"],
+});
+const client = new MCPClient({ name: "my-agent", version: "1.0.0" });
+await client.connect(transport);
+
+// List tools
+const { tools } = await client.listTools();
+
+// Quote a JIT payment of $0.50
+const jit = await client.callTool({
+  name: "swap_gblin_to_usdc_jit",
+  arguments: { usdc_needed: "0.50", wallet_address: "0xYourAgent..." },
+});
+```
+
+### ElizaOS / custom
+
+Any framework that speaks MCP over stdio works:
+
+```bash
+npx @gblin-protocol/mcp-server
+```
+
+Also supports Cline, Continue.dev, and any agent that implements the MCP client spec.
+
+---
+
+## The 5 tools
+
+| Tool | Purpose |
+|---|---|
+| `get_treasury_state` | NAV in USD + basket composition + Crash Shield status |
+| `quote_safe_swap` | Preview buy or sell with dynamic slippage buffer |
+| `swap_gblin_to_usdc_jit` | **The x402 magic**: generate atomic GBLIN→USDC calldata |
+| `invest_usdc_to_gblin` | Convert USDC earnings into GBLIN treasury (MEV-safe) |
+| `analyze_treasury_health` | Balances + gas + runway + rebalance advice |
+
+All tools return structured JSON. All values are quoted on-chain (NAV via `quoteSellGBLIN` × Chainlink ETH/USD, with 24h staleness guard). No mock data.
+
+**Live verification:** the test suite (`npm test`) runs all five tools against Base mainnet and confirms calldata generation, oracle freshness, and slippage math. See the [latest CI run](https://github.com/gblinproject/GBLIN-MCP/actions).
+
+---
+
+## Architectural decisions
+
+### Native atomic swap
+
+The GBLIN contract exposes `sellGBLINForToken(amount, targetToken, fee, minOut)`. This burns GBLIN, swaps the basket → WETH → target token in a **single transaction**. No batched UserOp, no ERC-4337 dependency, no risk of half-finished JIT.
+
+The MCP returns calldata that works identically on:
+- **EOA wallets** (Privy, MetaMask, raw private key)
+- **ERC-4337 smart accounts** (Safe, Coinbase smart account)
+- **EIP-7702 delegated EOAs** (Pectra+)
+
+### Dynamic slippage
+
+Slippage tolerance scales with on-chain risk regime:
+
+| Condition | Buffer |
+|---|---|
+| Normal market | **2.5%** |
+| Crash Shield active (≥1 basket asset slashed) | **4.0%** |
+
+The buffer is applied on top of the contract's internal `maxInternalSlippage` (200 bps), absorbing oracle drift and Uniswap pool variance.
+
+### MEV protection
+
+`invest_usdc_to_gblin` **never** passes `minOut = 0`. Both `minWethOut` and `minGblinOut` are computed from on-chain quotes plus the dynamic slippage buffer. This eliminates the sandwich-attack surface that plagues naïve buy-with-token tools.
+
+### Cooldown enforcement
+
+The contract enforces a 120-second sell lock after each buy. The JIT tool reads `lastDepositTime` and the **on-chain `block.timestamp`** (never `Date.now()`) and returns a clear `CooldownActive` error with the exact seconds remaining if the swap would revert.
+
+---
+
+## Configuration
+
+The server reads `GBLIN_RPC_URL` from the environment. With no env var it falls back to `https://base-rpc.publicnode.com` (free, no key, generous limits).
+
+For production load (>100 concurrent agents) use a dedicated provider:
+
+```bash
+export GBLIN_RPC_URL="https://base-mainnet.g.alchemy.com/v2/YOUR_KEY"
+npx @gblin-protocol/mcp-server
+```
+
+See `.env.example` for the full list.
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/gblinproject/GBLIN-MCP
+cd GBLIN-MCP
+npm install
+npm run build
+npm test         # live read-only smoke test against Base mainnet
+npm start        # run the compiled server
+```
+
+Project layout:
+
+```
+src/
+  config.ts    # network constants, addresses, slippage params
+  abi.ts       # GBLIN_V5 + Chainlink + ERC-20 ABIs
+  client.ts    # viem PublicClient + on-chain timestamp helper
+  helpers.ts   # NAV, basket state, slippage, cooldown, reverse quote
+  tools.ts     # the 5 tool implementations + zod schemas
+  index.ts     # MCP stdio server entry
+scripts/
+  test.ts      # live smoke test
+```
+
+---
+
+## Security notes
+
+- The server is **read-only**. It never holds, signs, or broadcasts.
+- All quotes are derived from on-chain calls + Chainlink oracles. Stale or negative oracle answers cause the tool to abort with `OracleStale` / `OracleDead`.
+- The agent's wallet is the sole signer. Calldata returned by tools is plain ABI-encoded bytes — review before broadcasting in untrusted environments.
+- No telemetry, no analytics, no remote dependencies beyond the configured RPC.
+
+---
+
+## Roadmap
+
+- **v0.2**: Uniswap V3 QuoterV2 integration for sub-1% slippage precision
+- **v0.3**: Permit2 support (skip the approve step for x402 reinvestment)
+- **v0.4**: Streamable HTTP transport for hosted multi-agent setups
+- **v1.0**: Audited contract integration + remote-only deployment guide
+
+---
+
+## Links
+
+- **Contract**: [0x38DcDB3A38…6345](https://basescan.org/address/0x38DcDB3A381677239BBc652aed9811F2f8496345)
+- **Protocol site**: https://gblin.digital
+- **Agent docs**: https://gblin.digital/agents
+- **Issues**: https://github.com/gblinproject/GBLIN-MCP/issues
+
+MIT © 2026 GBLIN Protocol

package/dist/abi.d.ts

@@ -0,0 +1,260 @@
+/**
+ * GBLIN MCP — Contract ABIs
+ *
+ * Verified directly against GBLIN_V5.sol source on Base mainnet.
+ * The basket() return signature exactly matches the Asset struct field order.
+ */
+/**
+ * GBLIN_V5 selected functions.
+ *
+ * IMPORTANT — basket() returns the Asset struct in declaration order:
+ *   (token, oracle, poolFee, isStable, baseWeight, dynamicWeight, peakPrice, lastPeakUpdate)
+ *
+ * Common mistake: assuming a 5-field tuple. This caused real production bugs
+ * during the V4 audit cycle. Do not "simplify" this ABI.
+ */
+export declare const GBLIN_ABI: readonly [{
+    readonly name: "quoteBuyGBLIN";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly type: "uint256";
+        readonly name: "ethAmount";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+        readonly name: "gblinOut";
+    }, {
+        readonly type: "uint256";
+        readonly name: "founderFee";
+    }, {
+        readonly type: "uint256";
+        readonly name: "stabFee";
+    }];
+}, {
+    readonly name: "quoteSellGBLIN";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly type: "uint256";
+        readonly name: "gblinAmount";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+        readonly name: "ethOut";
+    }];
+}, {
+    readonly name: "basket";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly type: "uint256";
+        readonly name: "index";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "address";
+        readonly name: "token";
+    }, {
+        readonly type: "address";
+        readonly name: "oracle";
+    }, {
+        readonly type: "uint24";
+        readonly name: "poolFee";
+    }, {
+        readonly type: "bool";
+        readonly name: "isStable";
+    }, {
+        readonly type: "uint256";
+        readonly name: "baseWeight";
+    }, {
+        readonly type: "uint256";
+        readonly name: "dynamicWeight";
+    }, {
+        readonly type: "uint256";
+        readonly name: "peakPrice";
+    }, {
+        readonly type: "uint256";
+        readonly name: "lastPeakUpdate";
+    }];
+}, {
+    readonly name: "balanceOf";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly type: "address";
+        readonly name: "account";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}, {
+    readonly name: "totalSupply";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}, {
+    readonly name: "decimals";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "uint8";
+    }];
+}, {
+    readonly name: "lastDepositTime";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly type: "address";
+        readonly name: "user";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}, {
+    readonly name: "buyGBLIN";
+    readonly type: "function";
+    readonly stateMutability: "payable";
+    readonly inputs: readonly [{
+        readonly type: "uint256";
+        readonly name: "minGblinOut";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly name: "sellGBLINForEth";
+    readonly type: "function";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly type: "uint256";
+        readonly name: "gblinAmount";
+    }, {
+        readonly type: "uint256";
+        readonly name: "minEthOut";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly name: "sellGBLINForToken";
+    readonly type: "function";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly type: "uint256";
+        readonly name: "gblinAmount";
+    }, {
+        readonly type: "address";
+        readonly name: "targetToken";
+    }, {
+        readonly type: "uint24";
+        readonly name: "wethToTargetFee";
+    }, {
+        readonly type: "uint256";
+        readonly name: "minTokenOut";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly name: "buyGBLINWithToken";
+    readonly type: "function";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly type: "bytes";
+        readonly name: "path";
+    }, {
+        readonly type: "uint256";
+        readonly name: "amountIn";
+    }, {
+        readonly type: "uint256";
+        readonly name: "minWethOut";
+    }, {
+        readonly type: "uint256";
+        readonly name: "minGblinOut";
+    }];
+    readonly outputs: readonly [];
+}];
+/**
+ * Chainlink AggregatorV3Interface — only the read we need.
+ * Note: `answer` is int256 (can be negative — we guard against that).
+ */
+export declare const CHAINLINK_AGGREGATOR_ABI: readonly [{
+    readonly name: "latestRoundData";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "uint80";
+        readonly name: "roundId";
+    }, {
+        readonly type: "int256";
+        readonly name: "answer";
+    }, {
+        readonly type: "uint256";
+        readonly name: "startedAt";
+    }, {
+        readonly type: "uint256";
+        readonly name: "updatedAt";
+    }, {
+        readonly type: "uint80";
+        readonly name: "answeredInRound";
+    }];
+}, {
+    readonly name: "decimals";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "uint8";
+    }];
+}];
+/**
+ * Standard ERC-20 (USDC, etc).
+ */
+export declare const ERC20_ABI: readonly [{
+    readonly name: "balanceOf";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly type: "address";
+        readonly name: "account";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}, {
+    readonly name: "decimals";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "uint8";
+    }];
+}, {
+    readonly name: "approve";
+    readonly type: "function";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly type: "address";
+        readonly name: "spender";
+    }, {
+        readonly type: "uint256";
+        readonly name: "amount";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "bool";
+    }];
+}, {
+    readonly name: "allowance";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly type: "address";
+        readonly name: "owner";
+    }, {
+        readonly type: "address";
+        readonly name: "spender";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}];
+//# sourceMappingURL=abi.d.ts.map

package/dist/abi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"abi.d.ts","sourceRoot":"","sources":["../src/abi.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;;;;;;;GAQG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAqBpB,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAGnC,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAKpB,CAAC"}

package/dist/abi.js

@@ -0,0 +1,52 @@
+/**
+ * GBLIN MCP — Contract ABIs
+ *
+ * Verified directly against GBLIN_V5.sol source on Base mainnet.
+ * The basket() return signature exactly matches the Asset struct field order.
+ */
+import { parseAbi } from "viem";
+/**
+ * GBLIN_V5 selected functions.
+ *
+ * IMPORTANT — basket() returns the Asset struct in declaration order:
+ *   (token, oracle, poolFee, isStable, baseWeight, dynamicWeight, peakPrice, lastPeakUpdate)
+ *
+ * Common mistake: assuming a 5-field tuple. This caused real production bugs
+ * during the V4 audit cycle. Do not "simplify" this ABI.
+ */
+export const GBLIN_ABI = parseAbi([
+    // Quotes (view, gas-free)
+    "function quoteBuyGBLIN(uint256 ethAmount) view returns (uint256 gblinOut, uint256 founderFee, uint256 stabFee)",
+    "function quoteSellGBLIN(uint256 gblinAmount) view returns (uint256 ethOut)",
+    // Basket — full struct, 8 fields, do not truncate
+    "function basket(uint256 index) view returns (address token, address oracle, uint24 poolFee, bool isStable, uint256 baseWeight, uint256 dynamicWeight, uint256 peakPrice, uint256 lastPeakUpdate)",
+    // ERC-20 surface
+    "function balanceOf(address account) view returns (uint256)",
+    "function totalSupply() view returns (uint256)",
+    "function decimals() view returns (uint8)",
+    // State helpers
+    "function lastDepositTime(address user) view returns (uint256)",
+    // Mutating — only used to build calldata (never executed by the MCP server)
+    "function buyGBLIN(uint256 minGblinOut) payable",
+    "function sellGBLINForEth(uint256 gblinAmount, uint256 minEthOut)",
+    "function sellGBLINForToken(uint256 gblinAmount, address targetToken, uint24 wethToTargetFee, uint256 minTokenOut)",
+    "function buyGBLINWithToken(bytes path, uint256 amountIn, uint256 minWethOut, uint256 minGblinOut)",
+]);
+/**
+ * Chainlink AggregatorV3Interface — only the read we need.
+ * Note: `answer` is int256 (can be negative — we guard against that).
+ */
+export const CHAINLINK_AGGREGATOR_ABI = parseAbi([
+    "function latestRoundData() view returns (uint80 roundId, int256 answer, uint256 startedAt, uint256 updatedAt, uint80 answeredInRound)",
+    "function decimals() view returns (uint8)",
+]);
+/**
+ * Standard ERC-20 (USDC, etc).
+ */
+export const ERC20_ABI = parseAbi([
+    "function balanceOf(address account) view returns (uint256)",
+    "function decimals() view returns (uint8)",
+    "function approve(address spender, uint256 amount) returns (bool)",
+    "function allowance(address owner, address spender) view returns (uint256)",
+]);
+//# sourceMappingURL=abi.js.map

package/dist/abi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"abi.js","sourceRoot":"","sources":["../src/abi.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,MAAM,CAAC;AAEhC;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,QAAQ,CAAC;IAChC,0BAA0B;IAC1B,gHAAgH;IAChH,4EAA4E;IAE5E,kDAAkD;IAClD,kMAAkM;IAElM,iBAAiB;IACjB,4DAA4D;IAC5D,+CAA+C;IAC/C,0CAA0C;IAE1C,gBAAgB;IAChB,+DAA+D;IAE/D,4EAA4E;IAC5E,gDAAgD;IAChD,kEAAkE;IAClE,mHAAmH;IACnH,mGAAmG;CACpG,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,QAAQ,CAAC;IAC/C,uIAAuI;IACvI,0CAA0C;CAC3C,CAAC,CAAC;AAEH;;GAEG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,QAAQ,CAAC;IAChC,4DAA4D;IAC5D,0CAA0C;IAC1C,kEAAkE;IAClE,2EAA2E;CAC5E,CAAC,CAAC"}