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

• 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.

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.

Related MCP server: mcp-document-chat

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 package installed

Setup

1. Clone or download this repository.

2. Create and activate a virtual environment (recommended):

   python -m venv venv
   source venv/bin/activate

3. Install the required dependencies:

   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:

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.

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:

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:

   {
     "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.