{"id":29470543,"url":"https://github.com/djdarcy/mcp-server-tutorial","last_synced_at":"2025-10-25T12:03:37.212Z","repository":{"id":304603233,"uuid":"1019265765","full_name":"djdarcy/MCP-Server-Tutorial","owner":"djdarcy","description":"A detailed hands-on tutorial for learning Model Context Protocol (MCP) server development with Python. Includes working examples, VSCode debugging setup, tests, and a step-by-step guide covering everything from basic architecture to deployment. Perfect for anyone wanting to build AI-integrated tools and to understand how Claude extensions work.","archived":false,"fork":false,"pushed_at":"2025-07-14T06:12:47.000Z","size":128,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-14T07:48:57.925Z","etag":null,"topics":["ai-assistant","ai-integration","ai-tools","anthropic","beginner-friendly","claude","claude-code","claude-desktop","debugging","developer-tools","examples","learning-resources","llm-tools","mcp","model-context-protocol","python","sdk","step-by-step","tutorial","vscode"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/djdarcy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"djdarcy","ko_fi":"djdarcy","buy_me_a_coffee":"djdarcy"}},"created_at":"2025-07-14T04:21:27.000Z","updated_at":"2025-07-14T06:18:36.000Z","dependencies_parsed_at":"2025-07-14T07:49:04.067Z","dependency_job_id":"3bd22cf1-72a1-47bb-ab42-fa3022772916","html_url":"https://github.com/djdarcy/MCP-Server-Tutorial","commit_stats":null,"previous_names":["djdarcy/mcp-server-tutorial"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/djdarcy/MCP-Server-Tutorial","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/djdarcy%2FMCP-Server-Tutorial","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/djdarcy%2FMCP-Server-Tutorial/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/djdarcy%2FMCP-Server-Tutorial/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/djdarcy%2FMCP-Server-Tutorial/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/djdarcy","download_url":"https://codeload.github.com/djdarcy/MCP-Server-Tutorial/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/djdarcy%2FMCP-Server-Tutorial/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265289038,"owners_count":23741287,"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":["ai-assistant","ai-integration","ai-tools","anthropic","beginner-friendly","claude","claude-code","claude-desktop","debugging","developer-tools","examples","learning-resources","llm-tools","mcp","model-context-protocol","python","sdk","step-by-step","tutorial","vscode"],"created_at":"2025-07-14T12:05:02.554Z","updated_at":"2025-10-25T12:03:37.207Z","avatar_url":"https://github.com/djdarcy.png","language":"Python","readme":"# MCP Server Tutorial\n\nA detailed, hands-on tutorial for learning MCP (Model Context Protocol) server development with working examples and debugging tools.\n\n## Project Overview\n\nThis tutorial project creates a minimal, well-documented MCP server designed to help you understand:\n- How MCP servers work\n- How to debug MCP servers with VS Code\n- How to diagnose common MCP issues\n- How to register servers with Claude Desktop\n- How to build your own MCP tools and servers\n\n**Requirements**: Python 3.10+ (MCP library requirement)\n\n## Quick Start\n\n### 1. Setup Environment\n\n```bash\n# Run the setup script\nscripts\\setup.bat\n\n# Or manually:\npython -m venv venv\nvenv\\Scripts\\activate.bat\npip install mcp\n```\n\n### 2. Test the Server\n\n```bash\n# Activate virtual environment\nvenv\\Scripts\\activate.bat\n\n# Run tests (basic test without Unicode issues)\npython tests\\test_simple.py\n\n# Or run full test suite (may have Unicode display issues on Windows)\npython tests\\test_server.py\n\n# Or use the safe test runner for Windows\nscripts\\test_safe.bat\n```\n\n**Note for Windows users:** If you see Unicode encoding errors, use `scripts\\test_safe.bat` which redirects output to `test_output.log`.\n\n### 3. Debug the Server\n\n1. Open this folder in VS Code\n2. Go to Run and Debug (Ctrl+Shift+D)\n3. Select \"Debug MCP Server\"\n4. Press F5 to start debugging\n\nKey breakpoints to set:\n- `server.py:89` - Tool discovery\n- `server.py:110` - Tool execution\n- `handlers.py:25` - Individual tool handlers\n\n### 4. Register with Claude Code\n\n1. Copy the configuration from `config\\claude_desktop.json`\n2. Add to your Claude Desktop configuration file\n3. Restart Claude Desktop\n4. The server should appear as \"simple-mcp-debug\"\n\n## Project Structure\n\n```\nMCPDebugTest/\n├── CLAUDE.md                    # Detailed learning documentation\n├── README.md                    # This file\n├── setup.bat                    # Windows setup script\n├── requirements.txt             # Python dependencies\n├── simple_mcp_server/           # Main MCP server code\n│   ├── server.py                # MCP server implementation\n│   ├── tools.py                 # Tool definitions\n│   ├── handlers.py              # Tool handlers\n│   └── debug_utils.py           # Debugging utilities\n├── tests/                       # Test scripts\n│   └── test_server.py           # Server validation tests\n├── config/                      # Configuration files\n│   └── claude_desktop.json      # Claude Desktop config\n├── .vscode/                     # VS Code configuration\n│   └── launch.json              # Debug configurations\n└── logs/                        # Debug logs (created on first run)\n```\n\n## Available Tools\n\nThe MCP server exposes these tools for testing:\n\n### 1. hello_world\nSimple greeting tool\n- **Parameters**: `name` (optional)\n- **Purpose**: Basic functionality test\n\n### 2. echo\nEcho back messages with optional prefix\n- **Parameters**: `message` (required), `prefix` (optional)\n- **Purpose**: Input/output testing\n\n### 3. get_time\nGet current time in various formats\n- **Parameters**: `format` (iso/readable/timestamp), `timezone` (optional)\n- **Purpose**: System interaction testing\n\n### 4. math_add\nAdd two numbers together\n- **Parameters**: `a` (required), `b` (required)\n- **Purpose**: Parameter validation testing\n\n### 5. debug_info\nGet server debug information\n- **Parameters**: `include_tools` (boolean), `include_stats` (boolean)\n- **Purpose**: Server introspection\n\n## Debugging Features\n\n### Logging\n- Detailed MCP protocol message logging\n- Performance metrics\n- Error tracking with stack traces\n- Separate log files for different aspects\n\n### VS Code Integration\n- Pre-configured debug launch configurations\n- Breakpoint-friendly code structure\n- Variable inspection capabilities\n- Step-through debugging\n\n### Test Suite\n- Automated tool discovery testing\n- Parameter validation testing\n- Error handling validation\n- Handler functionality testing\n\n## Understanding MCP Protocol\n\n### Tool Discovery Flow\n1. Client connects to server\n2. Client calls `list_tools()` RPC\n3. Server returns available tools with schemas\n4. Client can now call individual tools\n\n### Tool Execution Flow\n1. Client calls `call_tool(name, arguments)` RPC\n2. Server validates arguments against schema\n3. Server routes to appropriate handler\n4. Handler processes request and returns result\n5. Server formats response and sends back\n\n### Key Debugging Points\n- **Tool Registration**: Set breakpoints in `get_all_tools()`\n- **Tool Discovery**: Set breakpoints in `handle_list_tools()`\n- **Tool Execution**: Set breakpoints in `handle_call_tool()`\n- **Individual Handlers**: Set breakpoints in specific tool handlers\n\n## Common Issues and Solutions\n\n### Issue: Tools Not Appearing in Claude Code\n**Debug Steps:**\n1. Check Claude Desktop configuration\n2. Verify server starts without errors\n3. Check `list_tools()` response in logs\n4. Restart Claude Desktop\n\n### Issue: Tool Execution Fails\n**Debug Steps:**\n1. Check parameter validation in logs\n2. Set breakpoints in tool handlers\n3. Verify handler return format\n4. Check error handling paths\n\n### Issue: Server Won't Start\n**Debug Steps:**\n1. Check Python environment\n2. Verify MCP library installation\n3. Check import paths\n4. Review startup logs\n\n### Issue: Unicode/Emoji Characters in Windows Console\n**Problem:** Windows Command Prompt may not display Unicode characters properly\n**Solutions:**\n1. Use `scripts\\test_safe.bat` which redirects output to a file\n2. Use Windows Terminal or PowerShell instead of Command Prompt\n3. Set console code page: `chcp 65001` before running tests\n4. Check `test_output.log` for full test results\n\n### Issue: Test Suite Crashes with UnicodeEncodeError\n**Problem:** Python logging fails when trying to output Unicode characters to Windows console\n**Solutions:**\n1. Run tests with `scripts\\test_safe.bat` to redirect output\n2. Use the simplified test runner: `python tests\\test_simple.py`\n3. Check log files in the `logs\\` directory for detailed output\n4. The server functionality works correctly; only the console output has Unicode issues\n\n## Next Steps\n\nOnce you understand this tutorial server:\n\n1. **Build Your Own Server**: Use the same patterns to create your own MCP server\n2. **Explore Advanced Features**: Add more complex tools and state management\n3. **Deploy to Production**: Follow the production deployment guide in the docs\n4. **Contribute Back**: Share improvements and additional examples with the community\n\n## Learning Resources\n\n### Helpful Tutorial\n\nThis project includes a complete step-by-step tutorial covering all aspects of MCP development:\n\n**📖 [Complete Tutorial Guide](docs/tutorial/README.md)**\n\n#### Tutorial Chapters:\n\n1. **[Understanding MCP Architecture](docs/tutorial/01_understanding_mcp_architecture.md)**\n   - MCP protocol fundamentals and client-server communication\n   - Core concepts: tools, resources, prompts, and protocol flow\n   - How MCP fits into the AI assistant ecosystem\n\n2. **[Protocol Flow](docs/tutorial/02_protocol_flow.md)**\n   - Message exchange patterns and protocol handshake\n   - Tool discovery and execution lifecycle\n   - Error handling and response formatting\n\n3. **[Tool Registration](docs/tutorial/03_tool_registration.md)**\n   - Defining tools with JSON Schema validation\n   - Best practices for tool naming and parameter design\n   - Advanced tool features and capabilities\n\n4. **[Error Handling](docs/tutorial/04_error_handling.md)**\n   - Different error handling strategies\n   - Debugging common failure scenarios\n   - Protocol-compliant error responses\n\n5. **[Debugging and Testing](docs/tutorial/05_debugging_testing.md)**\n   - VS Code debugging setup and breakpoint strategies\n   - Test suite development and automated validation\n   - Protocol-level debugging techniques\n\n6. **[Authentication and Security](docs/tutorial/06_authentication_security.md)**\n   - Security considerations for MCP servers\n   - Authentication patterns and access control\n   - Best practices for production deployment\n\n7. **[State Management](docs/tutorial/07_state_management.md)**\n   - Managing server state and session data\n   - Persistence strategies and data consistency\n   - Advanced state management patterns\n\n8. **[Claude Integration](docs/tutorial/08_claude_integration.md)**\n   - Claude Desktop configuration and setup\n   - Integration troubleshooting and optimization\n   - Cross-platform deployment considerations\n\n9. **[Production Deployment](docs/tutorial/09_production_deployment.md)**\n   - Production-ready server configuration\n   - Monitoring, logging, and maintenance\n   - Scaling and performance optimization\n\n### Additional Documentation\n\n- **[Debugging Guide](docs/debugging_guide.md)** - Various debugging strategies and troubleshooting\n- **[Project Creation Process](docs/project_creation.md)** - Complete development journey and decision rationale\n- **[Completion Report](docs/COMPLETION_REPORT.md)** - Project status and implementation details\n\n### External Resources\n\n- [MCP Specification](https://modelcontextprotocol.io/specification)\n- [Python MCP SDK](https://github.com/modelcontextprotocol/python-sdk)\n- [Claude Desktop Documentation](https://modelcontextprotocol.io/quickstart/user)\n- [VS Code Python Debugging](https://code.visualstudio.com/docs/python/debugging)\n\n## Contributing\n\nThis is a learning project. Feel free to:\n- Add more test tools\n- Enhance debugging capabilities\n- Improve documentation\n- Add more extensive tests\n\n---\n\n*Happy debugging! 🐛🔍*\n","funding_links":["https://github.com/sponsors/djdarcy","https://ko-fi.com/djdarcy","https://buymeacoffee.com/djdarcy"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdjdarcy%2Fmcp-server-tutorial","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdjdarcy%2Fmcp-server-tutorial","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdjdarcy%2Fmcp-server-tutorial/lists"}