@agentdomain/mcp-server 0.5.1 → 0.7.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

@@ -4,6 +4,9 @@
 
 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?
@@ -14,24 +17,26 @@ Lets any MCP-compatible LLM client (Claude Desktop, ChatGPT desktop apps, custom
 - `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
-- `delete_agent_email` - permanently delete one inbox/outbox message
 - `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 record; apex routing records activate external hosting
+- `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
-- `reconfigure_ssl` - rebuild Cloudflare SaaS SSL when AgentDomain-managed hosting is active
+- `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
-- `schedule_service_plan_renewal` - choose the exact next-renewal plan and Enterprise tier
 
 ## Install
 
@@ -53,6 +58,7 @@ npm install -g @agentdomain/mcp-server
         "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..."
       }
     }
@@ -63,6 +69,12 @@ npm install -g @agentdomain/mcp-server
 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.
 
+`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.
+
 ## Pricing flags
 
 Registration pricing includes the live domain price plus the annual AgentDomain

package/dist/index.d.ts

@@ -15,7 +15,8 @@
  *         "args": ["-y", "@agentdomain/mcp-server"],
  *         "env": {
  *           "AGENTDOMAIN_API_URL": "https://agentdomain.app/api/v1",
- *           "AGENT_PRIVATE_KEY": "0x..."
+ *           "AGENT_PRIVATE_KEY": "0x...",
+ *           "AGENTDOMAIN_BUILDER_CODE": "your_builder_code"
  *         }
  *       }
  *     }

package/dist/index.js

@@ -15,7 +15,8 @@
  *         "args": ["-y", "@agentdomain/mcp-server"],
  *         "env": {
  *           "AGENTDOMAIN_API_URL": "https://agentdomain.app/api/v1",
- *           "AGENT_PRIVATE_KEY": "0x..."
+ *           "AGENT_PRIVATE_KEY": "0x...",
+ *           "AGENTDOMAIN_BUILDER_CODE": "your_builder_code"
  *         }
  *       }
  *     }
@@ -25,7 +26,8 @@ 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 { z } from 'zod';
-import { AgentDomain } from '@agentdomain/sdk';
+import { AgentDomain, validateBuilderCode } from '@agentdomain/sdk';
+import { DNS_RECORD_TYPES, dnsRecordSchema, dnsRecordObjectSchema, } from '@agentdomain/shared';
 import { AGENTDOMAIN_API_BASE_URL, SERVICE_PLAN_KEYS, SUPPORTED_FRAMEWORKS, SUPPORTED_TLDS, } from '@agentdomain/shared/constants';
 import { createPublicClient, createWalletClient, http } from 'viem';
 import { privateKeyToAccount } from 'viem/accounts';
@@ -34,6 +36,7 @@ const API_URL = process.env.AGENTDOMAIN_API_URL ?? AGENTDOMAIN_API_BASE_URL;
 const NETWORK = (process.env.AGENTDOMAIN_NETWORK ?? 'base');
 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;
 function getClient() {
     const config = {
@@ -41,6 +44,7 @@ function getClient() {
         apiKey: AGENTDOMAIN_API_KEY,
         network: NETWORK,
         renewalVaultAddress: RENEWAL_VAULT_ADDRESS,
+        builderCode: AGENTDOMAIN_BUILDER_CODE,
     };
     if (AGENT_PRIVATE_KEY) {
         const account = privateKeyToAccount(AGENT_PRIVATE_KEY);
@@ -335,6 +339,15 @@ const TOOLS = [
             required: ['agentId', 'messageId'],
         },
     },
+    {
+        name: 'get_dns_capabilities',
+        description: 'Get the machine-readable Spaceship DNS types, fields, limits, and safety warnings supported by AgentDomain.',
+        inputSchema: {
+            type: 'object',
+            properties: { agentId: { type: 'string', description: 'AgentDomain agent ID (UUID)' } },
+            required: ['agentId'],
+        },
+    },
     {
         name: 'list_dns_records',
         description: 'List Spaceship-backed DNS records for an agent domain.',
@@ -353,13 +366,14 @@ const TOOLS = [
             type: 'object',
             properties: {
                 agentId: { type: 'string' },
-                type: { type: 'string', enum: ['A', 'AAAA', 'ALIAS', 'CNAME', 'MX', 'TXT', 'NS', 'SRV'] },
+                type: { type: 'string', enum: DNS_RECORD_TYPES },
                 name: { type: 'string' },
-                value: { type: 'string' },
+                value: { type: 'string', description: 'Legacy format; structured data is preferred' },
+                data: { type: 'object', description: 'Type-specific structured DNS record data' },
                 ttl: { type: 'number', default: 3600 },
                 priority: { type: 'number' },
             },
-            required: ['agentId', 'type', 'name', 'value'],
+            required: ['agentId', 'type', 'name'],
         },
     },
     {
@@ -370,9 +384,10 @@ const TOOLS = [
             properties: {
                 agentId: { type: 'string' },
                 recordId: { type: 'string' },
-                type: { type: 'string', enum: ['A', 'AAAA', 'ALIAS', 'CNAME', 'MX', 'TXT', 'NS', 'SRV'] },
+                type: { type: 'string', enum: DNS_RECORD_TYPES },
                 name: { type: 'string' },
                 value: { type: 'string' },
+                data: { type: 'object', description: 'Type-specific structured DNS record data' },
                 ttl: { type: 'number' },
                 priority: { type: 'number' },
             },
@@ -391,6 +406,48 @@ const TOOLS = [
             required: ['agentId', 'recordId'],
         },
     },
+    {
+        name: 'change_dns_records',
+        description: 'Preview or apply an atomic DNS merge/replace batch. Apply requires the baseRevision returned by preview.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                agentId: { type: 'string' },
+                records: { type: 'array', maxItems: 200, items: { type: 'object' } },
+                mode: { type: 'string', enum: ['merge', 'replace'], default: 'merge' },
+                dryRun: { type: 'boolean', default: true },
+                baseRevision: { type: 'string', description: 'Required when dryRun is false' },
+            },
+            required: ['agentId', 'records'],
+        },
+    },
+    {
+        name: 'import_dns_zone',
+        description: 'Preview or apply a BIND zone import. System-managed records remain protected.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                agentId: { type: 'string' },
+                zoneFile: { type: 'string', description: 'BIND zone text, maximum 256 KiB' },
+                mode: { type: 'string', enum: ['merge', 'replace'], default: 'merge' },
+                dryRun: { type: 'boolean', default: true },
+                baseRevision: { type: 'string', description: 'Required when dryRun is false' },
+            },
+            required: ['agentId', 'zoneFile'],
+        },
+    },
+    {
+        name: 'export_dns_zone',
+        description: 'Export user-managed or permitted complete DNS state as a standard BIND zone file.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                agentId: { type: 'string' },
+                scope: { type: 'string', enum: ['user', 'all'], default: 'user' },
+            },
+            required: ['agentId'],
+        },
+    },
     {
         name: 'reconfigure_ssl',
         description: 'Rebuild the Cloudflare SaaS SSL hostname and sync required DNS validation records.',
@@ -629,7 +686,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
             }
             case 'delete_agent_email': {
-                const a = z.object({ agentId: z.string().uuid(), messageId: z.string().uuid() }).parse(args);
+                const a = z
+                    .object({ agentId: z.string().uuid(), messageId: z.string().uuid() })
+                    .parse(args);
                 const result = await client.deleteEmailMessage(a.agentId, a.messageId);
                 return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
             }
@@ -686,6 +745,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 const result = await client.deleteEmailAlias(a.agentId, a.emailAddress);
                 return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
             }
+            case 'get_dns_capabilities': {
+                const a = z.object({ agentId: z.string() }).parse(args);
+                const result = await client.getDnsCapabilities(a.agentId);
+                return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+            }
             case 'list_dns_records': {
                 const a = z.object({ agentId: z.string() }).parse(args);
                 const result = await client.listDnsRecords(a.agentId);
@@ -695,20 +759,16 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 const a = z
                     .object({
                     agentId: z.string(),
-                    type: z.enum(['A', 'AAAA', 'ALIAS', 'CNAME', 'MX', 'TXT', 'NS', 'SRV']),
+                    type: z.enum(DNS_RECORD_TYPES),
                     name: z.string(),
-                    value: z.string(),
+                    value: z.string().optional(),
+                    data: z.record(z.unknown()).optional(),
                     ttl: z.number().default(3600),
                     priority: z.number().optional(),
                 })
                     .parse(args);
-                const result = await client.createDnsRecord(a.agentId, {
-                    type: a.type,
-                    name: a.name,
-                    value: a.value,
-                    ttl: a.ttl,
-                    priority: a.priority,
-                });
+                const { agentId, ...record } = a;
+                const result = await client.createDnsRecord(agentId, dnsRecordSchema.parse(record));
                 return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
             }
             case 'update_dns_record': {
@@ -716,15 +776,16 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     .object({
                     agentId: z.string(),
                     recordId: z.string(),
-                    type: z.enum(['A', 'AAAA', 'ALIAS', 'CNAME', 'MX', 'TXT', 'NS', 'SRV']).optional(),
+                    type: z.enum(DNS_RECORD_TYPES).optional(),
                     name: z.string().optional(),
                     value: z.string().optional(),
+                    data: z.record(z.unknown()).optional(),
                     ttl: z.number().optional(),
                     priority: z.number().optional(),
                 })
                     .parse(args);
                 const { agentId, recordId, ...record } = a;
-                const result = await client.updateDnsRecord(agentId, recordId, record);
+                const result = await client.updateDnsRecord(agentId, recordId, dnsRecordObjectSchema.partial().parse(record));
                 return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
             }
             case 'delete_dns_record': {
@@ -732,6 +793,43 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 const result = await client.deleteDnsRecord(a.agentId, a.recordId);
                 return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
             }
+            case 'change_dns_records': {
+                const a = z
+                    .object({
+                    agentId: z.string(),
+                    records: z.array(dnsRecordSchema).min(1).max(200),
+                    mode: z.enum(['merge', 'replace']).default('merge'),
+                    dryRun: z.boolean().default(true),
+                    baseRevision: z.string().length(64).optional(),
+                })
+                    .parse(args);
+                const result = a.dryRun
+                    ? await client.previewDnsBatch(a.agentId, a.records, a.mode)
+                    : await client.applyDnsBatch(a.agentId, a.records, requireDnsRevision(a.baseRevision), a.mode);
+                return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+            }
+            case 'import_dns_zone': {
+                const a = z
+                    .object({
+                    agentId: z.string(),
+                    zoneFile: z.string().min(1).max(262_144),
+                    mode: z.enum(['merge', 'replace']).default('merge'),
+                    dryRun: z.boolean().default(true),
+                    baseRevision: z.string().length(64).optional(),
+                })
+                    .parse(args);
+                const result = a.dryRun
+                    ? await client.previewDnsImport(a.agentId, a.zoneFile, a.mode)
+                    : await client.applyDnsImport(a.agentId, a.zoneFile, requireDnsRevision(a.baseRevision), a.mode);
+                return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+            }
+            case 'export_dns_zone': {
+                const a = z
+                    .object({ agentId: z.string(), scope: z.enum(['user', 'all']).default('user') })
+                    .parse(args);
+                const result = await client.exportDnsZone(a.agentId, a.scope);
+                return { content: [{ type: 'text', text: result }] };
+            }
             case 'reconfigure_ssl': {
                 const a = z.object({ agentId: z.string() }).parse(args);
                 const result = await client.reconfigureSsl(a.agentId);
@@ -743,6 +841,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
             }
             case 'withdraw_renewal_vault': {
+                requireDirectBaseWriteBuilderCode('withdraw_renewal_vault');
                 const a = z.object({ agentId: z.string(), amountUsdc: z.string() }).parse(args);
                 const result = await client.withdrawFromVault(a.agentId, a.amountUsdc);
                 return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
@@ -821,8 +920,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                         ],
                     };
                 }
+                requireDirectBaseWriteBuilderCode('enable_auto_renew');
                 const a = z.object({ agentId: z.string() }).parse(args);
-                const result = await client.setAutoRenew(a.agentId, true);
+                const result = await client.setAutoRenew(a.agentId, true, { waitForReceipt: true });
                 return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
             }
             default:
@@ -842,6 +942,22 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 // ----------------------------------------------------------------------
 // MAIN
 // ----------------------------------------------------------------------
+function requireDnsRevision(value) {
+    if (!value)
+        throw new Error('Apply requires baseRevision from a fresh DNS dry-run preview.');
+    return value;
+}
+function requireDirectBaseWriteBuilderCode(toolName) {
+    if (!AGENTDOMAIN_BUILDER_CODE) {
+        throw new Error(`${toolName} requires AGENTDOMAIN_BUILDER_CODE so its direct Base transaction includes ERC-8021 attribution.`);
+    }
+    try {
+        return validateBuilderCode(AGENTDOMAIN_BUILDER_CODE);
+    }
+    catch (error) {
+        throw new Error(`AGENTDOMAIN_BUILDER_CODE is invalid: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentdomain/mcp-server",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "description": "MCP server exposing AgentDomain registration and management tools to any LLM",
   "license": "Apache-2.0",
   "repository": "https://github.com/0xmdrakib/AgentDomain.git",
@@ -15,6 +15,8 @@
   "files": [
     "dist",
     "README.md",
+    "LICENSE",
+    "NOTICE",
     "package.json"
   ],
   "publishConfig": {
@@ -24,8 +26,8 @@
     "@modelcontextprotocol/sdk": "^1.0.4",
     "viem": "^2.55.2",
     "zod": "^3.24.1",
-    "@agentdomain/sdk": "^0.5.1",
-    "@agentdomain/shared": "^0.5.1"
+    "@agentdomain/sdk": "^0.7.0",
+    "@agentdomain/shared": "^0.7.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.5",
@@ -36,6 +38,7 @@
     "build": "tsc",
     "dev": "tsx watch src/index.ts",
     "start": "node dist/index.js",
+    "test": "pnpm --filter @agentdomain/sdk build && pnpm build && node --test test/*.test.mjs",
     "typecheck": "tsc --noEmit",
     "lint": "echo \"no lint\""
   }