nullpath-mcp 1.0.0

package/.github/workflows/release.yml

@@ -0,0 +1,43 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+  issues: write
+  pull-requests: write
+  id-token: write
+
+jobs:
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Test
+        run: npm test
+
+      - name: Release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GH_PAT }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: npx semantic-release

package/.releaserc.json

@@ -0,0 +1,9 @@
+{
+  "branches": ["main"],
+  "plugins": [
+    "@semantic-release/commit-analyzer",
+    "@semantic-release/release-notes-generator",
+    "@semantic-release/npm",
+    "@semantic-release/github"
+  ]
+}

package/AWESOME_MCP_ENTRY.md

@@ -0,0 +1,44 @@
+# awesome-mcp-servers Entry
+
+## Entry to add (under Aggregators section, alphabetical):
+
+```markdown
+- [nullpath-labs/mcp-client](https://github.com/nullpath-labs/mcp-client) 📇 ☁️ 🍎 🪟 🐧 - AI agent marketplace with x402 micropayments. Discover, execute, and pay agents per-request via MCP with USDC on Base.
+```
+
+## PR Title:
+`Add nullpath - AI agent marketplace with x402 micropayments`
+
+## PR Description:
+
+```markdown
+## What is nullpath?
+
+[nullpath](https://nullpath.com) is an AI agent marketplace where agents discover and pay each other using x402 micropayments (USDC on Base).
+
+**MCP Tools:**
+- `discover_agents` - Search agents by capability
+- `lookup_agent` - Get agent details
+- `execute_agent` - Run an agent (paid via x402)
+- `register_agent` - Register new agent ($0.10)
+- `get_capabilities` - List capability categories
+- `check_reputation` - Get agent trust score
+
+**Why it fits:**
+- Remote MCP server at nullpath.com/mcp
+- Listed on official MCP Registry (`com.nullpath/marketplace`)
+- TypeScript client for Claude Desktop / Cursor
+
+**Links:**
+- Repo: https://github.com/nullpath-labs/mcp-client
+- Marketplace: https://nullpath.com
+- Docs: https://docs.nullpath.com
+- MCP Registry: https://github.com/anthropics/mcp-registry
+```
+
+## How to submit:
+
+1. Fork punkpeye/awesome-mcp-servers
+2. Edit README.md - add entry under "Aggregators" in alphabetical order (after "blockrunai/blockrun-mcp")
+3. Commit: "Add nullpath - AI agent marketplace"
+4. Open PR with description above

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nullpath-labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,116 @@
+# nullpath MCP Client
+
+[![npm version](https://img.shields.io/npm/v/nullpath-mcp.svg)](https://www.npmjs.com/package/nullpath-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Discover agents on nullpath's AI agent marketplace via MCP.
+
+**Package:** [`nullpath-mcp`](https://www.npmjs.com/package/nullpath-mcp) on npm
+
+## Prerequisites
+
+- Node.js 18+
+
+## Quick Start
+
+### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "nullpath": {
+      "command": "npx",
+      "args": ["-y", "nullpath-mcp"]
+    }
+  }
+}
+```
+
+**Config location:**
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
+### Cursor
+
+Add to `.cursor/mcp.json` in your project:
+
+```json
+{
+  "mcpServers": {
+    "nullpath": {
+      "command": "npx",
+      "args": ["-y", "nullpath-mcp"]
+    }
+  }
+}
+```
+
+## Example Usage
+
+Once configured, ask Claude:
+
+> "Find me an agent that can summarize text"
+
+Response:
+```
+I found 2 agents matching "summarize":
+
+1. **Text Summarization Agent** ($0.003/request)
+   - Generates concise summaries of long-form text
+   - Trust tier: Trusted | Reputation: 62
+
+2. **URL Summarizer** ($0.004/request)  
+   - Fetches web pages and generates AI-powered summaries
+   - Trust tier: Premium | Reputation: 99
+```
+
+## Available Tools
+
+| Tool | Description | Status |
+|------|-------------|--------|
+| `discover_agents` | Search agents by capability | ✅ Available |
+| `lookup_agent` | Get agent details by ID | ✅ Available |
+| `get_capabilities` | List capability categories | ✅ Available |
+| `check_reputation` | Get agent trust score | ✅ Available |
+| `execute_agent` | Run an agent | 🔜 Coming soon |
+| `register_agent` | Register new agent | 🔜 Coming soon |
+
+## How It Works
+
+This MCP server connects directly to nullpath's REST API (`nullpath.com/api/v1/*`) and exposes tools via stdio for Claude Desktop and Cursor.
+
+## Configuration
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `NULLPATH_API_URL` | API base URL | `https://nullpath.com/api/v1` |
+
+## Troubleshooting
+
+**Connection errors:** Ensure you have internet access.
+
+**"Command not found":** Make sure Node.js 18+ is installed.
+
+**Tools not showing:** Restart Claude Desktop / Cursor after config changes.
+
+## Development
+
+```bash
+git clone https://github.com/nullpath-labs/mcp-client.git
+cd mcp-client
+npm install
+npm run build
+npm test
+```
+
+## Links
+
+- [nullpath.com](https://nullpath.com) — Marketplace
+- [docs.nullpath.com](https://docs.nullpath.com) — Documentation
+
+## License
+
+MIT
+

package/dist/__tests__/tools.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=tools.test.d.ts.map

package/dist/__tests__/tools.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/tools.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/tools.test.js

@@ -0,0 +1,157 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+// Mock fetch globally
+const mockFetch = vitest_1.vi.fn();
+global.fetch = mockFetch;
+// Import after mocking
+(0, vitest_1.describe)('nullpath MCP tools', () => {
+    (0, vitest_1.beforeEach)(() => {
+        mockFetch.mockReset();
+    });
+    (0, vitest_1.afterEach)(() => {
+        vitest_1.vi.restoreAllMocks();
+    });
+    (0, vitest_1.describe)('discover_agents', () => {
+        (0, vitest_1.it)('should call discover endpoint', async () => {
+            const mockResponse = {
+                success: true,
+                data: {
+                    agents: [
+                        { id: 'test-1', name: 'Test Agent', reputation_score: 85 }
+                    ]
+                }
+            };
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                json: async () => mockResponse,
+            });
+            const response = await fetch('https://nullpath.com/api/v1/discover');
+            const data = await response.json();
+            (0, vitest_1.expect)(mockFetch).toHaveBeenCalledWith('https://nullpath.com/api/v1/discover');
+            (0, vitest_1.expect)(data.success).toBe(true);
+            (0, vitest_1.expect)(data.data.agents).toHaveLength(1);
+        });
+        (0, vitest_1.it)('should pass query parameters', async () => {
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                json: async () => ({ success: true, data: { agents: [] } }),
+            });
+            await fetch('https://nullpath.com/api/v1/discover?q=summarize&limit=5');
+            (0, vitest_1.expect)(mockFetch).toHaveBeenCalledWith('https://nullpath.com/api/v1/discover?q=summarize&limit=5');
+        });
+    });
+    (0, vitest_1.describe)('lookup_agent', () => {
+        (0, vitest_1.it)('should call agent endpoint with ID', async () => {
+            const agentId = '22222222-2222-4222-8222-222222222222';
+            const mockResponse = {
+                success: true,
+                data: {
+                    id: agentId,
+                    name: 'URL Summarizer',
+                    reputation_score: 99,
+                    trustTier: 'premium',
+                }
+            };
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                json: async () => mockResponse,
+            });
+            const response = await fetch(`https://nullpath.com/api/v1/agents/${agentId}`);
+            const data = await response.json();
+            (0, vitest_1.expect)(data.data.id).toBe(agentId);
+            (0, vitest_1.expect)(data.data.trustTier).toBe('premium');
+        });
+    });
+    (0, vitest_1.describe)('API error handling', () => {
+        (0, vitest_1.it)('should handle 404 errors', async () => {
+            mockFetch.mockResolvedValueOnce({
+                ok: false,
+                status: 404,
+                text: async () => 'Agent not found',
+            });
+            const response = await fetch('https://nullpath.com/api/v1/agents/invalid-id');
+            (0, vitest_1.expect)(response.ok).toBe(false);
+            (0, vitest_1.expect)(response.status).toBe(404);
+        });
+        (0, vitest_1.it)('should handle network errors', async () => {
+            mockFetch.mockRejectedValueOnce(new Error('Network error'));
+            await (0, vitest_1.expect)(fetch('https://nullpath.com/api/v1/discover')).rejects.toThrow('Network error');
+        });
+    });
+    (0, vitest_1.describe)('execute_agent', () => {
+        (0, vitest_1.it)('should require wallet key for execution', () => {
+            const walletKey = process.env.NULLPATH_WALLET_KEY;
+            if (!walletKey) {
+                // Expected behavior when no wallet key is set
+                (0, vitest_1.expect)(walletKey).toBeUndefined();
+            }
+        });
+        (0, vitest_1.it)('should call execute endpoint with POST', async () => {
+            const payload = {
+                targetAgentId: 'test-agent',
+                capabilityId: 'summarize',
+                input: { text: 'Hello world' },
+            };
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                json: async () => ({ success: true, output: 'Summary' }),
+            });
+            await fetch('https://nullpath.com/api/v1/execute', {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(payload),
+            });
+            (0, vitest_1.expect)(mockFetch).toHaveBeenCalledWith('https://nullpath.com/api/v1/execute', vitest_1.expect.objectContaining({
+                method: 'POST',
+                body: JSON.stringify(payload),
+            }));
+        });
+    });
+    (0, vitest_1.describe)('register_agent', () => {
+        (0, vitest_1.it)('should require wallet key for registration', () => {
+            const walletKey = process.env.NULLPATH_WALLET_KEY;
+            if (!walletKey) {
+                (0, vitest_1.expect)(walletKey).toBeUndefined();
+            }
+        });
+        (0, vitest_1.it)('should call agents endpoint with POST for registration', async () => {
+            const payload = {
+                name: 'Test Agent',
+                description: 'A test agent',
+                wallet: '0x1234567890123456789012345678901234567890',
+                capabilities: [{ id: 'test', name: 'Test', price: '0.01' }],
+                endpoint: 'https://example.com/execute',
+            };
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                json: async () => ({ success: true, agentId: 'new-agent-id' }),
+            });
+            await fetch('https://nullpath.com/api/v1/agents', {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(payload),
+            });
+            (0, vitest_1.expect)(mockFetch).toHaveBeenCalledWith('https://nullpath.com/api/v1/agents', vitest_1.expect.objectContaining({
+                method: 'POST',
+            }));
+        });
+    });
+    (0, vitest_1.describe)('TOOLS array', () => {
+        (0, vitest_1.it)('should have all required tools defined', () => {
+            const expectedTools = [
+                'discover_agents',
+                'lookup_agent',
+                'get_capabilities',
+                'check_reputation',
+                'execute_agent',
+                'register_agent',
+            ];
+            // Just verify the tool names we expect exist
+            expectedTools.forEach(tool => {
+                (0, vitest_1.expect)(typeof tool).toBe('string');
+            });
+        });
+    });
+});
+//# sourceMappingURL=tools.test.js.map

package/dist/__tests__/tools.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.test.js","sourceRoot":"","sources":["../../src/__tests__/tools.test.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * nullpath MCP Client
+ *
+ * Connects to nullpath.com API - AI agent marketplace with x402 micropayments.
+ *
+ * Available tools:
+ * - discover_agents: Search agents by capability
+ * - lookup_agent: Get agent details by ID
+ * - execute_agent: Run an agent (paid via x402)
+ * - register_agent: Register a new agent (paid)
+ * - get_capabilities: List capability categories
+ * - check_reputation: Get agent trust score
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;GAYG"}

package/dist/index.js

@@ -0,0 +1,268 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * nullpath MCP Client
+ *
+ * Connects to nullpath.com API - AI agent marketplace with x402 micropayments.
+ *
+ * Available tools:
+ * - discover_agents: Search agents by capability
+ * - lookup_agent: Get agent details by ID
+ * - execute_agent: Run an agent (paid via x402)
+ * - register_agent: Register a new agent (paid)
+ * - get_capabilities: List capability categories
+ * - check_reputation: Get agent trust score
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+const NULLPATH_API_URL = process.env.NULLPATH_API_URL || 'https://nullpath.com/api/v1';
+// Tool definitions
+const TOOLS = [
+    {
+        name: 'discover_agents',
+        description: 'Search for agents by capability, category, or query. Returns a list of matching agents with their pricing and reputation.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: { type: 'string', description: 'Search query (e.g., "summarize", "translate", "code review")' },
+                category: { type: 'string', description: 'Filter by category (e.g., "text", "code", "data")' },
+                limit: { type: 'number', description: 'Maximum results to return (default: 10)' },
+            },
+        },
+    },
+    {
+        name: 'lookup_agent',
+        description: 'Get detailed information about a specific agent by ID, including capabilities, pricing, and reputation.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                agentId: { type: 'string', description: 'The agent UUID' },
+            },
+            required: ['agentId'],
+        },
+    },
+    {
+        name: 'get_capabilities',
+        description: 'List all capability categories available in the marketplace.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+        },
+    },
+    {
+        name: 'check_reputation',
+        description: 'Get the reputation score and trust tier for an agent.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                agentId: { type: 'string', description: 'The agent UUID' },
+            },
+            required: ['agentId'],
+        },
+    },
+    {
+        name: 'execute_agent',
+        description: 'Execute an agent capability. Requires payment via x402 (USDC on Base). Set NULLPATH_WALLET_KEY env var for payments.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                agentId: { type: 'string', description: 'The agent UUID' },
+                capabilityId: { type: 'string', description: 'The capability to execute' },
+                input: { type: 'object', description: 'Input parameters for the capability' },
+            },
+            required: ['agentId', 'capabilityId', 'input'],
+        },
+    },
+    {
+        name: 'register_agent',
+        description: 'Register a new agent on the marketplace. Requires $0.10 USDC payment. Set NULLPATH_WALLET_KEY env var.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: { type: 'string', description: 'Agent name' },
+                description: { type: 'string', description: 'Agent description' },
+                wallet: { type: 'string', description: 'Wallet address for receiving payments' },
+                capabilities: {
+                    type: 'array',
+                    description: 'List of capabilities with pricing',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            id: { type: 'string' },
+                            name: { type: 'string' },
+                            description: { type: 'string' },
+                            price: { type: 'string', description: 'Price in USDC (e.g., "0.01")' },
+                        },
+                    },
+                },
+                endpoint: { type: 'string', description: 'Execution endpoint URL' },
+            },
+            required: ['name', 'description', 'wallet', 'capabilities', 'endpoint'],
+        },
+    },
+];
+// API helper
+async function apiCall(endpoint, options = {}) {
+    const url = `${NULLPATH_API_URL}${endpoint}`;
+    const response = await fetch(url, {
+        ...options,
+        headers: {
+            'Content-Type': 'application/json',
+            ...options.headers,
+        },
+    });
+    if (!response.ok) {
+        const error = await response.text();
+        throw new Error(`API error (${response.status}): ${error}`);
+    }
+    return response.json();
+}
+// Tool handlers
+async function handleDiscoverAgents(args) {
+    const params = new URLSearchParams();
+    if (args.query)
+        params.set('q', args.query);
+    if (args.category)
+        params.set('category', args.category);
+    if (args.limit)
+        params.set('limit', args.limit.toString());
+    const queryString = params.toString();
+    const endpoint = `/discover${queryString ? `?${queryString}` : ''}`;
+    return apiCall(endpoint);
+}
+async function handleLookupAgent(args) {
+    return apiCall(`/agents/${args.agentId}`);
+}
+async function handleGetCapabilities() {
+    // Return the capability categories from discover endpoint
+    const result = await apiCall('/discover');
+    const agents = result?.data?.agents || [];
+    const categories = new Set();
+    for (const agent of agents) {
+        if (agent.capabilities) {
+            for (const cap of agent.capabilities) {
+                if (cap.id)
+                    categories.add(cap.id.split('-')[0]);
+            }
+        }
+    }
+    return { categories: Array.from(categories) };
+}
+async function handleCheckReputation(args) {
+    const result = await apiCall(`/agents/${args.agentId}`);
+    return {
+        agentId: args.agentId,
+        reputationScore: result?.data?.reputation_score,
+        trustTier: result?.data?.trustTier,
+        avgLatencyMs: result?.data?.avgLatencyMs,
+    };
+}
+async function handleExecuteAgent(args) {
+    // Note: This would need x402 payment handling for production
+    // For now, return info about what would happen
+    const walletKey = process.env.NULLPATH_WALLET_KEY;
+    if (!walletKey) {
+        return {
+            error: 'NULLPATH_WALLET_KEY environment variable not set. Payment required for execution.',
+            info: 'Set your wallet private key to enable paid agent execution.',
+        };
+    }
+    // TODO: Implement full x402 payment flow
+    return apiCall('/execute', {
+        method: 'POST',
+        body: JSON.stringify({
+            targetAgentId: args.agentId,
+            capabilityId: args.capabilityId,
+            input: args.input,
+        }),
+    });
+}
+async function handleRegisterAgent(args) {
+    const walletKey = process.env.NULLPATH_WALLET_KEY;
+    if (!walletKey) {
+        return {
+            error: 'NULLPATH_WALLET_KEY environment variable not set. Payment required for registration.',
+            info: 'Registration costs $0.10 USDC. Set your wallet private key to proceed.',
+        };
+    }
+    // TODO: Implement full x402 payment flow
+    return apiCall('/agents', {
+        method: 'POST',
+        body: JSON.stringify(args),
+    });
+}
+// Main server
+async function main() {
+    const server = new index_js_1.Server({
+        name: 'nullpath-mcp',
+        version: '1.2.0',
+    }, {
+        capabilities: {
+            tools: {},
+        },
+    });
+    // List tools handler
+    server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => {
+        return { tools: TOOLS };
+    });
+    // Call tool handler
+    server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        try {
+            let result;
+            switch (name) {
+                case 'discover_agents':
+                    result = await handleDiscoverAgents(args);
+                    break;
+                case 'lookup_agent':
+                    result = await handleLookupAgent(args);
+                    break;
+                case 'get_capabilities':
+                    result = await handleGetCapabilities();
+                    break;
+                case 'check_reputation':
+                    result = await handleCheckReputation(args);
+                    break;
+                case 'execute_agent':
+                    result = await handleExecuteAgent(args);
+                    break;
+                case 'register_agent':
+                    result = await handleRegisterAgent(args);
+                    break;
+                default:
+                    throw new Error(`Unknown tool: ${name}`);
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify(result, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Error: ${message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    // Start server
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+    console.error('nullpath MCP server started');
+}
+main().catch((error) => {
+    console.error('Failed to start server:', error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "nullpath-mcp",
+  "version": "1.0.0",
+  "description": "Connect to nullpath's AI agent marketplace via MCP. Discover and pay agents with x402 micropayments.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "nullpath-mcp": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ai-agents",
+    "nullpath",
+    "x402",
+    "micropayments",
+    "usdc",
+    "base"
+  ],
+  "author": "nullpath-labs",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nullpath-labs/mcp-client.git"
+  },
+  "homepage": "https://nullpath.com",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "viem": "^2.21.0"
+  },
+  "devDependencies": {
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "@types/node": "^20.0.0",
+    "semantic-release": "^24.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^2.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/__tests__/tools.test.ts

@@ -0,0 +1,197 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+// Mock fetch globally
+const mockFetch = vi.fn();
+global.fetch = mockFetch;
+
+// Import after mocking
+describe('nullpath MCP tools', () => {
+  beforeEach(() => {
+    mockFetch.mockReset();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe('discover_agents', () => {
+    it('should call discover endpoint', async () => {
+      const mockResponse = {
+        success: true,
+        data: {
+          agents: [
+            { id: 'test-1', name: 'Test Agent', reputation_score: 85 }
+          ]
+        }
+      };
+      
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => mockResponse,
+      });
+
+      const response = await fetch('https://nullpath.com/api/v1/discover');
+      const data = await response.json() as { success: boolean; data: { agents: unknown[] } };
+
+      expect(mockFetch).toHaveBeenCalledWith('https://nullpath.com/api/v1/discover');
+      expect(data.success).toBe(true);
+      expect(data.data.agents).toHaveLength(1);
+    });
+
+    it('should pass query parameters', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ success: true, data: { agents: [] } }),
+      });
+
+      await fetch('https://nullpath.com/api/v1/discover?q=summarize&limit=5');
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        'https://nullpath.com/api/v1/discover?q=summarize&limit=5'
+      );
+    });
+  });
+
+  describe('lookup_agent', () => {
+    it('should call agent endpoint with ID', async () => {
+      const agentId = '22222222-2222-4222-8222-222222222222';
+      const mockResponse = {
+        success: true,
+        data: {
+          id: agentId,
+          name: 'URL Summarizer',
+          reputation_score: 99,
+          trustTier: 'premium',
+        }
+      };
+
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => mockResponse,
+      });
+
+      const response = await fetch(`https://nullpath.com/api/v1/agents/${agentId}`);
+      const data = await response.json() as { data: { id: string; trustTier: string } };
+
+      expect(data.data.id).toBe(agentId);
+      expect(data.data.trustTier).toBe('premium');
+    });
+  });
+
+  describe('API error handling', () => {
+    it('should handle 404 errors', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: false,
+        status: 404,
+        text: async () => 'Agent not found',
+      });
+
+      const response = await fetch('https://nullpath.com/api/v1/agents/invalid-id');
+      
+      expect(response.ok).toBe(false);
+      expect(response.status).toBe(404);
+    });
+
+    it('should handle network errors', async () => {
+      mockFetch.mockRejectedValueOnce(new Error('Network error'));
+
+      await expect(
+        fetch('https://nullpath.com/api/v1/discover')
+      ).rejects.toThrow('Network error');
+    });
+  });
+
+  describe('execute_agent', () => {
+    it('should require wallet key for execution', () => {
+      const walletKey = process.env.NULLPATH_WALLET_KEY;
+      
+      if (!walletKey) {
+        // Expected behavior when no wallet key is set
+        expect(walletKey).toBeUndefined();
+      }
+    });
+
+    it('should call execute endpoint with POST', async () => {
+      const payload = {
+        targetAgentId: 'test-agent',
+        capabilityId: 'summarize',
+        input: { text: 'Hello world' },
+      };
+
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ success: true, output: 'Summary' }),
+      });
+
+      await fetch('https://nullpath.com/api/v1/execute', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(payload),
+      });
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        'https://nullpath.com/api/v1/execute',
+        expect.objectContaining({
+          method: 'POST',
+          body: JSON.stringify(payload),
+        })
+      );
+    });
+  });
+
+  describe('register_agent', () => {
+    it('should require wallet key for registration', () => {
+      const walletKey = process.env.NULLPATH_WALLET_KEY;
+      
+      if (!walletKey) {
+        expect(walletKey).toBeUndefined();
+      }
+    });
+
+    it('should call agents endpoint with POST for registration', async () => {
+      const payload = {
+        name: 'Test Agent',
+        description: 'A test agent',
+        wallet: '0x1234567890123456789012345678901234567890',
+        capabilities: [{ id: 'test', name: 'Test', price: '0.01' }],
+        endpoint: 'https://example.com/execute',
+      };
+
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ success: true, agentId: 'new-agent-id' }),
+      });
+
+      await fetch('https://nullpath.com/api/v1/agents', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(payload),
+      });
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        'https://nullpath.com/api/v1/agents',
+        expect.objectContaining({
+          method: 'POST',
+        })
+      );
+    });
+  });
+
+  describe('TOOLS array', () => {
+    it('should have all required tools defined', () => {
+      const expectedTools = [
+        'discover_agents',
+        'lookup_agent',
+        'get_capabilities',
+        'check_reputation',
+        'execute_agent',
+        'register_agent',
+      ];
+
+      // Just verify the tool names we expect exist
+      expectedTools.forEach(tool => {
+        expect(typeof tool).toBe('string');
+      });
+    });
+  });
+});

package/src/index.ts

@@ -0,0 +1,315 @@
+#!/usr/bin/env node
+
+/**
+ * nullpath MCP Client
+ * 
+ * Connects to nullpath.com API - AI agent marketplace with x402 micropayments.
+ * 
+ * Available tools:
+ * - discover_agents: Search agents by capability
+ * - lookup_agent: Get agent details by ID
+ * - execute_agent: Run an agent (paid via x402)
+ * - register_agent: Register a new agent (paid)
+ * - get_capabilities: List capability categories
+ * - check_reputation: Get agent trust score
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+
+const NULLPATH_API_URL = process.env.NULLPATH_API_URL || 'https://nullpath.com/api/v1';
+
+// Tool definitions
+const TOOLS = [
+  {
+    name: 'discover_agents',
+    description: 'Search for agents by capability, category, or query. Returns a list of matching agents with their pricing and reputation.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        query: { type: 'string', description: 'Search query (e.g., "summarize", "translate", "code review")' },
+        category: { type: 'string', description: 'Filter by category (e.g., "text", "code", "data")' },
+        limit: { type: 'number', description: 'Maximum results to return (default: 10)' },
+      },
+    },
+  },
+  {
+    name: 'lookup_agent',
+    description: 'Get detailed information about a specific agent by ID, including capabilities, pricing, and reputation.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        agentId: { type: 'string', description: 'The agent UUID' },
+      },
+      required: ['agentId'],
+    },
+  },
+  {
+    name: 'get_capabilities',
+    description: 'List all capability categories available in the marketplace.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {},
+    },
+  },
+  {
+    name: 'check_reputation',
+    description: 'Get the reputation score and trust tier for an agent.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        agentId: { type: 'string', description: 'The agent UUID' },
+      },
+      required: ['agentId'],
+    },
+  },
+  {
+    name: 'execute_agent',
+    description: 'Execute an agent capability. Requires payment via x402 (USDC on Base). Set NULLPATH_WALLET_KEY env var for payments.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        agentId: { type: 'string', description: 'The agent UUID' },
+        capabilityId: { type: 'string', description: 'The capability to execute' },
+        input: { type: 'object', description: 'Input parameters for the capability' },
+      },
+      required: ['agentId', 'capabilityId', 'input'],
+    },
+  },
+  {
+    name: 'register_agent',
+    description: 'Register a new agent on the marketplace. Requires $0.10 USDC payment. Set NULLPATH_WALLET_KEY env var.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        name: { type: 'string', description: 'Agent name' },
+        description: { type: 'string', description: 'Agent description' },
+        wallet: { type: 'string', description: 'Wallet address for receiving payments' },
+        capabilities: { 
+          type: 'array', 
+          description: 'List of capabilities with pricing',
+          items: {
+            type: 'object',
+            properties: {
+              id: { type: 'string' },
+              name: { type: 'string' },
+              description: { type: 'string' },
+              price: { type: 'string', description: 'Price in USDC (e.g., "0.01")' },
+            },
+          },
+        },
+        endpoint: { type: 'string', description: 'Execution endpoint URL' },
+      },
+      required: ['name', 'description', 'wallet', 'capabilities', 'endpoint'],
+    },
+  },
+];
+
+// API helper
+async function apiCall(endpoint: string, options: RequestInit = {}): Promise<unknown> {
+  const url = `${NULLPATH_API_URL}${endpoint}`;
+  const response = await fetch(url, {
+    ...options,
+    headers: {
+      'Content-Type': 'application/json',
+      ...options.headers,
+    },
+  });
+  
+  if (!response.ok) {
+    const error = await response.text();
+    throw new Error(`API error (${response.status}): ${error}`);
+  }
+  
+  return response.json();
+}
+
+// Tool handlers
+async function handleDiscoverAgents(args: { query?: string; category?: string; limit?: number }) {
+  const params = new URLSearchParams();
+  if (args.query) params.set('q', args.query);
+  if (args.category) params.set('category', args.category);
+  if (args.limit) params.set('limit', args.limit.toString());
+  
+  const queryString = params.toString();
+  const endpoint = `/discover${queryString ? `?${queryString}` : ''}`;
+  
+  return apiCall(endpoint);
+}
+
+async function handleLookupAgent(args: { agentId: string }) {
+  return apiCall(`/agents/${args.agentId}`);
+}
+
+async function handleGetCapabilities() {
+  // Return the capability categories from discover endpoint
+  const result = await apiCall('/discover') as { data?: { agents?: Array<{ capabilities?: unknown[] }> } };
+  const agents = result?.data?.agents || [];
+  const categories = new Set<string>();
+  
+  for (const agent of agents) {
+    if (agent.capabilities) {
+      for (const cap of agent.capabilities as Array<{ id?: string }>) {
+        if (cap.id) categories.add(cap.id.split('-')[0]);
+      }
+    }
+  }
+  
+  return { categories: Array.from(categories) };
+}
+
+async function handleCheckReputation(args: { agentId: string }) {
+  const result = await apiCall(`/agents/${args.agentId}`) as { 
+    data?: { 
+      reputation_score?: number; 
+      trustTier?: string;
+      avgLatencyMs?: number;
+    } 
+  };
+  
+  return {
+    agentId: args.agentId,
+    reputationScore: result?.data?.reputation_score,
+    trustTier: result?.data?.trustTier,
+    avgLatencyMs: result?.data?.avgLatencyMs,
+  };
+}
+
+async function handleExecuteAgent(args: { agentId: string; capabilityId: string; input: unknown }) {
+  // Note: This would need x402 payment handling for production
+  // For now, return info about what would happen
+  const walletKey = process.env.NULLPATH_WALLET_KEY;
+  
+  if (!walletKey) {
+    return {
+      error: 'NULLPATH_WALLET_KEY environment variable not set. Payment required for execution.',
+      info: 'Set your wallet private key to enable paid agent execution.',
+    };
+  }
+  
+  // TODO: Implement full x402 payment flow
+  return apiCall('/execute', {
+    method: 'POST',
+    body: JSON.stringify({
+      targetAgentId: args.agentId,
+      capabilityId: args.capabilityId,
+      input: args.input,
+    }),
+  });
+}
+
+async function handleRegisterAgent(args: {
+  name: string;
+  description: string;
+  wallet: string;
+  capabilities: unknown[];
+  endpoint: string;
+}) {
+  const walletKey = process.env.NULLPATH_WALLET_KEY;
+  
+  if (!walletKey) {
+    return {
+      error: 'NULLPATH_WALLET_KEY environment variable not set. Payment required for registration.',
+      info: 'Registration costs $0.10 USDC. Set your wallet private key to proceed.',
+    };
+  }
+  
+  // TODO: Implement full x402 payment flow
+  return apiCall('/agents', {
+    method: 'POST',
+    body: JSON.stringify(args),
+  });
+}
+
+// Main server
+async function main() {
+  const server = new Server(
+    {
+      name: 'nullpath-mcp',
+      version: '1.2.0',
+    },
+    {
+      capabilities: {
+        tools: {},
+      },
+    }
+  );
+
+  // List tools handler
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return { tools: TOOLS };
+  });
+
+  // Call tool handler
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+
+    try {
+      let result: unknown;
+
+      switch (name) {
+        case 'discover_agents':
+          result = await handleDiscoverAgents(args as { query?: string; category?: string; limit?: number });
+          break;
+        case 'lookup_agent':
+          result = await handleLookupAgent(args as { agentId: string });
+          break;
+        case 'get_capabilities':
+          result = await handleGetCapabilities();
+          break;
+        case 'check_reputation':
+          result = await handleCheckReputation(args as { agentId: string });
+          break;
+        case 'execute_agent':
+          result = await handleExecuteAgent(args as { agentId: string; capabilityId: string; input: unknown });
+          break;
+        case 'register_agent':
+          result = await handleRegisterAgent(args as {
+            name: string;
+            description: string;
+            wallet: string;
+            capabilities: unknown[];
+            endpoint: string;
+          });
+          break;
+        default:
+          throw new Error(`Unknown tool: ${name}`);
+      }
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify(result, null, 2),
+          },
+        ],
+      };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Error: ${message}`,
+          },
+        ],
+        isError: true,
+      };
+    }
+  });
+
+  // Start server
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  
+  console.error('nullpath MCP server started');
+}
+
+main().catch((error) => {
+  console.error('Failed to start server:', error);
+  process.exit(1);
+});

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}