Petstore MCP Server & Client

A comprehensive Model Context Protocol (MCP) implementation for the Swagger Petstore API. This project includes both a complete MCP server and a sophisticated client system for seamless agent integration.

Overview

This project provides:

MCP Server: Complete implementation of all Petstore API endpoints
MCP Client: High-level client with agent-friendly interfaces
Agent Integration: Ready-to-use components for AI agents
Configuration Management: Flexible configuration system
Prompt Templates: Pre-built prompts for different scenarios

Related MCP server: Swagger MCP Server

Project Structure

petstore/ ├── openapi.yaml # OpenAPI 3.0 specification ├── petstore-mcp-server.py # MCP server implementation ├── petstore_mcp_client.py # Comprehensive MCP client ├── agent_interface.py # High-level agent interface ├── transport.py # MCP transport layer ├── prompt_manager.py # Prompt template management ├── sampling.py # AI model sampling configurations ├── client_config.py # Configuration management ├── requirements.txt # Server dependencies ├── client_requirements.txt # Client dependencies ├── mcp-server-config.json # MCP server configuration ├── example_usage.py # Usage examples ├── test_server.py # Server testing script ├── setup.sh # Setup script └── README.md # This documentation

MCP Server

Features

The MCP server provides comprehensive access to the Petstore API with 19 tools across three categories:

Pet Management (8 tools)

add_pet: Add a new pet to the store
update_pet: Update an existing pet
get_pet_by_id: Find pet by ID
find_pets_by_status: Find pets by status (available, pending, sold)
find_pets_by_tags: Find pets by tags
update_pet_with_form: Update a pet using form data
delete_pet: Delete a pet
upload_pet_image: Upload an image for a pet

Store Operations (4 tools)

get_inventory: Get pet inventories by status
place_order: Place an order for a pet
get_order_by_id: Find purchase order by ID
delete_order: Delete purchase order by ID

User Management (7 tools)

create_user: Create a new user
create_users_with_list: Create multiple users from a list
login_user: Log user into the system
logout_user: Log out current user session
get_user_by_name: Get user by username
update_user: Update user information
delete_user: Delete a user

Server Installation

Install server dependencies:
pip3 install -r requirements.txt
Make the server executable:
chmod +x petstore-mcp-server.py
Or run the setup script:
bash setup.sh

Server Configuration

For Amazon Q CLI

Add the server to your MCP configuration:

{ "mcpServers": { "petstore": { "command": "python3", "args": ["petstore-mcp-server.py"], "cwd": "/path/to/petstore", "env": {} } } }

Running the Server

# Direct execution python3 petstore-mcp-server.py # With Amazon Q CLI q chat --mcp-server petstore

Server API Examples

Pet Management

Add a new pet:

{ "pet": { "name": "Buddy", "photoUrls": ["https://example.com/buddy.jpg"], "category": { "id": 1, "name": "Dogs" }, "tags": [ { "id": 1, "name": "friendly" } ], "status": "available" } }

Find pets by status:

{ "status": "available" }

Store Operations

Place an order:

{ "order": { "petId": 123, "quantity": 1, "shipDate": "2024-12-01T10:00:00Z", "status": "placed", "complete": false } }

User Management

Create a user:

{ "user": { "username": "johndoe", "firstName": "John", "lastName": "Doe", "email": "john@example.com", "password": "password123", "phone": "555-1234", "userStatus": 1 } }

MCP Client

Client Architecture

The MCP client system consists of multiple layers for maximum flexibility and ease of use:

Core Components

Transport Layer (transport.py)
- Handles MCP server communication
- Connection management with async context managers
- Error handling and logging
Configuration Management (client_config.py)
- Centralized configuration system
- Server connection settings
- Retry policies and caching options
Prompt Management (prompt_manager.py)
- Template-based prompt generation
- Different templates for various operations
- Extensible prompt system
Sampling Configuration (sampling.py)
- Multiple AI model sampling presets
- Configurable parameters for different use cases
- Easy configuration management
Agent Interface (agent_interface.py)
- High-level task execution
- Seamless integration of all components
- Agent-friendly API

Client Installation

Install client dependencies:
pip3 install -r client_requirements.txt
Ensure server is available:
# Make sure the MCP server is in the same directory ls petstore-mcp-server.py

Client Usage

Basic Client Usage

from petstore_mcp_client import PetstoreClient async def main(): client = PetstoreClient() async with client.connect(): # Find available pets pets = await client.find_pets_by_status("available") # Add a new pet new_pet = await client.add_pet( name="Buddy", photo_urls=["https://example.com/buddy.jpg"], status="available" ) # Get inventory inventory = await client.get_inventory()

Agent Interface Usage

from agent_interface import PetstoreAgent from client_config import ClientConfig async def main(): # Initialize agent with configuration config = ClientConfig.default() agent = PetstoreAgent(config) # Execute high-level tasks result = await agent.execute_task("find_pets", status="available") # Get prompts for AI models prompt = agent.get_prompt("pet_search", status="available", tags=["friendly"]) # Get sampling configuration sampling_config = agent.get_sampling_config("balanced")

Advanced Client Features

from petstore_mcp_client import PetstoreAgent async def main(): agent = PetstoreAgent() # Execute complex workflows workflow_result = await agent.execute_pet_workflow( "create_pet", name="Max", category="Dogs", tags=["friendly", "large"] ) # Get store summary summary = await agent.client.get_store_summary()

Configuration Options

Client Configuration

from client_config import ClientConfig, ServerConfig # Custom configuration config = ClientConfig( server=ServerConfig( command="python3", args=["./petstore-mcp-server.py"], timeout=30 ), retry_attempts=3, retry_delay=1.0, log_level="INFO", enable_caching=True, cache_ttl=300 )

Sampling Configurations

Available sampling presets:

conservative: Low temperature, focused responses
balanced: Moderate creativity and focus (default)
creative: Higher temperature, more creative responses
precise: Zero temperature, deterministic responses

from sampling import SamplingManager sampling = SamplingManager() # Get different configurations conservative = sampling.get_config_dict("conservative") creative = sampling.get_config_dict("creative")

Prompt Templates

Available prompt templates:

pet_search: For finding and filtering pets
pet_management: For pet inventory operations
order_processing: For handling customer orders
user_management: For user account operations

from prompt_manager import PromptManager prompts = PromptManager() # Get prompt for pet search prompt = prompts.get_prompt( "pet_search", status="available", tags=["friendly", "small"] )

Agent Integration

Task-Based Operations

The agent interface provides high-level tasks that AI agents can easily use:

# Find pets await agent.execute_task("find_pets", status="available", tags=["friendly"]) # Manage pets await agent.execute_task("manage_pet", action="add", name="Buddy", photoUrls=["url"]) # Process orders await agent.execute_task("process_order", action="place", petId=123, quantity=1) # Manage users await agent.execute_task("manage_user", action="create", username="john", email="john@example.com")

Workflow Execution

# Pet management workflow result = await agent.execute_pet_workflow( "create_pet", name="Luna", category="Cats", tags=["indoor", "quiet"], photo_urls=["https://example.com/luna.jpg"] ) # Inventory management workflow inventory = await agent.execute_pet_workflow("manage_inventory")

Error Handling

The client system includes comprehensive error handling:

Network Errors: Automatic retry with exponential backoff
API Errors: Meaningful error messages and suggestions
Validation Errors: Input validation with helpful feedback
Connection Errors: Graceful degradation and recovery

Testing

Server Testing

# Test server functionality python3 test_server.py

Client Testing

# Test client functionality python3 example_usage.py

API Reference

Base URL

Production: https://petstore3.swagger.io/api/v3

Authentication

API Key authentication for certain endpoints
OAuth2 support for pet operations

Rate Limiting

Configurable retry policies
Exponential backoff for failed requests

Development

Extending the Server

Add new tool functions using @server.call_tool() decorator
Update tool definitions in handle_list_tools()
Add appropriate error handling and validation
Update documentation

Extending the Client

Add new methods to PetstoreClient class
Create corresponding agent workflows
Add prompt templates for new operations
Update configuration options

Adding New Prompts

from prompt_manager import PromptTemplate # Create new template template = PromptTemplate( system="You are a pet care specialist.", user_template="Provide care advice for {pet_type} with {condition}", examples={"basic": "Care for a sick dog"} ) # Add to manager prompt_manager.add_template("pet_care", template)

Security Considerations

API keys are handled securely
Passwords are not logged or cached
HTTPS connections for all API calls
Input validation and sanitization
Error messages don't expose sensitive information

Performance

Async/await throughout for non-blocking operations
Connection pooling for HTTP requests
Configurable caching with TTL
Efficient JSON parsing and serialization

Contributing

Fork the repository
Create a feature branch
Add tests for new functionality
Update documentation
Submit a pull request

License

This project follows the same license as the Swagger Petstore API (Apache 2.0).

Support

For issues and questions:

Check the example usage scripts
Review the test files
Examine the configuration options
Create an issue with detailed information