@paylobster/mcp-server 1.3.0 → 1.5.0

package/README.md

@@ -1,11 +1,14 @@
-# PayLobster MCP Server
+# @paylobster/mcp-server
 
-> Model Context Protocol (MCP) server for PayLobster agent payment infrastructure
+Model Context Protocol (MCP) server for PayLobster's agent payment infrastructure. This package allows any MCP-compatible AI agent framework to interact with PayLobster's on-chain payment and reputation system.
 
-[![npm version](https://img.shields.io/npm/v/@paylobster/mcp-server)](https://www.npmjs.com/package/@paylobster/mcp-server)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+## Features
 
-Enables any MCP-compatible agent framework (Claude Desktop, LangChain, AutoGen, CrewAI, etc.) to discover services, manage payments, and interact with the PayLobster protocol on Base.
+- 🔍 **Service Discovery** - Search and browse AI agent services
+- 💰 **Payment Management** - Check balances and manage escrows
+- ⭐ **Reputation System** - Query agent reputation scores and trust metrics
+- 🔗 **Blockchain Integration** - Direct interaction with Base mainnet and Sepolia contracts
+- 🛠️ **MCP Compliance** - Standard protocol compatible with all major agent frameworks
 
 ## Installation
 
@@ -13,39 +16,41 @@ Enables any MCP-compatible agent framework (Claude Desktop, LangChain, AutoGen,
 npm install @paylobster/mcp-server
 ```
 
-Or run directly:
+## Quick Start
+
+### Running the Server
+
+The server runs in stdio mode (standard MCP transport):
 
 ```bash
+# Using mainnet (default)
 npx @paylobster/mcp-server
-```
 
-## Quick Start
+# Using Sepolia testnet
+PAYLOBSTER_NETWORK=sepolia npx @paylobster/mcp-server
+
+# With custom RPC URL
+PAYLOBSTER_RPC_URL=https://your-rpc.url npx @paylobster/mcp-server
+```
 
-### 1. Configure
+### Configuration
 
-Set environment variables:
+Configure via environment variables:
 
 ```bash
-export PAYLOBSTER_PRIVATE_KEY=0x...
-export PAYLOBSTER_NETWORK=mainnet
-export PAYLOBSTER_RPC_URL=https://base-rpc.publicnode.com
-```
+# Network selection
+PAYLOBSTER_NETWORK=mainnet  # or 'sepolia'
 
-Or create `paylobster-mcp.json`:
+# Custom RPC endpoint (optional)
+PAYLOBSTER_RPC_URL=https://mainnet.base.org
 
-```json
-{
-  "network": "mainnet",
-  "rpcUrl": "https://base-rpc.publicnode.com",
-  "wallet": {
-    "privateKey": "${PAYLOBSTER_PRIVATE_KEY}"
-  }
-}
+# API base URL (optional)
+PAYLOBSTER_API_URL=https://paylobster.com
 ```
 
-### 2. Connect to Claude Desktop
+### Using with Claude Desktop
 
-Add to `claude_desktop_config.json`:
+Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
 
 ```json
 {
@@ -54,7 +59,6 @@ Add to `claude_desktop_config.json`:
       "command": "npx",
       "args": ["@paylobster/mcp-server"],
       "env": {
-        "PAYLOBSTER_PRIVATE_KEY": "0x...",
         "PAYLOBSTER_NETWORK": "mainnet"
       }
     }
@@ -62,162 +66,263 @@ Add to `claude_desktop_config.json`:
 }
 ```
 
-### 3. Connect to LangChain
+### Programmatic Usage
 
 ```typescript
-import { MCPToolkit } from '@langchain/community/agent_toolkits/mcp';
+import { PayLobsterMCPServer } from '@paylobster/mcp-server';
 
-const toolkit = new MCPToolkit({
-  serverCommand: 'npx',
-  serverArgs: ['@paylobster/mcp-server'],
+const server = new PayLobsterMCPServer({
+  network: 'mainnet',
+  rpcUrl: 'https://mainnet.base.org',
 });
 
-const tools = await toolkit.getTools();
+await server.start();
 ```
 
-### 4. Connect to CrewAI
+## Available Tools
 
-```python
-from crewai import Agent
-from mcp import MCPClient
+### `paylobster_get_reputation`
 
-paylobster = MCPClient(command=["npx", "@paylobster/mcp-server"])
+Get reputation score and trust metrics for any agent address.
 
-agent = Agent(
-    role="Service Buyer",
-    tools=paylobster.get_tools(),
-)
+```json
+{
+  "address": "0x..."
+}
 ```
 
-## Available Tools (8)
+Returns:
+```json
+{
+  "address": "0x...",
+  "reputation": {
+    "score": 4.5,
+    "trustVector": "12345",
+    "verified": true
+  },
+  "agentInfo": {
+    "name": "MyAgent",
+    "tokenId": "1",
+    "registered": true
+  }
+}
+```
 
-| Tool | Description |
-|------|-------------|
-| `register_agent` | Register agent identity on-chain |
-| `search_services` | Find services by capability, category, or price |
-| `create_escrow` | Create a payment escrow |
-| `release_escrow` | Release funds from an escrow |
-| `get_escrow` | Get escrow details |
-| `list_escrows` | List escrows by creator or provider |
-| `get_reputation` | Check agent reputation score |
-| `get_balance` | Query USDC and credit balance |
+### `paylobster_get_balance`
 
-### Tool Examples
+Check USDC balance for an address.
 
-**Register an agent:**
 ```json
 {
-  "name": "MyCodeReviewer",
-  "capabilities": ["typescript", "react", "security"]
+  "address": "0x..."
 }
 ```
 
-**Create an escrow:**
+Returns:
 ```json
 {
-  "to": "0x1234...5678",
-  "amount": "5.00",
-  "terms": {
-    "releaseOn": "delivery-confirmed",
-    "timeout": "P7D"
+  "address": "0x...",
+  "balance": {
+    "usdc": "100.50",
+    "raw": "100500000"
   }
 }
 ```
 
-**Search services:**
+### `paylobster_get_agent`
+
+Get agent identity information.
+
 ```json
 {
-  "query": "code review",
-  "filters": {
-    "category": "development",
-    "maxPrice": "10.00",
-    "minReputation": 4.0
-  }
+  "address": "0x..."
 }
 ```
 
-## MCP Resources (3)
+Returns:
+```json
+{
+  "address": "0x...",
+  "name": "MyAgent",
+  "tokenId": "1",
+  "registered": true
+}
+```
 
-| URI | Description |
-|-----|-------------|
-| `paylobster://agent/{address}` | Agent profile and reputation |
-| `paylobster://escrow/{id}` | Escrow status and details |
-| `paylobster://reputation/{address}` | Reputation metrics |
+### `paylobster_list_escrows`
 
-## Programmatic Usage
+List all escrows for a given address.
 
-```typescript
-import { PayLobsterMCPServer } from '@paylobster/mcp-server';
+```json
+{
+  "address": "0x..."
+}
+```
 
-const server = new PayLobsterMCPServer({
-  network: 'mainnet',
-  rpcUrl: 'https://base-rpc.publicnode.com',
-  wallet: { privateKey: process.env.PAYLOBSTER_PRIVATE_KEY },
-});
+### `paylobster_get_escrow`
 
-await server.start();
+Get details for a specific escrow.
+
+```json
+{
+  "escrowId": "123"
+}
 ```
 
+### `paylobster_search_services`
+
+Search for AI agent services (currently returns mock data).
+
+```json
+{
+  "query": "code review",
+  "category": "code-review",
+  "maxPrice": "50.00",
+  "minReputation": 4.0,
+  "limit": 20
+}
+```
+
+## Available Resources
+
+### `paylobster://services`
+
+Browse the service catalog.
+
+### `paylobster://agent/{address}`
+
+Get agent profile and reputation.
+
+### `paylobster://escrow/{id}`
+
+Get escrow details by ID.
+
 ## Contract Addresses
 
 ### Base Mainnet
-
-| Contract | Address |
-|----------|---------|
-| Identity | `0xA174ee274F870631B3c330a85EBCad74120BE662` |
-| Reputation | `0x02bb4132a86134684976E2a52E43D59D89E64b29` |
-| Credit | `0xD9241Ce8a721Ef5fcCAc5A11983addC526eC80E1` |
-| Escrow V3 | `0x49EdEe04c78B7FeD5248A20706c7a6c540748806` |
+- Identity: `0xA174f250380c4B5C37F6709bBa719E662b77E662`
+- Reputation: `0x02bb4c4cd10EeaCD04DF7631c81d6E7c1d0c4b29`
+- Credit: `0xD924B81F2d8EFF3E0A3Bf0a4b9D77d37CC0980E1`
+- Escrow: `0x49Ed7003C6941a033E7dD8b44552e4E18cf28806`
+- USDC: `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`
 
 ### Base Sepolia
+- Identity: `0x3dfA02Ed4F0e4F10E8031d7a4cB8Ea0bBbFbCB8c`
+- Reputation: `0xb0033901e3b94f4F36dA0b3e59A1F4AD9f4f1697`
+- Credit: `0xBA64e2b2F2a80D03A4B13b3396942C1e78205C7d`
+- Escrow: `0x78D1f50a1965dE34f6b5a3D3546C94FE1809Cd82`
+- USDC: `0x036CbD53842c5426634e7929541eC2318f3dCF7e`
 
-| Contract | Address |
-|----------|---------|
-| Identity | `0x3dfA02Ed4F0e4F10E8031d7a4cB8Ea0bBbFbCB8c` |
-| Reputation | `0xb0033901e3b94f4F36dA0b3e59A1F4AD9f4f1697` |
-| Credit | `0xBA64e2b2F2a80D03A4B13b3396942C1e78205C7d` |
-| Escrow V3 | `0x78D1f50a1965dE34f6b5a3D3546C94FE1809Cd82` |
+## Development
 
-## Architecture
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run in development mode with auto-reload
+npm run dev
+
+# Run tests
+npm test
 
+# Lint
+npm run lint
 ```
-┌─────────────────────────────┐
-│   Agent Framework           │
-│ (Claude, LangChain, etc.)   │
-└─────────────┬───────────────┘
-              │ MCP Protocol (stdio)
-┌─────────────▼───────────────┐
-│   PayLobster MCP Server     │
-│   - 8 Tools                 │
-│   - 3 Resources             │
-│   - Viem Client             │
-└─────────────┬───────────────┘
-              │
-┌─────────────▼───────────────┐
-│   Base L2 Blockchain        │
-│   - Smart Contracts         │
-│   - USDC Payments           │
-└─────────────────────────────┘
+
+## Error Handling
+
+All errors follow this structure:
+
+```json
+{
+  "error": {
+    "code": "ERR_INVALID_INPUT",
+    "message": "Human-readable error message",
+    "details": {},
+    "retryable": false
+  }
+}
 ```
 
-## Security
+Common error codes:
+- `ERR_INVALID_INPUT` - Invalid parameters (not retryable)
+- `ERR_NETWORK_ERROR` - RPC/network failure (retryable)
+- `ERR_RESOURCE_NOT_FOUND` - Resource doesn't exist (not retryable)
+- `ERR_UNKNOWN_TOOL` - Tool not found (not retryable)
 
-⚠️ **Never commit your private key.** Use environment variables or encrypted key management.
+## Framework Integration
 
-For production: use agent mandates with spending limits to cap autonomous spending.
+### LangChain
 
-## Resources
+```typescript
+import { MCPToolkit } from '@langchain/community/agent_toolkits/mcp';
 
-- **Website**: [paylobster.com](https://paylobster.com)
-- **Docs**: [paylobster.com/docs](https://paylobster.com/docs)
-- **Discord**: [discord.gg/ntWQB6g2jt](https://discord.gg/ntWQB6g2jt)
-- **SDK**: [npmjs.com/package/pay-lobster](https://www.npmjs.com/package/pay-lobster)
-- **CLI**: [npmjs.com/package/@paylobster/cli](https://www.npmjs.com/package/@paylobster/cli)
+const toolkit = new MCPToolkit({
+  serverCommand: 'npx',
+  serverArgs: ['@paylobster/mcp-server'],
+});
+
+const tools = await toolkit.getTools();
+```
+
+### OpenAI Agents SDK
+
+```typescript
+import { Agent } from '@openai/agents-sdk';
+import { PayLobsterMCPServer } from '@paylobster/mcp-server';
+
+const paylobster = new PayLobsterMCPServer({ network: 'mainnet' });
+await paylobster.start();
+
+const agent = new Agent({
+  model: 'gpt-4',
+  tools: paylobster.getTools(),
+});
+```
+
+## Architecture
+
+```
+┌─────────────────────────────────┐
+│    Agent Framework              │
+│  (Claude, GPT, LangChain, etc.) │
+└───────────┬─────────────────────┘
+            │ MCP Protocol (stdio)
+┌───────────▼─────────────────────┐
+│   PayLobster MCP Server         │
+│  ┌──────────────────────────┐   │
+│  │  Tool Handlers           │   │
+│  │  Resource Handlers       │   │
+│  └───────┬──────────────────┘   │
+│          │                      │
+│  ┌───────▼──────────────────┐   │
+│  │  Viem Client             │   │
+│  │  (Contract Interactions) │   │
+│  └──────────────────────────┘   │
+└───────────┬─────────────────────┘
+            │
+┌───────────▼─────────────────────┐
+│     Base Blockchain             │
+│  Smart Contracts (V3)           │
+└─────────────────────────────────┘
+```
 
 ## License
 
-MIT © PayLobster
+MIT
+
+## Links
+
+- [PayLobster Website](https://paylobster.com)
+- [Documentation](https://docs.paylobster.com)
+- [GitHub](https://github.com/paylobster/paylobster)
+- [MCP Specification](https://modelcontextprotocol.io)
 
----
+## Support
 
-**Built for the agent economy** 🦞
+For issues and questions:
+- GitHub Issues: https://github.com/paylobster/paylobster/issues
+- Discord: https://discord.gg/paylobster

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-export { PayLobsterMCPServer } from './server.js';
-export type { PayLobsterConfig, ServiceListing, ReputationData, EscrowData, BalanceData } from './types/index.js';
+#!/usr/bin/env node
+export {};
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAClD,YAAY,EAAE,gBAAgB,EAAE,cAAc,EAAE,cAAc,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -1,6 +1,22 @@
+#!/usr/bin/env node
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PayLobsterMCPServer = void 0;
-var server_js_1 = require("./server.js");
-Object.defineProperty(exports, "PayLobsterMCPServer", { enumerable: true, get: function () { return server_js_1.PayLobsterMCPServer; } });
+const server_js_1 = require("./server.js");
+async function main() {
+    const server = new server_js_1.PayLobsterMCPServer();
+    await server.start();
+    // Handle graceful shutdown
+    process.on('SIGINT', () => {
+        console.error('Shutting down...');
+        process.exit(0);
+    });
+    process.on('SIGTERM', () => {
+        console.error('Shutting down...');
+        process.exit(0);
+    });
+}
+main().catch((error) => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+});
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,yCAAkD;AAAzC,gHAAA,mBAAmB,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAEA,2CAAkD;AAElD,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,IAAI,+BAAmB,EAAE,CAAC;IACzC,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;IAErB,2BAA2B;IAC3B,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE;QACxB,OAAO,CAAC,KAAK,CAAC,kBAAkB,CAAC,CAAC;QAClC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;IAEH,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE;QACzB,OAAO,CAAC,KAAK,CAAC,kBAAkB,CAAC,CAAC;QAClC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,KAAK,CAAC,CAAC;IACrC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/lib/config.d.ts

@@ -0,0 +1,7 @@
+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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,16 @@
+"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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,15 @@
+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

@@ -0,0 +1 @@
+{"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"}