MCP 服务器

mcp-document-assistant

A local AI document assistant MCP server that enables listing, reading, and editing documents via tools, resources, and prompts, allowing LLMs to manage document workflows through natural language.

README

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:

Identify the requested document.
Retrieve the document.
Understand its contents.
Format the content using Markdown.
Preserve the original meaning.
Apply appropriate headings, lists, tables, and other Markdown structures.
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.