# DocumentMCP Server & Client (Advanced)

A Model Context Protocol (MCP) project written in Python. This codebase is the combination of the two following courses:
- [Introduction to Model Context Protocol](https://academy.claude.com/courses/introduction-to-model-context-protocol)
- [Model Context Protocol Advanced Topics](https://academy.claude.com/courses/model-context-protocol-advanced-topics)

It includes an **MCP Server** that provides tools to interact with documents and the filesystem, and a **Python MCP Client** that demonstrates advanced MCP capabilities such as Sampling, Roots, Progress Reporting, and Logging.

> [!NOTE]
> **Deprecation Notice (SEP-2577)**: As of July 28, 2026, the **Sampling**, **Roots**, and **Logging** capabilities have been officially deprecated in the MCP specification. 
> - This repository intentionally retains these features in `mcp_server.py` and `mcp_client.py` for educational purposes (with deprecation warnings suppressed). 
> - In contrast, the basic `server.py` and `client.py` examples have been updated to demonstrate the modern approach of using `sys.stderr` for logging instead of the protocol's logging capability.

## Features

### Server
- **Tools**:
  - **Read Documents** (`read_doc_contents`): Retrieve the contents of a specific document by its ID.
  - **Edit Documents** (`edit_document`): Perform find-and-replace operations on document contents.
  - **Summarize** (`summarize`): Uses the Sampling capability to ask the client to summarize text via an LLM.
  - **Research** (`research`): A simulated long-running task that uses Progress Reporting and Logging to keep the client updated.
  - **List Roots** (`list_roots`): Retrieves a list of allowed root directories exposed by the client.
  - **Read Directory** (`read_dir`): Reads the contents of a directory, restricting access to client-approved Roots.
- **Resources**:
  - List available documents.
  - Fetch specific document contents via URI.
- **Prompts**:
  - **Format**: Prompt template to help rewrite a document in Markdown format.

### Client
- Connects to the local MCP Server using standard I/O (stdio).
- Implements **Callbacks** for advanced server capabilities:
  - **Sampling**: Resolves LLM completion requests initiated by the server.
  - **Logging**: Receives and prints server logs.
  - **Progress**: Receives and displays progress updates for long-running server tools.
  - **Roots**: Exposes specified local directories to the server.
- Includes a basic `client.py` and a full-featured `mcp_client.py`.

## Mock Documents

The server comes with the following mock documents pre-configured:
- `deposition.md`
- `report.pdf`
- `financials.docx`
- `outlook.pdf`
- `plan.md`
- `spec.txt`

## Prerequisites

- Python 3.8+
- [mcp](https://pypi.org/project/mcp/) package installed

## Setup

1. Clone or download this repository.
2. Create and activate a virtual environment (recommended):
   ```bash
   python -m venv venv
   source venv/bin/activate
   ```
3. Install the required dependencies:
   ```bash
   pip install -r requirements.txt
   ```

## Usage

### Running the Full Client

The included `mcp_client.py` script starts the MCP Server, connects to it, lists its tools, and tests the advanced tools (`summarize`, `research`, `list_roots`). 

You can provide root directories as command-line arguments to expose them to the server:

```bash
python mcp_client.py /path/to/some/directory /another/directory
```

### Running the Basic Client and Server

A minimal client (`client.py`) and a minimal server (`server.py`) are also provided to demonstrate a simple tool execution with progress tracking.

```bash
python client.py
```

### Inspecting the Server

You can test and inspect the server interactively using the official MCP Inspector. 

With your virtual environment active, run:

```bash
npx @modelcontextprotocol/inspector python mcp_server.py
```

## Integration with MCP Agents

You can configure this MCP server to be used with any compatible MCP client or agent (such as Claude Desktop, Cursor, Antigravity, etc.).

1. Locate your agent's MCP configuration file.
2. Add the following configuration, providing the **absolute paths**:

   ```json
   {
     "mcpServers": {
       "my-document-server": {
         "command": "/absolute/path/to/your/project/venv/bin/python",
         "args": [
           "/absolute/path/to/your/project/mcp_server.py"
         ]
       }
     }
   }
   ```
3. Restart your agent or client.