Zetrix MCP Server

Instructions

Implementation Reference

• src/index.ts:1505-1591 (handler)

  MCP tool handler: Validates Zetrix project directory exists, generates advanced contract files using ZetrixContractGenerator.generate(), writes files to disk, returns detailed success summary with architecture overview.
  case "zetrix_contract_generate_advanced": { const options = args as unknown as ContractGenerationOptions; try { const { existsSync } = await import("fs"); const { join } = await import("path"); // If outputDirectory is not specified, assume current directory // User should have already called zetrix_contract_init_dev_environment const outputDir = options.outputDirectory || process.cwd(); // Check if we're in a valid Zetrix project (has package.json with zetrix tools) const packageJsonPath = join(outputDir, 'package.json'); if (!existsSync(packageJsonPath)) { throw new Error( `No Zetrix project found at ${outputDir}.\n\n` + `Please initialize the project first using:\n` + `zetrix_contract_init_dev_environment with contractName: "${options.contractName}"\n\n` + `Then call zetrix_contract_generate_advanced with outputDirectory: "./${options.contractName}"` ); } // Generate contract files const { files, summary, classDiagram } = zetrixContractGenerator.generate(options); // Write files to disk zetrixContractGenerator.writeFiles(files); return { content: [ { type: "text", text: `✅ Successfully generated advanced ${options.contractName} contract! ${summary} Generated contract architecture: ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 📁 ${options.contractName}Interface.js ↳ Contract API definition ↳ Method signatures for main and query functions 📁 ${options.contractName}Lib.js ↳ Reusable utility library ↳ Validation, storage, and math utilities ↳ Can be imported by other contracts 📁 ${options.contractName}Utils.js ↳ Feature-specific modules ↳ Ownership, pausable, whitelist, blacklist ↳ Modular and extensible design 📁 ${options.contractName}.js ↳ Main contract implementation ↳ init(), main(), query() entry points ↳ Business logic and routing ${options.includeTests !== false ? ` 📁 ${options.contractName}Tests.md ↳ Comprehensive test specifications ↳ TEST_INVOKE and TEST_QUERY examples ↳ Security and edge case tests ` : ''} ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Contract Type: ${options.contractType.toUpperCase()} ${options.tokenStandard ? `Token Standard: ${options.tokenStandard}` : ''} Features: ${options.features?.join(", ") || "Basic"} You can now: 1. Review and customize the generated contract files 2. Add your business logic to ${options.contractName}.js 3. Run the test specifications 4. Deploy to Zetrix blockchain 💡 Tip: The modular architecture allows you to: - Extend functionality by adding new utils modules - Reuse the library in other contracts - Test each module independently - Maintain clean separation of concerns`, }, ], }; } catch (error) { const errorMessage = error instanceof Error ? error.message : String(error); throw new Error(`Failed to generate contract: ${errorMessage}`); } }
• src/index.ts:721-754 (schema)

  Input schema definition for the tool, specifying parameters like contractName, contractType, features, tokenStandard, etc., with validation rules.
  inputSchema: { type: "object", properties: { contractName: { type: "string", description: "Name of the main contract (e.g., 'StableCoin', 'NFTMarketplace')", }, contractType: { type: "string", enum: ["token", "nft", "defi", "governance", "marketplace", "custom"], description: "Type of contract to generate", }, features: { type: "array", items: { type: "string", enum: ["pausable", "ownable", "roles", "upgradeable", "whitelist", "blacklist", "timelock", "oracle"], }, description: "Advanced features to include", }, tokenStandard: { type: "string", enum: ["ZTP20", "ZTP721", "ZTP1155"], description: "Token standard (required if contractType is 'token' or 'nft')", }, includeTests: { type: "boolean", description: "Generate comprehensive test specifications (default: true)", }, outputDirectory: { type: "string", description: "Directory to output the contract files (defaults to current directory)", }, },
• src/index.ts:718-756 (registration)

  Tool registration in the MCP tools array, defining name, detailed description emphasizing workflow, and linking to input schema.
  { name: "zetrix_contract_generate_advanced", description: "Generate advanced multi-class Zetrix smart contract with interfaces, libraries, utilities, main contract, and comprehensive test specs. **MANDATORY WORKFLOW: (1) First call zetrix_contract_init_dev_environment with contractName (e.g., 'CertificateContract'). (2) Then call this tool with the SAME contractName and outputDirectory set to './{contractName}'. Calling this tool WITHOUT initializing the project first will result in an error.** Supports complex architectures with inheritance, composition, and modular design.", inputSchema: { type: "object", properties: { contractName: { type: "string", description: "Name of the main contract (e.g., 'StableCoin', 'NFTMarketplace')", }, contractType: { type: "string", enum: ["token", "nft", "defi", "governance", "marketplace", "custom"], description: "Type of contract to generate", }, features: { type: "array", items: { type: "string", enum: ["pausable", "ownable", "roles", "upgradeable", "whitelist", "blacklist", "timelock", "oracle"], }, description: "Advanced features to include", }, tokenStandard: { type: "string", enum: ["ZTP20", "ZTP721", "ZTP1155"], description: "Token standard (required if contractType is 'token' or 'nft')", }, includeTests: { type: "boolean", description: "Generate comprehensive test specifications (default: true)", }, outputDirectory: { type: "string", description: "Directory to output the contract files (defaults to current directory)", }, }, required: ["contractName", "contractType"], },
• src/zetrix-contract-generator.ts:1234-1339 (helper)

  Core helper method implementing contract generation: analyzes options to create class structures, generates modular files (interfaces, libraries, main contract, tests, deployment scripts), produces Mermaid class diagram and summary.
  public generate(options: ContractGenerationOptions): { files: { path: string; content: string; type: string }[]; summary: string; classDiagram: string; } { const { contractName, outputDirectory = "." } = options; // Analyze requirements and generate class structure const classes = this.analyzeAndGenerateClasses(options); // Generate class diagram const classDiagram = this.generateClassDiagram(classes); const files: { path: string; content: string; type: string }[] = []; // Generate interface (optional, for documentation) const interfaceClass = classes.find(c => c.type === "interface"); if (interfaceClass) { files.push({ path: join(outputDirectory, `contracts/interface/I${contractName}.md`), content: `# ${interfaceClass.name} Interface\n\n${classDiagram}`, type: "interface" }); } // Generate libraries const libraries = classes.filter(c => c.type === "library"); for (const lib of libraries) { files.push({ path: join(outputDirectory, `contracts/library/${lib.name}.js`), content: this.generateLibrary(lib.name, lib), type: "library" }); } // Generate main contract (MUST be in contracts/ root, NOT specs/) files.push({ path: join(outputDirectory, `contracts/${contractName}.js`), content: this.generateMainContract(options, classes), type: "contract" }); // Generate tests if (options.includeTests !== false) { files.push({ path: join(outputDirectory, `tests/unit/${contractName}Test.js`), content: this.generateUnitTests(options, classes), type: "test-unit" }); files.push({ path: join(outputDirectory, `tests/integration/${contractName}IntegrationTest.js`), content: this.generateIntegrationTests(options), type: "test-integration" }); } // Generate deployment script files.push({ path: join(outputDirectory, `scripts/deploy-${contractName}.js`), content: this.generateDeploymentScript(options), type: "deployment" }); // Generate class diagram as separate file files.push({ path: join(outputDirectory, `docs/${contractName}-Architecture.md`), content: classDiagram, type: "documentation" }); const summary = `Successfully generated ${contractName} contract architecture! 📊 Class Structure Analysis: - ${classes.length} classes identified - ${classes.filter(c => c.type === "library").length} library modules - ${classes.filter(c => c.type === "interface").length} interface definition - ${classes.filter(c => c.type === "contract").length} main contract 📁 Generated Files (${files.length} total): ${files.map(f => { const emoji = f.type === "interface" ? "📋" : f.type === "library" ? "📚" : f.type === "contract" ? "📜" : f.type === "test-unit" ? "🧪" : f.type === "test-integration" ? "🔗" : f.type === "deployment" ? "🚀" : "📖"; return `${emoji} ${f.path}`; }).join('\n')} ✨ Key Features: - ES5-compatible JavaScript (Zetrix VM ready) - Private methods defined before public methods - Modular architecture with separate libraries - Comprehensive test coverage (unit + integration) - Production-ready deployment scripts - Full class diagram documentation 🔧 Features Implemented: ${options.features?.join(", ") || "Basic functionality"} 📝 Next Steps: 1. Review the class diagram in docs/${contractName}-Architecture.md 2. Customize business logic in contracts/specs/${contractName}.js 3. Run unit tests: npm test tests/unit/${contractName}Test.js 4. Run integration tests: npm test tests/integration/${contractName}IntegrationTest.js 5. Deploy: node scripts/deploy-${contractName}.js --network testnet `; return { files, summary, classDiagram }; }
• src/zetrix-contract-generator.ts:1341-1350 (helper)

  Helper method to write generated contract files to the filesystem, creating directories as needed.
  public writeFiles(files: { path: string; content: string }[]): void { for (const file of files) { const dir = file.path.substring(0, file.path.lastIndexOf("/")); if (dir && !existsSync(dir)) { mkdirSync(dir, { recursive: true }); } writeFileSync(file.path, file.content, "utf-8"); } } }