AI PC Assistant

You run an MCP server on your machine to let AI assistants safely perform actions like managing files, searching content, running allowed commands, launching apps, and automating routine tasks. This server handles the heavy lifting locally, keeps actions sandboxed, and exposes controlled interfaces for your preferred AI tools to interact with your computer.

How to use

You connect an MCP client to the server to start issuing safe, governed actions. The server provides HTTP and WebSocket transports for your client to communicate securely. Use an HTTP client to send MCP requests to http://127.0.0.1:3000/mcp or connect via WebSocket to ws://127.0.0.1:4000. Your client can request file operations, searches, command execution (from an allow-listed set), clipboard access, and automation tools. Start by ensuring your license is valid, then use your client to call the available tools through the MCP endpoints.

How to install

Prerequisites you need before installing the MCP server are Node.js 16+, and npm or yarn. You will install dependencies, validate or obtain a license, build the server, and then run it in either development or production mode.

Step-by-step commands you will execute:

# 1) Create and navigate to the project directory
mkdir chhotu_sa_mcp_mvp
cd chhotu_sa_mcp_mvp

# 2) Install dependencies
npm install

# 3) Obtain a license (demo license created for 90 days locally)
npm run setup-license

# 4) Build the server
npm run build

# 5) Run in development mode (optional for development)
npm run dev

# 6) Run in production mode
npm start

Configuration and runtime details

Environment variables you may configure include the following, which influence how the server runs and exposes its transports.

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

Security, licensing, and troubleshooting

Licensing is enforced at startup and during operation. A license token is validated automatically to ensure authorized use. Licenses expire after 90 days by default and can be regenerated if needed.

Common issues and resolutions:

• License Not Valid — Regenerate license with the license setup flow.
• Command Not Allowed — Expand the allow-list of commands in development mode or adjust tool permissions.
• Platform-Specific Issues — Ensure required clipboard utilities are available on macOS, PowerShell is accessible on Windows, and clipboard tools are installed on Linux.

Available tools

list_files

List directory contents with metadata; supports recursive listing for thorough exploration.

read_file

Read file contents to retrieve data stored on disk.

write_file

Create or overwrite files with specified content.

delete_file

Remove files or directories from the filesystem.

move_file

Move or rename files and folders across the filesystem.

search_files

Find files by name, with recursive search and configurable result limits.

search_content

Search text content within files to locate information quickly.

run_command

Execute shell commands from a controlled allow-list of safe commands.

list_allowed_commands

Query the set of commands that are currently permitted for execution.

launch_app

Launch applications in a cross-platform manner.

get_clipboard

Read the current contents of the system clipboard.

set_clipboard

Write data to the system clipboard.

create_folder_structure

Create nested folder hierarchies in a single operation.

bulk_rename

Rename multiple files with a common prefix or suffix.

cleanup_desktop

Organize files on the desktop by type to reduce clutter.

kv_set

Store small pieces of data locally for quick retrieval.

kv_get

Retrieve stored values by key.

kv_delete

Remove stored values by key.

kv_list

List all keys currently stored in local storage.

kv_clear

Clear all stored keys and values.