# local-tools-mcp-server

A minimal, production-ready MCP server that gives AI assistants access to local file system tools — file search, directory listing, system info, and file metadata.

Built for [WorkBuddy](https://www.codebuddy.cn/) and any MCP-compatible client.

## Tools

| Tool | Description |
|------|-------------|
| `localtools_search_files` | Search files by name pattern / extension with recursive depth control |
| `localtools_system_info` | OS, CPU, memory, uptime, user, Node.js version |
| `localtools_list_directory` | List directory contents with pagination and hidden-file toggle |
| `localtools_get_file_info` | File/directory metadata + text file preview (first 1000 bytes) |

All tools are read-only. No files are ever created, modified, or deleted.

## Quick Start

### Prerequisites

- Node.js >= 18
- npm >= 9

### Install & Build

```bash
git clone https://github.com/YOUR_USERNAME/local-tools-mcp-server.git
cd local-tools-mcp-server
npm install
npm run build
```

### Configure in WorkBuddy

Add to `~/.workbuddy/mcp.json`:

```json
{
  "mcpServers": {
    "local-tools": {
      "command": "node",
      "args": ["E:/path/to/local-tools-mcp-server/dist/index.js"]
    }
  }
}
```

Then activate the connector in WorkBuddy's **Connector Management** page.

### Configure in Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "local-tools": {
      "command": "node",
      "args": ["/path/to/local-tools-mcp-server/dist/index.js"]
    }
  }
}
```

## Usage Examples

Once connected, the AI can use these tools naturally:

> "Search my D drive for all .py files, max depth 5"
>
> "How much free memory does my system have?"
>
> "List the contents of my Downloads folder"
>
> "Get info on C:\projects\config.json"

## Project Structure

```
local-tools-mcp-server/
├── src/
│   └── index.ts          # All 4 tools + server entry point (~730 lines)
├── dist/                 # Compiled JS output (gitignored)
├── package.json
├── tsconfig.json
└── README.md
```

## Tech Stack

- **Runtime**: Node.js
- **Language**: TypeScript
- **Validation**: Zod
- **Protocol**: [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
- **Transport**: stdio (local process, zero network config)

## Security

- All file system access is read-only
- Paths are resolved and validated before any operation
- Permission errors are caught and reported gracefully
- No external dependencies beyond the MCP SDK and Zod

## License

MIT