cloud-mcp/README.md

# Cloud MCP - Personal MCP Server

A comprehensive personal MCP (Model Context Protocol) server built with Bun and TypeScript, designed for developers, DevOps engineers, and families.

## Features

### 🚀 Programming Tools
- **Code Snippet Management**: Save, search, list, and delete code snippets with tags and categories
- **Project Templates**: Quickly generate Vite + Vue3 + TypeScript projects (frontend or fullstack)
- **Technical Documentation**: Quick access to TypeScript, Vue3, and Bun documentation
- **Code Review**: Get code review suggestions and optimization tips

### 🔧 DevOps Tools
- **NAS Management**: List, upload, download, and search files on your NAS
- **Server Monitoring**: Check cloud server status (CPU, memory, disk) and view logs
- **Router Management**: Monitor soft router status, traffic, and connected devices

### 👨‍👩‍👦 Family Tools
- **Math Resources**: Search and save math teaching resources, generate problems by grade
- **Baby Milestones**: Record and track baby milestones and set reminders

### ⚽ Hobby Tools
- **Football Information**: Get match schedules, team info, and league standings
- **Game Information**: Search game info, find deals, and manage wishlist

### 📝 Common Tools
- **Notes Management**: Create, search, list, and delete personal notes
- **Task Management**: Add, list, and complete tasks

## Installation

1. Clone or navigate to the project directory:
```bash
cd cloud-mcp
```

2. Install dependencies:
```bash
bun install
```

3. Configure environment variables (optional):
```bash
cp .env.example .env
# Edit .env with your configuration
```

## Configuration

Create a `.env` file in the project root with the following variables (all optional):

```env
# NAS Configuration
NAS_HOST=your-nas-ip
NAS_USERNAME=your-username
NAS_PASSWORD=your-password
NAS_PROTOCOL=smb  # smb, ftp, or sftp

# Cloud Server Configuration
SERVER_HOST=your-server-ip
SERVER_USERNAME=your-username
SERVER_PORT=22
SERVER_KEY_PATH=/path/to/ssh/key

# Soft Router Configuration
ROUTER_HOST=your-router-ip
ROUTER_USERNAME=admin
ROUTER_PASSWORD=your-password

# Email Configuration (SMTP)
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_USER=your-email@gmail.com
EMAIL_PASSWORD=your-app-password
EMAIL_FROM=Your Name
EMAIL_SECURE=false

# API Keys (optional)
FOOTBALL_API_KEY=your-football-api-key
GAME_API_KEY=your-game-api-key
```

## Usage

### Running the Server

```bash
bun run dev
```

Or build and run:

```bash
bun run build
bun run start
```

### Connecting to MCP Clients

The server uses stdio transport, so it can be connected to any MCP-compatible client (like Claude Desktop, Cursor, etc.).

Example configuration for Claude Desktop (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "cloud-mcp": {
      "command": "bun",
      "args": ["run", "/path/to/cloud-mcp/src/index.ts"]
    }
  }
}
```

## Available Tools

### Programming
- `code_snippet_save` - Save a code snippet
- `code_snippet_search` - Search code snippets
- `code_snippet_list` - List all code snippets
- `code_snippet_delete` - Delete a code snippet
- `project_template_create` - Create Vite + Vue3 project
- `project_template_create_fullstack` - Create fullstack project
- `project_template_list` - List available templates
- `docs_typescript` - Get TypeScript documentation
- `docs_vue3` - Get Vue3 documentation
- `docs_bun` - Get Bun documentation
- `code_review` - Review code
- `code_optimize` - Get optimization suggestions
- `git_status` - Get git repository status
- `git_add` - Stage files for commit
- `git_commit` - Commit staged changes
- `git_push` - Push commits to remote
- `git_pull` - Pull latest changes from remote
- `git_log` - Show commit history
- `git_branch` - List, create, or delete branches
- `git_diff` - Show changes between commits or working directory

### DevOps
- `nas_list_files` - List NAS files
- `nas_upload_file` - Upload file to NAS
- `nas_download_file` - Download file from NAS
- `nas_search_files` - Search files on NAS
- `server_status` - Get server status
- `server_deploy` - Deploy application
- `server_logs` - View server logs
- `router_status` - Get router status
- `router_traffic` - Get traffic statistics
- `router_devices` - List connected devices

### Family
- `math_resource_search` - Search math resources
- `math_problem_generate` - Generate math problems
- `math_resource_save` - Save math resource
- `baby_milestone_add` - Record baby milestone
- `baby_milestone_list` - List milestones
- `baby_reminder_set` - Set baby reminder

### Hobbies
- `football_matches` - Get football matches
- `football_team_info` - Get team information
- `football_standings` - Get league standings
- `game_info` - Get game information
- `game_deals` - Get game deals
- `game_wishlist` - Manage game wishlist

### Common
- `note_create` - Create a note
- `note_search` - Search notes
- `note_list` - List notes
- `note_delete` - Delete a note
- `task_add` - Add a task
- `task_list` - List tasks
- `task_complete` - Complete a task
- `email_send` - Send email via SMTP (supports text, HTML, and attachments)

## Data Storage

All data is stored in PostgreSQL database. The application requires a PostgreSQL database connection.

### Database Setup

1. **Configure Database Connection**

   Set the `DATABASE_URL` environment variable in your `.env` file:
   ```
   DATABASE_URL=postgresql://user:password@host:port/database
   ```

2. **Initialize Database Schema**

   Run the initialization script to create all required tables:
   ```bash
   bun run init-db
   ```

   This will create the following tables:
   - `code_snippets` - Code snippets
   - `notes` - Personal notes
   - `tasks` - Tasks
   - `baby_milestones` - Baby milestones
   - `math_resources` - Math resources
   - `game_wishlist` - Game wishlist

### Database Schema

The database schema is defined in `src/storage/schema.sql`. All tables include appropriate indexes for optimal query performance.

## Development

### Project Structure

```
cloud-mcp/
├── src/
│   ├── index.ts              # Entry point
│   ├── server.ts              # MCP server core
│   ├── tools/                 # Tool modules
│   │   ├── programming/       # Programming tools
│   │   ├── devops/            # DevOps tools
│   │   ├── family/             # Family tools
│   │   ├── hobbies/            # Hobby tools
│   │   └── common/             # Common tools
│   ├── storage/               # Storage layer
│   │   ├── config.ts          # Configuration
│   │   └── database.ts        # Database/storage
│   └── utils/                 # Utilities
│       └── logger.ts           # Logging
├── data/                      # Data files (created at runtime)
├── package.json
├── tsconfig.json
└── README.md
```

### Adding New Tools

1. Create a new tool file in the appropriate directory under `src/tools/`
2. Export a registration function (e.g., `registerMyTool`)
3. Import and call it in `src/index.ts`

Example:

```typescript
// src/tools/myfeature/myTool.ts
import { mcpServer } from '../../server.js';

export function registerMyTool(): void {
  mcpServer.registerTool(
    {
      name: 'my_tool',
      description: 'My tool description',
      inputSchema: {
        type: 'object',
        properties: {
          // ...
        },
      },
    },
    async (args) => {
      // Tool implementation
      return {
        content: [{ type: 'text', text: 'Result' }],
      };
    }
  );
}
```

## License

MIT

## Contributing

This is a personal MCP server, but feel free to fork and customize for your own needs!