## Example Usage Guide
### Using the MCP Server
#### 1. Basic File Operations
**List files:**
```json
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "list_files",
"arguments": {
"path": "~/Documents",
"recursive": false
}
}
}
```
**Read a file:**
```json
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "read_file",
"arguments": {
"path": "~/Documents/notes.txt"
}
}
}
```
**Write a file:**
```json
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "write_file",
"arguments": {
"path": "~/Documents/new_file.txt",
"content": "Hello, World!"
}
}
}
```
#### 2. Search Operations
**Search for files by name:**
```json
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "search_files",
"arguments": {
"baseDir": "~/",
"query": "invoice",
"maxResults": 50
}
}
}
```
**Search file contents:**
```json
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "search_content",
"arguments": {
"baseDir": "~/Documents",
"query": "password",
"maxResults": 20
}
}
}
```
#### 3. Command Execution
**Run an allowed command:**
```json
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "run_command",
"arguments": {
"command": "ls -la",
"timeout": 30000
}
}
}
```
**List available commands:**
```json
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "list_allowed_commands",
"arguments": {}
}
}
```
#### 4. System Operations
**Launch an app:**
```json
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "launch_app",
"arguments": {
"appName": "Visual Studio Code"
}
}
}
```
**Get clipboard content:**
```json
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "get_clipboard",
"arguments": {}
}
}
```
**Set clipboard content:**
```json
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "set_clipboard",
"arguments": {
"content": "My copied text"
}
}
}
```
#### 5. Automation
**Create folder structure:**
```json
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "create_folder_structure",
"arguments": {
"basePath": "~/Projects/myapp",
"structure": {
"src": {
"components": {},
"utils": {},
"styles": {}
},
"public": {},
"tests": {},
"README.md": ""
}
}
}
}
```
**Bulk rename files:**
```json
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "bulk_rename",
"arguments": {
"directory": "~/Downloads",
"pattern": "*.png",
"prefix": "screenshot_",
"suffix": ""
}
}
}
```
**Cleanup desktop:**
```json
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "cleanup_desktop",
"arguments": {
"desktopPath": "~/Desktop"
}
}
}
```
#### 6. Key-Value Store
**Store a value:**
```json
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "kv_set",
"arguments": {
"key": "user_preferences",
"value": {
"theme": "dark",
"language": "en",
"notifications": true
}
}
}
}
```
**Retrieve a value:**
```json
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "kv_get",
"arguments": {
"key": "user_preferences"
}
}
}
```
**List all keys:**
```json
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "kv_list",
"arguments": {}
}
}
```
**Delete a key:**
```json
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "kv_delete",
"arguments": {
"key": "user_preferences"
}
}
}
```
**Clear all data:**
```json
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "kv_clear",
"arguments": {}
}
}
```
### Success Response Format
All tools return structured JSON responses:
```json
{
"content": [
{
"type": "text",
"text": "{\"success\": true, \"data\": {...}}"
}
]
}
```
### Error Response Format
```json
{
"content": [
{
"type": "text",
"text": "{\"error\": \"File not found\", \"code\": \"FILE_NOT_FOUND\"}"
}
]
}
```
### Using with Claude Desktop
Add to `claude_desktop_config.json`:
```json
{
"mcpServers": {
"chhotu": {
"command": "node",
"args": ["/absolute/path/to/dist/server.js"]
}
}
}
```
Then in Claude, you can say:
- "List all PDF files in my Documents folder"
- "Search for files containing 'invoice' on my desktop"
- "Create a folder structure for a new React project"
- "Organize my desktop by file type"
### Using Programmatically
```typescript
import { readFileContents } from './src/core/fileSystem.js';
import { searchFiles } from './src/core/search.js';
import { launchApplication } from './src/core/apps.js';
import { kvSet, kvGet } from './src/core/kv.js';
// Read a file
const content = await readFileContents('/path/to/file.txt');
console.log(content);
// Search for files
const results = await searchFiles('/path', 'pattern', 100);
console.log(results);
// Launch an app
const result = await launchApplication('VS Code');
console.log(result);
// Use KV store
await kvSet('mykey', { data: 'value' });
const value = await kvGet('mykey');
console.log(value);
```
### Testing in Development
1. Start the server:
```bash
npm run dev
```
2. In another terminal, test with curl:
```bash
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":"~"}
}
}'
```
3. Or connect via WebSocket:
```bash
websocat ws://127.0.0.1:4000
```
### Common Patterns
**File organization workflow:**
```
1. list_files to see what's there
2. search_files to find specific items
3. bulk_rename to standardize names
4. move_file to organize
5. cleanup_desktop for automatic organization
```
**Automation workflow:**
```
1. create_folder_structure for setup
2. run_command for processing
3. write_file to save results
4. kv_set to store state
```
**Data collection workflow:**
```
1. search_content to find information
2. read_file to get full content
3. kv_set to cache results
4. kv_list to review stored items
```
---
**For more details, see README.md and the source code in src/tools/**
