<p align="center">
  <img src="https://capsule-render.vercel.app/api?type=waving&color=0:4285F4,100:34A853&height=200&section=header&text=MCP File Manager&fontSize=60&fontColor=ffffff&animation=fadeIn" alt="banner" />
</p>

<p align="center">
  <img src="https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python&logoColor=white" alt="Python 3.10+"/>
  <img src="https://img.shields.io/badge/package%20manager-uv-de5fe9?logo=uv&logoColor=white" alt="uv"/>
  <img src="https://img.shields.io/badge/protocol-MCP-6E56CF" alt="MCP"/>
  <img src="https://img.shields.io/badge/LLM-Gemini%20API-4285F4?logo=googlegemini&logoColor=white" alt="Gemini API"/>
  <img src="https://img.shields.io/badge/license-MIT-informational" alt="MIT License"/>
</p>

# MCP File Manager

A local **Model Context Protocol (MCP)** project that lets you manage files on your machine through natural language, powered by the **Gemini API** (free tier) as the client-side LLM.

The project has two halves that talk to each other over stdio (standard input/output pipes) — no network involved:

- **`server.py`** — an MCP server exposing file-manipulation **tools**, read-only **resources**, and reusable **prompts**.
- **`client.py`** — a terminal chat client that launches the server as a subprocess, connects to Gemini, and bridges the two: Gemini decides what to do, the server does it.

```mermaid
flowchart LR
    U([User]) -->|types message| C[MCP Client<br/>chat loop]
    C -->|conversation + tool schema| G[(Gemini API<br/>function calling)]
    G -->|final text| C
    G -.->|requests a tool call| C
    C <-->|JSON-RPC over stdio| S[MCP Server]
    S --- T[Tools<br/>list_directory, read_file,<br/>write_file, delete_file, update_file]
    S --- R[Resources<br/>file:// attachments via @]
    S --- P[Prompts<br/>summarize_file, clean_up_code via /]

    style G fill:#4285F4,color:#fff
    style S fill:#34A853,color:#fff
    style C fill:#111,color:#fff
```

## Features

- **Tools** (model-controlled — Gemini decides when to call these):
  - `list_directory` — list files/folders in a given path
  - `read_file` — read a file's contents
  - `write_file` — create or overwrite a file
  - `delete_file` — delete a file
  - `update_file` — find-and-replace text inside a file (supports replacing all occurrences or just the first)

- **Resources** (user-controlled — attach a file to the conversation with `@`):
  - `file:///{path}` — exposes any file's content for direct attachment, no LLM tool call needed

- **Prompts** (user-controlled — reusable instruction templates with `/`):
  - `summarize_file` — summarize a file's contents
  - `clean_up_code` — review and clean up a code file

- **Interactive chat client**:
  - Type `/` alone to see a numbered picker of available prompts
  - Type `@` alone to see a numbered picker of files in the current directory to attach
  - Or use them inline: `/summarize_file report.txt`, `tell me about @report.txt`
  - Full multi-step tool-calling loop — Gemini can chain multiple tool calls per turn

## Requirements

- Python 3.10+
- [uv](https://docs.astral.sh/uv/) for dependency management
- A free Gemini API key from [Google AI Studio](https://aistudio.google.com/apikey)

## Setup

```bash
git clone <your-repo-url>
cd mcp_project

uv venv
# Windows
.venv\Scripts\activate
# macOS/Linux
source .venv/bin/activate

uv sync
```

Create a `.env` file in the project root (never commit this file — it's already covered by `.gitignore`):

```
GEMINI_API_KEY=add-your-api-key
```

## Usage

### Run the client

```bash
uv run client.py
```

You'll see the list of tools the server exposes, then a `You:` prompt. Try:

```
You: list files in the current directory
You: create a file called notes.txt with the content "hello world"
You: change hello to goodbye in notes.txt
You: /
  1. /summarize_file - Ask the assistant to summarize the contents of a file.
  2. /clean_up_code - Ask the assistant to review and clean up a code file.
Pick a number: 1
  path: notes.txt
You: @
  1. notes.txt
  2. server.py
Pick a number: 1
Your message about this file: what's in here?
```

Type `quit` or `exit` to end the session.

### Inspect the server directly (debugging)

The MCP Python SDK ships a visual inspector for testing tools/resources/prompts without involving an LLM at all:

```bash
uv run mcp dev server.py
```

## Minimal Project structure

```
mcp-file-manager/
├── .env                # your Gemini API key (not committed)
├── pyproject.toml       # uv-managed dependencies
├── server.py            # MCP server: tools, resources, prompts
├── client.py            # MCP client: chat loop + Gemini integration
└── README.md
```

## How it works (short version)

1. `client.py` launches `server.py` as a subprocess and opens an MCP session over stdio.
2. On startup, the client fetches the server's tool list and converts it into Gemini's function-calling schema.
3. On each user message, the client sends the conversation + tool list to Gemini.
4. If Gemini responds with a function call, the client executes it against the MCP server and feeds the result back to Gemini — repeating until Gemini returns a final text answer.
5. `/` and `@` are handled entirely on the client side (never sent to Gemini as-is) — they fetch a **prompt** or **resource** directly from the MCP server and inject the result into the conversation before the normal flow above runs.

## Notes & limitations

- This is a local, single-user learning project — the file tools operate with the same permissions as whatever account runs `client.py`, so be mindful of what directory you run it from.
- `update_file`'s find-and-replace is a plain read-modify-write; it isn't safe against concurrent edits to the same file.
- The `/` command only supports single-argument prompts out of the box; extend `_handle_prompt` if you add multi-argument prompts.

## Learn more

- [Model Context Protocol docs](https://modelcontextprotocol.io/)
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
- [Gemini function calling](https://ai.google.dev/gemini-api/docs/function-calling)

## License

MIT License.