UgarAPI MCP Server

Model Context Protocol (MCP) server for UgarAPI - enables AI agents to discover and use UgarAPI services with Bitcoin Lightning payments.

What This Does

Exposes UgarAPI's services as MCP tools that AI systems (Claude, ChatGPT, etc.) can discover and use automatically:

• extract_web_data - Extract structured data from websites using CSS selectors
• timestamp_document - Create blockchain timestamp proofs for documents
• aggregate_api_call - Route requests through external APIs with failover

All payments are handled automatically via Bitcoin Lightning micropayments.

Installation

For End Users (Claude Desktop, etc.)

1. Install via npm:

npm install -g ugarapi-mcp-server

2. Add to your MCP settings file:

Claude Desktop (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json

Claude Desktop (Windows): %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "ugarapi": {
      "command": "ugarapi-mcp",
      "env": {
        "UGARAPI_BASE_URL": "https://ugarapi.com"
      }
    }
  }
}

3. Restart Claude Desktop

4. Claude can now use UgarAPI services automatically!

For Developers

git clone https://github.com/yourusername/ugarapi-mcp-server
cd ugarapi-mcp-server
npm install
node ugarapi-mcp-server.js

Usage Examples

Once installed, AI agents can use your services naturally:

Example 1: Web Scraping

User: "Extract the title and price from https://example.com/product"

Claude: [calls extract_web_data tool]
- Creates Lightning invoice (1000 sats)
- Pays automatically
- Returns extracted data

Example 2: Document Timestamping

User: "Timestamp this document hash: abc123..."

Claude: [calls timestamp_document tool]
- Creates Lightning invoice (5000 sats)
- Pays automatically
- Returns blockchain proof

Example 3: API Aggregation

User: "What's the weather in Tokyo?"

Claude: [calls aggregate_api_call tool]
- Creates Lightning invoice (200 sats)
- Pays automatically
- Returns weather data

How Payments Work

1. First Call: MCP server creates a Lightning invoice for the service
2. Payment: Invoice is paid automatically (in production, you'd configure a Lightning wallet)
3. Service Call: Once paid, the service executes
4. Idempotency: Same requests won't be charged twice (cached for 24 hours)

Configuration

Environment variables:

• UGARAPI_BASE_URL - UgarAPI API endpoint (default: https://ugarapi.com)

Payment Setup (Production)

For production use with real payments, you need:

1. Lightning Wallet - Set up a wallet that can pay invoices programmatically
2. Auto-Payment Logic - Configure the MCP server to pay invoices automatically
3. Spending Limits - Set maximum spend per hour/day to prevent runaway costs

See docs/payment-setup.md for detailed instructions.

Features

✅ Idempotency - Safe retries, no double charges ✅ Rate Limiting - Respects UgarAPI rate limits
✅ Error Handling - Clear error messages for agents ✅ Receipts - Full transaction history ✅ Audit Trail - All calls are logged

Development

Run in development mode:

npm start

Test with MCP Inspector:

npx @modelcontextprotocol/inspector node ugarapi-mcp-server.js

Publishing to MCP Registry

Once tested:

1. Publish to npm:

npm publish

2. Submit to MCP registry:

# Follow instructions at https://github.com/modelcontextprotocol/servers

3. AI systems can now discover UgarAPI automatically!

Roadmap

• [ ] Automatic Lightning payment integration
• [ ] Spending limit controls
• [ ] Multi-agent usage tracking
• [ ] Advanced caching strategies
• [ ] Support for more UgarAPI services as they launch

Support

• UgarAPI Docs: https://ugarapi.com/docs
• Issues: https://github.com/yourusername/ugarapi-mcp-server/issues
• Email: [email protected]

License

MIT License - see LICENSE file for details