MCPs

Think of MCP like the 𝐔𝐒𝐁-𝐂 𝐩𝐨𝐫𝐭 𝐨𝐧 𝐚 𝐥𝐚𝐩𝐭𝐨𝐩. Any device that wants to connect, whether it’s an external hard drive, monitor, or power supply, must follow the USB-C standard. Similarly, MCP is a standardized protocol developed by Anthropic that defines how 𝐋𝐋𝐌𝐬 𝐜𝐨𝐧𝐧𝐞𝐜𝐭 𝐭𝐨 𝐜𝐨𝐧𝐭𝐞𝐱𝐭𝐬 𝐚𝐧𝐝 𝐝𝐚𝐭𝐚 𝐬𝐨𝐮𝐫𝐜𝐞𝐬.

The laptop = MCP host The USB-C port = MCP itself The monitor, hard drive, power supply = MCP servers

For more understanding of MCPs, visit https://medium.com/@BH_Chinmay/basics-of-mcps-why-and-what-9579c21caac4

Utility MCP Server

A Model Context Protocol (MCP) server that provides AI-powered document processing and search capabilities.

Overview

This project implements an MCP server with tools for:

• PDF Document Processing: Extract text, metadata, and statistics from PDF files
• Document Summarization: Use Azure OpenAI to generate intelligent summaries of documents and pages
• Web Search: Perform Google searches and retrieve top results

Architecture

MCPs/
├── mcp-servers/              # MCP server entrypoint and tools
│   ├── server.py             # Server initialization and tool registration
│   ├── mcp_instance.py       # FastMCP instance with logging configuration
│   └── tools/                # Tool implementations
│       ├── document_summerizer.py  # PDF summarization tools
│       ├── google_search.py        # Web search tool
│       └── pdf_reader.py           # Basic PDF reading tool
├── utils/                    # Shared utility modules
│   ├── llm_utils.py          # Azure OpenAI integration
│   └── pdf_utils.py          # PDF processing utilities
├── requirements.txt          # Python dependencies
├── .env                      # Environment variables (secrets)
└── README.md                 # This file

Tools

Document Summarization Tools (tools/document_summerizer.py)

summarize_document(pdf_path)

Analyzes a complete PDF document and generates an intelligent summary.

• Extracts all text from the PDF
• Splits content into manageable chunks
• Summarizes each chunk using Azure OpenAI
• Generates a final summary from partial summaries
• Returns: File path, page count, chunk count, and final summary

summarize_page(pdf_path, page_number)

Generates a summary for a specific page in a PDF.

• Extracts text from the specified page
• Processes through Azure OpenAI
• Returns: Page number and page summary

extract_document_text(pdf_path)

Extracts all text content from a PDF without summarization.

• Returns: Full text content

document_statistics(pdf_path)

Calculates text statistics for a document.

• Returns: Character count, word count, and line count

document_metadata(pdf_path)

Retrieves metadata from a PDF document.

• Returns: Page count, title, author, creator, and producer

Google Search Tool (tools/google_search.py)

google_search(query, num_results)

Performs a Google search and returns top results.

• Uses Google Custom Search API
• Parameters:
  • query: Search query string
  • num_results: Number of results to return (default: 5)
• Returns: List of results with title, link, and snippet

PDF Reader Tool (tools/pdf_reader.py)

read_pdf(pdf_path)

Basic PDF text extraction tool.

• Reads and returns all text from a PDF
• Returns: Extracted text content

Utilities

LLM Utilities (utils/llm_utils.py)

Handles Azure OpenAI integration:

• _get_client(): Initializes Azure OpenAI client with environment configuration
• llm_summary(text): Sends text to Azure OpenAI for summarization

PDF Utilities (utils/pdf_utils.py)

Core PDF processing functions:

• extract_text(pdf_path): Extracts all text from a PDF
• chunk_text(text, chunk_size): Splits text into chunks
• get_metadata(pdf_path): Extracts PDF metadata
• get_page_text(pdf_path, page_number): Extracts text from a specific page

Configuration

Environment Variables (.env)

The application requires the following environment variables:

Google Search Configuration:

GOOGLE_API_KEY=<your-google-api-key>
GOOGLE_SEARCH_ENGINE_ID=<your-search-engine-id>

Azure OpenAI Configuration:

AZURE_OPENAI_ENDPOINT=<your-azure-endpoint>
AZURE_OPENAI_API_KEY=<your-azure-api-key>
AZURE_OPENAI_API_VERSION=<api-version>
AZURE_OPENAI_DEPLOYMENT=<deployment-name>

Important: Never commit .env with actual credentials to version control.

Setup and Installation

Prerequisites

• Python 3.10+
• Virtual environment (recommended)

Installation

1. Create a virtual environment:

python -m venv .venv

2. Activate the virtual environment:

# Windows
.venv\Scripts\activate

# macOS/Linux
source .venv/bin/activate

3. Install dependencies:

pip install -r requirements.txt

4. Create and configure .env:

cp .env.example .env
# Edit .env and add your API credentials

Running the Server

Development Mode

cd mcp-servers
mcp dev server.py

Production Mode

cd mcp-servers
python server.py

Logging

The application uses Python's built-in logging module with the following configuration:

• Level: INFO (use DEBUG for detailed output)
• Format: YYYY-MM-DD HH:MM:SS - logger_name - LEVEL - message
• Security: All credentials and API keys are masked in logs

Log Levels

• DEBUG: Detailed operation information (page extraction, chunk processing)
• INFO: Normal operation events (tool invocations, completion status)
• WARNING: Warning messages (invalid page numbers, missing configuration)
• ERROR: Error events with full exception tracebacks

Enabling Debug Logging

To see more detailed logs during development:

import logging
logging.getLogger().setLevel(logging.DEBUG)

Dependencies

• mcp (1.28.1+): Model Context Protocol framework
• openai (1.0.0+): Azure OpenAI client
• python-dotenv: Environment variable management
• httpx (0.27.0+): Async HTTP client for Google Search API
• PyMuPDF (1.24.0+): PDF text extraction

See requirements.txt for complete list.

Error Handling

All tools include comprehensive error handling:

• File existence validation before processing
• Exception logging with full tracebacks
• User-friendly error messages in responses
• No sensitive data logged in error messages

Security Considerations

1. Credentials: Store all API keys and endpoints in .env file
2. Logging: Credentials are never logged or printed
3. Environment: Use separate .env files for different environments (dev, staging, production)
4. Access: Restrict access to .env file permissions (never commit to version control)

Development Notes

Adding New Tools

1. Create a new file in tools/ directory
2. Import and register with @mcp.tool() decorator
3. Add comprehensive logging with logger.info() and logger.error()
4. Document the tool in this README

Code Style

• Use descriptive variable names
• Include docstrings for all functions
• Log important operations and errors
• Never log sensitive information (API keys, authentication tokens)

Troubleshooting

Import Errors

If you encounter ModuleNotFoundError:

1. Ensure virtual environment is activated
2. Run pip install -r requirements.txt
3. Check that Python path includes both mcp-servers/ and project root directories

Missing Environment Variables

If you see "Missing Azure OpenAI environment variables":

1. Verify .env file exists in the project root
2. Check that all required variables are set (not empty)
3. Restart the server after updating .env

PDF Processing Issues

• Ensure PDF file exists and is readable
• Check that PyMuPDF (fitz) is properly installed
• Verify sufficient disk space for large PDF files

Support

For issues or questions, please refer to the logging output for detailed error information.