MCP Document Assistant

A local AI document assistant demonstrating the Model Context Protocol (MCP) using Python, FastMCP, Ollama, and Qwen3:4B.

This project was developed while studying Anthropic's Introduction to Model Context Protocol course. The original course examples use Claude; this implementation explores the same MCP concepts using a locally hosted Qwen3:4B model through Ollama.

---

Overview

The project demonstrates how an AI application can communicate with external capabilities through the Model Context Protocol.

The implementation contains:

• An MCP server built with FastMCP
• An MCP client
• MCP tools
• MCP resources
• MCP prompts
• A local Qwen3:4B model running through Ollama
• An interactive command-line interface
• MCP Inspector for testing and debugging

The document assistant uses a simple in-memory document store to demonstrate how an LLM can discover, retrieve, modify, and work with external information through MCP.

---

Architecture

                         ┌───────────────────┐
                         │       User        │
                         │   CLI Interface   │
                         └─────────┬─────────┘
                                   │
                                   ▼
                         ┌───────────────────┐
                         │     Qwen3:4B      │
                         │      Ollama       │
                         └─────────┬─────────┘
                                   │
                                   ▼
                         ┌───────────────────┐
                         │     MCP Client    │
                         │                   │
                         │  Tools            │
                         │  Resources        │
                         │  Prompts          │
                         └─────────┬─────────┘
                                   │
                              MCP / STDIO
                                   │
                                   ▼
                         ┌───────────────────┐
                         │     MCP Server    │
                         │      FastMCP      │
                         └─────────┬─────────┘
                                   │
                    ┌──────────────┼──────────────┐
                    │              │              │
                    ▼              ▼              ▼
                 Tools         Resources       Prompts
                    │              │              │
                    └──────────────┼──────────────┘
                                   │
                                   ▼
                         ┌───────────────────┐
                         │   Document Store  │
                         └───────────────────┘

---

MCP Tools

The MCP server exposes three document-related tools.

list_documents

Returns a list of all available document IDs.

read_document

Reads the contents of a document using its document ID.

edit_document

Updates the contents of an existing document.

Tool Workflow

User Request
     │
     ▼
Qwen3
     │
     ▼
MCP Client
     │
     ▼
MCP Server
     │
     ▼
Tool Execution
     │
     ▼
Tool Result
     │
     ▼
Qwen3
     │
     ▼
Final Response

---

MCP Resources

The MCP server exposes document resources:

docs://documents
docs://documents/{doc_id}

docs://documents

Returns the list of available document IDs.

docs://documents/{doc_id}

Returns the contents of a specific document.

Tools vs Resources

The project demonstrates the distinction between MCP tools and resources.

Tools perform actions or operations:

list_documents
read_document
edit_document

Resources provide data or contextual information:

docs://documents
docs://documents/{doc_id}

In simple terms:

MCP Primitive	Purpose
Tools	Perform actions
Resources	Provide data/context
Prompts	Provide reusable instructions/workflows

---

MCP Prompts

The project also demonstrates MCP prompts.

A prompt is a reusable instruction or workflow exposed by the MCP server.

For example:

/format report.pdf

A formatting workflow can instruct the model to:

1. Identify the requested document.
2. Retrieve the document.
3. Understand its contents.
4. Format the content using Markdown.
5. Preserve the original meaning.
6. Apply appropriate headings, lists, tables, and other Markdown structures.
7. Update the document when required.

The purpose is to demonstrate how MCP prompts can provide standardized workflows to an AI application.

---

Example Documents

The demonstration server contains:

deposition.md
report.pdf
financials.docx
outlook.pdf
plan.md
spec.txt

For demonstration purposes, these documents are represented using an in-memory Python dictionary.

---

Example Interaction

List Available Documents

> list the available documents

Response:
deposition.md
report.pdf
financials.docx
outlook.pdf
plan.md
spec.txt

Reference a Document

> What does @plan.md say?

Response:
The plan outlines the steps for the project's implementation.

The @ syntax allows the user to reference a document directly from the CLI.

Read and Summarize a Document

> Read plan.md and summarize it.

The application retrieves the document and provides its contents to the model so that the model can generate a response.

---

Local LLM with Ollama

This implementation uses:

Qwen3:4B

through:

Ollama

The model runs locally instead of requiring a cloud-hosted LLM API.

The relationship is:

Qwen3:4B
    │
    ▼
  Ollama
    │
    ▼
MCP-enabled Application
    │
    ▼
MCP Client
    │
    ▼
MCP Server

Check installed models:

ollama list

Pull Qwen3:4B if necessary:

ollama pull qwen3:4b

---

Claude vs Qwen3

The original Anthropic course examples use Claude.

This implementation uses Qwen3:4B through Ollama to demonstrate that MCP is not inherently tied to Claude.

Course Architecture

Claude
  │
  ▼
MCP Client
  │
  ▼
MCP Server

Local Implementation

Qwen3:4B
  │
  ▼
Ollama
  │
  ▼
MCP Client
  │
  ▼
MCP Server

The important concept is that the LLM, MCP client, and MCP server are separate components.

The MCP server can therefore provide capabilities independently of the underlying model provider.

---

MCP Inspector

MCP Inspector is a graphical development and debugging interface for MCP servers.

It can be used to inspect:

• Server connectivity
• Available tools
• Tool descriptions
• Tool input schemas
• Tool calls
• Tool results
• Resources
• Resource contents
• Prompts
• Prompt arguments

Start MCP Inspector with:

uv run mcp dev mcp_server.py

The command starts the Inspector and provides a local browser URL.

The Inspector was used during development to verify that the MCP server correctly exposes its capabilities.

---

Project Structure

mcp-document-assistant/
│
├── core/
│   ├── __init__.py
│   ├── chat.py
│   ├── claude.py
│   ├── cli.py
│   ├── cli_chat.py
│   ├── ollama.py
│   └── tools.py
│
├── main.py
├── mcp_client.py
├── mcp_server.py
├── pyproject.toml
├── uv.lock
├── README.md
└── .gitignore

---

Main Components

mcp_server.py

Defines the MCP server using FastMCP.

The server contains:

• Document data
• MCP tools
• MCP resources
• MCP prompts

mcp_client.py

Implements the MCP client.

The client handles:

• Starting the MCP server process
• Establishing the MCP transport
• Initializing the MCP session
• Listing available tools
• Calling tools
• Listing prompts
• Retrieving prompts
• Reading resources
• Closing the MCP connection

core/chat.py

Contains the main chat workflow.

The general workflow is:

User Query
    │
    ▼
LLM
    │
    ▼
Tool Request
    │
    ▼
MCP Client
    │
    ▼
MCP Server
    │
    ▼
Tool Result
    │
    ▼
LLM
    │
    ▼
Final Response

core/tools.py

Manages MCP tool discovery and execution.

It handles:

• Tool discovery
• Finding the appropriate MCP client
• Tool execution
• Processing tool results

core/cli_chat.py

Provides document-specific chat functionality.

It handles:

• Document references using @
• MCP resources
• MCP prompts
• Document retrieval
• Prompt processing

core/cli.py

Provides the interactive command-line interface.

It includes:

• Command completion
• Resource completion
• Prompt completion
• Command history
• Keyboard bindings
• Interactive chat

core/ollama.py

Provides the local Ollama model integration used by the application.

---

Requirements

• Python 3.10+
• uv
• Ollama
• Qwen3:4B
• MCP Python SDK
• prompt-toolkit
• python-dotenv

---

Installation

Clone the repository:

git clone https://github.com/SamamaSaleem/mcp-document-assistant.git
cd mcp-document-assistant

Install dependencies:

uv sync

Pull Qwen3:4B:

ollama pull qwen3:4b

Verify the model:

ollama list

Expected model:

qwen3:4b

---

Running the Application

From the project directory:

uv run main.py

The application provides an interactive CLI.

Example:

> list the available documents

Response:
deposition.md
report.pdf
financials.docx
outlook.pdf
plan.md
spec.txt

Reference a document:

> What does @plan.md say?

Ask the assistant to retrieve and summarize a document:

> Read plan.md and summarize it.

---

Running MCP Inspector

To inspect the MCP server independently:

uv run mcp dev mcp_server.py

MCP Inspector provides a graphical interface for testing the server's MCP capabilities.

The server exposes:

Tools
├── list_documents
├── read_document
└── edit_document

Resources
├── docs://documents
└── docs://documents/{doc_id}

Prompts
└── format

---

Learning Objectives

This project was built to gain practical understanding of:

• Model Context Protocol
• MCP client/server architecture
• FastMCP
• MCP tools
• MCP resources
• MCP prompts
• Tool discovery
• Tool execution
• Resource discovery
• Resource retrieval
• Prompt retrieval
• Prompt-based workflows
• MCP Inspector
• Local LLM inference
• Ollama
• Qwen3
• Async Python
• uv
• LLM tool calling

---

Key Architectural Takeaway

The most important concept demonstrated by this project is the separation between the LLM, MCP client, and MCP server.

The LLM provides reasoning and language understanding.

The MCP client provides the connection between the AI application and MCP servers.

The MCP server exposes capabilities through standardized MCP primitives.

                    LLM
                     │
                     │ reasoning / tool selection
                     ▼
                MCP Client
                     │
                     │ MCP communication
                     ▼
                MCP Server
                     │
          ┌──────────┼──────────┐
          │          │          │
          ▼          ▼          ▼
        Tools    Resources    Prompts
          │          │          │
          └──────────┼──────────┘
                     │
                     ▼
              External Data
              / Capabilities

This separation allows MCP servers to be used independently of a particular model provider.

---

Course

This project was developed while completing:

Introduction to Model Context Protocol (MCP)

Anthropic Academy

The course provided the conceptual and practical foundation for the MCP components demonstrated in this repository.

The project also explores adapting the course architecture to a local Qwen3:4B model through Ollama.

---

Status

Educational / Portfolio Project

The current implementation demonstrates MCP concepts using:

Python
FastMCP
MCP Client
MCP Server
Qwen3:4B
Ollama
MCP Inspector

The document store is currently implemented in memory for demonstration purposes.

---

Future Improvements

Potential future improvements include:

• Persistent document storage
• Real PDF parsing
• Real DOCX parsing
• File-system based MCP resources
• Additional document manipulation tools
• Streaming responses
• Multiple MCP servers
• Database MCP tools
• Search MCP tools
• Web MCP tools
• RAG integration
• Vector database integration
• Persistent conversation history
• More advanced agentic workflows
• MCP authentication and authorization
• Support for additional local LLMs
• Support for cloud-hosted LLM providers

---

License

This project is intended for educational and portfolio purposes.