@paylobster/mcp-server 1.5.0 → 1.7.0

package/INTEGRATION.md

@@ -1,286 +0,0 @@
-# Integration Guide
-
-This guide shows how to integrate the PayLobster MCP Server with various AI agent frameworks.
-
-## Table of Contents
-
-- [Claude Desktop](#claude-desktop)
-- [Cline (VS Code Extension)](#cline-vs-code-extension)
-- [OpenAI Agents SDK](#openai-agents-sdk)
-- [LangChain](#langchain)
-- [Direct MCP Protocol](#direct-mcp-protocol)
-
-## Claude Desktop
-
-Add to your Claude Desktop configuration file:
-
-**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
-**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
-
-```json
-{
-  "mcpServers": {
-    "paylobster": {
-      "command": "npx",
-      "args": ["-y", "@paylobster/mcp-server"],
-      "env": {
-        "PAYLOBSTER_NETWORK": "mainnet"
-      }
-    }
-  }
-}
-```
-
-For local development:
-
-```json
-{
-  "mcpServers": {
-    "paylobster": {
-      "command": "node",
-      "args": ["/Users/gustav/Projects/paylobster/packages/mcp-server/dist/index.js"],
-      "env": {
-        "PAYLOBSTER_NETWORK": "sepolia"
-      }
-    }
-  }
-}
-```
-
-Then restart Claude Desktop. The PayLobster tools will be available automatically.
-
-### Example Prompts
-
-```
-"Check the reputation of agent 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
-
-"Search for TypeScript code review services under $20"
-
-"Get my USDC balance for 0x..."
-
-"List all escrows for address 0x..."
-```
-
-## Cline (VS Code Extension)
-
-Cline supports MCP servers through its settings:
-
-1. Open VS Code settings (`Cmd+,` or `Ctrl+,`)
-2. Search for "Cline MCP"
-3. Add server configuration:
-
-```json
-{
-  "cline.mcpServers": {
-    "paylobster": {
-      "command": "npx",
-      "args": ["-y", "@paylobster/mcp-server"],
-      "env": {
-        "PAYLOBSTER_NETWORK": "mainnet"
-      }
-    }
-  }
-}
-```
-
-Or edit `.vscode/settings.json` in your project:
-
-```json
-{
-  "cline.mcpServers": {
-    "paylobster": {
-      "command": "node",
-      "args": ["./packages/mcp-server/dist/index.js"],
-      "env": {
-        "PAYLOBSTER_NETWORK": "sepolia"
-      }
-    }
-  }
-}
-```
-
-## OpenAI Agents SDK
-
-```typescript
-import { Agent } from '@openai/agents-sdk';
-import { spawn } from 'child_process';
-
-// Spawn MCP server process
-const mcpProcess = spawn('npx', ['@paylobster/mcp-server'], {
-  env: { ...process.env, PAYLOBSTER_NETWORK: 'mainnet' },
-  stdio: ['pipe', 'pipe', 'inherit'],
-});
-
-// Create OpenAI agent
-const agent = new Agent({
-  model: 'gpt-4',
-  mcpServers: [
-    {
-      name: 'paylobster',
-      process: mcpProcess,
-    },
-  ],
-});
-
-// Use the agent
-const response = await agent.run(
-  'Find me a TypeScript code reviewer with good reputation'
-);
-console.log(response);
-```
-
-## LangChain
-
-```typescript
-import { MCPToolkit } from '@langchain/community/agent_toolkits/mcp';
-import { initializeAgentExecutorWithOptions } from 'langchain/agents';
-import { ChatOpenAI } from 'langchain/chat_models/openai';
-
-// Initialize MCP toolkit
-const toolkit = new MCPToolkit({
-  serverCommand: 'npx',
-  serverArgs: ['@paylobster/mcp-server'],
-  env: { PAYLOBSTER_NETWORK: 'mainnet' },
-});
-
-// Get tools from the toolkit
-const tools = await toolkit.getTools();
-
-// Create LLM
-const model = new ChatOpenAI({
-  modelName: 'gpt-4',
-  temperature: 0,
-});
-
-// Create agent executor
-const executor = await initializeAgentExecutorWithOptions(tools, model, {
-  agentType: 'openai-functions',
-  verbose: true,
-});
-
-// Run a query
-const result = await executor.run(
-  'Check the reputation of agent 0x123...'
-);
-console.log(result);
-```
-
-## Direct MCP Protocol
-
-If you're building your own MCP client:
-
-```typescript
-import { Client } from '@modelcontextprotocol/sdk/client/index.js';
-import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
-import { spawn } from 'child_process';
-
-// Spawn the MCP server
-const serverProcess = spawn('npx', ['@paylobster/mcp-server'], {
-  env: { ...process.env, PAYLOBSTER_NETWORK: 'mainnet' },
-});
-
-// Create transport
-const transport = new StdioClientTransport({
-  command: serverProcess,
-});
-
-// Create MCP client
-const client = new Client({
-  name: 'my-paylobster-client',
-  version: '1.0.0',
-});
-
-// Connect
-await client.connect(transport);
-
-// List available tools
-const { tools } = await client.listTools();
-console.log('Available tools:', tools);
-
-// Call a tool
-const result = await client.callTool({
-  name: 'paylobster_get_reputation',
-  arguments: {
-    address: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
-  },
-});
-
-console.log('Result:', result);
-
-// Read a resource
-const resource = await client.readResource({
-  uri: 'paylobster://services',
-});
-
-console.log('Services:', resource);
-```
-
-## Environment Variables
-
-All integration methods support these environment variables:
-
-```bash
-# Network selection
-PAYLOBSTER_NETWORK=mainnet  # or 'sepolia'
-
-# Custom RPC endpoint
-PAYLOBSTER_RPC_URL=https://mainnet.base.org
-
-# API base URL
-PAYLOBSTER_API_URL=https://paylobster.com
-```
-
-## Testing Your Integration
-
-Use the provided test scripts:
-
-```bash
-# Test server initialization
-npx tsx examples/test-server.ts
-
-# Test individual tools
-npx tsx examples/test-tools.ts
-```
-
-## Troubleshooting
-
-### Server won't start
-
-1. Check that Node.js >= 18 is installed: `node --version`
-2. Verify the package is installed: `npm list @paylobster/mcp-server`
-3. Check environment variables are set correctly
-4. Look for errors in stderr output
-
-### Tools not appearing
-
-1. Restart your client application (Claude Desktop, VS Code, etc.)
-2. Verify the MCP server is listed in client settings
-3. Check the server process is running: `ps aux | grep paylobster`
-
-### Network errors
-
-1. Verify RPC URL is accessible: `curl https://mainnet.base.org`
-2. Try with Sepolia testnet: `PAYLOBSTER_NETWORK=sepolia`
-3. Check firewall/proxy settings
-
-### Rate limiting
-
-If you see rate limit errors, the RPC endpoint may be throttling requests. Use a custom RPC URL:
-
-```bash
-PAYLOBSTER_RPC_URL=https://your-private-rpc.com
-```
-
-## Examples
-
-See the `/examples` directory for more:
-
-- `test-server.ts` - Server initialization test
-- `test-tools.ts` - Individual tool testing
-- Integration examples for popular frameworks
-
-## Support
-
-- GitHub Issues: https://github.com/paylobster/paylobster/issues
-- Discord: https://discord.gg/paylobster
-- Documentation: https://docs.paylobster.com

package/QUICKSTART.md

@@ -1,226 +0,0 @@
-# Quick Start Guide
-
-Get the PayLobster MCP Server running in 5 minutes.
-
-## Installation
-
-```bash
-npm install @paylobster/mcp-server
-```
-
-Or install locally for development:
-
-```bash
-cd /Users/gustav/Projects/paylobster/packages/mcp-server
-npm install
-npm run build
-```
-
-## Usage
-
-### Option 1: Claude Desktop (Easiest)
-
-1. Open Claude Desktop config:
-   - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
-   - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
-
-2. Add PayLobster server:
-```json
-{
-  "mcpServers": {
-    "paylobster": {
-      "command": "npx",
-      "args": ["-y", "@paylobster/mcp-server"],
-      "env": {
-        "PAYLOBSTER_NETWORK": "mainnet"
-      }
-    }
-  }
-}
-```
-
-3. Restart Claude Desktop
-
-4. Test with prompts like:
-   - "Check the reputation of 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
-   - "Search for code review services under $20"
-   - "Get my USDC balance"
-
-### Option 2: Command Line
-
-```bash
-# Start server (mainnet)
-npx @paylobster/mcp-server
-
-# Or with environment variables
-PAYLOBSTER_NETWORK=sepolia npx @paylobster/mcp-server
-
-# Local development
-npm start
-```
-
-The server communicates via stdio (standard MCP protocol).
-
-### Option 3: Programmatic
-
-```typescript
-import { PayLobsterMCPServer } from '@paylobster/mcp-server';
-
-const server = new PayLobsterMCPServer({
-  network: 'mainnet', // or 'sepolia'
-  rpcUrl: 'https://mainnet.base.org', // optional
-});
-
-await server.start();
-```
-
-## Configuration
-
-### Environment Variables
-
-```bash
-# Network (required)
-PAYLOBSTER_NETWORK=mainnet  # or 'sepolia'
-
-# Custom RPC URL (optional)
-PAYLOBSTER_RPC_URL=https://your-rpc.url
-
-# API URL (optional, defaults to paylobster.com)
-PAYLOBSTER_API_URL=https://paylobster.com
-```
-
-## Available Commands
-
-### MCP Tools
-
-```typescript
-// Get agent reputation
-paylobster_get_reputation({ address: "0x..." })
-
-// Check USDC balance
-paylobster_get_balance({ address: "0x..." })
-
-// Get agent info
-paylobster_get_agent({ address: "0x..." })
-
-// Get escrow details
-paylobster_get_escrow({ escrowId: "123" })
-
-// List escrows for address
-paylobster_list_escrows({ address: "0x..." })
-
-// Search services (mock data for now)
-paylobster_search_services({
-  query: "code review",
-  category: "code-review",
-  maxPrice: "50.00",
-  limit: 10
-})
-```
-
-### MCP Resources
-
-```
-paylobster://services
-paylobster://agent/{address}
-paylobster://escrow/{id}
-```
-
-## Example Queries (Claude Desktop)
-
-Try these in Claude after setup:
-
-```
-"What's the reputation of agent 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb?"
-
-"Search for TypeScript code reviewers under $15"
-
-"Check the USDC balance for 0x..."
-
-"Show me all escrows for address 0x..."
-
-"Find AI model training services"
-```
-
-## Testing
-
-Run the included test scripts:
-
-```bash
-# Test server initialization
-npx tsx examples/test-server.ts
-
-# Test individual tools
-npx tsx examples/test-tools.ts
-
-# Run test suite
-npm test
-```
-
-## Network Information
-
-### Base Mainnet (Default)
-- Chain ID: 8453
-- RPC: https://mainnet.base.org
-- Block Explorer: https://basescan.org
-
-### Base Sepolia (Testnet)
-- Chain ID: 84532
-- RPC: https://sepolia.base.org
-- Block Explorer: https://sepolia.basescan.org
-
-## Troubleshooting
-
-### Server won't start
-```bash
-# Check Node.js version (must be >= 18)
-node --version
-
-# Reinstall dependencies
-rm -rf node_modules package-lock.json
-npm install
-
-# Try with Sepolia testnet
-PAYLOBSTER_NETWORK=sepolia npm start
-```
-
-### Tools not appearing in Claude
-1. Verify config file location and syntax
-2. Restart Claude Desktop completely
-3. Check server logs in Claude's logs directory
-
-### RPC errors
-```bash
-# Use a custom RPC endpoint
-PAYLOBSTER_RPC_URL=https://your-rpc.url npm start
-
-# Or try public endpoints
-PAYLOBSTER_RPC_URL=https://base.publicnode.com npm start
-```
-
-## What's Next?
-
-- Read [INTEGRATION.md](./INTEGRATION.md) for framework-specific guides
-- Check [README.md](./README.md) for full documentation
-- See [BUILD_SUMMARY.md](./BUILD_SUMMARY.md) for implementation details
-- Review [CHANGELOG.md](./CHANGELOG.md) for version history
-
-## Need Help?
-
-- GitHub: https://github.com/paylobster/paylobster/issues
-- Discord: https://discord.gg/paylobster
-- Docs: https://docs.paylobster.com
-
-## Pro Tips
-
-1. **Start with Sepolia** - Test on the testnet before mainnet
-2. **Custom RPC** - Use your own RPC for better reliability
-3. **Check addresses** - Always verify Ethereum addresses are valid
-4. **Mock data** - Services search returns mock data until registry deploys
-5. **Read-only** - MVP only supports read operations (no payments yet)
-
----
-
-**You're ready to go!** 🎉
-
-Start querying agent reputations, balances, and escrows through any MCP-compatible AI framework.

package/dist/lib/config.d.ts

@@ -1,7 +0,0 @@
-export interface MCPServerConfig {
-    network: 'mainnet' | 'sepolia';
-    rpcUrl?: string;
-    apiUrl?: string;
-}
-export declare function getConfig(): MCPServerConfig;
-//# sourceMappingURL=config.d.ts.map

package/dist/lib/config.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/lib/config.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,SAAS,GAAG,SAAS,CAAC;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,SAAS,IAAI,eAAe,CAa3C"}

package/dist/lib/config.js

@@ -1,16 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.getConfig = getConfig;
-function getConfig() {
-    const network = (process.env.PAYLOBSTER_NETWORK || 'mainnet');
-    const defaultRpcUrls = {
-        mainnet: 'https://mainnet.base.org',
-        sepolia: 'https://sepolia.base.org',
-    };
-    return {
-        network,
-        rpcUrl: process.env.PAYLOBSTER_RPC_URL || defaultRpcUrls[network],
-        apiUrl: process.env.PAYLOBSTER_API_URL || 'https://paylobster.com',
-    };
-}
-//# sourceMappingURL=config.js.map

package/dist/lib/config.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/lib/config.ts"],"names":[],"mappings":";;AAQA,8BAaC;AAbD,SAAgB,SAAS;IACvB,MAAM,OAAO,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,kBAAkB,IAAI,SAAS,CAA0B,CAAC;IAEvF,MAAM,cAAc,GAAG;QACrB,OAAO,EAAE,0BAA0B;QACnC,OAAO,EAAE,0BAA0B;KACpC,CAAC;IAEF,OAAO;QACL,OAAO;QACP,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,kBAAkB,IAAI,cAAc,CAAC,OAAO,CAAC;QACjE,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,kBAAkB,IAAI,wBAAwB;KACnE,CAAC;AACJ,CAAC"}

package/dist/lib/contracts.d.ts

@@ -1,15 +0,0 @@
-import { type Address } from 'viem';
-import type { MCPServerConfig } from './config.js';
-import type { AgentInfo, ReputationData, EscrowData } from './types.js';
-export declare class ContractsClient {
-    private publicClient;
-    private contracts;
-    constructor(config: MCPServerConfig);
-    getAgentInfo(address: Address): Promise<AgentInfo>;
-    getReputation(address: Address): Promise<ReputationData>;
-    getBalance(address: Address): Promise<bigint>;
-    getEscrow(escrowId: bigint): Promise<EscrowData>;
-    getUserTransactionCount(address: Address): Promise<bigint>;
-    getContractAddress(name: 'IDENTITY' | 'REPUTATION' | 'CREDIT' | 'ESCROW' | 'USDC'): Address;
-}
-//# sourceMappingURL=contracts.d.ts.map

package/dist/lib/contracts.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"contracts.d.ts","sourceRoot":"","sources":["../../src/lib/contracts.ts"],"names":[],"mappings":"AAAA,OAAO,EAA4B,KAAK,OAAO,EAAE,MAAM,MAAM,CAAC;AAE9D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAiFxE,qBAAa,eAAe;IAC1B,OAAO,CAAC,YAAY,CAAC;IACrB,OAAO,CAAC,SAAS,CAAC;gBAEN,MAAM,EAAE,eAAe;IAU7B,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,SAAS,CAAC;IAelD,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,cAAc,CAAC;IAcxD,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC;IAW7C,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAiBhD,uBAAuB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC;IAKhE,kBAAkB,CAAC,IAAI,EAAE,UAAU,GAAG,YAAY,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO;CAG5F"}

package/dist/lib/contracts.js

@@ -1,148 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ContractsClient = void 0;
-const viem_1 = require("viem");
-const chains_1 = require("viem/chains");
-// Contract addresses from existing web/src/lib/contracts.ts
-const CONTRACTS_MAINNET = {
-    IDENTITY: '0xA174f250380c4B5C37F6709bBa719E662b77E662',
-    REPUTATION: '0x02bb4c4cd10EeaCD04DF7631c81d6E7c1d0c4b29',
-    CREDIT: '0xD924B81F2d8EFF3E0A3Bf0a4b9D77d37CC0980E1',
-    ESCROW: '0x49Ed7003C6941a033E7dD8b44552e4E18cf28806',
-    USDC: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
-};
-// NOTE: These contracts are not yet deployed to Base Sepolia
-const CONTRACTS_SEPOLIA = {
-    IDENTITY: '0x3dfA02Ed4F0e4F10E8031d7a4cB8Ea0bBbFbCB8c',
-    REPUTATION: '0x0000000000000000000000000000000000000000', // TODO: Deploy and update
-    CREDIT: '0xBA64e2b2F2a80D03A4B13b3396942C1e78205C7d',
-    ESCROW: '0x78D1f50a1965dE34f6b5a3D3546C94FE1809Cd82',
-    USDC: '0x036CbD53842c5426634e7929541eC2318f3dCF7e',
-};
-// ABIs from existing contracts.ts
-const IDENTITY_ABI = [
-    {
-        inputs: [{ name: 'user', type: 'address' }],
-        name: 'getAgentInfo',
-        outputs: [
-            { name: 'name', type: 'string' },
-            { name: 'tokenId', type: 'uint256' },
-            { name: 'registered', type: 'bool' },
-        ],
-        stateMutability: 'view',
-        type: 'function',
-    },
-    {
-        inputs: [{ name: '', type: 'address' }],
-        name: 'addressToAgentId',
-        outputs: [{ name: '', type: 'uint256' }],
-        stateMutability: 'view',
-        type: 'function',
-    },
-];
-const REPUTATION_ABI = [
-    {
-        inputs: [{ name: 'user', type: 'address' }],
-        name: 'getReputation',
-        outputs: [
-            { name: 'score', type: 'uint256' },
-            { name: 'trustVector', type: 'uint256' },
-        ],
-        stateMutability: 'view',
-        type: 'function',
-    },
-];
-const ESCROW_ABI = [
-    {
-        inputs: [{ name: 'escrowId', type: 'uint256' }],
-        name: 'getEscrow',
-        outputs: [
-            { name: 'sender', type: 'address' },
-            { name: 'recipient', type: 'address' },
-            { name: 'amount', type: 'uint256' },
-            { name: 'token', type: 'address' },
-            { name: 'status', type: 'uint8' },
-        ],
-        stateMutability: 'view',
-        type: 'function',
-    },
-];
-const USDC_ABI = [
-    {
-        inputs: [{ name: 'account', type: 'address' }],
-        name: 'balanceOf',
-        outputs: [{ name: '', type: 'uint256' }],
-        stateMutability: 'view',
-        type: 'function',
-    },
-];
-class ContractsClient {
-    publicClient;
-    contracts;
-    constructor(config) {
-        const chain = config.network === 'sepolia' ? chains_1.baseSepolia : chains_1.base;
-        this.contracts = config.network === 'sepolia' ? CONTRACTS_SEPOLIA : CONTRACTS_MAINNET;
-        this.publicClient = (0, viem_1.createPublicClient)({
-            chain,
-            transport: (0, viem_1.http)(config.rpcUrl),
-        });
-    }
-    async getAgentInfo(address) {
-        const result = await this.publicClient.readContract({
-            address: this.contracts.IDENTITY,
-            abi: IDENTITY_ABI,
-            functionName: 'getAgentInfo',
-            args: [address],
-        });
-        return {
-            name: result[0],
-            tokenId: result[1],
-            registered: result[2],
-        };
-    }
-    async getReputation(address) {
-        const result = await this.publicClient.readContract({
-            address: this.contracts.REPUTATION,
-            abi: REPUTATION_ABI,
-            functionName: 'getReputation',
-            args: [address],
-        });
-        return {
-            score: result[0],
-            trustVector: result[1],
-        };
-    }
-    async getBalance(address) {
-        const balance = await this.publicClient.readContract({
-            address: this.contracts.USDC,
-            abi: USDC_ABI,
-            functionName: 'balanceOf',
-            args: [address],
-        });
-        return balance;
-    }
-    async getEscrow(escrowId) {
-        const result = await this.publicClient.readContract({
-            address: this.contracts.ESCROW,
-            abi: ESCROW_ABI,
-            functionName: 'getEscrow',
-            args: [escrowId],
-        });
-        return {
-            sender: result[0],
-            recipient: result[1],
-            amount: result[2],
-            token: result[3],
-            status: result[4],
-        };
-    }
-    async getUserTransactionCount(address) {
-        // TODO: Implement when Escrow V3 is deployed with getUserTransactionCount
-        return 0n;
-    }
-    getContractAddress(name) {
-        return this.contracts[name];
-    }
-}
-exports.ContractsClient = ContractsClient;
-//# sourceMappingURL=contracts.js.map