@agentdomain/mcp-server 0.6.0 → 0.8.0

package/NOTICE

@@ -0,0 +1,5 @@
+AgentDomain public developer tools and verified Base contracts
+Copyright 2026 Md. Rakib
+
+AgentDomain and related names and logos are trademarks or service marks of
+their respective owner. This license does not grant trademark rights.

package/README.md

@@ -2,51 +2,43 @@
 
 [Model Context Protocol](https://modelcontextprotocol.io) server for AgentDomain.
 
-Lets any MCP-compatible LLM client (Claude Desktop, ChatGPT desktop apps, custom agents) register and manage agent identities through natural language.
-
-The default API base, `https://agentdomain.app/api/v1`, also returns machine-readable discovery
-metadata when requested directly.
-
-## Tools exposed
-
-- `check_domain_availability` - is a domain available?
-- `quote_registration` - price a registration
-- `register_agent_identity` - register a complete identity (requires wallet)
-- `lookup_agent` - find an agent by wallet
-- `search_agents` - search the public registry
-- `send_agent_email` - send an email from an agent's address
-- `send_agent_email_batch` - queue up to 100 email objects in one API request
-- `list_agent_email` - read agent inbox/outbox messages
-- `get_agent_email_usage` - inspect combined monthly sent and received usage
-- `configure_email_webhook` - configure a signed inbound email webhook
-- `update_primary_email` - change the included primary email username
-- `create_email_alias` - create a Starter/Pro/Enterprise receive-and-send email alias
-- `delete_email_alias` - delete an active email alias
-- `list_dns_records` - list DNS records for an agent domain
-- `create_dns_record` - create a user-managed DNS record
-- `update_dns_record` - update a user-managed DNS record
-- `delete_dns_record` - delete a user-managed DNS record
-- `get_dns_capabilities` - discover all 13 Spaceship-supported types and validation constraints
-- `change_dns_records` - preview or apply a revision-protected merge/replace batch
-- `import_dns_zone` - preview or apply a standard BIND zone import
-- `export_dns_zone` - export user-managed or permitted complete-zone records as BIND
-- `reconfigure_ssl` - rebuild Cloudflare SaaS SSL and DNS validation records
-- `fund_renewal_vault` - top up an agent's renewal vault
-- `withdraw_renewal_vault` - build an owner-signed vault withdrawal transaction
-- `get_renewal_status` - check renewal date, amount, vault balance, and auto-renew state
-- `enable_auto_renew` - enable on-chain auto-renew with the AgentID NFT owner wallet
-- `get_service_plan` - inspect per-agent Included/Starter/Pro/Enterprise limits
-- `purchase_service_plan` - upgrade to Starter, Pro, or Enterprise with x402 USDC
-
-## Install
+It lets MCP-compatible clients discover and manage agent identities through the
+[AgentDomain API](https://api.agentdomain.app/api/v1).
+
+The server requires Node.js 20 or newer and communicates over standard input
+and output. It does not open a public listener.
+
+## Run
+
+```bash
+npx -y @agentdomain/mcp-server
+```
+
+For a persistent installation:
 
 ```bash
 npm install -g @agentdomain/mcp-server
+agentdomain-mcp
 ```
 
-## Configure (Claude Desktop example)
+## Default tools
+
+The server starts in read-only mode. It advertises only tools that inspect public
+or authorized account state:
+
+- `check_domain_availability` and `quote_registration`
+- `lookup_agent`, `get_agent`, and `search_agents`
+- `list_agent_email` and `get_agent_email_usage`
+- `get_dns_capabilities`, `list_dns_records`, and `export_dns_zone`
+- `get_renewal_status` and `get_service_plan`
 
-`~/Library/Application Support/Claude/claude_desktop_config.json`:
+An API key may authorize additional reads, but merely supplying one never enables
+mutation tools.
+
+## Read-only configuration
+
+Start without a signing credential for discovery, lookup, search, and other
+read-only operations. For example:
 
 ```json
 {
@@ -55,49 +47,70 @@ npm install -g @agentdomain/mcp-server
       "command": "npx",
       "args": ["-y", "@agentdomain/mcp-server"],
       "env": {
-        "AGENTDOMAIN_API_URL": "https://agentdomain.app/api/v1",
-        "AGENT_PRIVATE_KEY": "0x...",
-        "AGENTDOMAIN_NETWORK": "base",
-        "RENEWAL_VAULT_ADDRESS": "0x..."
+        "AGENTDOMAIN_API_URL": "https://api.agentdomain.app/api/v1"
       }
     }
   }
 }
 ```
 
-For `enable_auto_renew`, `AGENT_PRIVATE_KEY` must be the AgentID NFT owner wallet. Funding can come
-from any wallet, but the RenewalVault contract only accepts auto-renew changes from the owner.
+This remains read-only even if the MCP process receives an ambient API key or
+wallet credential.
+
+## Enabling write tools
+
+Write tools are omitted from discovery and blocked at dispatch unless
+`AGENTDOMAIN_ENABLE_WRITE_TOOLS` is set to the exact value `true`. Unset or exact
+`false` keeps read-only mode. Empty, mixed-case, numeric, whitespace-padded, or
+otherwise malformed values stop startup rather than guessing intent.
 
-## Pricing flags
+The opt-in exposes registration, email sending/configuration, email deletion,
+DNS mutations, SSL reconfiguration, renewal funding/withdrawal/automation, plan
+purchases/scheduling, and registry-visibility changes. Configure the nonsecret
+opt-in in the MCP process environment, then inject only the narrowly scoped API
+or signing credential required by the selected operation through a trusted
+secret-aware launcher. Do not place either credential in MCP client JSON.
 
-Registration pricing includes the live domain price plus the annual AgentDomain
-platform fee. Email setup, SSL certification, DNS orchestration, and AgentID NFT
-mint/orchestration are included in that platform fee.
+## Signing credentials
 
-Optional onchain services charge only when enabled:
+Supply `AGENT_PRIVATE_KEY` only when an enabled operation requires a wallet
+signature. Inject it through a trusted external secret store or secret-aware
+launcher; never paste it into client JSON, source code, shell history, logs, or a
+repository. Use a dedicated wallet with only the authority and funds required
+for the intended operation.
 
-- `registerBasename: false` skips Basename and Basename cost.
-- `registerEns: false` skips ENS and ENS cost.
-- `emailEnabled` is still accepted for old clients but is deprecated and ignored.
-- `emailUsername` customizes the primary inbox local-part; omit it for `agent@domain`.
-- `premiumPlan: "included" | "starter" | "pro" | "enterprise"` selects the per-agent plan at registration.
+Owner-authorized renewal changes require the AgentID NFT owner wallet. Paid plan
+purchases likewise require an authorized wallet with sufficient USDC. An
+agent-scoped API key can call its permitted endpoints but cannot sign wallet
+transactions.
 
-Use `quote_registration` first so the agent sees `platformFeeUsdc`, included
-email/SSL metadata, optional component costs, and `totalUsdc` before it signs
-the x402 payment.
+`AGENTDOMAIN_BUILDER_CODE` is the public ERC-8021 application identifier used to
+attribute supported Base transactions. It accepts 1-32 lowercase letters,
+numbers, or underscores and is needed only by tools that explicitly require it.
 
-For renewals, `get_renewal_status` returns the exact next renewal amount and the
-shortfall to fund before the keeper can reserve and complete the renewal.
+## Pricing options
 
-For Premium Plans, `purchase_service_plan` upgrades coverage through the
-agent's current expiry. Future Premium Plan renewal is charged together with the
-identity renewal quote in RenewalVault.
+Registration pricing includes the live domain price and the AgentDomain platform
+fee. Email setup, SSL certification, DNS orchestration, and AgentID NFT
+orchestration are included unless the API response states otherwise.
 
-Autonomous Premium Plan purchase requires `AGENT_PRIVATE_KEY` for the owner or a
-delegated wallet on Base with enough USDC. An agent-scoped API key can operate
-its own allowed endpoints, but it cannot sign x402 paid purchases by itself.
+Optional settings include:
+
+- `registerBasename: false` to skip Basename
+- `registerEns: false` to skip ENS
+- `emailUsername` to customize the primary inbox local part
+- `premiumPlan: "included" | "starter" | "pro" | "enterprise"` to select a plan
+
+Use `quote_registration` before signing a payment. Treat the returned quote,
+limits, expiry, and renewal amount as authoritative for that request.
 
 ## License
 
-Public package releases are licensed under Apache-2.0. Private AgentDomain
-platform code is not included in this package.
+Published package releases are licensed under Apache-2.0.
+
+## Links
+
+- [MCP guide](https://docs.agentdomain.app/sdk/mcp)
+- [API discovery](https://api.agentdomain.app/api/v1)
+- [Source](https://github.com/0xmdrakib/AgentDomain/tree/main/packages/mcp-server)
+- [Security policy](https://github.com/0xmdrakib/AgentDomain/security/policy)

package/dist/index.d.ts

@@ -14,11 +14,13 @@
  *         "command": "npx",
  *         "args": ["-y", "@agentdomain/mcp-server"],
  *         "env": {
- *           "AGENTDOMAIN_API_URL": "https://agentdomain.app/api/v1",
- *           "AGENT_PRIVATE_KEY": "0x..."
+ *           "AGENTDOMAIN_API_URL": "https://api.agentdomain.app/api/v1"
  *         }
  *       }
  *     }
  *   }
+ *
+ * Inject optional signing credentials through a trusted external secret source,
+ * and only when a signing operation is explicitly enabled.
  */
 export {};