nostr-agents 0.0.1

Model Context Protocol (MCP) communication through Nostr.

Agentstr - Nostr Agent Tools

File Descriptions

1. nwc_client.py

A Python class (NWCClient) for interacting with a Nostr Wallet Connect (NWC) service to handle Lightning Network payments.

• Functionality:
  • Initialize with an NWC connection string.
  • List transactions (list_tx).
  • Get wallet balance (get_balance).
  • Create invoices (make_invoice).
  • Check invoice status (check_invoice).
  • Pay invoices (try_pay_invoice).
  • Monitor payment success with callbacks (on_payment_success).
• Usage: Used by other scripts to handle payment-related operations.
• Example: Create an invoice and monitor payment:

  client = NWCClient(nwc_str)
  invoice = client.make_invoice(amt=5, desc='test')
  client.on_payment_success(invoice, callback=lambda: print('Payment succeeded'))
  

2. nostr_client.py

A core client (NostrClient) for interacting with the Nostr protocol.

• Functionality:
  • Initialize with relay URLs, private key, and optional NWC string.
  • Sign events with a private key.
  • Manage relay connections (get_relay_manager).
  • Read posts by tag (read_posts_by_tag).
  • Fetch and update user metadata (get_metadata_for_pubkey, update_metadata).
  • Send and listen for encrypted direct messages (send_direct_message_to_pubkey, direct_message_listener).
• Usage: Foundation for other scripts to interact with Nostr relays.
• Example: Read posts with a specific tag:

  client = NostrClient(relays, private_key)
  posts = client.read_posts_by_tag('mcp_tool_discovery')
  

3. nostr_mcp_client.py

A client (NostrMCPClient) for interacting with MCP servers over Nostr.

• Functionality:
  • Initialize with a NostrClient and MCP server public key.
  • List available tools (list_tools).
  • Call tools with arguments, handling payments if required (call_tool).
• Usage: Used to invoke tools (e.g., math operations, weather queries) on remote MCP servers.
• Example: Call a multiplication tool:

  mcp_client = NostrMCPClient(nostr_client, server_public_key)
  result = mcp_client.call_tool("multiply", {"a": 69, "b": 420})
  

4. nostr_mcp_server.py

A server (NostrMCPServer) that exposes tools via Nostr and handles tool execution with optional payment requirements.

• Functionality:
  • Initialize with a display name and NostrClient.
  • Add tools with optional pricing in satoshis (add_tool).
  • List available tools (list_tools).
  • Execute tools based on incoming requests (call_tool).
  • Handle direct messages to process tool calls and payments (_direct_message_callback).
  • Start the server to listen for requests (start).
• Usage: Hosts tools like math operations and responds to client requests.
• Example: Add and run a math server:

  server = NostrMCPServer("Math MCP Server", client)
  server.add_tool(lambda a, b: a + b, name="add")
  server.start()
  

5. nostr_agent_server.py

A server (NostrAgentServer) that integrates an external agent API with Nostr for chat-based interactions.

• Functionality:
  • Initialize with an agent URL, satoshis cost, and NostrClient.
  • Fetch agent information (agent_info).
  • Handle chat requests with optional thread IDs (chat).
  • Process direct messages, requiring payments if specified (_direct_message_callback).
  • Start the server to listen for messages (start).
• Usage: Bridges Nostr with an external agent service.
• Example: Start an agent server:

  server = NostrAgentServer(agent_url, 5, client)
  server.start()