# 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

```text
                         ┌───────────────────┐
                         │       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

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

---

## MCP Resources

The MCP server exposes document resources:

```text
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:

```text
list_documents
read_document
edit_document
```

**Resources** provide data or contextual information:

```text
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:

```text
/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:

```text
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

```text
> list the available documents

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

### Reference a Document

```text
> 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

```text
> 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:

```text
Qwen3:4B
```

through:

```text
Ollama
```

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

The relationship is:

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

Check installed models:

```bash
ollama list
```

Pull Qwen3:4B if necessary:

```bash
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

```text
Claude
  │
  ▼
MCP Client
  │
  ▼
MCP Server
```

### Local Implementation

```text
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:

```bash
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

```text
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:

```text
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:

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

Install dependencies:

```bash
uv sync
```

Pull Qwen3:4B:

```bash
ollama pull qwen3:4b
```

Verify the model:

```bash
ollama list
```

Expected model:

```text
qwen3:4b
```

---

## Running the Application

From the project directory:

```bash
uv run main.py
```

The application provides an interactive CLI.

Example:

```text
> list the available documents

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

Reference a document:

```text
> What does @plan.md say?
```

Ask the assistant to retrieve and summarize a document:

```text
> Read plan.md and summarize it.
```

---

## Running MCP Inspector

To inspect the MCP server independently:

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

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

The server exposes:

```text
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.

```text
                    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:

```text
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.