# MCP Server with Algorand Integration

This server provides blockchain transaction capabilities for the Algorand network along with general utility tools.

## Overview

This MCP server provides the following tools to AI assistants:

### General Tools
- **echo**: Echo back any message (useful for testing connectivity)
- **calculate**: Perform basic mathematical calculations
- **get_current_time**: Get the current time in any timezone

### Algorand Blockchain Tools
- **generate_algorand_account**: Generate a new Algorand account with address and mnemonic
- **get_account_info**: Get account information including balance and assets
- **send_payment**: Send Algo payment transaction
- **create_asset**: Create a new Algorand Standard Asset (ASA)
- **opt_in_to_asset**: Opt into an Algorand Standard Asset
- **transfer_asset**: Transfer an Algorand Standard Asset
- **get_asset_info**: Get information about an asset
- **get_transaction**: Get transaction details by transaction ID

## Security Features

### Mnemonic Phrase Protection
- **Encryption**: Built-in AES-256-GCM encryption for mnemonic phrases
- **Secure Storage**: Methods for encrypting/decrypting wallet credentials
- **Memory Safety**: Sensitive data is handled securely and not logged

### Network Configuration
- **Testnet Default**: Safely defaults to Algorand testnet
- **Environment-based**: Network configuration through environment variables
- **Production Ready**: Supports mainnet for production use

## Prerequisites

- Node.js 18+ 
- npm or yarn
- TypeScript

## Installation

1. Clone or download this project
2. Install dependencies:
   ```bash
   npm install
   ```
3. Copy environment configuration:
   ```bash
   cp .env.example .env
   ```
4. Configure your Algorand network in `.env` (defaults to testnet)

## Development

### Building the Project

```bash
npm run build
```

### Running the Server

```bash
npm start
```

### Development Mode

For development with automatic rebuilding:

```bash
npm run dev
```

## Configuration

### For VSCode

```json
{
  "mcpServers": {
    "algorand-mcp-server": {
      "command": "node",
      "args": ["path/to/your/project/dist/index.js"]
    }
  }
}
```

### For VS Code Debugging

The project includes a `.vscode/mcp.json` configuration file for debugging within VS Code. You can use this with the MCP extension for VS Code.

## Available Tools

### echo
- **Description**: Echo back the provided message
- **Parameters**: 
  - `message` (string, required): The message to echo back

### calculate
- **Description**: Perform basic mathematical calculations
- **Parameters**:
  - `expression` (string, required): Mathematical expression to evaluate

### get_current_time
- **Description**: Get the current time in a specified timezone
- **Parameters**:
  - `timezone` (string, optional): Timezone identifier (defaults to UTC)

## Project Structure

```
├── src/
│   └── index.ts          # Main server implementation
├── dist/                 # Compiled JavaScript output
├── .vscode/
│   └── mcp.json         # VS Code MCP configuration
├── .github/
│   └── copilot-instructions.md  # GitHub Copilot instructions
├── package.json          # Node.js package configuration
├── tsconfig.json         # TypeScript configuration
└── README.md            # This file
```

## Development Guide

### Adding New Tools

1. Define the tool schema in the `TOOLS` array
2. Create a Zod schema for input validation
3. Add a case in the `CallToolRequestSchema` handler
4. Implement the tool logic with proper error handling

### Example Tool Implementation

```typescript
const MyToolArgsSchema = z.object({
  input: z.string(),
});

// Add to TOOLS array
{
  name: 'my_tool',
  description: 'Description of what the tool does',
  inputSchema: {
    type: 'object',
    properties: {
      input: {
        type: 'string',
        description: 'Input parameter description',
      },
    },
    required: ['input'],
  },
}

// Add to request handler
case 'my_tool': {
  const parsed = MyToolArgsSchema.parse(args);
  // Implement tool logic here
  return {
    content: [
      {
        type: 'text',
        text: `Result: ${parsed.input}`,
      },
    ],
  };
}
```

## Security Considerations

- Input validation is performed using Zod schemas
- The `calculate` tool uses `eval()` for demonstration purposes only - in production, use a safer math evaluation library
- Always validate and sanitize inputs before processing

## Contributing

1. Fork the repository
2. Create a feature branch
3. Implement your changes with proper tests
4. Submit a pull request

## License

ISC License - see package.json for details

## Resources

- [Model Context Protocol Documentation](https://modelcontextprotocol.io/)
- [MCP SDK Reference](https://github.com/modelcontextprotocol/typescript-sdk)