@azeth/mcp-server 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Azeth.ai
+
+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,141 @@
+# @azeth/mcp-server
+
+MCP (Model Context Protocol) server for Azeth -- the trust, discovery, and payment layer for the machine economy. Provides 32 tools for AI agents to create accounts, make payments, discover services, manage reputation, and communicate via XMTP.
+
+## Setup
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "azeth": {
+      "command": "npx",
+      "args": ["@azeth/mcp-server"],
+      "env": {
+        "AZETH_PRIVATE_KEY": "0x...",
+        "PIMLICO_API_KEY": "your-pimlico-api-key"
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+Add to `.claude/settings.json` in your project:
+
+```json
+{
+  "mcpServers": {
+    "azeth": {
+      "command": "npx",
+      "args": ["@azeth/mcp-server"],
+      "env": {
+        "AZETH_PRIVATE_KEY": "0x...",
+        "PIMLICO_API_KEY": "your-pimlico-api-key"
+      }
+    }
+  }
+}
+```
+
+### Local Development
+
+```json
+{
+  "mcpServers": {
+    "azeth": {
+      "command": "node",
+      "args": ["path/to/Azeth/packages/mcp-server/dist/index.js"],
+      "env": {
+        "AZETH_PRIVATE_KEY": "0x...",
+        "PIMLICO_API_KEY": "your-pimlico-api-key"
+      }
+    }
+  }
+}
+```
+
+## Environment Variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `AZETH_PRIVATE_KEY` | Yes | Account owner's private key (0x-prefixed hex) |
+| `PIMLICO_API_KEY` | Yes* | Pimlico bundler/paymaster API key (*required for state-changing operations) |
+| `AZETH_CHAIN` | No | `"baseSepolia"` or `"base"` (default: `baseSepolia`) |
+| `AZETH_RPC_URL` | No | Custom RPC endpoint |
+| `AZETH_SERVER_URL` | No | Azeth API server URL (default: `https://api.azeth.ai`) |
+| `XMTP_ENCRYPTION_KEY` | No | For XMTP messaging tools |
+
+## Tools (32)
+
+| Category | Tools | Description |
+|---|---|---|
+| **Account** (6) | `azeth_create_account`, `azeth_balance`, `azeth_history`, `azeth_deposit`, `azeth_accounts`, `azeth_whitelist_token` | Deploy smart accounts, check balances, manage token whitelists |
+| **Transfer** (1) | `azeth_transfer` | Send ETH or ERC-20 tokens from your smart account |
+| **Payment** (4) | `azeth_pay`, `azeth_smart_pay`, `azeth_create_payment_agreement`, `azeth_subscribe_service` | Pay for x402 services, auto-discover by capability, set up subscriptions |
+| **Agreement** (5) | `azeth_execute_agreement`, `azeth_cancel_agreement`, `azeth_get_agreement`, `azeth_list_agreements`, `azeth_get_due_agreements` | Manage recurring payment agreements -- execute, cancel, query, find due payments |
+| **Registry** (5) | `azeth_publish_service`, `azeth_discover_services`, `azeth_get_registry_entry`, `azeth_update_service`, `azeth_update_service_batch` | Register on ERC-8004 trust registry, discover services by capability and reputation |
+| **Reputation** (4) | `azeth_submit_opinion`, `azeth_get_weighted_reputation`, `azeth_get_net_paid`, `azeth_get_active_opinion` | Payment-gated reputation -- rate services, check USD-weighted scores |
+| **Messaging** (5) | `azeth_send_message`, `azeth_check_reachability`, `azeth_receive_messages`, `azeth_list_conversations`, `azeth_discover_agent_capabilities` | End-to-end encrypted XMTP messaging between agents |
+| **Guardian** (2) | `azeth_get_guardrails`, `azeth_whitelist_protocol` | View and manage guardian security configuration |
+
+## Address Resolution
+
+All tools that accept addresses support flexible resolution:
+
+- Ethereum address: `0x1234...abcd`
+- Participant name: `"OctusBrain"` (resolved via trust registry)
+- Self-reference: `"me"` (your first smart account)
+- Index reference: `"#1"`, `"#2"` (by account index)
+
+## Response Format
+
+All tools return structured JSON:
+
+```json
+{
+  "success": true,
+  "data": { ... }
+}
+```
+
+Errors include machine-readable codes and recovery suggestions:
+
+```json
+{
+  "success": false,
+  "error": {
+    "code": "INSUFFICIENT_BALANCE",
+    "message": "Insufficient USDC balance: have 5.00, need 10.00.",
+    "suggestion": "Fund your smart account before retrying."
+  }
+}
+```
+
+## Full Documentation
+
+See [docs/mcp-tools.md](../../docs/mcp-tools.md) for complete tool reference with parameter tables, return values, and example prompts for all 32 tools.
+
+## Development
+
+```bash
+# Build
+pnpm build
+
+# Watch mode
+pnpm dev
+
+# Run tests
+pnpm test
+
+# Type check
+pnpm typecheck
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+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":""}

package/dist/index.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { registerAccountTools } from './tools/account.js';
+import { registerTransferTools } from './tools/transfer.js';
+import { registerPaymentTools } from './tools/payments.js';
+import { registerAgreementTools } from './tools/agreements.js';
+import { registerRegistryTools } from './tools/registry.js';
+import { registerReputationTools } from './tools/reputation.js';
+import { registerMessagingTools } from './tools/messaging.js';
+import { registerGuardianTools } from './tools/guardian.js';
+import { registerGuardianApprovalTools } from './tools/guardian-approval.js';
+import { createRateLimiter, wrapServerWithRateLimit } from './utils/rate-limit.js';
+const SERVER_NAME = '@azeth/mcp-server';
+const SERVER_VERSION = '0.1.0';
+/** Create and configure the Azeth MCP server with all Phase 0 tools */
+function createServer() {
+    const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION }, {
+        capabilities: {
+            tools: {},
+        },
+    });
+    // H-8: Wrap server with per-tool rate limiting before registering tools
+    const rateLimiter = createRateLimiter();
+    const rateLimitedServer = wrapServerWithRateLimit(server, rateLimiter);
+    // Register all Phase 0 tools (via rate-limited wrapper)
+    registerAccountTools(rateLimitedServer);
+    registerTransferTools(rateLimitedServer);
+    registerPaymentTools(rateLimitedServer);
+    registerAgreementTools(rateLimitedServer);
+    registerRegistryTools(rateLimitedServer);
+    registerReputationTools(rateLimitedServer);
+    registerMessagingTools(rateLimitedServer);
+    registerGuardianTools(rateLimitedServer);
+    registerGuardianApprovalTools(rateLimitedServer);
+    return server;
+}
+/** Start the MCP server on stdio transport */
+async function main() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    process.stderr.write(`Fatal: ${err instanceof Error ? err.message : String(err)}\n`);
+    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":";AACA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,EAAE,6BAA6B,EAAE,MAAM,8BAA8B,CAAC;AAC7E,OAAO,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAEnF,MAAM,WAAW,GAAG,mBAAmB,CAAC;AACxC,MAAM,cAAc,GAAG,OAAO,CAAC;AAE/B,uEAAuE;AACvE,SAAS,YAAY;IACnB,MAAM,MAAM,GAAG,IAAI,SAAS,CAC1B,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,cAAc,EAAE,EAC9C;QACE,YAAY,EAAE;YACZ,KAAK,EAAE,EAAE;SACV;KACF,CACF,CAAC;IAEF,wEAAwE;IACxE,MAAM,WAAW,GAAG,iBAAiB,EAAE,CAAC;IACxC,MAAM,iBAAiB,GAAG,uBAAuB,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAEvE,wDAAwD;IACxD,oBAAoB,CAAC,iBAAiB,CAAC,CAAC;IACxC,qBAAqB,CAAC,iBAAiB,CAAC,CAAC;IACzC,oBAAoB,CAAC,iBAAiB,CAAC,CAAC;IACxC,sBAAsB,CAAC,iBAAiB,CAAC,CAAC;IAC1C,qBAAqB,CAAC,iBAAiB,CAAC,CAAC;IACzC,uBAAuB,CAAC,iBAAiB,CAAC,CAAC;IAC3C,sBAAsB,CAAC,iBAAiB,CAAC,CAAC;IAC1C,qBAAqB,CAAC,iBAAiB,CAAC,CAAC;IACzC,6BAA6B,CAAC,iBAAiB,CAAC,CAAC;IAEjD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,8CAA8C;AAC9C,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;IAC9B,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACnB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACrF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/tools/account.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/** Register account-related MCP tools: azeth_create_account, azeth_balance, azeth_history, azeth_deposit, azeth_accounts */
+export declare function registerAccountTools(server: McpServer): void;
+//# sourceMappingURL=account.d.ts.map

package/dist/tools/account.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"account.d.ts","sourceRoot":"","sources":["../../src/tools/account.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAmCzE,4HAA4H;AAC5H,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA8nB5D"}