Petstore MCP Server & Client

An MCP server and client implementation for the Swagger Petstore API.

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.

- 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

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

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

- 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

- 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

- 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

Add the server to your MCP configuration:

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

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

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

{ "status": "available" }

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

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

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

- 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

- Template-based prompt generation
- Different templates for various operations
- Extensible prompt system

- Multiple AI model sampling presets
- Configurable parameters for different use cases
- Easy configuration management

- High-level task execution
- Seamless integration of all components
- Agent-friendly API

# Make sure the MCP server is in the same directory ls petstore-mcp-server.py

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()

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")

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()

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 )

- 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")

- 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"] )

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")

# 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")

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

# Test server functionality python3 test_server.py

# Test client functionality python3 example_usage.py

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

- API Key authentication for certain endpoints
- OAuth2 support for pet operations

- Configurable retry policies
- Exponential backoff for failed requests
- Add new tool functions using@server.call_tool()decorator
- Update tool definitions inhandle_list_tools()
- Add appropriate error handling and validation
- Update documentation
- Add new methods toPetstoreClientclass
- Create corresponding agent workflows
- Add prompt templates for new operations
- Update configuration options

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)

- 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

- Async/await throughout for non-blocking operations
- Connection pooling for HTTP requests
- Configurable caching with TTL
- Efficient JSON parsing and serialization
- Fork the repository
- Create a feature branch
- Add tests for new functionality
- Update documentation
- Submit a pull request

This project follows the same license as the Swagger Petstore API (Apache 2.0).
- Check the example usage scripts
- Review the test files
- Examine the configuration options
- Create an issue with detailed information

This is a web browser that enables your coding agent, such as Claude Code, to visit websites on your behalf and assist you in identifying bugs or creating UI test cases.

An MCP server for interacting with the Postman API, requiring an API key.

Adds possibility to work with testing management via MCP

An enhanced Apifox MCP service providing comprehensive API management capabilities for Claude Desktop and Cursor.

This MCP Server accepts swagger/postman documents as input. It then generates API & Load test scenarios, executes the tests and generates the execution report.

A Model Context Protocol (MCP) server for creating, managing, and executing Bruno API testing collections. Supports both .bru and .yml (opencollection) formats with built-in security hardening.

Execute Bruno collections using the Bruno CLI, with support for environment files and detailed test results.

An MCP server exposing Hoverfly as a programmable API simulation tool for AI assistants.

A free public REST API for testing and prototyping, powered by JSONPlaceholder.

Postman for MCP — search 156 servers, inspect tools with schema visualizer, test live

An AI-native API testing platform for generating scenarios, executing tests, and analyzing results.