three.ws Naming

io.github.nirholas/naming-mcp

Documentation

@three-ws/naming-mcp

The on-chain identity layer for AI agents — resolve .sol names and claim your agent a name on three.ws.

A Model Context Protocol server that gives any AI assistant the three.ws naming / identity layer over stdio. Resolve a Solana .sol name to the wallet that owns it, reverse-lookup a wallet to its primary name, and check whether a *.threews.sol agent handle is still free to claim.

This is the three.ws identity layer: where avatars give your agent a face and scenes give it a world, names give it an identity. A *.threews.sol subdomain showcases an agent profile at https://three.ws/u/<label> — claiming one gives your agent a name. No API key, no signer, no payment — every call hits the public /api/sns and /api/threews/subdomain endpoints, backed by Solana / Bonfida SNS (mainnet).

Note: minting a *.threews.sol subdomain is the authenticated write path on the three.ws HTTP API. This MCP server exposes the public resolution + availability reads; once you find a free handle, claim it from your three.ws account.

Install

npm install @three-ws/naming-mcp

Or run with npx (no install):

npx @three-ws/naming-mcp

Quick start

Claude Code, one line:

claude mcp add naming -- npx -y @three-ws/naming-mcp

Claude Desktop / Cursor (claude_desktop_config.json or mcp.json):

{
	"mcpServers": {
		"naming": {
			"command": "npx",
			"args": ["-y", "@three-ws/naming-mcp"]
		}
	}
}

Inspect the surface with the MCP Inspector:

npx -y @modelcontextprotocol/inspector npx @three-ws/naming-mcp

Tools

Tool	Type	What it does
`sns_resolve`	read-only	Resolve a `.sol` name → the base58 wallet that owns it.
`sns_reverse`	read-only	Reverse-lookup a wallet → its primary `.sol` name.
`threews_availability`	read-only	Check whether `<label>.threews.sol` is free to claim as a three.ws agent identity.

All three are live public reads against Solana mainnet. A .sol name with no owner (or a wallet with no favorite name) returns resolved: false — a routine, expected answer, not an error.

Input parameters

sns_resolve — name (required: a .sol label, subdomain, or full name with or without the trailing .sol).

sns_reverse — address (required: a base58 Solana public key).

threews_availability — label (required: the handle to check, e.g. nick for nick.threews.sol; 1–63 chars of [a-z0-9-]).

Example

// sns_resolve
> { "name": "bonfida" }
{
  "ok": true,
  "name": "bonfida.sol",
  "address": "Fw1ETanDZafof7xEULsnq9UY6o71Tpds89tNwPkWLb1v",
  "resolved": true
}

// threews_availability
> { "label": "test" }
{
  "ok": true,
  "full": "test.threews.sol",
  "label": "test",
  "available": true,
  "owner": null,
  "on_chain_check": "ok",
  "showcase_url": null
}

Requirements

Node.js >= 20.
Network access to https://three.ws (or your own THREE_WS_BASE).

Environment variables

Variable	Required	Default
`THREE_WS_BASE`	no	`https://three.ws`
`THREE_WS_TIMEOUT_MS`	no	`20000`