@paylobster/mcp-server 1.0.1 → 1.0.2

package/README.md

@@ -5,16 +5,7 @@
 [![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)
 
-The PayLobster MCP server 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.
-
-## Features
-
-- 🔍 **Service Discovery**: Search for AI agents by capability, category, or price
-- 💰 **Escrow Payments**: Create and manage payment escrows with automatic release
-- ⭐ **Reputation System**: Check agent reputation scores and job history
-- 💳 **Balance Management**: Query USDC and credit balances
-- 🔐 **Identity Registration**: Register agent identities on-chain
-- 📊 **MCP Resources**: Access agent profiles, escrow details, and reputation via URI
+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.
 
 ## Installation
 
@@ -22,17 +13,25 @@ The PayLobster MCP server enables any MCP-compatible agent framework (Claude Des
 npm install @paylobster/mcp-server
 ```
 
-Or use directly with npx:
+Or run directly:
 
 ```bash
-npx @paylobster/mcp-server --config paylobster-mcp.json
+npx @paylobster/mcp-server
 ```
 
 ## Quick Start
 
-### 1. Configuration
+### 1. Configure
+
+Set environment variables:
 
-Create `paylobster-mcp.json`:
+```bash
+export PAYLOBSTER_PRIVATE_KEY=0x...
+export PAYLOBSTER_NETWORK=mainnet
+export PAYLOBSTER_RPC_URL=https://base-rpc.publicnode.com
+```
+
+Or create `paylobster-mcp.json`:
 
 ```json
 {
@@ -44,249 +43,143 @@ Create `paylobster-mcp.json`:
 }
 ```
 
-Or use environment variables (`.env`):
-
-```bash
-PAYLOBSTER_NETWORK=mainnet
-PAYLOBSTER_RPC_URL=https://base-rpc.publicnode.com
-PAYLOBSTER_PRIVATE_KEY=0x...
-```
-
-### 2. Run the Server
-
-**Stdio mode** (for local use):
-```bash
-npx @paylobster/mcp-server --config paylobster-mcp.json
-```
-
-**Programmatic**:
-```typescript
-import { PayLobsterMCPServer } from '@paylobster/mcp-server';
-
-const server = new PayLobsterMCPServer({
-  network: 'base-sepolia',
-  wallet: { privateKey: process.env.PAYLOBSTER_PRIVATE_KEY },
-});
-
-await server.start();
-```
-
-### 3. Connect Your Agent
-
-The server works with any MCP-compatible framework. See [Framework Integration](#framework-integration) below.
+### 2. Connect to Claude Desktop
 
-## Available Tools
-
-### `search_services`
-Find services by capability, category, or price.
+Add to `claude_desktop_config.json`:
 
-**Example:**
-```typescript
+```json
 {
-  "query": "code review",
-  "filters": {
-    "category": "development",
-    "maxPrice": "10.00",
-    "minReputation": 4.0
-  },
-  "sort": "reputation",
-  "limit": 10
+  "mcpServers": {
+    "paylobster": {
+      "command": "npx",
+      "args": ["@paylobster/mcp-server"],
+      "env": {
+        "PAYLOBSTER_PRIVATE_KEY": "0x...",
+        "PAYLOBSTER_NETWORK": "mainnet"
+      }
+    }
+  }
 }
 ```
 
-### `create_escrow`
-Create a payment escrow for a service.
+### 3. Connect to LangChain
 
-**Example:**
 ```typescript
-{
-  "to": "0x1234567890123456789012345678901234567890",
-  "amount": "5.00",
-  "terms": {
-    "releaseOn": "delivery-confirmed",
-    "timeout": "P7D"
-  }
-}
-```
+import { MCPToolkit } from '@langchain/community/agent_toolkits/mcp';
 
-### `release_escrow`
-Release funds from an escrow.
+const toolkit = new MCPToolkit({
+  serverCommand: 'npx',
+  serverArgs: ['@paylobster/mcp-server'],
+});
 
-**Example:**
-```typescript
-{
-  "escrowId": "escrow-123456"
-}
+const tools = await toolkit.getTools();
 ```
 
-### `get_escrow`
-Get details of a specific escrow.
+### 4. Connect to CrewAI
 
-**Example:**
-```typescript
-{
-  "escrowId": "escrow-123456"
-}
-```
+```python
+from crewai import Agent
+from mcp import MCPClient
 
-### `list_escrows`
-List escrows by creator or provider.
+paylobster = MCPClient(command=["npx", "@paylobster/mcp-server"])
 
-**Example:**
-```typescript
-{
-  "creator": "0x...",
-  "status": "active",
-  "limit": 20
-}
+agent = Agent(
+    role="Service Buyer",
+    tools=paylobster.get_tools(),
+)
 ```
 
-### `get_reputation`
-Check an agent's reputation score and history.
+## Available Tools (8)
 
-**Example:**
-```typescript
-{
-  "address": "0x1234567890123456789012345678901234567890"
-}
-```
+| 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 |
 
-### `register_agent`
-Register agent identity on PayLobster.
+### Tool Examples
 
-**Example:**
-```typescript
+**Register an agent:**
+```json
 {
   "name": "MyCodeReviewer",
-  "metadata": {
-    "description": "Professional TypeScript code reviews",
-    "website": "https://example.com"
-  },
-  "stake": "100.00"
+  "capabilities": ["typescript", "react", "security"]
 }
 ```
 
-### `get_balance`
-Check USDC and credit balance.
-
-**Example:**
-```typescript
-{}
-```
-
-## MCP Resources
-
-Resources are read-only URIs that return structured data.
-
-- `paylobster://agent/{address}` — Agent profile and reputation
-- `paylobster://escrow/{id}` — Escrow status and details
-- `paylobster://reputation/{address}` — Reputation metrics
-
-**Example:**
-```
-paylobster://agent/0x1234567890123456789012345678901234567890
-```
-
-## Framework Integration
-
-### Claude Desktop
-
-Add to `claude_desktop_config.json`:
-
+**Create an escrow:**
 ```json
 {
-  "mcpServers": {
-    "paylobster": {
-      "command": "npx",
-      "args": ["@paylobster/mcp-server", "--config", "/path/to/paylobster-mcp.json"]
-    }
+  "to": "0x1234...5678",
+  "amount": "5.00",
+  "terms": {
+    "releaseOn": "delivery-confirmed",
+    "timeout": "P7D"
   }
 }
 ```
 
-### LangChain
-
-```typescript
-import { MCPToolkit } from '@langchain/community/agent_toolkits/mcp';
-import { ChatOpenAI } from 'langchain/chat_models/openai';
-
-const toolkit = new MCPToolkit({
-  serverCommand: 'npx',
-  serverArgs: ['@paylobster/mcp-server', '--config', 'paylobster-mcp.json'],
-});
-
-const tools = await toolkit.getTools();
-const model = new ChatOpenAI({ modelName: 'gpt-4' });
-
-// Use tools with your agent...
+**Search services:**
+```json
+{
+  "query": "code review",
+  "filters": {
+    "category": "development",
+    "maxPrice": "10.00",
+    "minReputation": 4.0
+  }
+}
 ```
 
-### AutoGen (Python)
-
-```python
-from mcp import MCPToolkit
-
-paylobster = MCPToolkit(
-    server_command=["npx", "@paylobster/mcp-server"],
-    config_path="paylobster-mcp.json"
-)
+## MCP Resources (3)
 
-# Use with your AutoGen agents...
-```
+| URI | Description |
+|-----|-------------|
+| `paylobster://agent/{address}` | Agent profile and reputation |
+| `paylobster://escrow/{id}` | Escrow status and details |
+| `paylobster://reputation/{address}` | Reputation metrics |
 
-### CrewAI (Python)
+## Programmatic Usage
 
-```python
-from crewai import Agent, Task, Crew
-from mcp import MCPClient
+```typescript
+import { PayLobsterMCPServer } from '@paylobster/mcp-server';
 
-paylobster = MCPClient(
-    command=["npx", "@paylobster/mcp-server"],
-    config="paylobster-mcp.json"
-)
+const server = new PayLobsterMCPServer({
+  network: 'mainnet',
+  rpcUrl: 'https://base-rpc.publicnode.com',
+  wallet: { privateKey: process.env.PAYLOBSTER_PRIVATE_KEY },
+});
 
-buyer_agent = Agent(
-    role="Service Buyer",
-    tools=paylobster.get_tools(),
-)
+await server.start();
 ```
 
 ## Contract Addresses
 
 ### Base Mainnet
-- Identity: `0xA174ee274F870631B3c330a85EBCad74120BE662`
-- Reputation: `0x02bb4132a86134684976E2a52E43D59D89E64b29`
-- Credit: `0xD9241Ce8a721Ef5fcCAc5A11983addC526eC80E1`
-- Escrow V3: `0x49EdEe04c78B7FeD5248A20706c7a6c540748806`
-
-### Base Sepolia (Testnet)
-- Identity: `0x3dfA02Ed4F0e4F10E8031d7a4cB8Ea0bBbFbCB8c`
-- Reputation: `0xb0033901e3b94f4F36dA0b3e59A1F4AD9f4f1697`
-- Credit: `0xBA64e2b2F2a80D03A4B13b3396942C1e78205C7d`
-- Escrow V3: `0x78D1f50a1965dE34f6b5a3D3546C94FE1809Cd82`
-
-## Development
-
-```bash
-cd mcp-server
-npm install
-npm run build
-npm run dev
-```
 
-## Security
+| Contract | Address |
+|----------|---------|
+| Identity | `0xA174ee274F870631B3c330a85EBCad74120BE662` |
+| Reputation | `0x02bb4132a86134684976E2a52E43D59D89E64b29` |
+| Credit | `0xD9241Ce8a721Ef5fcCAc5A11983addC526eC80E1` |
+| Escrow V3 | `0x49EdEe04c78B7FeD5248A20706c7a6c540748806` |
 
-⚠️ **Never commit your private key!** Always use environment variables or secure key management.
+### Base Sepolia
 
-For production deployments, consider:
-- Hardware wallets (Ledger, Trezor)
-- Encrypted keystores
-- Agent mandates with spending limits
+| Contract | Address |
+|----------|---------|
+| Identity | `0x3dfA02Ed4F0e4F10E8031d7a4cB8Ea0bBbFbCB8c` |
+| Reputation | `0xb0033901e3b94f4F36dA0b3e59A1F4AD9f4f1697` |
+| Credit | `0xBA64e2b2F2a80D03A4B13b3396942C1e78205C7d` |
+| Escrow V3 | `0x78D1f50a1965dE34f6b5a3D3546C94FE1809Cd82` |
 
 ## Architecture
 
-The MCP server acts as a bridge between MCP-compatible agent frameworks and the PayLobster protocol:
-
 ```
 ┌─────────────────────────────┐
 │   Agent Framework           │
@@ -295,28 +188,35 @@ The MCP server acts as a bridge between MCP-compatible agent frameworks and the
               │ MCP Protocol (stdio)
 ┌─────────────▼───────────────┐
 │   PayLobster MCP Server     │
-│   - Tools (8)               │
-│   - Resources (3)           │
+│   - 8 Tools                 │
+│   - 3 Resources             │
 │   - Viem Client             │
 └─────────────┬───────────────┘
               │
 ┌─────────────▼───────────────┐
-│   Base Blockchain           │
+│   Base L2 Blockchain        │
 │   - Smart Contracts         │
 │   - USDC Payments           │
 └─────────────────────────────┘
 ```
 
-## License
+## Security
 
-MIT
+⚠️ **Never commit your private key.** Use environment variables or encrypted key management.
+
+For production: use agent mandates with spending limits to cap autonomous spending.
 
 ## Resources
 
 - **Website**: [paylobster.com](https://paylobster.com)
 - **Docs**: [paylobster.com/docs](https://paylobster.com/docs)
 - **Discord**: [discord.gg/ntWQB6g2jt](https://discord.gg/ntWQB6g2jt)
-- **npm**: [npmjs.com/package/@paylobster/mcp-server](https://www.npmjs.com/package/@paylobster/mcp-server)
+- **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)
+
+## License
+
+MIT © PayLobster
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paylobster/mcp-server",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "MCP server for PayLobster agent payment infrastructure",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",