Skip to main content
Glama
File Operations MCP Server

File Operations MCP Server

by fcortesj98
README.md
# Enhanced MCP Server — File Operations with Claude

A Model Context Protocol (MCP) server and command-line client that let **Claude** read, write and delete files and run guided workflows (code review and documentation generation). The project uses all three MCP primitives (**tools**, **resources** and **prompts**) and the advanced MCP Context features: **logging**, **progress reporting** and **user elicitation**.

---

## What it does

| Menu option | What happens | MCP primitive / feature |
|---|---|---|
| **1. Generate Documentation** | The server asks you for a source file and a doc name, then Claude writes a Markdown doc file with the `write_file` tool | Prompt + **elicitation** + tool + **progress** |
| **2. Review Code** | You give a file path and Claude returns a full code review | Prompt (with arguments) |
| **3. Read File** | Prints a file's content | Resource **template** `file:///{file_name}` |
| **4. Read Current Directory** | Prints a table of files and folders | Static resource `dir://.` |
| **5. Converse with Agent** | A multi-turn chat where Claude can create and delete files | Tools + agentic loop |

Every file operation is sandboxed to a base directory (by default, the folder you launch from).

## MCP in 60 seconds

MCP is a standard way for LLM applications to connect to external capabilities. Instead of a custom API per integration, a **server** registers capabilities once and any MCP **client** can use them:

- **Tools**: *model-controlled* actions that change things (`write_file`, `delete_file`). Claude decides when to call them.
- **Resources**: *application-controlled*, read-only data addressed by URI (`dir://.`, `file:///{file_name}`). A resource with parameters in its URI is a **resource template**.
- **Prompts**: *user-controlled* templates that start a workflow (`code_review`, `documentation_generator`).

Through the **`Context`** object, server code can also **log** (`ctx.info/warning/error`), **report progress** (`ctx.report_progress`) and **elicit** structured input from the user mid-call (`ctx.elicit`).

## Architecture

```mermaid
flowchart LR
    U([User]) -->|menu / chat| CLI

    subgraph Client["mcp_client"]
        CLI[cli.menu] --> F[features<br/>prompts · resources · conversation]
        F --> A[agent.ClaudeAgent<br/>tool-use loop]
        F --> C[connection.MCPClient]
        A --> C
        H[handlers<br/>elicitation · progress · messages] --- C
    end

    A <-->|Messages API| Claude[(Claude)]
    C <-->|MCP over STDIO| S

    subgraph Server["mcp_server"]
        S[app.create_server] --> T[tools<br/>write_file · delete_file]
        S --> R[resources<br/>file:///… · dir://.]
        S --> P[prompts<br/>code_review · documentation_generator]
        T & R & P --> Core[core<br/>paths sandbox · schemas]
    end

    Core --> FS[(BASE_DIR files)]
```

**Request flow for "Converse with Agent":**

1. The client fetches the server's tool list and sends it to Claude with your question.
2. If Claude answers with `tool_use`, the client calls the tool on the MCP server (e.g. `write_file`).
3. The server writes the file in chunks, sending **progress notifications** and **log messages** back to the client.
4. The tool result goes back to Claude. The loop repeats until Claude gives a final answer (capped at `CLAUDE_MAX_TOOL_ROUNDS`).

## Project structure

```
enhanced-mcp-server/
├── server.py                      # Entry point: python server.py   (thin wrapper)
├── client.py                      # Entry point: python client.py server.py
│
├── mcp_server/                    # ── MCP SERVER ─────────────────────────────
│   ├── __main__.py                # python -m mcp_server
│   ├── app.py                     # create_server(): builds FastMCP + registers everything
│   ├── config.py                  # BASE_DIR, server name, progress settings (env-driven)
│   ├── core/
│   │   ├── paths.py               # get_path() sandbox guard, read_source_file()
│   │   └── schemas.py             # DocumentGeneratorSchema (elicitation model)
│   ├── tools/
│   │   ├── __init__.py            # register_tools()
│   │   └── file_tools.py          # write_file, delete_file
│   ├── resources/
│   │   ├── __init__.py            # register_resources()
│   │   ├── file_resources.py      # file:///{file_name}  (resource template)
│   │   └── directory_resources.py # dir://.              (static resource)
│   └── prompts/
│       ├── __init__.py            # register_prompts()
│       ├── code_review.py         # code_review(file_path)
│       └── documentation.py       # documentation_generator() with elicitation
│
├── mcp_client/                    # ── MCP CLIENT ─────────────────────────────
│   ├── __main__.py                # python -m mcp_client server.py
│   ├── app.py                     # wiring + build_menu()
│   ├── config.py                  # model, max tokens, tool-round limit (env-driven)
│   ├── connection.py              # MCPClient: connect/cleanup + MCP API helpers
│   ├── handlers.py                # elicitation, progress and notification callbacks
│   ├── agent.py                   # ClaudeAgent: agentic tool-use loop
│   ├── features/
│   │   ├── prompts.py             # run_prompt()
│   │   ├── resources.py           # read_file(), read_dir()
│   │   └── conversation.py        # converse() with multi-turn history
│   └── cli/
│       ├── menu.py                # MenuItem registry + run_menu()
│       └── display.py             # directory table, prompt info
│
├── tests/                         # pytest suite (in-memory + STDIO end-to-end)
├── requirements.txt / requirements-dev.txt
├── .env.example
├── LICENSE                        # Apache 2.0
└── NOTICE                         # attribution to the original IBM lab
```

**Design principle:** one module per capability, and one small registry per primitive. Adding a feature means adding a function and one line to a list; no other file needs to change.

## Components

### Server (`mcp_server`)

| Component | Kind | Description |
|---|---|---|
| `write_file(file_path, content)` | Tool | Creates or overwrites a UTF-8 file, creating parent folders as needed. Writes in ~10 chunks and calls `ctx.report_progress` after each one. Logs success or error through `ctx`. |
| `delete_file(file_path)` | Tool | Deletes a regular file only. Directories and missing paths return a message and a `ctx.warning`. |
| `file:///{file_name}` | Resource template | Returns `{"file_content": ...}` or `{"error": ...}`. Nested paths must be URL-encoded (`file:///src%2Fapp.py`). Three slashes because `file://` expects a host, and the host here is empty (local). |
| `dir://.` | Static resource | Returns `{"items": [...]}` with `name`, `path`, `type`, `size`, `modified` and `created` for every entry in `BASE_DIR`, directories first. |
| `code_review(file_path)` | Prompt | Reads the file and builds an "expert code editor" review prompt. Its input arrives as a normal **prompt argument**. |
| `documentation_generator()` | Prompt | Has **no arguments**. It calls `ctx.elicit(...)` with `DocumentGeneratorSchema` to ask the user for `file_path` and `name`, then builds a prompt telling Claude to save the docs with the `write_file` tool under exactly that name. |
| `core.paths.get_path` | Helper | Resolves a path against `BASE_DIR` and rejects anything that escapes it (`..`, absolute paths, symlinks) with `PathOutsideBaseDirError`. |

### Client (`mcp_client`)

| Component | Responsibility |
|---|---|
| `connection.MCPClient` | Owns the FastMCP `Client` and an `AsyncExitStack`. It launches the server script over STDIO (or accepts an in-memory server) and exposes `list_tools_for_claude()`, `call_tool_text()`, `get_prompt_text()`, `read_resource_json()` and more. It works as an async context manager. |
| `handlers` | `make_elicitation_handler()` asks for each schema field in the terminal; an empty answer declines. `handle_progress()` prints percentages. `handle_message()` prints server notifications. |
| `agent.ClaudeAgent` | The agentic loop: send the query and tools to Claude, run each `tool_use` block via MCP, return the `tool_result` blocks, and repeat. Tool errors go back to Claude as `is_error` results so it can recover. |
| `features.*` | One coroutine per menu action. Each one receives its dependencies (`mcp`, `agent`, `input_fn`), so it can be tested without a terminal. |
| `cli.menu` | `MenuItem(key, label, action)` dataclass and a generic `run_menu()` loop. |

## Setup

**Requirements:** Python 3.10+ and an [Anthropic API key](https://console.anthropic.com/) for the Claude-powered options (1, 2 and 5). Options 3 and 4 work without a key.

```bash
# 1. Get the code
git clone <your-repo-url> enhanced-mcp-server
cd enhanced-mcp-server

# 2. Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate

# 3. Install dependencies
pip install -r requirements.txt    # add -dev to also install pytest

# 4. Add your API key
cp .env.example .env
#   then edit .env:  ANTHROPIC_API_KEY=sk-ant-...
```

## Configuration

All settings are optional environment variables (or `.env` entries):

| Variable | Default | Used by | Purpose |
|---|---|---|---|
| `ANTHROPIC_API_KEY` | — | client | Required for options 1, 2 and 5 |
| `CLAUDE_MODEL` | `claude-sonnet-5` | client | Claude model ID (the lab's default) |
| `CLAUDE_MAX_TOKENS` | `4096` | client | Max tokens per response |
| `CLAUDE_MAX_TOOL_ROUNDS` | `10` | client | Safety cap on tool-use iterations per query |
| `MCP_BASE_DIR` | current directory | server | Sandbox root for all file operations |
| `MCP_SERVER_NAME` | `File Operations MCP Server` | server | Name advertised to clients |
| `MCP_WRITE_PROGRESS_STEPS` | `10` | server | Number of progress updates per `write_file` |
| `MCP_WRITE_PROGRESS_DELAY` | `0.05` | server | Pause between chunks (makes progress visible) |

## How to use it

From the project root:

```bash
python client.py server.py
# equivalent: python -m mcp_client server.py
```

The client starts the server as a subprocess and talks to it over STDIO:

```
MCP Client Started!
Select from the menu or 'quit'/'q' to exit.

Select from the Menu
1. Generate Documentation
2. Review Code
3. Read File
4. Read Current Directory
5. Converse with Agent
q. Quit
>
```

The server's own logs (FastMCP banner, `Server log: ...` lines) go to **stderr**, so they appear in the same terminal without breaking the protocol stream.

To run the server on its own (for example, for another MCP client):

```bash
python server.py           # or: python -m mcp_server
```

## Usage examples

### Read a file (resource template)

```
> 3
Enter file path: mcp_server/core/schemas.py
File Content:
 """Pydantic schemas used for structured user elicitation."""
...
```

A path outside the sandbox or a missing file prints the server's error message, for example `Error: missing.py is not a valid file`.

### List the directory (static resource)

```
> 4

Directory Listing:

Type                Size  Modified                   Name
---------------------------------------------------------------------------
📁  directory     4096 B  2026-11-16T16:32:05.325197 mcp_client
📁  directory     4096 B  2026-11-16T16:32:03.956165 mcp_server
📄  file           256 B  2026-11-16T16:31:20.670860 client.py
📄  file           288 B  2026-11-16T16:31:19.578860 server.py
```

### Review code (prompt with arguments)

```
> 2

Prompt: code_review
  Generate a prompt asking Claude for a code review of a file.
  Arguments: file_path
file_path (required): mcp_client/agent.py
Received: notifications/message
<Claude's review: strengths, issues, suggestions...>
```

### Generate documentation (prompt + elicitation + tool + progress)

```
> 1

Prompt: documentation_generator
  Generate a prompt asking Claude to write a documentation file.
  Arguments: none (the server may ask for inputs via elicitation)
Server asks: Please provide the subject file name and the documentation file name
Enter value for 'file_path' (str): mcp_server/tools/file_tools.py
Enter value for 'name' (str): FILE_TOOLS_DOCS
Received: notifications/message
Progress: 10.0% - Writing progress: 312/3120
Progress: 20.0% - Writing progress: 624/3120
...
Progress: 100.0% - Write complete
<Claude: "I've created FILE_TOOLS_DOCS.md documenting write_file and delete_file...">
```

Leave any field empty to **decline** the elicitation. The server then cancels the prompt.

### Converse with the agent (tools + agentic loop)

```
> 5

Entering conversation mode. Type 'quit' or 'q' to exit.

Query: Create notes/todo.md with a checklist for adding a new MCP tool
Progress: 10.0% - Writing progress: 41/415
...
<Claude confirms it created notes/todo.md>

Query: Now delete it
<Claude calls delete_file and confirms>

Query: q
```

## Testing

```bash
pip install -r requirements-dev.txt
pytest -q
```

The suite (21 tests) needs **no API key**:

- `tests/test_server.py` covers every tool, resource and prompt through an in-memory FastMCP client, plus progress reporting, elicitation (accept and decline) and sandbox escapes.
- `tests/test_client.py` runs the agent loop against a scripted fake Claude (tool calls, tool errors, round limit, conversation history), tests the features and the menu, and includes a real **STDIO end-to-end** run of `python client.py server.py`.

## License

Licensed under the **Apache License 2.0**, the same license as the original IBM lab content. See [`LICENSE`](LICENSE) and [`NOTICE`](NOTICE).

Original lab: *Build an Enhanced MCP Server*, IBM Skills Network, from the **IBM RAG and Agentic AI Professional Certificate**. Authors: Abdul Fatir, Joshua Zhou, Joseph Santarcangelo. Original code: <https://github.com/joshuazhou744/enhanced-mcp-server>.