AI PC Assistant MCP Server

# 🤖 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