{"id":29092340,"url":"https://github.com/devteds/mcp-test-service","last_synced_at":"2025-10-19T08:03:27.304Z","repository":{"id":299011708,"uuid":"1001807573","full_name":"devteds/mcp-test-service","owner":"devteds","description":null,"archived":false,"fork":false,"pushed_at":"2025-06-14T05:17:24.000Z","size":22,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-28T07:05:38.243Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/devteds.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-14T04:27:08.000Z","updated_at":"2025-06-14T05:17:27.000Z","dependencies_parsed_at":"2025-06-14T06:31:47.976Z","dependency_job_id":null,"html_url":"https://github.com/devteds/mcp-test-service","commit_stats":null,"previous_names":["devteds/mcp-test-service"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/devteds/mcp-test-service","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devteds%2Fmcp-test-service","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devteds%2Fmcp-test-service/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devteds%2Fmcp-test-service/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devteds%2Fmcp-test-service/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/devteds","download_url":"https://codeload.github.com/devteds/mcp-test-service/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devteds%2Fmcp-test-service/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265611440,"owners_count":23797887,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-28T07:05:35.654Z","updated_at":"2025-10-19T08:03:22.266Z","avatar_url":"https://github.com/devteds.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MCP Test Service\n\nA complete **Model Context Protocol (MCP)** implementation example featuring a product search service with both MCP and REST API endpoints.\n\nThis project demonstrates how to build, test, and deploy MCP services using modern Python development practices.\n\n**Author:** Chandra Shettigar (chandra@devteds.com)\n\n## 🎯 What This Project Demonstrates\n\n- **Complete MCP Implementation** - Full JSON-RPC 2.0 protocol support\n- **Multiple Interface Support** - Both MCP protocol and REST API endpoints\n- **Production-Ready Code** - Comprehensive testing, formatting, and validation\n- **Modern Development Environment** - VS Code/Cursor devcontainer setup\n- **Real-World Example** - Product search with inventory management\n\n## 📖 Related Blog Post\n\nThis code was written as a companion to the blog post: **[Building Your First MCP Server](https://dev.to/shettigarc/building-your-first-mcp-server-53e8)**\n\nThe blog post covers the theory and best practices behind MCP service development, while this repository provides the complete working implementation.\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- **VS Code** or **Cursor** editor\n- **Docker** installed and running\n- **Dev Containers extension** installed\n\n### 1. Clone and Open\n\n```bash\ngit clone git@github.com:devteds/mcp-test-service.git\ncd mcp-test-service\n```\n\nOpen in VS Code/Cursor and select **\"Reopen in Container\"** when prompted.\n\n### 2. Verify Setup\n\n```bash\npython verify_setup.py\n```\n\nYou should see:\n```\n✅ All dependencies installed and working correctly!\n🚀 Your devcontainer is ready for MCP development\n```\n\n### 3. Start the MCP Service\n\n```bash\npython -m mcp_service\n```\n\nThe service will start on `http://localhost:8000`\n\n### 4. Test the Service\n\nIn a new terminal:\n\n```bash\n# Test MCP client\npython mcp_client_example.py\n\n# Run test suite\npython -m pytest tests/ -v\n\n# Test REST API\ncurl http://localhost:8000/api/v1/products/search?query=iPhone\n```\n\n## 🏗️ Project Structure\n\n```\nmcp-test/\n├── .devcontainer/          # Development container configuration\n│   ├── devcontainer.json   # VS Code/Cursor devcontainer settings\n│   ├── Dockerfile          # Python development environment\n│   └── bashrc              # Shell configuration with aliases\n├── mcp_service/            # Main MCP service package\n│   ├── __init__.py\n│   ├── main.py            # FastAPI application and MCP server\n│   ├── server.py          # MCP protocol implementation\n│   ├── handlers.py        # MCP tool handlers\n│   ├── models.py          # Pydantic data models\n│   └── data.py            # Sample product database\n├── tests/                  # Comprehensive test suite\n│   └── test_product_service.py\n├── mcp_client_example.py   # Example MCP client usage\n├── verify_setup.py         # Environment verification script\n├── requirements.txt        # Python dependencies\n└── README.md              # This file\n```\n\n## 🔧 Development Environment\n\n### Devcontainer Features\n\nThe project includes a fully configured development environment with:\n\n- **Python 3.11** with all dependencies pre-installed\n- **VS Code Extensions**: Python, Black, isort, flake8, pytest\n- **Automatic Formatting**: Code formatting on save\n- **Port Forwarding**: MCP service accessible on port 8000\n- **Shell Aliases**: Convenient commands for common tasks\n\n### Available Commands\n\nThe devcontainer includes these helpful aliases:\n\n```bash\nmcp-start      # Start the MCP service\nmcp-test       # Run the test suite\nmcp-client     # Run the MCP client example\nmcp-format     # Format code with black and isort\nmcp-verify     # Verify environment setup\n```\n\n## 🛠️ MCP Service Details\n\n### Available Tools\n\nThe MCP service provides three tools:\n\n1. **`search_products`** - Search for products by name or category\n2. **`get_product_details`** - Get detailed information about a specific product  \n3. **`check_inventory`** - Check stock levels for a product\n\n### Sample Data\n\nThe service includes sample products across three categories:\n- **Electronics**: iPhone 15 Pro, MacBook Air M3\n- **Footwear**: Nike Air Max, Adidas Ultraboost\n- **Appliances**: *(expandable)*\n\n### API Endpoints\n\n**MCP Protocol:**\n- `POST /api/v1/mcp` - Main MCP JSON-RPC endpoint\n\n**REST API:**\n- `GET /api/v1/mcp/capabilities` - Service capabilities discovery\n- `GET /api/v1/products/search` - Product search\n- `GET /api/v1/products/{id}` - Product details\n- `GET /api/v1/products/{id}/inventory` - Inventory check\n- `GET /health` - Health check\n- `GET /docs` - Interactive API documentation\n\n## 🧪 Testing\n\n### Run All Tests\n\n```bash\npython -m pytest tests/ -v\n```\n\n### Test Coverage\n\nThe test suite covers:\n- ✅ MCP protocol message handling\n- ✅ All MCP tool implementations\n- ✅ REST API endpoints\n- ✅ Error handling and edge cases\n- ✅ Data validation and serialization\n\n### Manual Testing\n\n```bash\n# Test MCP capabilities discovery\ncurl http://localhost:8000/api/v1/mcp/capabilities\n\n# Test product search\ncurl \"http://localhost:8000/api/v1/products/search?query=iPhone\"\n\n# Test MCP client\npython mcp_client_example.py\n```\n\n## 🎨 Code Quality\n\n### Formatting and Linting\n\nThe project uses:\n- **Black** for code formatting\n- **isort** for import sorting  \n- **flake8** for linting\n- **pytest** for testing\n\nFormat code:\n```bash\nblack . \u0026\u0026 isort .\n```\n\n### Pre-configured VS Code Settings\n\n- Format on save enabled\n- Organize imports on save\n- pytest integration\n- flake8 linting enabled\n\n## 🔍 Verification and Troubleshooting\n\n### Environment Verification\n\n```bash\npython verify_setup.py\n```\n\nThis script checks:\n- ✅ All required dependencies are installed\n- ✅ MCP SDK functionality works\n- ✅ Service imports are successful\n- ✅ Data functions are operational\n\n### Common Issues\n\n**Port 8000 already in use:**\n```bash\n# Kill existing process\npkill -f \"python -m mcp_service\"\n# Or use a different port\nuvicorn mcp_service.main:app --port 8001\n```\n\n**Dependencies missing:**\n```bash\n# Rebuild devcontainer\n# Command Palette \u003e \"Dev Containers: Rebuild Container\"\n```\n\n**Tests failing:**\n```bash\n# Check service is running\ncurl http://localhost:8000/health\n\n# Run tests with verbose output\npython -m pytest tests/ -v --tb=short\n```\n\n## 📚 Learning Resources\n\n### Understanding MCP\n\n- **MCP Specification**: [Model Context Protocol Documentation](https://spec.modelcontextprotocol.io/)\n- **MCP SDK**: [Official Python SDK](https://github.com/modelcontextprotocol/python-sdk)\n- **JSON-RPC 2.0**: [Protocol Specification](https://www.jsonrpc.org/specification)\n\n### Key Concepts Demonstrated\n\n1. **Protocol Implementation** - Complete JSON-RPC 2.0 MCP server\n2. **Tool Registration** - Dynamic tool discovery and execution\n3. **Type Safety** - Pydantic models for data validation\n4. **Error Handling** - Proper MCP error responses\n5. **Testing Strategy** - Comprehensive test coverage\n6. **Development Workflow** - Modern Python development practices\n\n## 🤝 Contributing\n\n1. **Fork the repository**\n2. **Create a feature branch**: `git checkout -b feature/amazing-feature`\n3. **Make your changes** and ensure tests pass\n4. **Format code**: `black . \u0026\u0026 isort .`\n5. **Run tests**: `python -m pytest tests/ -v`\n6. **Commit changes**: `git commit -m 'Add amazing feature'`\n7. **Push to branch**: `git push origin feature/amazing-feature`\n8. **Open a Pull Request**\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## 🙏 Acknowledgments\n\n- **Author**: [Chandra Shettigar](https://github.com/shettigarc) - Project creator and maintainer\n- **Anthropic** for the Model Context Protocol specification\n- **FastAPI** for the excellent web framework\n- **Pydantic** for data validation and serialization\n- **MCP Community** for tools and examples\n\n---\n\n**Happy MCP Development!** 🚀\n\nFor questions or issues, please open a GitHub issue or refer to the related blog post for detailed explanations. ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevteds%2Fmcp-test-service","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdevteds%2Fmcp-test-service","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevteds%2Fmcp-test-service/lists"}