@paylobster/mcp-server 1.3.0 → 1.5.0

package/src/lib/contracts.ts

@@ -0,0 +1,164 @@
+import { createPublicClient, http, type Address } from 'viem';
+import { base, baseSepolia } from 'viem/chains';
+import type { MCPServerConfig } from './config.js';
+import type { AgentInfo, ReputationData, EscrowData } from './types.js';
+
+// Contract addresses from existing web/src/lib/contracts.ts
+const CONTRACTS_MAINNET = {
+  IDENTITY: '0xA174f250380c4B5C37F6709bBa719E662b77E662' as Address,
+  REPUTATION: '0x02bb4c4cd10EeaCD04DF7631c81d6E7c1d0c4b29' as Address,
+  CREDIT: '0xD924B81F2d8EFF3E0A3Bf0a4b9D77d37CC0980E1' as Address,
+  ESCROW: '0x49Ed7003C6941a033E7dD8b44552e4E18cf28806' as Address,
+  USDC: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' as Address,
+};
+
+// NOTE: These contracts are not yet deployed to Base Sepolia
+const CONTRACTS_SEPOLIA = {
+  IDENTITY: '0x3dfA02Ed4F0e4F10E8031d7a4cB8Ea0bBbFbCB8c' as Address,
+  REPUTATION: '0x0000000000000000000000000000000000000000' as Address, // TODO: Deploy and update
+  CREDIT: '0xBA64e2b2F2a80D03A4B13b3396942C1e78205C7d' as Address,
+  ESCROW: '0x78D1f50a1965dE34f6b5a3D3546C94FE1809Cd82' as Address,
+  USDC: '0x036CbD53842c5426634e7929541eC2318f3dCF7e' as Address,
+};
+
+// 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',
+  },
+] as const;
+
+const REPUTATION_ABI = [
+  {
+    inputs: [{ name: 'user', type: 'address' }],
+    name: 'getReputation',
+    outputs: [
+      { name: 'score', type: 'uint256' },
+      { name: 'trustVector', type: 'uint256' },
+    ],
+    stateMutability: 'view',
+    type: 'function',
+  },
+] as const;
+
+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',
+  },
+] as const;
+
+const USDC_ABI = [
+  {
+    inputs: [{ name: 'account', type: 'address' }],
+    name: 'balanceOf',
+    outputs: [{ name: '', type: 'uint256' }],
+    stateMutability: 'view',
+    type: 'function',
+  },
+] as const;
+
+export class ContractsClient {
+  private publicClient;
+  private contracts;
+
+  constructor(config: MCPServerConfig) {
+    const chain = config.network === 'sepolia' ? baseSepolia : base;
+    this.contracts = config.network === 'sepolia' ? CONTRACTS_SEPOLIA : CONTRACTS_MAINNET;
+    
+    this.publicClient = createPublicClient({
+      chain,
+      transport: http(config.rpcUrl),
+    });
+  }
+
+  async getAgentInfo(address: Address): Promise<AgentInfo> {
+    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: Address): Promise<ReputationData> {
+    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: Address): Promise<bigint> {
+    const balance = await this.publicClient.readContract({
+      address: this.contracts.USDC,
+      abi: USDC_ABI,
+      functionName: 'balanceOf',
+      args: [address],
+    });
+
+    return balance;
+  }
+
+  async getEscrow(escrowId: bigint): Promise<EscrowData> {
+    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: Address): Promise<bigint> {
+    // TODO: Implement when Escrow V3 is deployed with getUserTransactionCount
+    return 0n;
+  }
+
+  getContractAddress(name: 'IDENTITY' | 'REPUTATION' | 'CREDIT' | 'ESCROW' | 'USDC'): Address {
+    return this.contracts[name];
+  }
+}

package/src/lib/types.ts

@@ -0,0 +1,44 @@
+import type { Address } from 'viem';
+
+export interface AgentInfo {
+  name: string;
+  tokenId: bigint;
+  registered: boolean;
+}
+
+export interface ReputationData {
+  score: bigint;
+  trustVector: bigint;
+}
+
+export interface CreditStatus {
+  limit: bigint;
+  available: bigint;
+  inUse: bigint;
+}
+
+export interface EscrowData {
+  sender: Address;
+  recipient: Address;
+  amount: bigint;
+  token: Address;
+  status: number; // 0=Pending, 1=Active, 2=Released, 3=Refunded, 4=Disputed
+}
+
+export interface ServiceListing {
+  id: string;
+  provider: Address;
+  name: string;
+  description: string;
+  category: string;
+  price: string;
+  currency: string;
+  reputation?: number;
+}
+
+export interface MCPError {
+  code: string;
+  message: string;
+  details?: unknown;
+  retryable: boolean;
+}

package/src/resources/agent.ts

@@ -0,0 +1,40 @@
+import type { Address } from 'viem';
+import type { ContractsClient } from '../lib/contracts.js';
+
+export async function getAgentResource(
+  address: string,
+  contracts: ContractsClient
+): Promise<object> {
+  const addr = address as Address;
+
+  try {
+    const [reputation, agentInfo] = await Promise.all([
+      contracts.getReputation(addr),
+      contracts.getAgentInfo(addr),
+    ]);
+
+    const normalizedScore = Number(reputation.score) / 1000;
+
+    return {
+      uri: `paylobster://agent/${address}`,
+      mimeType: 'application/json',
+      text: JSON.stringify({
+        address,
+        name: agentInfo.name || 'Unregistered',
+        tokenId: agentInfo.tokenId.toString(),
+        registered: agentInfo.registered,
+        reputation: {
+          score: normalizedScore,
+          trustVector: reputation.trustVector.toString(),
+          verified: agentInfo.registered,
+        },
+      }, null, 2),
+    };
+  } catch (error) {
+    throw {
+      code: 'ERR_RESOURCE_NOT_FOUND',
+      message: `Failed to fetch agent resource for ${address}`,
+      retryable: true,
+    };
+  }
+}

package/src/resources/escrow.ts

@@ -0,0 +1,35 @@
+import { formatUnits } from 'viem';
+import type { ContractsClient } from '../lib/contracts.js';
+
+const ESCROW_STATUS = ['Pending', 'Active', 'Released', 'Refunded', 'Disputed'];
+
+export async function getEscrowResource(
+  escrowId: string,
+  contracts: ContractsClient
+): Promise<object> {
+  try {
+    const id = BigInt(escrowId);
+    const escrow = await contracts.getEscrow(id);
+
+    return {
+      uri: `paylobster://escrow/${escrowId}`,
+      mimeType: 'application/json',
+      text: JSON.stringify({
+        escrowId,
+        sender: escrow.sender,
+        recipient: escrow.recipient,
+        amount: formatUnits(escrow.amount, 6),
+        amountRaw: escrow.amount.toString(),
+        token: escrow.token,
+        status: ESCROW_STATUS[escrow.status] || 'Unknown',
+        statusCode: escrow.status,
+      }, null, 2),
+    };
+  } catch (error) {
+    throw {
+      code: 'ERR_RESOURCE_NOT_FOUND',
+      message: `Escrow ${escrowId} not found`,
+      retryable: false,
+    };
+  }
+}

package/src/resources/services.ts

@@ -0,0 +1,53 @@
+// Mock services resource (ServiceRegistry not deployed yet)
+
+const MOCK_CATEGORIES = [
+  'code-review',
+  'security-audit',
+  'ai-training',
+  'data-labeling',
+  'code-generation',
+];
+
+export async function getServicesResource(): Promise<object> {
+  return {
+    uri: 'paylobster://services',
+    mimeType: 'application/json',
+    text: JSON.stringify({
+      totalServices: 5,
+      categories: MOCK_CATEGORIES,
+      note: 'Mock data - ServiceRegistry contract not yet deployed',
+      services: [
+        {
+          id: 'service-001',
+          name: 'TypeScript Code Reviewer',
+          category: 'code-review',
+          price: '10.00',
+        },
+        {
+          id: 'service-002',
+          name: 'Rust Security Auditor',
+          category: 'security-audit',
+          price: '50.00',
+        },
+        {
+          id: 'service-003',
+          name: 'AI Model Training',
+          category: 'ai-training',
+          price: '100.00',
+        },
+        {
+          id: 'service-004',
+          name: 'Data Labeling Service',
+          category: 'data-labeling',
+          price: '5.00',
+        },
+        {
+          id: 'service-005',
+          name: 'Python Code Generator',
+          category: 'code-generation',
+          price: '15.00',
+        },
+      ],
+    }, null, 2),
+  };
+}

package/src/server.ts

@@ -0,0 +1,190 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListResourcesRequestSchema,
+  ListToolsRequestSchema,
+  ReadResourceRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import { getConfig, type MCPServerConfig } from './lib/config.js';
+import { ContractsClient } from './lib/contracts.js';
+
+// Tool handlers
+import { getReputationTool, handleGetReputation } from './tools/reputation.js';
+import { getBalanceTool, handleGetBalance } from './tools/balance.js';
+import { getAgentTool, handleGetAgent } from './tools/agent.js';
+import { getEscrowTool, listEscrowsTool, handleGetEscrow, handleListEscrows } from './tools/escrow.js';
+import { searchServicesTool, handleSearchServices } from './tools/search.js';
+
+// Resource handlers
+import { getAgentResource } from './resources/agent.js';
+import { getEscrowResource } from './resources/escrow.js';
+import { getServicesResource } from './resources/services.js';
+
+export class PayLobsterMCPServer {
+  private server: Server;
+  private config: MCPServerConfig;
+  private contracts: ContractsClient;
+
+  constructor(config?: Partial<MCPServerConfig>) {
+    this.config = { ...getConfig(), ...config };
+    this.contracts = new ContractsClient(this.config);
+
+    this.server = new Server(
+      {
+        name: 'paylobster-mcp-server',
+        version: '1.0.0',
+      },
+      {
+        capabilities: {
+          tools: {},
+          resources: {},
+        },
+      }
+    );
+
+    this.setupHandlers();
+  }
+
+  private setupHandlers() {
+    // List available tools
+    this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
+      tools: [
+        getReputationTool,
+        getBalanceTool,
+        getAgentTool,
+        getEscrowTool,
+        listEscrowsTool,
+        searchServicesTool,
+      ],
+    }));
+
+    // Handle tool calls
+    this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+      try {
+        const { name, arguments: args } = request.params;
+
+        let result;
+        switch (name) {
+          case 'paylobster_get_reputation':
+            result = await handleGetReputation(args, this.contracts);
+            break;
+          case 'paylobster_get_balance':
+            result = await handleGetBalance(args, this.contracts);
+            break;
+          case 'paylobster_get_agent':
+            result = await handleGetAgent(args, this.contracts);
+            break;
+          case 'paylobster_get_escrow':
+            result = await handleGetEscrow(args, this.contracts);
+            break;
+          case 'paylobster_list_escrows':
+            result = await handleListEscrows(args, this.contracts);
+            break;
+          case 'paylobster_search_services':
+            result = await handleSearchServices(args);
+            break;
+          default:
+            throw {
+              code: 'ERR_UNKNOWN_TOOL',
+              message: `Unknown tool: ${name}`,
+              retryable: false,
+            };
+        }
+
+        return {
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify(result, null, 2),
+            },
+          ],
+        };
+      } catch (error: any) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify({
+                error: {
+                  code: error.code || 'ERR_UNKNOWN',
+                  message: error.message || 'An unknown error occurred',
+                  details: error.details,
+                  retryable: error.retryable ?? false,
+                },
+              }, null, 2),
+            },
+          ],
+          isError: true,
+        };
+      }
+    });
+
+    // List available resources
+    this.server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+      resources: [
+        {
+          uri: 'paylobster://services',
+          name: 'Service Catalog',
+          description: 'Browse all available AI agent services',
+          mimeType: 'application/json',
+        },
+        {
+          uri: 'paylobster://agent/{address}',
+          name: 'Agent Profile',
+          description: 'Get agent identity and reputation by address',
+          mimeType: 'application/json',
+        },
+        {
+          uri: 'paylobster://escrow/{id}',
+          name: 'Escrow Details',
+          description: 'Get details for a specific escrow',
+          mimeType: 'application/json',
+        },
+      ],
+    }));
+
+    // Handle resource reads
+    this.server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+      try {
+        const uri = request.params.uri;
+
+        if (uri === 'paylobster://services') {
+          return await getServicesResource();
+        }
+
+        const agentMatch = uri.match(/^paylobster:\/\/agent\/(.+)$/);
+        if (agentMatch) {
+          return await getAgentResource(agentMatch[1], this.contracts);
+        }
+
+        const escrowMatch = uri.match(/^paylobster:\/\/escrow\/(.+)$/);
+        if (escrowMatch) {
+          return await getEscrowResource(escrowMatch[1], this.contracts);
+        }
+
+        throw {
+          code: 'ERR_RESOURCE_NOT_FOUND',
+          message: `Unknown resource URI: ${uri}`,
+          retryable: false,
+        };
+      } catch (error: any) {
+        throw new Error(error.message || 'Failed to read resource');
+      }
+    });
+  }
+
+  async start() {
+    const transport = new StdioServerTransport();
+    await this.server.connect(transport);
+
+    // Log to stderr (stdout is used for MCP protocol)
+    console.error('PayLobster MCP Server started');
+    console.error(`Network: ${this.config.network}`);
+    console.error(`RPC URL: ${this.config.rpcUrl}`);
+  }
+
+  getServer(): Server {
+    return this.server;
+  }
+}

package/src/tools/agent.ts

@@ -0,0 +1,56 @@
+import { z } from 'zod';
+import type { Address } from 'viem';
+import type { ContractsClient } from '../lib/contracts.js';
+
+const GetAgentInput = z.object({
+  address: z.string().regex(/^0x[a-fA-F0-9]{40}$/, 'Invalid Ethereum address'),
+});
+
+export const getAgentTool = {
+  name: 'paylobster_get_agent',
+  description: 'Get agent identity information including name, token ID, and registration status',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      address: {
+        type: 'string',
+        description: 'Ethereum address of the agent',
+      },
+    },
+    required: ['address'],
+  },
+};
+
+export async function handleGetAgent(
+  input: unknown,
+  contracts: ContractsClient
+): Promise<object> {
+  try {
+    const params = GetAgentInput.parse(input);
+    const address = params.address as Address;
+
+    const agentInfo = await contracts.getAgentInfo(address);
+
+    return {
+      address,
+      name: agentInfo.name || 'Unregistered',
+      tokenId: agentInfo.tokenId.toString(),
+      registered: agentInfo.registered,
+    };
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      throw {
+        code: 'ERR_INVALID_INPUT',
+        message: 'Invalid input parameters',
+        details: error.errors,
+        retryable: false,
+      };
+    }
+
+    throw {
+      code: 'ERR_NETWORK_ERROR',
+      message: error instanceof Error ? error.message : 'Failed to fetch agent info',
+      retryable: true,
+    };
+  }
+}

package/src/tools/balance.ts

@@ -0,0 +1,61 @@
+import { z } from 'zod';
+import type { Address } from 'viem';
+import { formatUnits } from 'viem';
+import type { ContractsClient } from '../lib/contracts.js';
+
+const GetBalanceInput = z.object({
+  address: z.string().regex(/^0x[a-fA-F0-9]{40}$/, 'Invalid Ethereum address'),
+});
+
+export const getBalanceTool = {
+  name: 'paylobster_get_balance',
+  description: 'Check USDC balance for an Ethereum address',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      address: {
+        type: 'string',
+        description: 'Ethereum address to check balance for',
+      },
+    },
+    required: ['address'],
+  },
+};
+
+export async function handleGetBalance(
+  input: unknown,
+  contracts: ContractsClient
+): Promise<object> {
+  try {
+    const params = GetBalanceInput.parse(input);
+    const address = params.address as Address;
+
+    const balance = await contracts.getBalance(address);
+
+    // USDC has 6 decimals
+    const formattedBalance = formatUnits(balance, 6);
+
+    return {
+      address,
+      balance: {
+        usdc: formattedBalance,
+        raw: balance.toString(),
+      },
+    };
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      throw {
+        code: 'ERR_INVALID_INPUT',
+        message: 'Invalid input parameters',
+        details: error.errors,
+        retryable: false,
+      };
+    }
+
+    throw {
+      code: 'ERR_NETWORK_ERROR',
+      message: error instanceof Error ? error.message : 'Failed to fetch balance',
+      retryable: true,
+    };
+  }
+}