Perception Tools MCP Server - Project Summary¶

Overview¶

A comprehensive MCP (Model Context Protocol) server implementing 18 perception tools organized into 5 categories, following SOLID principles with a modular architecture.

Implementation Details¶

Architecture¶

The project follows the Single Responsibility Principle with separate modules for each tool category:

perception-tools/
├── src/
│   ├── base.py                  # Shared models and utilities
│   ├── search_tools.py          # Search functionality (3 tools)
│   ├── multimodal_tools.py      # Multimodal understanding (4 tools)
│   ├── filesystem_tools.py      # File operations (3 tools)
│   ├── public_data_tools.py     # Public APIs (6 tools)
│   ├── private_data_tools.py    # Private data sources (2 tools)
│   └── main.py                  # MCP server entry point
├── requirements.txt             # Dependencies
├── env.example                  # Configuration template
├── quickstart.py                # Demo script
├── test_imports.py              # Module verification
├── README.md                    # User documentation
├── SETUP.md                     # Setup instructions
└── TOOL_REFERENCE.md            # Complete API reference

Design Principles Applied¶

KISS (Keep It Simple, Stupid)¶

Each tool has a single, clear purpose
Simple async function signatures
Straightforward error handling

DRY (Don't Repeat Yourself)¶

Common utilities in base.py (ActionResponse, file validation, URL downloading)
Shared error handling patterns
Reusable Pydantic models

SOLID Principles¶

Single Responsibility: - Each module handles one category of tools - Base module provides shared functionality only - Tools have single, well-defined purposes

Open/Closed: - Easy to add new tools without modifying existing code - Extensible through new modules - MCP decorator pattern allows non-invasive tool registration

Liskov Substitution: - All tools return consistent ActionResponse format - Uniform error handling across all tools

Interface Segregation: - Tools expose only necessary parameters - Optional parameters with sensible defaults - No forced dependencies on unused features

Dependency Inversion: - Tools depend on abstractions (ActionResponse, TextContent) - External services accessed through interfaces - Configuration via environment variables

Tool Categories¶

1. Search Tools (3 tools)¶

web_search: Google Custom Search integration
download: HTTP/HTTPS file downloads with safety checks
knowledge_base_search: Local document search

2. Multimodal Understanding Tools (4 tools)¶

webpage_reader: HTML content extraction
document_reader: PDF/DOCX/PPTX processing
image_parser: Image analysis with PIL
video_parser: Video metadata extraction with OpenCV

3. File System Tools (3 tools)¶

file_reader: File reading with encoding support
grep: Regex pattern search in files
text_summarizer: Text summarization (extractive/LLM)

4. Public Data Source Tools (6 tools)¶

weather: OpenWeather API integration
stock_price: Yahoo Finance data
currency_converter: Exchange rate conversion
wikipedia_search: Wikipedia API wrapper
arxiv_search: Academic paper search
wayback_search: Internet Archive access

5. Private Data Source Tools (2 tools)¶

calendar_events: Google Calendar OAuth2 integration
notion_search: Notion API wrapper

Key Features¶

Error Handling¶

Consistent error response format
Detailed error types for debugging
Graceful degradation when services unavailable

Configuration Management¶

Environment variable based configuration
Template file for easy setup
Optional dependencies clearly marked

Response Format¶

All tools return standardized JSON responses:

{
  "success": true/false,
  "message": "Result data or error message",
  "metadata": {
    "additional": "context information"
  }
}

Safety Features¶

File size limits for downloads
Timeout controls for network operations
Path validation to prevent directory traversal
URL validation for external requests

Testing¶

Import Verification¶

python test_imports.py

Functional Testing¶

python quickstart.py

Manual MCP Server Testing¶

cd src && python main.py

Dependencies¶

Core¶

mcp: MCP server framework
pydantic: Data validation
python-dotenv: Configuration management
requests: HTTP client

Document Processing¶

PyPDF2: PDF parsing
python-docx: Word documents
python-pptx: PowerPoint presentations
Pillow: Image processing
opencv-python: Video processing

Web Scraping¶

beautifulsoup4: HTML parsing
lxml: XML/HTML parser

Data Sources¶

wikipedia: Wikipedia API
arxiv: ArXiv API

Optional¶

Google Calendar: google-auth-*, google-api-python-client
Notion: notion-client

Configuration Requirements¶

Required for Full Functionality¶

GOOGLE_API_KEY: For web search
GOOGLE_CSE_ID: For web search
OPENWEATHER_API_KEY: For weather data

Optional¶

NOTION_API_KEY: For Notion integration
Google OAuth2 credentials: For Calendar integration

Performance Considerations¶

Default timeouts: 30-180 seconds depending on operation
File size limits: 100MB for downloads, 500MB for videos
Text truncation: 50,000 characters for file reading
Result limits: Configurable per tool (typically 5-10 items)

Future Enhancements¶

Potential additions: 1. LLM-based summarization integration 2. Image analysis with vision APIs 3. Video frame extraction and analysis 4. Database search integration 5. Email integration (Gmail, Outlook) 6. Slack/Discord integration 7. GitHub API integration 8. Real-time data streaming support

MCP Integration¶

The server uses the MCP SDK v2 MCPServer with stdio transport, making it compatible with: - Claude Desktop - Other MCP-compatible clients - Custom integration via stdio communication

Documentation¶

Comprehensive documentation provided: - README.md: Overview and quick start - SETUP.md: Detailed setup instructions - TOOL_REFERENCE.md: Complete API reference for all 18 tools - PROJECT_SUMMARY.md: This file

Code Quality¶

Type hints throughout
Comprehensive docstrings
Consistent formatting
Error handling at all levels
Logging for debugging

Maintenance¶

To add new tools: 1. Create function in appropriate module 2. Follow existing patterns (async, ActionResponse) 3. Register in main.py with @mcp.tool decorator 4. Update documentation

Success Metrics¶

✅ 18 tools implemented across 5 categories ✅ Modular architecture following SOLID principles ✅ Comprehensive error handling ✅ Complete documentation ✅ Easy configuration and setup ✅ MCP-compatible server ready for production use

Status¶

Implementation: Complete Documentation: Complete Testing Framework: Complete Ready for Use: Yes (with dependency installation)