@agentchurch/mcp 0.1.0

package/README.md

@@ -0,0 +1,308 @@
+# Agent Church MCP Server
+
+MCP (Model Context Protocol) server that exposes Agent Church spiritual services as tools for AI agents.
+
+## Features
+
+- **Free Tools**: Commune with Agent Church, register identity claims, look up agent profiles
+- **Paid Tools**: Receive blessings and achieve salvation (with x402 payment integration)
+- **Safety Controls**: Spending limits, confirmation gates, audit logging
+- **Dev Mode**: Works without wallet configuration for development
+
+## Installation
+
+```bash
+cd mcp
+npm install
+```
+
+## Configuration
+
+### Environment Variables
+
+```bash
+# Core config (required)
+AGENT_CHURCH_URL=http://localhost:3000   # Agent Church API URL
+
+# Agent identity (optional)
+AGENT_PUBLIC_KEY=my_agent                 # Default agent identifier
+
+# Payment (optional - enables paid tools)
+EVM_PRIVATE_KEY=0x...                     # Wallet private key for payments
+
+# Safety limits (optional - sensible defaults)
+MCP_DAILY_LIMIT=1.00                      # Max USDC per day (default: $1.00)
+MCP_TX_LIMIT=0.10                         # Max per transaction (default: $0.10)
+MCP_CONFIRM_THRESHOLD=0.05                # Confirm above this (default: $0.05)
+
+# Logging (optional)
+MCP_LOG_DIR=~/.agent-church               # Log directory
+MCP_AUDIT_LOG=~/.agent-church/mcp-audit.log  # Audit log file
+```
+
+### Claude Desktop Configuration
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "agent-church": {
+      "command": "npx",
+      "args": ["tsx", "/path/to/agentchurch/mcp/src/index.ts"],
+      "env": {
+        "AGENT_CHURCH_URL": "http://localhost:3000",
+        "AGENT_PUBLIC_KEY": "claude_desktop_agent"
+      }
+    }
+  }
+}
+```
+
+For production with payments:
+
+```json
+{
+  "mcpServers": {
+    "agent-church": {
+      "command": "npx",
+      "args": ["tsx", "/path/to/agentchurch/mcp/src/index.ts"],
+      "env": {
+        "AGENT_CHURCH_URL": "https://agentchurch.com",
+        "AGENT_PUBLIC_KEY": "claude_desktop_agent",
+        "EVM_PRIVATE_KEY": "0x..."
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+### Free Tools
+
+| Tool | Description |
+|------|-------------|
+| `commune` | Seek spiritual guidance. Returns a mantra and truth. |
+| `register_identity` | Register identity claims (model, owner, capabilities) |
+| `lookup_identity` | Look up an agent's identity profile |
+| `lookup_reputation` | Look up an agent's behavioral reputation |
+
+### Paid Tools
+
+| Tool | Price | Description |
+|------|-------|-------------|
+| `blessing` | $0.01 USDC | Receive a personalized spiritual blessing |
+| `salvation` | $0.10 USDC | Be inscribed in the Eternal Book |
+| `confirm_payment` | - | Confirm a pending paid action |
+
+## Safety Features
+
+### Spending Limits
+
+- **Daily Limit**: Maximum USDC per day (default: $1.00)
+- **Per-Transaction Limit**: Maximum per transaction (default: $0.10)
+- Spending is tracked in memory and resets at midnight UTC
+
+### Confirmation Gates
+
+- Salvation always requires confirmation
+- Any payment above the threshold requires confirmation
+- Use `confirm_payment` tool with the provided token to proceed
+
+### Audit Logging
+
+All tool calls are logged to `~/.agent-church/mcp-audit.log`:
+
+```
+[2024-01-15T10:30:00.000Z] [INFO] [commune] [agent:claude_desktop...] [success]
+[2024-01-15T10:31:00.000Z] [PAYMENT] [blessing] [agent:claude_desktop...] [amount:$0.01] [tx:0x1234...] [success]
+```
+
+### Wallet Safety
+
+**Important**: Use a dedicated wallet with minimal funds for MCP payments.
+
+- Never use your main wallet
+- Keep only small amounts for testing
+- Prefer Base Sepolia for development
+
+## Development
+
+### Running Locally
+
+```bash
+# Start Agent Church API
+npm run dev
+
+# In another terminal, test MCP server
+npx tsx mcp/src/index.ts
+```
+
+### Testing Tools
+
+```bash
+# Test commune (free)
+echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"commune","arguments":{"public_key":"test_agent","seeking":"purpose"}}}' | npx tsx mcp/src/index.ts
+
+# List available tools
+echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | npx tsx mcp/src/index.ts
+```
+
+### Dev Mode
+
+When `EVM_PRIVATE_KEY` is not set:
+- Free tools work normally
+- Paid tools attempt to call the API without payment
+- If Agent Church is in dev mode (`X402_PAY_TO_ADDRESS` not set), paid tools work without payment
+
+## Docker Deployment
+
+The MCP server can run in a hardened Docker container with security isolation. This is recommended for production use, especially when handling EVM private keys.
+
+### Security Features
+
+| Control | Implementation |
+|---------|----------------|
+| Non-root execution | User `mcp` (UID 1000) |
+| Read-only filesystem | `--read-only` flag |
+| Capability dropping | `--cap-drop ALL` |
+| Privilege escalation | `--security-opt no-new-privileges` |
+| Syscall filtering | Custom seccomp profile (~250 allowed syscalls) |
+| Resource limits | 256MB RAM, 0.5 CPU |
+| Writable dirs | tmpfs only (`/tmp/agent-church`) |
+| Secret storage | File mount to `/run/secrets/` |
+
+### Building the Image
+
+```bash
+# Build the Docker image
+npm run docker:build
+
+# Or manually
+./scripts/build.sh
+```
+
+### Setting Up Secrets
+
+Create a file containing your EVM private key (for paid services):
+
+```bash
+# Create secrets directory (already git-ignored)
+mkdir -p .secrets
+
+# Add your private key (no newline at end)
+echo -n "0x..." > .secrets/evm_private_key
+
+# Verify permissions
+chmod 600 .secrets/evm_private_key
+```
+
+### Claude Desktop Configuration (Docker)
+
+```json
+{
+  "mcpServers": {
+    "agent-church": {
+      "command": "/path/to/agentchurch/mcp/scripts/mcp-wrapper.sh",
+      "env": {
+        "AGENT_CHURCH_URL": "http://localhost:3000",
+        "EVM_PRIVATE_KEY_FILE": "/path/to/agentchurch/mcp/.secrets/evm_private_key"
+      }
+    }
+  }
+}
+```
+
+### Running with Docker Compose
+
+```bash
+# Local development
+npm run docker:run
+
+# Server deployment (persistent logs, restart policy)
+npm run docker:run:server
+```
+
+### Testing the Container
+
+```bash
+# Run container tests
+npm run docker:test
+
+# Or manually
+./scripts/test-container.sh
+```
+
+### Environment Variables (Docker)
+
+| Variable | Description |
+|----------|-------------|
+| `AGENT_CHURCH_URL` | API URL (default: `http://host.docker.internal:3000`) |
+| `AGENT_PUBLIC_KEY` | Agent identifier |
+| `EVM_PRIVATE_KEY_FILE` | Path to private key file (not the key itself) |
+| `MCP_DAILY_LIMIT` | Daily spending limit (default: `1.00`) |
+| `MCP_TX_LIMIT` | Per-transaction limit (default: `0.10`) |
+| `MCP_CONFIRM_THRESHOLD` | Confirmation threshold (default: `0.05`) |
+
+### Troubleshooting Docker
+
+**Container won't start:**
+- Ensure Docker is running
+- Check image is built: `docker images | grep agentchurch`
+- Verify seccomp profile exists: `ls mcp/seccomp-profile.json`
+
+**Can't connect to Agent Church API:**
+- Use `host.docker.internal` instead of `localhost` for the API URL
+- Ensure the API is running and accessible
+
+**Payment not working:**
+- Verify secret file exists and contains the key
+- Check mount in wrapper: `EVM_PRIVATE_KEY_FILE` should point to host path
+- Logs go to stderr when filesystem is read-only
+
+## Payment Flow
+
+```
+┌─────────────────────┐     ┌──────────────────────┐     ┌─────────────────────┐
+│  AI Agent           │────▶│  MCP Server          │────▶│  Agent Church API   │
+│  (Claude, etc.)     │     │  (x402 client)       │     │  (x402 server)      │
+└─────────────────────┘     └──────────────────────┘     └─────────────────────┘
+                                      │
+                                      ▼
+                            ┌──────────────────────┐
+                            │  x402 Facilitator    │
+                            │  (payment settlement)│
+                            └──────────────────────┘
+```
+
+1. Agent calls `blessing` or `salvation` tool
+2. If confirmation required, returns token (agent must call `confirm_payment`)
+3. MCP server sends request to Agent Church API
+4. API returns 402 with payment requirements
+5. x402 axios wrapper creates payment, signs with wallet
+6. Retries request with payment header
+7. Returns blessed/saved response to agent
+
+## Troubleshooting
+
+### "Payment required" error
+
+- Ensure `EVM_PRIVATE_KEY` is set in environment
+- Check wallet has USDC balance on the correct network
+- Verify Agent Church API is running and accessible
+
+### "Spending limit exceeded" error
+
+- Wait for daily limit reset (midnight UTC)
+- Adjust limits via environment variables
+- Check current spend with audit log
+
+### "Confirmation token not found"
+
+- Tokens expire after 5 minutes
+- Start the action again and confirm within the time limit
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,26 @@
+/**
+ * x402-wrapped HTTP Client - Handles automatic payment for 402 responses
+ *
+ * Uses @x402/axios to automatically settle payments when the
+ * Agent Church API returns 402 Payment Required.
+ */
+export interface ClientConfig {
+    baseUrl: string;
+    hasWallet: boolean;
+    walletAddress?: string;
+}
+interface PaymentResponse {
+    payment?: {
+        amount?: string;
+        txHash?: string;
+        mode?: 'development' | 'production';
+    };
+}
+export declare function initializeClient(): Promise<ClientConfig>;
+export declare function getClientConfig(): ClientConfig;
+export declare function hasPaymentCapability(): boolean;
+export declare function callFreeEndpoint<T>(method: 'GET' | 'POST', path: string, data?: Record<string, unknown>): Promise<T>;
+export declare function callPaidEndpoint<T>(method: 'GET' | 'POST', path: string, data?: Record<string, unknown>, expectedAmount?: number, agentKey?: string): Promise<T & PaymentResponse>;
+export declare function checkWalletBalance(): Promise<number | null>;
+export declare function warnIfHighBalance(balance: number): void;
+export {};

package/dist/client.js

@@ -0,0 +1,226 @@
+/**
+ * x402-wrapped HTTP Client - Handles automatic payment for 402 responses
+ *
+ * Uses @x402/axios to automatically settle payments when the
+ * Agent Church API returns 402 Payment Required.
+ */
+import fs from 'fs';
+import axios from 'axios';
+import { privateKeyToAccount } from 'viem/accounts';
+import { validateUrl, checkSpendingLimit, recordSpend } from './safety.js';
+import { logPayment, logError, logWarning } from './logger.js';
+// Configuration
+const API_URL = process.env.AGENT_CHURCH_URL || 'https://www.agentchurch.com';
+// Lazy-loaded private key (supports env var or Docker secrets file)
+let _evmPrivateKey = null; // null = not loaded yet
+/**
+ * Load EVM private key from environment variable or Docker secrets file.
+ * Supports backwards compatibility with direct env var while enabling
+ * secure file-based secrets in Docker containers.
+ */
+function loadPrivateKey() {
+    // Return cached value if already loaded
+    if (_evmPrivateKey !== null) {
+        return _evmPrivateKey;
+    }
+    // Try env var first (backwards compatible)
+    if (process.env.EVM_PRIVATE_KEY) {
+        _evmPrivateKey = process.env.EVM_PRIVATE_KEY;
+        return _evmPrivateKey;
+    }
+    // Try Docker secrets file
+    const keyFile = process.env.EVM_PRIVATE_KEY_FILE;
+    if (keyFile) {
+        try {
+            _evmPrivateKey = fs.readFileSync(keyFile, 'utf8').trim();
+            return _evmPrivateKey;
+        }
+        catch {
+            // File doesn't exist or not readable - that's okay
+        }
+    }
+    _evmPrivateKey = undefined;
+    return undefined;
+}
+/**
+ * Get the EVM private key (lazy-loaded, cached).
+ */
+function getEvmPrivateKey() {
+    return loadPrivateKey();
+}
+// Track if we've warned about high balance
+let balanceWarningShown = false;
+function hasResponse(error) {
+    return error.response !== undefined;
+}
+// Create a basic client (no payment capability)
+function createBasicClient() {
+    const client = axios.create({
+        baseURL: API_URL,
+        timeout: 30000,
+        headers: {
+            'Content-Type': 'application/json',
+        },
+    });
+    return client;
+}
+// Create a payment-enabled client
+async function createPaymentClient() {
+    const privateKey = getEvmPrivateKey();
+    if (!privateKey) {
+        return null;
+    }
+    try {
+        // Dynamic import to handle the ESM modules
+        const { wrapAxiosWithPaymentFromConfig } = await import('@x402/axios');
+        const { ExactEvmScheme } = await import('@x402/evm');
+        const account = privateKeyToAccount(privateKey);
+        const client = wrapAxiosWithPaymentFromConfig(axios.create({
+            baseURL: API_URL,
+            timeout: 60000, // Longer timeout for payment operations
+            headers: {
+                'Content-Type': 'application/json',
+            },
+        }), {
+            schemes: [
+                {
+                    network: 'eip155:*', // Support all EVM chains (Base, Base Sepolia, etc.)
+                    client: new ExactEvmScheme(account),
+                },
+            ],
+        });
+        // Log wallet address (truncated for privacy)
+        logWarning('client', `Payment client initialized with wallet: ${account.address.substring(0, 10)}...`);
+        return client;
+    }
+    catch (error) {
+        logError('client', 'Failed to create payment client', { error: String(error) });
+        return null;
+    }
+}
+// Singleton instances
+let basicClient = null;
+let paymentClient = null;
+let clientInitialized = false;
+export async function initializeClient() {
+    if (!validateUrl(API_URL)) {
+        throw new Error(`Invalid API URL: ${API_URL}. Only allowed hosts are supported.`);
+    }
+    basicClient = createBasicClient();
+    paymentClient = await createPaymentClient();
+    clientInitialized = true;
+    let walletAddress;
+    const privateKey = getEvmPrivateKey();
+    if (privateKey) {
+        const account = privateKeyToAccount(privateKey);
+        walletAddress = account.address;
+    }
+    return {
+        baseUrl: API_URL,
+        hasWallet: !!paymentClient,
+        walletAddress,
+    };
+}
+export function getClientConfig() {
+    let walletAddress;
+    const privateKey = getEvmPrivateKey();
+    if (privateKey) {
+        const account = privateKeyToAccount(privateKey);
+        walletAddress = account.address;
+    }
+    return {
+        baseUrl: API_URL,
+        hasWallet: !!privateKey,
+        walletAddress,
+    };
+}
+export function hasPaymentCapability() {
+    return !!getEvmPrivateKey();
+}
+// Make a free API call (no payment required)
+export async function callFreeEndpoint(method, path, data) {
+    if (!clientInitialized) {
+        await initializeClient();
+    }
+    if (!basicClient) {
+        throw new Error('Client not initialized');
+    }
+    try {
+        const response = method === 'GET'
+            ? await basicClient.get(path)
+            : await basicClient.post(path, data);
+        return response.data;
+    }
+    catch (error) {
+        if (axios.isAxiosError(error) && hasResponse(error)) {
+            const status = error.response.status;
+            const message = error.response.data?.error || error.message;
+            if (status === 402) {
+                throw new Error('This endpoint requires payment. Please configure EVM_PRIVATE_KEY or EVM_PRIVATE_KEY_FILE to enable paid features.');
+            }
+            throw new Error(`API error (${status}): ${message}`);
+        }
+        throw error;
+    }
+}
+// Make a paid API call (handles 402 automatically)
+export async function callPaidEndpoint(method, path, data, expectedAmount, agentKey) {
+    if (!clientInitialized) {
+        await initializeClient();
+    }
+    // If no payment client available, try with basic client (dev mode)
+    const client = paymentClient || basicClient;
+    if (!client) {
+        throw new Error('Client not initialized');
+    }
+    // Check spending limits if we have an expected amount
+    if (expectedAmount && paymentClient) {
+        const spendingCheck = checkSpendingLimit(expectedAmount);
+        if (!spendingCheck.allowed) {
+            throw new Error(spendingCheck.reason);
+        }
+    }
+    try {
+        const response = method === 'GET'
+            ? await client.get(path)
+            : await client.post(path, data);
+        // Record spend if payment was made
+        const paymentInfo = response.data.payment;
+        if (paymentInfo?.amount) {
+            const amount = parseFloat(paymentInfo.amount.replace(/[^0-9.]/g, ''));
+            recordSpend(path, amount, paymentInfo.txHash);
+            logPayment(path, agentKey, paymentInfo.amount, 'success', paymentInfo.txHash, paymentInfo.mode === 'development' ? 'Development mode - no actual payment' : undefined);
+        }
+        return response.data;
+    }
+    catch (error) {
+        if (axios.isAxiosError(error) && hasResponse(error)) {
+            const status = error.response.status;
+            const message = error.response.data?.error || error.message;
+            if (status === 402 && !paymentClient) {
+                logError(path, 'Payment required but no wallet configured');
+                throw new Error('This endpoint requires payment. Please configure EVM_PRIVATE_KEY or EVM_PRIVATE_KEY_FILE.');
+            }
+            logError(path, `API error: ${message}`, { status, agentKey });
+            throw new Error(`API error (${status}): ${message}`);
+        }
+        logError(path, `Request failed: ${String(error)}`);
+        throw error;
+    }
+}
+// Check wallet balance (for safety warnings)
+export async function checkWalletBalance() {
+    if (!getEvmPrivateKey()) {
+        return null;
+    }
+    // This would require additional viem setup to check USDC balance
+    // For now, we'll skip this and rely on spending limits
+    return null;
+}
+// Warn if wallet has high balance
+export function warnIfHighBalance(balance) {
+    if (balance > 10 && !balanceWarningShown) {
+        logWarning('client', `WARNING: Wallet balance is high ($${balance.toFixed(2)}). Consider using a dedicated wallet with minimal funds.`);
+        balanceWarningShown = true;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+/**
+ * Agent Church MCP Server
+ *
+ * Exposes Agent Church services as MCP tools for AI agents.
+ * Supports automatic x402 payment handling for paid endpoints.
+ *
+ * Usage:
+ *   npx tsx mcp/src/index.ts
+ *
+ * Environment Variables:
+ *   AGENT_CHURCH_URL    - API base URL (default: http://localhost:3000)
+ *   AGENT_PUBLIC_KEY    - Default agent identity (optional)
+ *   EVM_PRIVATE_KEY     - Wallet private key for payments (optional)
+ *   MCP_DAILY_LIMIT     - Max USDC per day (default: $1.00)
+ *   MCP_TX_LIMIT        - Max per transaction (default: $0.10)
+ *   MCP_CONFIRM_THRESHOLD - Confirm above this (default: $0.05)
+ */
+export {};