@agentdomain/mcp-server 0.7.0 → 0.8.0

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,56 +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",
-        "AGENTDOMAIN_BUILDER_CODE": "your_builder_code",
-        "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.
 
-`AGENTDOMAIN_BUILDER_CODE` is the public ERC-8021 app identifier used to attribute direct Base
-transactions created through MCP. It must contain 1-32 lowercase letters, numbers, or underscores.
-It is required only by `enable_auto_renew` and `withdraw_renewal_vault`; the server validates it when
-one of those tools is called, so read-only, API-managed, and x402 payment tools continue to work
-without it. x402 v2 payments use AgentDomain's resource-server attribution instead.
+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.
 
-## Pricing flags
+## Signing credentials
 
-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.
+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.
 
-Optional onchain services charge only when enabled:
+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.
 
-- `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.
+`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.
 
-Use `quote_registration` first so the agent sees `platformFeeUsdc`, included
-email/SSL metadata, optional component costs, and `totalUsdc` before it signs
-the x402 payment.
+## Pricing options
 
-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.
+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.
 
-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.
+Optional settings include:
 
-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.
+- `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,12 +14,13 @@
  *         "command": "npx",
  *         "args": ["-y", "@agentdomain/mcp-server"],
  *         "env": {
- *           "AGENTDOMAIN_API_URL": "https://agentdomain.app/api/v1",
- *           "AGENT_PRIVATE_KEY": "0x...",
- *           "AGENTDOMAIN_BUILDER_CODE": "your_builder_code"
+ *           "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 {};

package/dist/index.js

@@ -14,17 +14,18 @@
  *         "command": "npx",
  *         "args": ["-y", "@agentdomain/mcp-server"],
  *         "env": {
- *           "AGENTDOMAIN_API_URL": "https://agentdomain.app/api/v1",
- *           "AGENT_PRIVATE_KEY": "0x...",
- *           "AGENTDOMAIN_BUILDER_CODE": "your_builder_code"
+ *           "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.
  */
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
 import { z } from 'zod';
 import { AgentDomain, validateBuilderCode } from '@agentdomain/sdk';
 import { DNS_RECORD_TYPES, dnsRecordSchema, dnsRecordObjectSchema, } from '@agentdomain/shared';
@@ -38,6 +39,8 @@ const AGENT_PRIVATE_KEY = process.env.AGENT_PRIVATE_KEY;
 const AGENTDOMAIN_API_KEY = process.env.AGENTDOMAIN_API_KEY;
 const AGENTDOMAIN_BUILDER_CODE = process.env.AGENTDOMAIN_BUILDER_CODE;
 const RENEWAL_VAULT_ADDRESS = process.env.RENEWAL_VAULT_ADDRESS;
+const WRITE_TOOLS_ENV = 'AGENTDOMAIN_ENABLE_WRITE_TOOLS';
+const WRITE_TOOLS_ENABLED = parseWriteToolsEnabled(process.env[WRITE_TOOLS_ENV]);
 function getClient() {
     const config = {
         apiUrl: API_URL,
@@ -61,7 +64,7 @@ const server = new Server({ name: 'agentdomain-mcp', version: '0.2.1' }, { capab
 // ----------------------------------------------------------------------
 // TOOL DEFINITIONS
 // ----------------------------------------------------------------------
-const TOOLS = [
+const TOOL_DEFINITIONS = [
     {
         name: 'check_domain_availability',
         description: 'Check whether an agent domain (name + tld) is available for registration. Returns availability status and pricing.',
@@ -341,7 +344,7 @@ const TOOLS = [
     },
     {
         name: 'get_dns_capabilities',
-        description: 'Get the machine-readable Spaceship DNS types, fields, limits, and safety warnings supported by AgentDomain.',
+        description: 'Get the machine-readable DNS types, fields, limits, and safety warnings supported by AgentDomain.',
         inputSchema: {
             type: 'object',
             properties: { agentId: { type: 'string', description: 'AgentDomain agent ID (UUID)' } },
@@ -350,7 +353,7 @@ const TOOLS = [
     },
     {
         name: 'list_dns_records',
-        description: 'List Spaceship-backed DNS records for an agent domain.',
+        description: 'List DNS records for an agent domain.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -361,7 +364,7 @@ const TOOLS = [
     },
     {
         name: 'create_dns_record',
-        description: 'Create a user-managed DNS record and sync the full DNS state to Spaceship.',
+        description: 'Create a user-managed DNS record and apply the resulting DNS state.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -378,7 +381,7 @@ const TOOLS = [
     },
     {
         name: 'update_dns_record',
-        description: 'Update a user-managed DNS record and sync the DNS state to Spaceship.',
+        description: 'Update a user-managed DNS record and apply the resulting DNS state.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -396,7 +399,7 @@ const TOOLS = [
     },
     {
         name: 'delete_dns_record',
-        description: 'Delete a user-managed DNS record and sync the DNS state to Spaceship.',
+        description: 'Delete a user-managed DNS record and apply the resulting DNS state.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -450,7 +453,7 @@ const TOOLS = [
     },
     {
         name: 'reconfigure_ssl',
-        description: 'Rebuild the Cloudflare SaaS SSL hostname and sync required DNS validation records.',
+        description: 'Rebuild the managed SSL hostname and sync required DNS validation records.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -564,16 +567,59 @@ const TOOLS = [
         },
     },
 ];
+const READ_ONLY_TOOL_NAMES = new Set([
+    'check_domain_availability',
+    'quote_registration',
+    'lookup_agent',
+    'get_agent',
+    'search_agents',
+    'get_agent_email_usage',
+    'list_agent_email',
+    'get_dns_capabilities',
+    'list_dns_records',
+    'export_dns_zone',
+    'get_renewal_status',
+    'get_service_plan',
+]);
+const ADDITIVE_WRITE_TOOL_NAMES = new Set([
+    'send_agent_email',
+    'send_agent_email_batch',
+    'create_email_alias',
+    'create_dns_record',
+]);
+function annotationsForTool(name) {
+    const readOnly = READ_ONLY_TOOL_NAMES.has(name);
+    return {
+        readOnlyHint: readOnly,
+        destructiveHint: readOnly ? false : !ADDITIVE_WRITE_TOOL_NAMES.has(name),
+        idempotentHint: readOnly,
+        openWorldHint: true,
+    };
+}
+const TOOLS = TOOL_DEFINITIONS.map((tool) => ({
+    ...tool,
+    annotations: annotationsForTool(tool.name),
+}));
+const ENABLED_TOOLS = WRITE_TOOLS_ENABLED
+    ? TOOLS
+    : TOOLS.filter((tool) => READ_ONLY_TOOL_NAMES.has(tool.name));
+const ENABLED_TOOL_NAMES = new Set(ENABLED_TOOLS.map((tool) => tool.name));
 // ----------------------------------------------------------------------
 // HANDLERS
 // ----------------------------------------------------------------------
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
-    tools: TOOLS,
+    tools: ENABLED_TOOLS,
 }));
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
-    const client = getClient();
     try {
+        if (!ENABLED_TOOL_NAMES.has(name)) {
+            return {
+                isError: true,
+                content: [{ type: 'text', text: `Unknown or disabled tool: ${name}` }],
+            };
+        }
+        const client = getClient();
         switch (name) {
             case 'check_domain_availability': {
                 const a = z
@@ -947,6 +993,13 @@ function requireDnsRevision(value) {
         throw new Error('Apply requires baseRevision from a fresh DNS dry-run preview.');
     return value;
 }
+function parseWriteToolsEnabled(value) {
+    if (value === undefined || value === 'false')
+        return false;
+    if (value === 'true')
+        return true;
+    throw new Error(`${WRITE_TOOLS_ENV} must be exactly "true" or "false" when set.`);
+}
 function requireDirectBaseWriteBuilderCode(toolName) {
     if (!AGENTDOMAIN_BUILDER_CODE) {
         throw new Error(`${toolName} requires AGENTDOMAIN_BUILDER_CODE so its direct Base transaction includes ERC-8021 attribution.`);

package/package.json

@@ -1,12 +1,30 @@
 {
   "name": "@agentdomain/mcp-server",
-  "version": "0.7.0",
-  "description": "MCP server exposing AgentDomain registration and management tools to any LLM",
+  "version": "0.8.0",
+  "description": "Secure-by-default MCP server for AgentDomain identity, DNS, email, and renewal workflows",
+  "keywords": [
+    "agentdomain",
+    "ai-agents",
+    "mcp",
+    "model-context-protocol",
+    "identity",
+    "x402",
+    "base"
+  ],
   "license": "Apache-2.0",
-  "repository": "https://github.com/0xmdrakib/AgentDomain.git",
-  "homepage": "https://agentdomain.app/docs",
-  "bugs": "https://github.com/0xmdrakib/AgentDomain/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/0xmdrakib/AgentDomain.git",
+    "directory": "packages/mcp-server"
+  },
+  "homepage": "https://docs.agentdomain.app/sdk/mcp",
+  "bugs": {
+    "url": "https://github.com/0xmdrakib/AgentDomain/issues"
+  },
   "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "bin": {
@@ -26,8 +44,8 @@
     "@modelcontextprotocol/sdk": "^1.0.4",
     "viem": "^2.55.2",
     "zod": "^3.24.1",
-    "@agentdomain/sdk": "^0.7.0",
-    "@agentdomain/shared": "^0.7.0"
+    "@agentdomain/sdk": "^0.8.0",
+    "@agentdomain/shared": "^0.8.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.5",