three.ws Naming

@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/ — 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

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

Developing in the monorepo

sns_resolve is authored with @three-ws/tool-sdk, which is private and never published. So that this package installs for everyone, src/vendor/tool-sdk/ carries a byte-identical copy of the SDK's sources instead of a dependency on it. Edit the SDK in packages/tool-sdk/src/, never the copy, then resync:

npm run vendor:tool-sdk   # recopy the SDK into src/vendor/tool-sdk

npm run check:vendored # fails on drift between the SDK and the copy

Tests, from the repo root:

node --test "packages/naming-mcp/test/**/*.test.mjs"

test/registration.test.mjs checks the tool surface offline. test/packed-install.test.mjs packs the tarball, installs it into an empty directory with no workspace, and lists the tools over stdio, which proves the published package resolves every dependency from the npm registry.

Links

• Homepage: https://three.ws
• Changelog: https://three.ws/changelog
• Issues: https://github.com/nirholas/three.ws/issues
• License: Apache-2.0. See LICENSE.

Part of the three.ws SDK suite — 3D AI agents, on-chain identity, and agent payments.

Website · Changelog · GitHub