🤖 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

Create the core module in src/core/:

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

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))] };
  }
}

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

🤖 AI PC Assistant MCP Server

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

Create the core module in src/core/:

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

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))] };
  }
}

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