MCP Test Service

A complete Model Context Protocol (MCP) implementation example featuring a product search service with both MCP and REST API endpoints.

This project demonstrates how to build, test, and deploy MCP services using modern Python development practices.

Author: Chandra Shettigar (chandra@devteds.com)

🎯 What This Project Demonstrates

Complete MCP Implementation - Full JSON-RPC 2.0 protocol support
Multiple Interface Support - Both MCP protocol and REST API endpoints
Production-Ready Code - Comprehensive testing, formatting, and validation
Modern Development Environment - VS Code/Cursor devcontainer setup
Real-World Example - Product search with inventory management

📖 Related Blog Post

This code was written as a companion to the blog post: Building Your First MCP Server

The blog post covers the theory and best practices behind MCP service development, while this repository provides the complete working implementation.

🚀 Quick Start

Prerequisites

VS Code or Cursor editor
Docker installed and running
Dev Containers extension installed

1. Clone and Open

git clone git@github.com:devteds/mcp-test-service.git
cd mcp-test-service

Open in VS Code/Cursor and select "Reopen in Container" when prompted.

2. Verify Setup

python verify_setup.py

You should see:

✅ All dependencies installed and working correctly!
🚀 Your devcontainer is ready for MCP development

3. Start the MCP Service

python -m mcp_service

The service will start on http://localhost:8000

4. Test the Service

In a new terminal:

# Test MCP client
python mcp_client_example.py

# Run test suite
python -m pytest tests/ -v

# Test REST API
curl http://localhost:8000/api/v1/products/search?query=iPhone

🏗️ Project Structure

mcp-test/
├── .devcontainer/          # Development container configuration
│   ├── devcontainer.json   # VS Code/Cursor devcontainer settings
│   ├── Dockerfile          # Python development environment
│   └── bashrc              # Shell configuration with aliases
├── mcp_service/            # Main MCP service package
│   ├── __init__.py
│   ├── main.py            # FastAPI application and MCP server
│   ├── server.py          # MCP protocol implementation
│   ├── handlers.py        # MCP tool handlers
│   ├── models.py          # Pydantic data models
│   └── data.py            # Sample product database
├── tests/                  # Comprehensive test suite
│   └── test_product_service.py
├── mcp_client_example.py   # Example MCP client usage
├── verify_setup.py         # Environment verification script
├── requirements.txt        # Python dependencies
└── README.md              # This file

🔧 Development Environment

Devcontainer Features

The project includes a fully configured development environment with:

Python 3.11 with all dependencies pre-installed
VS Code Extensions: Python, Black, isort, flake8, pytest
Automatic Formatting: Code formatting on save
Port Forwarding: MCP service accessible on port 8000
Shell Aliases: Convenient commands for common tasks

Available Commands

The devcontainer includes these helpful aliases:

mcp-start      # Start the MCP service
mcp-test       # Run the test suite
mcp-client     # Run the MCP client example
mcp-format     # Format code with black and isort
mcp-verify     # Verify environment setup

🛠️ MCP Service Details

Available Tools

The MCP service provides three tools:

search_products - Search for products by name or category
get_product_details - Get detailed information about a specific product
check_inventory - Check stock levels for a product

Sample Data

The service includes sample products across three categories:

Electronics: iPhone 15 Pro, MacBook Air M3
Footwear: Nike Air Max, Adidas Ultraboost
Appliances: (expandable)

API Endpoints

MCP Protocol:

POST /api/v1/mcp - Main MCP JSON-RPC endpoint

REST API:

GET /api/v1/mcp/capabilities - Service capabilities discovery
GET /api/v1/products/search - Product search
GET /api/v1/products/{id} - Product details
GET /api/v1/products/{id}/inventory - Inventory check
GET /health - Health check
GET /docs - Interactive API documentation

🧪 Testing

Run All Tests

python -m pytest tests/ -v

Test Coverage

The test suite covers:

✅ MCP protocol message handling
✅ All MCP tool implementations
✅ REST API endpoints
✅ Error handling and edge cases
✅ Data validation and serialization

Manual Testing

# Test MCP capabilities discovery
curl http://localhost:8000/api/v1/mcp/capabilities

# Test product search
curl "http://localhost:8000/api/v1/products/search?query=iPhone"

# Test MCP client
python mcp_client_example.py

🎨 Code Quality

Formatting and Linting

The project uses:

Black for code formatting
isort for import sorting
flake8 for linting
pytest for testing

Format code:

black . && isort .

Pre-configured VS Code Settings

Format on save enabled
Organize imports on save
pytest integration
flake8 linting enabled

🔍 Verification and Troubleshooting

Environment Verification

python verify_setup.py

This script checks:

✅ All required dependencies are installed
✅ MCP SDK functionality works
✅ Service imports are successful
✅ Data functions are operational

Common Issues

Port 8000 already in use:

# Kill existing process
pkill -f "python -m mcp_service"
# Or use a different port
uvicorn mcp_service.main:app --port 8001

Dependencies missing:

# Rebuild devcontainer
# Command Palette > "Dev Containers: Rebuild Container"

Tests failing:

# Check service is running
curl http://localhost:8000/health

# Run tests with verbose output
python -m pytest tests/ -v --tb=short

📚 Learning Resources

Understanding MCP

MCP Specification: Model Context Protocol Documentation
MCP SDK: Official Python SDK
JSON-RPC 2.0: Protocol Specification

Key Concepts Demonstrated

Protocol Implementation - Complete JSON-RPC 2.0 MCP server
Tool Registration - Dynamic tool discovery and execution
Type Safety - Pydantic models for data validation
Error Handling - Proper MCP error responses
Testing Strategy - Comprehensive test coverage
Development Workflow - Modern Python development practices

🤝 Contributing

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes and ensure tests pass
Format code: black . && isort .
Run tests: python -m pytest tests/ -v
Commit changes: git commit -m 'Add amazing feature'
Push to branch: git push origin feature/amazing-feature
Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Author: Chandra Shettigar - Project creator and maintainer
Anthropic for the Model Context Protocol specification
FastAPI for the excellent web framework
Pydantic for data validation and serialization
MCP Community for tools and examples

Happy MCP Development! 🚀

For questions or issues, please open a GitHub issue or refer to the related blog post for detailed explanations.

Name		Name	Last commit message	Last commit date
Latest commit History 4 Commits
.devcontainer		.devcontainer
mcp_service		mcp_service
tests		tests
.dockerignore		.dockerignore
.gitignore		.gitignore
README.md		README.md
mcp_client_example.py		mcp_client_example.py
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt
verify_setup.py		verify_setup.py

devteds/mcp-test-service

Folders and files

Latest commit

History

Repository files navigation