### Installation & Setup

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/README.md

Commands to clone the repository, install dependencies, and start the server in development mode.

```bash
# Clone repository
git clone https://github.com/davibauer/coti-mcp.git
cd coti-mcp

# Install dependencies
npm install

# Development mode
npm run dev
```

--------------------------------

### Example ToolAnnotation: CREATE_ACCOUNT

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/types.md

Example of a tool registration using ToolAnnotations.

```typescript
export const CREATE_ACCOUNT: ToolAnnotations = {
  title: "Create Account",
  name: "create_account",
  description: "Create a new COTI account…",
  inputSchema: {
    network: z.enum(['testnet', 'mainnet']),
  }
};
```

--------------------------------

### Network Selection Example

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/configuration.md

TypeScript examples demonstrating how to select testnet or mainnet for blockchain operations.

```typescript
// Testnet operation
await performGetNativeBalance(accountAddress, 'testnet');

// Mainnet operation
await performGetNativeBalance(accountAddress, 'mainnet');
```

--------------------------------

### Network Unavailable Example

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/errors.md

Example demonstrating a network error during an operation, such as getting a native balance.

```typescript
try {
  // Network offline or slow
  await performGetNativeBalance(address, 'testnet');
} catch (error) {
  console.error(error.message);
  // Output: Failed to get native balance: Network error...
```

--------------------------------

### Installation

Source: https://github.com/davibauer/coti-mcp/blob/main/README.md

Steps to clone the repository, navigate into the directory, install dependencies, and run the development server.

```bash
git clone https://github.com/davibauer/coti-mcp.git
cd coti-mcp
npm install
npm run dev
```

--------------------------------

### Deployment Failure Example

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/errors.md

Example of a deployment failure due to insufficient gas, with error handling.

```typescript
try {
  await performDeployPrivateERC20Contract(
    key, 'Token', 'TKN', 6, 'testnet', '1000' // Gas limit too low
  );
} catch (error) {
  console.error(error.message);
  // Output: Failed to deploy private ERC20 contract: ...
}
```

--------------------------------

### Switch Network Example

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/api-reference/account-management.md

Example usage of the performSwitchNetwork function.

```typescript
const result = await performSwitchNetwork('mainnet', 'testnet');
// Returns network switch information
```

--------------------------------

### Example MCP Client Configuration

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/configuration.md

An example JSON configuration for an MCP client, specifying server details and debug settings.

```json
{
  "mcpServers": {
    "coti-mcp": {
      "command": "node",
      "args": ["path/to/build/index.js"],
      "env": {},
      "config": {
        "debug": true
      }
    }
  }
}
```

--------------------------------

### Gas Limit Customization Example

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/configuration.md

TypeScript example showing how to set a custom gas limit for deploying a private ERC20 contract.

```typescript
const result = await performDeployPrivateERC20Contract(
  privateKey,
  'My Token',
  'MTK',
  6,
  'testnet',
  '1000000' // Custom gas limit
);
```

--------------------------------

### Get Transaction Logs Example

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/api-reference/transaction-operations.md

Example usage of the performGetTransactionLogs function.

```typescript
const logs = await performGetTransactionLogs(
  transactionHash,
  'testnet'
);
// Returns array of TransactionLog objects with topics and data
```

--------------------------------

### Compile and Deploy Contract Example

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/api-reference/compiler-deployment.md

Example of compiling and deploying a Solidity contract with constructor arguments and gas limit using performCompileAndDeployContract.

```typescript
const solidityCode = `
  pragma solidity ^0.8.20;
  
  contract MyToken {
    string public tokenName;
    
    constructor(string memory _name) {
      tokenName = _name;
    }
  }
`;

const result = await performCompileAndDeployContract(
  privateKey,
  aesKey,
  solidityCode,
  'MyToken',
  'testnet',
  ['My Token'], // Constructor args
  '500000'       // Gas limit
);
// Returns: { contractAddress: '0xABC...', transactionHash: '0x123...', ... }
```

--------------------------------

### Get Native Balance Example

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/api-reference/native-tokens.md

Example usage of the performGetNativeBalance function.

```typescript
const result = await performGetNativeBalance(
  '0xAbC123...',
  'testnet'
);
// Returns:
// {
//   account: '0xAbC123...',
//   balanceWei: '1000000000000000000',
//   balanceCoti: '1.0',
//   formattedText: 'Account: 0xAbC123...\nBalance: 1000000000000000000 wei (1.0 COTI)'
// }
```

--------------------------------

### Example Usage of Get ERC20 Allowance

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/api-reference/erc20-operations.md

Example of how to use the performGetERC20Allowance function to retrieve an ERC20 allowance.

```typescript
const allowance = await performGetERC20Allowance(
  ownerAddress,
  spenderAddress,
  tokenAddress,
  'testnet'
);
```

--------------------------------

### Compile Contract Example

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/api-reference/compiler-deployment.md

Example of compiling a Solidity contract using the performCompileContract function.

```typescript
const solidityCode = `
  pragma solidity ^0.8.20;
  
  contract MyToken {
    string public name = "My Token";
    uint256 public totalSupply = 1000000;
  }
`;

const result = await performCompileContract(
  solidityCode,
  'MyToken'
);
// Returns: { contractName: 'MyToken', abi: [...], bytecode: '0x...', ... }
```

--------------------------------

### Invalid Network Example

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/errors.md

Example showing how an invalid network parameter is caught by input validation.

```typescript
try {
  await performGetNativeBalance(address, 'staging'); // Invalid
} catch (error) {
  // Caught by input validation
  console.error('Invalid network parameter');
}
```

--------------------------------

### Local Configuration Example

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/README.md

Example JSON configuration for setting up MCP servers locally.

```json
{
  "mcpServers": {
    "coti-mcp": {
      "command": "node",
      "args": ["path/to/build/index.js"],
      "config": {
        "debug": false
      }
    }
  }
}
```

--------------------------------

### Integration Example

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/api-reference/compiler-deployment.md

Demonstrates a step-by-step process for compiling, deploying, and interacting with a smart contract using the COTI MCP.

```typescript
// Step 1: Compile contract
const compiled = await performCompileContract(
  solidityCode,
  'MyCustomToken'
);

// Step 2: Deploy contract
const deployed = await performCompileAndDeployContract(
  privateKey,
  aesKey,
  solidityCode,
  'MyCustomToken',
  'testnet',
  ['My Custom Token', 'MCT', 18], // Constructor args
  '1000000'
);

// Step 3: Use deployed contract
const callResult = await performCallContractFunction(
  privateKey,
  aesKey,
  deployed.contractAddress,
  'balanceOf',
  [accountAddress],
  'testnet',
  compiled.abi
);

// Step 4: Check deployment status
const status = await performGetTransactionStatus(
  deployed.transactionHash,
  'testnet'
);
```

--------------------------------

### Private Key Schema Example

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/types.md

Format for private keys.

```regex
0x[0-9a-fA-F]{64}
```

--------------------------------

### Deploy and Mint ERC20 Token Example

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/README.md

A step-by-step example demonstrating how to deploy an ERC20 token contract and mint tokens using the COTI MCP.

```typescript
// 1. Create account
const account = await performCreateAccount('testnet');

// 2. Fund account (testnet faucet)
// ... (offline step)

// 3. Generate AES key
const aes = await performGenerateAesKey(
  account.privateKey, 'testnet'
);

// 4. Deploy token contract
const token = await performDeployPrivateERC20Contract(
  account.privateKey,
  'My Token',      // name
  'MTK',           // symbol
  6,               // decimals
  'testnet'
);

// 5. Mint tokens
const mint = await performMintPrivateERC20Token(
  account.privateKey,
  aes.aesKey,
  token.contractAddress,
  account.address,
  '1000000000000000000', // 1 token
  'testnet'
);
```

--------------------------------

### Get Transaction Status Example

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/api-reference/transaction-operations.md

Example usage of the performGetTransactionStatus function.

```typescript
const result = await performGetTransactionStatus(
  '0xabc123...',
  'testnet'
);
// Returns detailed transaction information including status
```

--------------------------------

### Transaction Monitoring Example

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/api-reference/native-tokens.md

Example demonstrating how to monitor the status of a native token transfer.

```typescript
// 1. Get transaction hash from transfer result
const { transactionHash } = await performTransferNative(...);

// 2. Monitor transaction status
const status = await performGetTransactionStatus(
  transactionHash,
  'testnet'
);

// 3. Check for success
if (status.status === 'Success') {
  console.log('Transfer confirmed!');
}
```

--------------------------------

### Deploy Private Message Contract Example

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/api-reference/private-messages.md

Example of how to deploy a private message contract.

```typescript
const result = await performDeployPrivateMessageContract(
  privateKey,
  aesKey,
  'testnet'
);
// Returns contract address for message operations
```

--------------------------------

### Sign Message Example

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/api-reference/account-management.md

Example of signing a message using the performSignMessage function.

```typescript
const result = await performSignMessage(privateKey, 'Hello', 'testnet');
// Signs the message with the private key
// Returns signature and signer address
```

--------------------------------

### Deploy Private ERC20 Contract Example

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/api-reference/erc20-operations.md

Example usage of the performDeployPrivateERC20Contract function.

```typescript
const result = await performDeployPrivateERC20Contract(
  privateKey,
  'My Private Token',
  'MPT',
  6,
  'testnet'
);
// Returns:
// {
//   contractAddress: '0xABC...',
//   transactionHash: '0x123...',
//   name: 'My Private Token',
//   symbol: 'MPT',
//   decimals: 6,
//   deployer: '0xDEF...',
//   ...
// }
```

--------------------------------

### Verify Signature Example

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/api-reference/account-management.md

Example of verifying a signature using the performVerifySignature function.

```typescript
const isValid = await performVerifySignature(message, signature, address, 'testnet');
```

--------------------------------

### Encrypt Message Example

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/api-reference/account-management.md

Example of encrypting a message using the performEncryptMessage function.

```typescript
const result = await performEncryptMessage(aesKey, 'Secret message');
// Uses buildStringInputText or similar COTI SDK functions
// Returns ciphertext and r factor needed for decryption
```

--------------------------------

### Development Environment Variable Example

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/configuration.md

Bash command to set the NODE_ENV variable for development.

```bash
NODE_ENV=development npm run dev
```

--------------------------------

### Get Private Message Count Example

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/api-reference/private-messages.md

Example of how to retrieve the number of messages from a specific sender.

```typescript
const count = await performGetPrivateMessageCount(
  contractAddress,
  contractAbi,
  senderAddress,
  recipientAddress,
  'testnet'
);
// Returns: 5 (5 messages from this sender)
```

--------------------------------

### Get Private Message Senders Example

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/api-reference/private-messages.md

Example of how to retrieve a list of all addresses that have sent messages to the caller.

```typescript
const senders = await performGetPrivateMessageSenders(
  contractAddress,
  contractAbi,
  recipientAddress,
  'testnet'
);
// Returns: ['0xabc...', '0xdef...', '0x123...']
```

--------------------------------

### Mint Private ERC20 Token Example

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/api-reference/erc20-operations.md

Example usage of the performMintPrivateERC20Token function.

```typescript
const result = await performMintPrivateERC20Token(
  privateKey,
  aesKey,
  tokenAddress,
  recipientAddress,
  '1000000000000000000', // 1 token with 18 decimals
  'testnet'
);
```

--------------------------------

### Address Schema Example

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/types.md

Format for blockchain addresses.

```regex
0x[0-9a-fA-F]{40}
```

--------------------------------

### Package.json Configuration

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/configuration.md

Example package.json file for the COTI MCP project, including name, version, scripts, and module settings.

```json
{
  "name": "@davibaue/coti-mcp",
  "version": "0.0.18",
  "description": "MCP server for COTI blockchain",
  "main": "index.js",
  "module": "./index.ts",
  "type": "module",
  "scripts": {
    "dev": "npx @smithery/cli dev"
  }
}
```

--------------------------------

### AES Key Not Generated Example

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/errors.md

Shows how to handle the 'Failed to generate AES key' error, typically due to an unfunded account.

```typescript
try {
  await performGenerateAesKey(privateKey, 'testnet');
} catch (error) {
  console.error(error.message);
  // Output: Failed to generate AES key: Make sure the account is funded.
}
```

--------------------------------

### Call Contract Function Example

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/api-reference/transaction-operations.md

Examples demonstrating how to call read-only and state-changing functions on a smart contract.

```typescript
// Call a read function
const result = await performCallContractFunction(
  privateKey,
  aesKey,
  tokenAddress,
  'balanceOf',
  [accountAddress], // args as strings
  'testnet'
);
// Returns: { functionArgs: [accountAddress], result: 1000n, ... }
```

```typescript
// Call a write function with gas limit
const result = await performCallContractFunction(
  privateKey,
  aesKey,
  contractAddress,
  'mint',
  [recipientAddress, '1000000000000000000'],
  'testnet',
  customAbi,
  '100000'
);
```

--------------------------------

### maskSensitiveString Example

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/types.md

Example usage of the maskSensitiveString function.

```typescript
maskSensitiveString('0x123456789abcdef') 
// Returns: '0x12...cdef'
```

--------------------------------

### Amount Conversion Example

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/types.md

TypeScript code for converting between COTI and wei amounts.

```typescript
const cotiAmount = parseFloat(amountWei) / 1e18; // Convert to COTI
const weiAmount = (cotiAmount * 1e18).toString(); // Convert to wei
```

--------------------------------

### Transfer Native Example

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/api-reference/native-tokens.md

Example usage of the performTransferNative function.

```typescript
const result = await performTransferNative(
  privateKey,
  '0xDEF456...',
  '1000000000000000000', // 1 COTI
  'testnet'
);
// Returns:
// {
//   transactionHash: '0xabc...',
//   token: 'COTI',
//   amountWei: '1000000000000000000',
//   recipient: '0xDEF456...',
//   sender: '0xABC123...',
//   network: 'testnet',
//   formattedText: 'Transaction successful!\nToken: COTI\nNetwork: testnet\n...'
// }
```

--------------------------------

### Send Private Message Example

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/README.md

An example illustrating how to deploy a private message contract, send an encrypted message, and then read it.

```typescript
// 1. Deploy message contract
const msgContract = await performDeployPrivateMessageContract(
  alicePrivateKey, aliceAesKey, 'testnet'
);

// 2. Send encrypted message
const sent = await performSendPrivateMessage(
  alicePrivateKey,
  aliceAesKey,
  msgContract.contractAddress,
  msgContract.abi,
  bobAddress,
  'Secret message',
  'testnet'
);

// 3. Bob receives and reads message
const message = await performReadPrivateMessage(
  bobPrivateKey,
  bobAesKey,
  msgContract.contractAddress,
  msgContract.abi,
  aliceAddress,
  0, // message index
  'testnet'
);
```

--------------------------------

### Invalid Private Key Example

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/errors.md

Demonstrates how to catch an 'Invalid private key format' error when importing an account.

```typescript
try {
  await performImportAccountFromPrivateKey('invalid_key');
} catch (error) {
  console.error(error.message);
  // Output: Failed to import account: Invalid private key format: ...
}
```

--------------------------------

### Send Private Message Example

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/api-reference/private-messages.md

Example of how to send an encrypted private message.

```typescript
const result = await performSendPrivateMessage(
  privateKey,
  aesKey,
  contractAddress,
  contractAbi,
  recipientAddress,
  'Secret message',
  'testnet'
);
// Message is encrypted before being sent to blockchain
```

--------------------------------

### Solidity Syntax Error Example

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/errors.md

Provides an example of catching a 'Compilation error' in Solidity, which can be caused by syntax errors, missing imports, type mismatches, or undefined variables/functions.

```typescript
const badCode = `
  pragma solidity ^0.8.20;
  contract Bad {
    function test() public {
      invalid_function(); // Doesn't exist
    }
  }
`;

try {
  await performCompileContract(badCode, 'Bad');
} catch (error) {
  console.error(error.message);
  // Output: Compilation error: Function "invalid_function" not found...
}
```

--------------------------------

### Basic Usage Pattern - Create or Import Account

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/README.md

TypeScript examples for creating a new COTI account or importing an existing one using a private key.

```typescript
const account = await performCreateAccount('testnet');
// or
const imported = await performImportAccountFromPrivateKey(existingKey);
```

--------------------------------

### Read Private Message Example

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/api-reference/private-messages.md

Example of how to read and decrypt a private message.

```typescript
const message = await performReadPrivateMessage(
  privateKey,
  aesKey,
  contractAddress,
  contractAbi,
  senderAddress,
  0, // First message
  'testnet'
);
```

--------------------------------

### Workflow Example

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/api-reference/private-messages.md

Demonstrates a typical workflow for using the private message contract, from deployment to reading messages.

```typescript
// 1. Deploy contract
const deployed = await performDeployPrivateMessageContract(
  alicePrivateKey,
  aliceAesKey,
  'testnet'
);
const contractAddress = deployed.contractAddress;
const contractAbi = deployed.abi; // Contract ABI

// 2. Alice sends encrypted message to Bob
const sent = await performSendPrivateMessage(
  alicePrivateKey,
  aliceAesKey,
  contractAddress,
  contractAbi,
  bobAddress,
  'Hello Bob, this is secret',
  'testnet'
);

// 3. Bob checks who has sent messages
const senders = await performGetPrivateMessageSenders(
  contractAddress,
  contractAbi,
  bobAddress,
  'testnet'
);
// Returns: [aliceAddress, ...]

// 4. Bob checks message count from Alice
const count = await performGetPrivateMessageCount(
  contractAddress,
  contractAbi,
  aliceAddress,
  bobAddress,
  'testnet'
);
// Returns: 1

// 5. Bob reads Alice's message (decrypted automatically)
const message = await performReadPrivateMessage(
  bobPrivateKey,
  bobAesKey,
  contractAddress,
  contractAbi,
  aliceAddress,
  0, // First message index
  'testnet'
);
// Returns: { message: 'Hello Bob, this is secret', ... }
```

--------------------------------

### Token Mint Overflow Example

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/errors.md

Shows how to catch an error when attempting to mint an ERC20 token with an amount exceeding the maximum allowed value.

```typescript
try {
  const maxUint64 = BigInt("18446744073709551615");
  const tooLarge = (maxUint64 + BigInt("1")).toString();
  await performMintPrivateERC20Token(
    key, aesKey, token, recipient, tooLarge, 'testnet'
  );
} catch (error) {
  console.error(error.message);
  // Output: The mint amount (...) exceeds the maximum allowed value...
}
```

--------------------------------

### Deploy Private ERC721 Contract Example

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/api-reference/erc721-operations.md

Example of how to call the performDeployPrivateERC721Contract function to deploy a new private ERC721 NFT contract.

```typescript
const result = await performDeployPrivateERC721Contract(
  privateKey,
  'My NFT Collection',
  'MNC',
  'testnet'
);
// Returns contract address and deployment details
```

--------------------------------

### Decryption Failed Example

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/errors.md

Example of a decryption failure when attempting to read a private message, potentially due to an incorrect AES key.

```typescript
try {
  // Using wrong AES key
  await performReadPrivateMessage(
    bobPrivateKey, wrongAesKey, contract, abi, aliceAddr, 0, 'testnet'
  );
} catch (error) {
  console.error(error.message);
  // Output: Failed to read private message: Cannot decrypt...
}
```

--------------------------------

### Basic Usage Pattern - Perform Blockchain Operations

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/README.md

TypeScript examples demonstrating how to deploy a private ERC20 token and transfer native COTI.

```typescript
// Deploy ERC20 token
const token = await performDeployPrivateERC20Contract(
  privateKey, 'My Token', 'MTK', 6, 'testnet'
);

// Transfer native COTI
const transfer = await performTransferNative(
  privateKey, recipientAddress, '1000000000000000000', 'testnet'
);
```

--------------------------------

### Mint Private ERC721 Token Example

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/api-reference/erc721-operations.md

Example of how to call the performMintPrivateERC721Token function to mint a new NFT token in an ERC721 collection.

```typescript
const result = await performMintPrivateERC721Token(
  privateKey,
  aesKey,
  collectionAddress,
  recipientAddress,
  'https://example.com/metadata/1.json',
  'testnet'
);
// Returns transaction hash and token ID
```

--------------------------------

### Basic Usage Pattern - Generate AES Key

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/README.md

TypeScript example for generating an AES key, which is required for private operations.

```typescript
const aesResult = await performGenerateAesKey(privateKey, 'testnet');
```

--------------------------------

### Catching and Handling Errors

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/errors.md

Example of catching an error, logging its details, and re-throwing it.

```typescript
try {
  const result = await performSomeOperation(...);
} catch (error) {
  if (error instanceof Error) {
    console.error('Error message:', error.message);
    console.error('Stack:', error.stack);
  }
  // Handle error appropriately
  throw error; // Re-throw if needed
}
```

--------------------------------

### Message Signing Failed Example

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/errors.md

Illustrates catching a 'Failed to sign message' error, which can occur with invalid keys or network issues.

```typescript
try {
  await performSignMessage(invalidKey, 'message', 'testnet');
} catch (error) {
  console.error(error.message);
  // Output: Failed to sign message: ...
}
```

--------------------------------

### Decimal Validation Error Example

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/errors.md

Demonstrates an error when deploying an ERC20 token with an invalid number of decimals.

```typescript
try {
  await performDeployPrivateERC20Contract(
    key, 'Token', 'TKN', 18, 'testnet' // Decimals > 6
  );
} catch (error) {
  console.error(error.message);
  // Output: Decimals must be an integer between 0 and 6
}
```

--------------------------------

### Invalid Token ID Example

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/errors.md

Illustrates a scenario where a query for a non-existent ERC721 token ID might fail.

```typescript
try {
  await performGetPrivateERC721TokenOwner(
    tokenAddress, '99999', 'testnet' // Non-existent token
  );
} catch (error) {
  console.error(error.message);
}
```

--------------------------------

### Invalid ABI Format Example

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/errors.md

Shows how to catch an 'Invalid ABI format' error, which arises when the provided ABI is not valid JSON or is malformed, leading to a JSON parsing failure.

```typescript
try {
  await performCallContractFunction(
    key, aesKey, contract, 'func', [],
    'testnet', '{invalid json}'
  );
} catch (error) {
  console.error(error.message);
  // Output: Invalid ABI format: SyntaxError: ...
}
```

--------------------------------

### Smithery Distribution

Source: https://github.com/davibauer/coti-mcp/blob/main/README.md

Command to install the COTI MCP server using the Smithery CLI for Claude client.

```bash
npx -y @smithery/cli install @davibauer/coti-mcp --client claude
```

--------------------------------

### Contract Not Found Example

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/errors.md

Shows how to handle a 'Contract not found in compiled output' error, which occurs when the specified contract name does not match any contract in the source code or is misspelled.

```typescript
try {
  await performCompileContract(code, 'NonExistentContract');
} catch (error) {
  console.error(error.message);
  // Output: Contract 'NonExistentContract' not found...
}
```

--------------------------------

### Cannot Determine Contract Type Example

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/errors.md

Demonstrates handling the 'Could not determine contract type' error, which occurs when a contract does not match standard ERC20 or ERC721 types and no custom ABI is provided.

```typescript
try {
  await performCallContractFunction(
    key, aesKey, unknownContractAddr, 'customFunc', [], 'testnet'
    // No ABI provided, contract is not ERC20/ERC721
  );
} catch (error) {
  console.error(error.message);
  // Output: Could not determine contract type...
}
```

--------------------------------

### Mint URI Extraction Failure Example

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/errors.md

Demonstrates how to handle a 'Failed to mint private ERC721 token' error, which occurs when the NFT mint succeeds but the token ID cannot be extracted from the transaction logs.

```typescript
try {
  const result = await performMintPrivateERC721Token(
    key, aesKey, token, recipient, 'invalid://uri', 'testnet'
  );
} catch (error) {
  console.error(error.message);
  // Output: Failed to mint private ERC721 token: ...
}
```

--------------------------------

### Contract Function Not Found Example

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/errors.md

Illustrates handling a 'Function not found in contract' error, triggered when the specified function name does not exist in the contract or is not included in the provided ABI.

```typescript
try {
  await performCallContractFunction(
    key, aesKey, contractAddr, 'invalidFunc', [], 'testnet'
  );
} catch (error) {
  console.error(error.message);
  // Output: Function 'invalidFunc' not found in contract...
}
```

--------------------------------

### Get Private ERC721 Is Approved For All

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/api-reference/erc721-operations.md

Checks if an operator is approved to manage all NFTs for an owner. This example demonstrates how to use the performGetPrivateERC721IsApprovedForAll function.

```typescript
const isApproved = await performGetPrivateERC721IsApprovedForAll(
  ownerAddress,
  operatorAddress,
  tokenAddress,
  'testnet'
);
```

--------------------------------

### Get Private ERC721 Total Supply

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/api-reference/erc721-operations.md

Retrieves the total number of NFTs minted in a collection. This example shows how to use the performGetPrivateERC721TotalSupply function.

```typescript
const totalSupply = await performGetPrivateERC721TotalSupply(
  tokenAddress,
  'testnet'
);
// Returns: "1000" (1000 NFTs minted)
```

--------------------------------

### MCP Server Initialization

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/configuration.md

Initializes the MCP server with basic metadata.

```typescript
const server = new McpServer({
  name: "COTI MCP Server",
  version: "0.2.1",
  description: "COTI MCP Server",
});
```

--------------------------------

### Decode Event Data Example

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/api-reference/transaction-operations.md

Example usage of the performDecodeEventData function.

```typescript
const decoded = await performDecodeEventData(
  contractAddress,
  'Transfer',
  '0xabcd...',
  erc20Abi,
  'testnet'
);
// Returns decoded Transfer event with from, to, value fields
```

--------------------------------

### Transfer Private ERC721 Example

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/api-reference/erc721-operations.md

Example of how to call the performTransferPrivateERC721 function to transfer an NFT from sender to recipient.

```typescript
const result = await performTransferPrivateERC721(
  privateKey,
  aesKey,
  tokenAddress,
  recipientAddress,
  '42', // Token ID
  'testnet'
);
```

--------------------------------

### Get ERC20 Allowance API Endpoint

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/api-reference/erc20-operations.md

This is the GET endpoint for retrieving the approved spending allowance for a spender.

```http
GET /tools/erc20/getErc20Allowance
```

--------------------------------

### Logging Configuration

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/configuration.md

Enables debug logging by setting the 'debug' property to true in the configuration.

```json
{
  "config": {
    "debug": true
  }
}
```

--------------------------------

### Create Account

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/api-reference/account-management.md

Creates a new COTI account with randomly generated private key and placeholder AES key.

```http
POST /tools/account/createAccount
```

```typescript
export async function performCreateAccount(
  network: 'testnet' | 'mainnet'
): Promise<{
  address: string;
  privateKey: string;
  aesKey: string;
  network: string;
  formattedText: string;
}> {
  // ... implementation details
}
```

```typescript
const result = await performCreateAccount('testnet');
// Returns:
// {
//   address: '0xAbC...',
//   privateKey: '0x123abc...',
//   aesKey: 'Fund this account to generate an AES key...',
//   network: 'testnet',
//   formattedText: '...'
// }
```

--------------------------------

### Module Organization

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/README.md

Illustrates the directory structure for organizing different types of tools within the MCP.

```bash
tools/
├── account/           # Account & key management
├── erc20/            # ERC20 token operations
├── erc721/           # ERC721 NFT operations
├── privateMessage/   # Encrypted messaging
├── native/           # COTI token operations
├── transaction/      # Contract interaction
├── compiler/         # Solidity compilation
├── deployment/       # Contract deployment
├── constants/        # Contract ABIs
├── shared/           # Shared utilities
└── verification/     # Contract verification
```

--------------------------------

### Tool Registration

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/configuration.md

Registers a tool with the MCP server, providing its identifier, definition, and handler function.

```typescript
server.registerTool(
  "tool_name",           // Tool identifier (snake_case)
  TOOL_DEFINITION,       // ToolAnnotations object
  toolHandler            // Handler function
);
```

```typescript
server.registerTool(
  "create_account",
  CREATE_ACCOUNT,
  createAccountHandler
);
```

--------------------------------

### Import Account From Private Key

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/api-reference/account-management.md

Imports a COTI account using an existing private key.

```http
POST /tools/account/importAccountFromPrivateKey
```

```typescript
export async function performImportAccountFromPrivateKey(
  private_key: string
): Promise<{
  address: string;
  privateKey: string;
  aesKey: string;
  formattedText: string;
}> {
  // ... implementation details
}
```

```typescript
const result = await performImportAccountFromPrivateKey('abc123...');
// Validates and derives public key from private key
// Returns account details
```

--------------------------------

### Get Private ERC721 Approved

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/api-reference/erc721-operations.md

Retrieves the address approved to transfer a specific NFT.

```typescript
const approved = await performGetPrivateERC721Approved(
  tokenAddress,
  '42',
  'testnet'
);
```

--------------------------------

### Server Configuration Schema

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/configuration.md

Defines the schema for server configuration, including a debug flag.

```typescript
export default function ({ config }: { config: z.infer<typeof configSchema> })
```

```typescript
export const configSchema = z.object({
  debug: z.boolean().default(false).describe("Enable debug logging"),
});
```

--------------------------------

### Perform Get Private ERC20 Decimals

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/api-reference/erc20-operations.md

Retrieves the decimal places for an ERC20 token.

```typescript
const decimals = await performGetPrivateERC20Decimals(tokenAddress, 'testnet');
```

--------------------------------

### Get Private ERC721 Token Owner

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/api-reference/erc721-operations.md

Retrieves the owner of a specific NFT token.

```typescript
const owner = await performGetPrivateERC721TokenOwner(
  tokenAddress,
  '42',
  'testnet'
);
```

--------------------------------

### Perform Get Private ERC20 Balance

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/api-reference/erc20-operations.md

Retrieves the ERC20 token balance for an account.

```typescript
const balance = await performGetPrivateERC20Balance(
  accountAddress,
  tokenAddress,
  'testnet'
);
```

--------------------------------

### Amount Formatting for Transfer

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/api-reference/native-tokens.md

TypeScript code snippet demonstrating how to convert human-readable COTI amounts to wei for transfers.

```typescript
// Transfer 1 COTI token
const amountInCoti = '1.0';
const amountInWei = (parseFloat(amountInCoti) * 1e18).toString();
// amountInWei = '1000000000000000000'

// Transfer 0.5 COTI
const halfCoti = '500000000000000000';

// Transfer 100 COTI
const oneHundredCoti = '100000000000000000000';
```

--------------------------------

### Get Private ERC721 Balance

Source: https://github.com/davibauer/coti-mcp/blob/main/_autodocs/api-reference/erc721-operations.md

Retrieves the number of NFTs owned by an account in a collection.

```typescript
const balance = await performGetPrivateERC721Balance(
  accountAddress,
  tokenAddress,
  'testnet'
);
// Returns: "5" (5 NFTs owned)
```