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