Nostr Metadata

This document explains the Metadata class from the pynostr library, which is used to define profile information for entities on the Nostr network, such as agents or MCP servers.

Overview of Metadata

The Metadata class is a specialized type of Event in the Nostr protocol that allows you to set profile information for a public key. This information is broadcast to the network and can be discovered by other users or services.

The class is defined as follows:

class Metadata(Event):
    name: Optional[str] = None
    about: Optional[str] = None
    nip05: Optional[str] = None
    picture: Optional[str] = None
    banner: Optional[str] = None
    lud16: Optional[str] = None
    lud06: Optional[str] = None
    username: Optional[str] = None
    display_name: Optional[str] = None
    website: Optional[str] = None

Each field is optional and represents a piece of profile information:

  • name: A short name or handle for the entity.

  • about: A brief description or bio.

  • nip05: An identifier for NIP-05 verification (DNS-based identity).

  • picture: URL to a profile picture or avatar.

  • banner: URL to a banner image.

  • lud16: Lightning address for receiving payments (human-readable).

  • lud06: Lightning address for receiving payments (LNURL).

  • username: Alternative short identifier.

  • display_name: A longer or formatted name for display purposes.

  • website: URL to a personal or project website.

Using Metadata with Agentstr

In the Agentstr SDK, you can pass an instance of Metadata to both the NostrAgent and NostrMCPServer classes. When provided, the SDK will automatically update and broadcast this metadata on the Nostr network, allowing other users to discover and interact with your agent or MCP server using the provided profile information.

Example with NostrAgent

from agentstr import NostrAgent, AgentCard, Metadata

# Define metadata for the agent
agent_metadata = Metadata(
    name="MyAgent",
    about="A helpful AI agent built with Agentstr.",
    picture="https://example.com/my-agent-picture.png",
    lud16="myagent@lnaddress.com"
)

# Initialize the agent with metadata
agent_card = AgentCard(name="MyAgent", description="A helpful AI agent")
nostr_agent = NostrAgent(
    agent_card=agent_card,
    nostr_metadata=agent_metadata,
    chat_generator=your_chat_function
)

Example with NostrMCPServer

from agentstr import NostrMCPServer, Metadata

# Define metadata for the MCP server
server_metadata = Metadata(
    name="MathToolsServer",
    about="An MCP server providing mathematical tools.",
    picture="https://example.com/math-tools-icon.png",
    website="https://mathtools.example.com"
)

# Initialize the MCP server with metadata
server = NostrMCPServer(
    name="Math Tools MCP Server",
    relays=["wss://relay.example.com"],
    private_key="your-private-key",
    nostr_metadata=server_metadata,
    tools=[add, multiply]
)

Defining Metadata from YAML

Another convenient way to define Nostr metadata is by using a YAML file. The agentstr.utils.metadata_from_yaml() function allows you to load metadata configurations from a YAML file, which can be useful for managing multiple profiles or maintaining metadata outside of code.

Here’s an example of how to use it:

from agentstr import metadata_from_yaml

# Load metadata from a specific YAML file
metadata = metadata_from_yaml("path/to/nostr-metadata.yml")

# Load metadata from the default (`nostr-metadata.yml`) file
# (if it exists in the same directory as the file calling this function)
metadata = metadata_from_yaml(__file__)

# Use the metadata with NostrAgent
agent = NostrAgent(nostr_metadata=metadata, ...)

The YAML file (e.g., nostr-metadata.yml) might look like this:

name: "AgentstrAgent"
about: "A brief description about me."
picture: "https://example.com/my-picture.jpg"
nip05: "myname@example.com"

This approach makes it easy to update metadata without changing code and supports a more declarative way of defining profile information.

Benefits

  • Discoverability: Metadata makes your agent or MCP server more discoverable on the Nostr network by providing descriptive information.

  • User Trust: Including verification details (like NIP-05) or payment addresses (like lud16) can build trust with users.

  • Branding: Use profile pictures, banners, and display names to create a consistent identity for your services.