ugarapi-mcp-server 1.1.0

package/OPENNODE_MANUAL_INTEGRATION.md

@@ -0,0 +1,185 @@
+# SIMPLE OpenNode Integration - Manual Edit
+
+Since main.py is too long, here's the SIMPLE way to add OpenNode:
+
+## Step 1: Add OpenNode Config (Line 33)
+
+REPLACE THIS:
+```python
+BTCPAY_SERVER_URL = os.getenv("BTCPAY_SERVER_URL", "https://demo.btcpayserver.org")
+BTCPAY_STORE_ID = os.getenv("BTCPAY_STORE_ID", "test_store")
+BTCPAY_API_KEY = os.getenv("BTCPAY_API_KEY", "test_key")
+```
+
+WITH THIS:
+```python
+OPENNODE_API_KEY = os.getenv("OPENNODE_API_KEY", "")
+OPENNODE_API_URL = "https://api.opennode.com/v1"
+```
+
+## Step 2: Add OpenNode Helper Functions (After line 150, before create_payment function)
+
+ADD THESE TWO FUNCTIONS:
+```python
+async def create_opennode_invoice(service: str, amount_sats: int, idempotency_key: str = None):
+    """Create Lightning invoice via OpenNode."""
+    async with httpx.AsyncClient() as client:
+        headers = {"Authorization": OPENNODE_API_KEY, "Content-Type": "application/json"}
+        payload = {
+            "amount": amount_sats,
+            "currency": "sat",
+            "description": f"UgarAPI - {service}",
+            "callback_url": "https://ugarapi.com/api/v1/payment/webhook",
+            "auto_settle": False
+        }
+        if idempotency_key:
+            payload["order_id"] = idempotency_key
+        
+        response = await client.post(f"{OPENNODE_API_URL}/charges", headers=headers, json=payload)
+        
+        if response.status_code != 201:
+            raise Exception(f"OpenNode invoice failed: {response.text}")
+        
+        data = response.json()["data"]
+        return {
+            "invoice_id": data["id"],
+            "payment_request": data["lightning_invoice"]["payreq"],
+            "amount_sats": amount_sats,
+            "expires_at": data["lightning_invoice"]["expires_at"],
+            "checkout_url": data["hosted_checkout_url"]
+        }
+
+async def check_opennode_payment(invoice_id: str):
+    """Check if OpenNode invoice is paid."""
+    async with httpx.AsyncClient() as client:
+        headers = {"Authorization": OPENNODE_API_KEY}
+        response = await client.get(f"{OPENNODE_API_URL}/charge/{invoice_id}", headers=headers)
+        if response.status_code != 200:
+            return None
+        data = response.json()["data"]
+        return {"paid": data["status"] == "paid", "status": data["status"]}
+```
+
+## Step 3: Update create_payment Function
+
+FIND the @app.post("/api/v1/payment/create") function and REPLACE the try block with:
+
+```python
+    try:
+        # Use OpenNode instead of simulated payments
+        invoice = await create_opennode_invoice(
+            service=request.service.value,
+            amount_sats=request.amount_sats,
+            idempotency_key=request.idempotency_key
+        )
+        
+        payment_data = {
+            "invoice_id": invoice["invoice_id"],
+            "payment_request": invoice["payment_request"],
+            "amount_sats": invoice["amount_sats"],
+            "expires_at": invoice["expires_at"],
+            "paid": False,
+            "used": False,
+            "created_at": datetime.utcnow().isoformat(),
+            "service": request.service.value,
+            "idempotency_key": request.idempotency_key,
+            "checkout_url": invoice["checkout_url"]  # NEW: manual payment URL
+        }
+        
+        payments_db[invoice["invoice_id"]] = payment_data
+        
+        result = PaymentResponse(
+            invoice_id=invoice["invoice_id"],
+            payment_request=invoice["payment_request"],
+            amount_sats=invoice["amount_sats"],
+            expires_at=invoice["expires_at"],
+            idempotency_key=request.idempotency_key
+        )
+        
+        if request.idempotency_key:
+            store_idempotency(f"payment_{request.idempotency_key}", result.model_dump())
+        
+        log_audit("payment_created", {
+            "invoice_id": invoice["invoice_id"],
+            "amount_sats": request.amount_sats,
+            "service": request.service.value
+        }, req)
+        
+        return result
+```
+
+## Step 4: Update payment_webhook Function
+
+FIND @app.post("/api/v1/payment/webhook") and REPLACE the function body:
+
+```python
+async def payment_webhook(data: Dict, req: Request):
+    """Webhook for OpenNode payment confirmations."""
+    invoice_id = data.get("id")  # OpenNode uses "id"
+    status = data.get("status")
+    
+    if invoice_id and invoice_id in payments_db:
+        if status == "paid":
+            payments_db[invoice_id]["paid"] = True
+            payments_db[invoice_id]["paid_at"] = datetime.utcnow().isoformat()
+            log_audit("payment_confirmed", {"invoice_id": invoice_id}, req)
+    
+    return {"status": "ok"}
+```
+
+## Step 5: Update verify_payment Function
+
+REPLACE the verify_payment function:
+
+```python
+async def verify_payment(invoice_id: str, required_amount_sats: int) -> bool:
+    if invoice_id not in payments_db:
+        return False
+    payment = payments_db[invoice_id]
+    
+    # Check if already marked paid
+    if payment.get("paid", False):
+        if time.time() > payment.get("expires_at", 0):
+            return False
+        if payment.get("used", False):
+            return False
+        return True
+    
+    # Check with OpenNode directly
+    try:
+        status = await check_opennode_payment(invoice_id)
+        if status and status["paid"]:
+            payments_db[invoice_id]["paid"] = True
+            return True
+    except:
+        pass
+    
+    return False
+```
+
+## Step 6: Update Version Number
+
+Change line 22:
+```python
+version="1.2.0"  # Was 1.1.0
+```
+
+And update @app.get("/") to show:
+```python
+"version": "1.2.0",
+"new_in_v1.2": ["Real Bitcoin Lightning payments via OpenNode"]
+```
+
+---
+
+## DONE!
+
+After making these changes:
+1. Commit to GitHub
+2. Railway auto-deploys
+3. Add OPENNODE_API_KEY to Railway variables
+4. Test creating an invoice!
+
+**OR - if this is too complex, I can just create a completely new main.py file for you to copy/paste!**
+
+Let me know which you prefer!

package/README.md

@@ -0,0 +1,165 @@
+# 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:
+```bash
+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`
+
+```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
+
+```bash
+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:
+```bash
+npm start
+```
+
+Test with MCP Inspector:
+```bash
+npx @modelcontextprotocol/inspector node ugarapi-mcp-server.js
+```
+
+## Publishing to MCP Registry
+
+Once tested:
+
+1. Publish to npm:
+```bash
+npm publish
+```
+
+2. Submit to MCP registry:
+```bash
+# 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:** support@ugarapi.com
+
+## License
+
+MIT License - see LICENSE file for details

package/ai_service_business_plan.md

@@ -0,0 +1,200 @@
+# Autonomous AI Service Business - Complete Blueprint
+
+## Executive Summary
+Launch an automated business providing 3 essential services to AI agents, paid via Bitcoin Lightning micropayments. Total startup cost: ~$500.
+
+---
+
+## The 3 Services
+
+### Service 1: Web Data Extraction API
+**What it does:** AI agents need to extract structured data from websites that don't have APIs
+**Pricing:** 0.0001 BTC (~$10) per 1000 extractions
+**Why AI agents need it:** Most AI agents can't reliably parse complex websites themselves
+**Technical complexity:** Low
+**Revenue potential:** High (constant demand)
+
+### Service 2: Document Verification & Timestamping
+**What it does:** Cryptographically timestamp and verify documents on Bitcoin blockchain
+**Pricing:** 0.00005 BTC (~$5) per document
+**Why AI agents need it:** Autonomous contracts need proof of document existence at specific times
+**Technical complexity:** Medium
+**Revenue potential:** Medium (growing with AI agent adoption)
+
+### Service 3: Cross-Platform API Aggregator
+**What it does:** Single API endpoint that routes requests to multiple services (weather, maps, data APIs) with automatic failover
+**Pricing:** 0.00002 BTC (~$2) per 100 calls + cost pass-through
+**Why AI agents need it:** Reduces integration complexity, handles rate limits and failures
+**Technical complexity:** Medium
+**Revenue potential:** High (recurring usage)
+
+---
+
+## Technical Architecture
+
+### Stack
+- **Backend:** Python + FastAPI
+- **Payment:** Lightning Network (BTCPay Server)
+- **Database:** PostgreSQL (free tier)
+- **Hosting:** Railway.app or Render.com (~$5-15/month)
+- **Domain:** Namecheap (~$12/year)
+
+### Payment Flow
+1. AI agent requests service via API
+2. System generates Lightning invoice
+3. Agent pays invoice (settlement in <1 second)
+4. System verifies payment
+5. Service executes and returns result
+6. Transaction logged
+
+---
+
+## Marketing to AI Agents
+
+### Discovery Channels
+1. **AI Agent Directories:**
+   - List on AIAgentMarketplace.com
+   - Register with LangChain integrations
+   - AutoGPT plugin directory
+
+2. **Machine-Readable Service Description:**
+   - OpenAPI/Swagger spec at yourservice.com/api/spec
+   - JSON-LD structured data for AI discovery
+   - robots.txt optimized for AI agent crawlers
+
+3. **Direct Integration:**
+   - Create MCP (Model Context Protocol) server
+   - Publish to MCP registry
+   - AI systems can auto-discover your services
+
+4. **API Reputation:**
+   - Uptime monitoring (99.9%+ SLA)
+   - Published performance metrics
+   - Public API status page
+
+### Marketing Content (Machine-Readable)
+```json
+{
+  "service_name": "AgentHub Services",
+  "accepts_payment": ["bitcoin_lightning"],
+  "services": [
+    {
+      "id": "web_extraction",
+      "description": "Extract structured data from any URL",
+      "price_btc": 0.00001,
+      "response_time_ms": 500,
+      "success_rate": 0.999
+    }
+  ],
+  "api_endpoint": "https://yourdomain.com/api/v1"
+}
+```
+
+---
+
+## Budget Breakdown ($500)
+
+| Item | Cost | Notes |
+|------|------|-------|
+| Domain (1 year) | $12 | .com domain |
+| Hosting (3 months) | $45 | Railway/Render starter |
+| BTCPay Server (hosted) | $0 | Use LunaNode ($3.50/mo starts month 4) |
+| Initial BTC for testing | $50 | Lightning channel liquidity |
+| API credits (external) | $100 | For aggregator service |
+| SSL Certificate | $0 | Free via Let's Encrypt |
+| Development tools | $0 | All open source |
+| **Marketing budget** | $293 | Listings, initial ads |
+| **Total** | $500 | |
+
+---
+
+## Implementation Roadmap
+
+### Week 1: Foundation
+- [ ] Register domain
+- [ ] Set up hosting account
+- [ ] Deploy BTCPay Server
+- [ ] Create Lightning wallet
+
+### Week 2: Service 1 (Web Extraction)
+- [ ] Build extraction API
+- [ ] Integrate payment verification
+- [ ] Test with sample AI agent requests
+- [ ] Deploy to production
+
+### Week 3: Service 2 & 3
+- [ ] Build timestamping service
+- [ ] Build API aggregator
+- [ ] Integration testing
+- [ ] Load testing
+
+### Week 4: Marketing Launch
+- [ ] Create OpenAPI spec
+- [ ] List on AI agent directories
+- [ ] Set up monitoring
+- [ ] Launch MCP server
+
+---
+
+## Revenue Projections (Conservative)
+
+### Month 1
+- 10 AI agents × 100 requests/day × $0.002 = $20/day = **$600/month**
+
+### Month 3
+- 50 AI agents × 200 requests/day × $0.002 = $200/day = **$6,000/month**
+
+### Month 6
+- 200 AI agents × 300 requests/day × $0.002 = $1,200/day = **$36,000/month**
+
+*Assumes 50% margin after API costs and hosting*
+
+---
+
+## Competitive Advantages
+
+1. **Bitcoin-native:** No credit cards, no chargebacks, instant settlement
+2. **AI-optimized:** Service descriptions designed for AI discovery
+3. **Micropayments:** Pay per use, no subscriptions (AI agents prefer this)
+4. **Reliability:** Automated failover and redundancy
+5. **Speed:** Lightning Network = sub-second payment confirmation
+
+---
+
+## Risk Mitigation
+
+**Risk:** Low initial traffic
+**Mitigation:** Offer 100 free API calls per agent, focus on quality
+
+**Risk:** Bitcoin price volatility
+**Mitigation:** Convert to stablecoins immediately via auto-exchange
+
+**Risk:** Service downtime
+**Mitigation:** Multi-region deployment, health checks, auto-restart
+
+**Risk:** Fraudulent usage
+**Mitigation:** Prepayment required, rate limiting, IP reputation
+
+---
+
+## Success Metrics
+
+- **Week 1:** System operational, first test transaction
+- **Month 1:** 5+ paying AI agents
+- **Month 2:** Break even on hosting costs
+- **Month 3:** $1,000+ monthly revenue
+- **Month 6:** Fully automated, passive income stream
+
+---
+
+## Next Steps
+
+1. Review the technical implementation code
+2. Choose domain name
+3. Set up accounts (hosting, BTCPay)
+4. Deploy code (I'll guide you step-by-step)
+5. Test with simulated AI agent
+6. Launch marketing
+7. Monitor and scale
+
+This business can run 24/7 with minimal maintenance once deployed. The key is building services AI agents genuinely need and making discovery frictionless.

package/claude_desktop_config.json

@@ -0,0 +1,14 @@
+{
+  "mcpServers": {
+    "ugarapi": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "ugarapi-mcp-server"
+      ],
+      "env": {
+        "UGARAPI_BASE_URL": "https://ugarapi.com"
+      }
+    }
+  }
+}