🤖 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

cd chhotu_sa_mcp_mvp
npm install

2. Obtain a License

First time users:

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

npm run build

Running

Development Mode

npm run dev

Production Mode

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

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:

npm run setup-license

Integration Examples

Claude Desktop

Add to claude_desktop_config.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

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:

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:

{
  "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/:

   export async function myOperation(input: string): Promise<string> {
     // Implementation
   }
   

2. Create tool wrapper in src/tools/:

   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:

   server.tool('my_tool', 'Description', MyToolInputSchema, myTool);
   

Testing

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:

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

# 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