# 🤖 AI PC Assistant MCP Server

A production-ready Model Context Protocol (MCP) server that enables AI assistants to safely perform real actions on your computer. Features file system management, local search, command execution, clipboard access, and more.

**Built for Day-1 monetization with license validation.**

## Features

### File System Tools
- **list_files** - List directory contents with metadata (recursive optional)
- **read_file** - Read file contents
- **write_file** - Write or create files
- **delete_file** - Delete files or directories
- **move_file** - Move or rename files

### Search Tools
- **search_files** - Find files by name (recursive with max results limit)
- **search_content** - Search text content within files

### Command Execution
- **run_command** - Execute shell commands (allow-listed only)
- **list_allowed_commands** - View permitted commands

### System Operations
- **launch_app** - Launch applications (platform-aware: macOS/Windows/Linux)
- **get_clipboard** - Read clipboard content
- **set_clipboard** - Write to clipboard

### Automation
- **create_folder_structure** - Create nested folder hierarchies
- **bulk_rename** - Rename multiple files with prefix/suffix
- **cleanup_desktop** - Auto-organize files by type

### Local Storage
- **kv_set** - Store notes or data locally
- **kv_get** - Retrieve stored values
- **kv_delete** - Delete stored values
- **kv_list** - List all stored keys
- **kv_clear** - Clear all storage

## Requirements

- Node.js 16+
- npm or yarn
- macOS, Windows, or Linux

## Installation

### 1. Clone or Download

```bash
cd chhotu_sa_mcp_mvp
npm install
```

### 2. Obtain a License

**First time users:**
```bash
npm run setup-license
```

This creates a demo license at `~/.mcp-license` (valid for 90 days). For production use, contact support for a commercial license.

### 3. Build

```bash
npm run build
```

## Running

### Development Mode
```bash
npm run dev
```

### Production Mode
```bash
npm run build
npm start
```

The server will:
- Validate your license
- Start MCP Server on stdio (for Claude Desktop, etc.)
- Start HTTP transport at `http://127.0.0.1:3000/mcp`
- Start WebSocket transport at `ws://127.0.0.1:4000`

## Configuration

### Environment Variables

```bash
NODE_ENV=production          # Set to 'production' for stricter security
PORT=3000                    # HTTP server port
WS_PORT=4000                 # WebSocket server port
DEBUG=true                   # Enable debug logging
```

### License

License file stored at `~/.mcp-license` (Unix/Mac) or `%USERPROFILE%\.mcp-license` (Windows)

To regenerate license:
```bash
npm run setup-license
```

## Integration Examples

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "chhotu": {
      "command": "node",
      "args": ["/path/to/dist/server.js"]
    }
  }
}
```

### ChatGPT with Custom GPT

Connect via HTTP or WebSocket:
- HTTP Endpoint: `http://127.0.0.1:3000/mcp`
- WebSocket Endpoint: `ws://127.0.0.1:4000`

### Programmatic Usage

```typescript
import { runCommand } from './src/core/commands.js';
import { readFileContents } from './src/core/fileSystem.js';

// Run a command
const result = await runCommand('ls -la');
console.log(result.stdout);

// Read a file
const content = await readFileContents('/path/to/file.txt');
console.log(content);
```

## Security Model

### Allow-Listed Commands

Only these shell commands are allowed by default:
- File operations: `ls`, `find`, `grep`, `cat`, `stat`, `file`
- System: `pwd`, `whoami`, `date`, `uname`, `which`
- Media: `ffmpeg`, `convert`, `imagemagick`, `sips`

Add more in development mode:
```typescript
import { addAllowedCommand } from './src/core/commands.js';
addAllowedCommand('my-safe-tool');
```

### Path Safety

- Prevents directory traversal (`../` attacks)
- Validates file access within allowed paths
- Sanitizes error messages

### Error Boundaries

All tools return structured, safe responses:
```json
{
  "success": false,
  "error": "File not found",
  "code": "FILE_NOT_FOUND"
}
```

## Project Structure

```
chhotu_sa_mcp_mvp/
├── server.ts                 # Main MCP server entry point
├── package.json             # Dependencies
├── tsconfig.json            # TypeScript config
├── src/
│   ├── config/
│   │   ├── index.ts         # Config initialization
│   │   └── license.ts       # License validation (HMAC)
│   ├── core/
│   │   ├── fileSystem.ts    # File operations
│   │   ├── search.ts        # File/content search
│   │   ├── commands.ts      # Command execution
│   │   ├── apps.ts          # App launching
│   │   ├── clipboard.ts     # Clipboard access (platform-aware)
│   │   └── kv.ts            # Key-value store
│   ├── tools/
│   │   ├── index.ts         # Tool registration
│   │   ├── fileTools.ts     # File system tools
│   │   ├── searchTools.ts   # Search tools
│   │   ├── commandTools.ts  # Command execution
│   │   ├── systemTools.ts   # App/clipboard tools
│   │   ├── automationTools.ts # Bulk operations
│   │   └── kvTools.ts       # KV store tools
│   └── utils/
│       ├── platform.ts      # Platform detection (macOS/Windows/Linux)
│       ├── paths.ts         # Safe path handling
│       └── errors.ts        # Error sanitization
└── README.md
```

## Development

### Adding a New Tool

1. Create the core module in `src/core/`:
   ```typescript
   export async function myOperation(input: string): Promise<string> {
     // Implementation
   }
   ```

2. Create tool wrapper in `src/tools/`:
   ```typescript
   import { z } from 'zod';
   import { myOperation } from '../core/myModule.js';

   export const MyToolInputSchema = z.object({
     input: z.string(),
   });

   export async function myTool(input: z.infer<typeof MyToolInputSchema>) {
     try {
       const result = await myOperation(input.input);
       return { content: [{ type: 'text', text: JSON.stringify(result) }] };
     } catch (error) {
       return { content: [createErrorResponse('ERROR', String(error))] };
     }
   }
   ```

3. Register in `src/tools/index.ts`:
   ```typescript
   server.tool('my_tool', 'Description', MyToolInputSchema, myTool);
   ```

### Testing

```bash
npm run dev
# In another terminal, test with curl
curl -X POST http://127.0.0.1:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"list_files","arguments":{"path":"~"}}}'
```

## Monetization

### License Validation

The server uses HMAC-SHA256 token validation:

```typescript
import { generateLicenseToken, validateLicenseToken } from './src/config/license.js';

// Generate a new license (for resellers)
const token = generateLicenseToken('customer@example.com');

// Validate at runtime (automatic in server startup)
const result = validateLicenseToken(token);
if (result.isValid) {
  console.log(`Valid for: ${result.licensee}`);
}
```

Licenses expire after 90 days by default. Modify in `src/config/license.ts` for different terms.

## Troubleshooting

### License Not Valid
```bash
# Regenerate license
npm run setup-license
```

### Command Not Allowed
Add to allow-list in `src/core/commands.ts` or use development mode.

### Platform-Specific Issues

**macOS:** Ensure `pbcopy`/`pbpaste` are available
**Windows:** Requires PowerShell for clipboard operations
**Linux:** Install `xclip` or `xsel` for clipboard

## Performance & Limits

- File search: Limited to 100 results by default
- Command timeout: 30 seconds
- Clipboard: Max 10MB
- HTTP buffer: 1MB

## License

Proprietary - Licensed under .mcp-license model

## Support

For issues or feature requests, contact: support@example.com

---

**Version:** 1.0.0  
**Last Updated:** November 2025