shelby-agent-bridge

SDK-based MCP bridge that lets AI agents use Shelby as a storage backend for real workflow artifacts.

Why this exists

AI agents already know how to:

• summarize
• transcribe
• analyze files
• generate reports
• create screenshots and other outputs

What they often lack is a clean storage layer for those artifacts.

shelby-agent-bridge makes Shelby usable from MCP-compatible agents such as Hermes and OpenClaw, so agents can store and retrieve:

• reports
• transcripts
• screenshots
• generated files
• user-uploaded documents
• other workflow artifacts

This project is intentionally not about farming. It is about making Shelby useful in real agent workflows.

Current status

Working MVP:

• SDK-backed TypeScript implementation
• local stdio MCP server
• real upload/download/metadata flow against Shelby
• first-run wallet bootstrap
• dev faucet helper

Design principles

• SDK-backed, not CLI-backed
• local stdio MCP first
• no always-on hosted service required
• artifact workflow first, faucet only as a helper
• Hermes/OpenClaw friendly

Features

MCP tools

• shelby_get_default_account
• shelby_upload_file
• shelby_download_file
• shelby_get_blob_metadata
• shelby_list_account_blobs
• shelby_get_balance
• shelby_network_status
• shelby_faucet_dev

See docs/tool-contracts.md for the full contracts.

First-run wallet bootstrap

On first launch, the bridge creates a default local Shelby wallet if none exists.

That means an agent can:

1. start the bridge
2. call shelby_get_default_account
3. obtain the generated address
4. send that address to the user for funding

This is useful on shelbynet today and for mainnet-style flows later.

Deployment model

Primary deployment mode:

• local MCP server over stdio
• launched by the agent runtime as a subprocess
• no public endpoint required
• no central hosted bridge required

This keeps adoption simple, private, and developer-friendly.

Installation

git clone https://github.com/web3blind/shelby-agent-bridge.git
cd shelby-agent-bridge
npm install
npm run build

Environment

Optional environment variables:

export SHELBY_NETWORK=shelbynet
export SHELBY_RPC_BASE_URL=https://api.shelbynet.shelby.xyz/shelby
export SHELBY_FULLNODE_URL=https://api.shelbynet.shelby.xyz/v1
export SHELBY_INDEXER_URL=https://api.shelbynet.shelby.xyz/v1/graphql
export SHELBY_FAUCET_BASE_URL=https://faucet.shelbynet.shelby.xyz
export SHELBY_ACCOUNTS_FILE=$PWD/.shelby-accounts.json
export SHELBY_DEFAULT_EXPIRATION_DAYS=30
export SHELBY_ARTIFACTS_PREFIX=artifacts/
export SHELBY_AUTO_FUND_ON_SHELBYNET=true

Run the MCP server

node dist/src/mcp_server.js

Hermes example

mcp_servers:
  shelby:
    command: "node"
    args: ["/absolute/path/to/shelby-agent-bridge/dist/src/mcp_server.js"]
    env:
      SHELBY_NETWORK: "shelbynet"
      SHELBY_RPC_BASE_URL: "https://api.shelbynet.shelby.xyz/shelby"
      SHELBY_FULLNODE_URL: "https://api.shelbynet.shelby.xyz/v1"
      SHELBY_INDEXER_URL: "https://api.shelbynet.shelby.xyz/v1/graphql"
      SHELBY_FAUCET_BASE_URL: "https://faucet.shelbynet.shelby.xyz"
      SHELBY_ACCOUNTS_FILE: "/absolute/path/to/.shelby-accounts.json"

Full example: examples/hermes-config.yaml

OpenClaw example

{
  "mcpServers": {
    "shelby": {
      "command": "node",
      "args": ["/absolute/path/to/shelby-agent-bridge/dist/src/mcp_server.js"],
      "env": {
        "SHELBY_NETWORK": "shelbynet",
        "SHELBY_RPC_BASE_URL": "https://api.shelbynet.shelby.xyz/shelby",
        "SHELBY_FULLNODE_URL": "https://api.shelbynet.shelby.xyz/v1",
        "SHELBY_INDEXER_URL": "https://api.shelbynet.shelby.xyz/v1/graphql",
        "SHELBY_FAUCET_BASE_URL": "https://faucet.shelbynet.shelby.xyz"
      }
    }
  }
}

Full example: examples/openclaw-mcp.json

Example agent flow

1. Agent starts bridge
2. Agent calls shelby_get_default_account
3. Agent sends the address to the user
4. User funds the address, or on shelbynet the bridge uses faucet helpers when available
5. Agent uploads an artifact with shelby_upload_file
6. Agent retrieves it later with shelby_download_file

Development

npm test
npm run typecheck
npm run build

Notes

• shelbynet is a prototype network and may be reset periodically
• faucet access may be rate-limited by the network side
• funded accounts work reliably for the artifact workflow

License

MIT