https://github.com/djdarcy/mcp-server-tutorial
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.
https://github.com/djdarcy/mcp-server-tutorial
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
Last synced: 4 months ago
JSON representation
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.
- Host: GitHub
- URL: https://github.com/djdarcy/mcp-server-tutorial
- Owner: djdarcy
- License: mit
- Created: 2025-07-14T04:21:27.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2025-07-14T06:12:47.000Z (7 months ago)
- Last Synced: 2025-07-14T07:48:57.925Z (7 months ago)
- 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
- Language: Python
- Homepage:
- Size: 125 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# MCP Server Tutorial
A detailed, hands-on tutorial for learning MCP (Model Context Protocol) server development with working examples and debugging tools.
## Project Overview
This tutorial project creates a minimal, well-documented MCP server designed to help you understand:
- How MCP servers work
- How to debug MCP servers with VS Code
- How to diagnose common MCP issues
- How to register servers with Claude Desktop
- How to build your own MCP tools and servers
**Requirements**: Python 3.10+ (MCP library requirement)
## Quick Start
### 1. Setup Environment
```bash
# Run the setup script
scripts\setup.bat
# Or manually:
python -m venv venv
venv\Scripts\activate.bat
pip install mcp
```
### 2. Test the Server
```bash
# Activate virtual environment
venv\Scripts\activate.bat
# Run tests (basic test without Unicode issues)
python tests\test_simple.py
# Or run full test suite (may have Unicode display issues on Windows)
python tests\test_server.py
# Or use the safe test runner for Windows
scripts\test_safe.bat
```
**Note for Windows users:** If you see Unicode encoding errors, use `scripts\test_safe.bat` which redirects output to `test_output.log`.
### 3. Debug the Server
1. Open this folder in VS Code
2. Go to Run and Debug (Ctrl+Shift+D)
3. Select "Debug MCP Server"
4. Press F5 to start debugging
Key breakpoints to set:
- `server.py:89` - Tool discovery
- `server.py:110` - Tool execution
- `handlers.py:25` - Individual tool handlers
### 4. Register with Claude Code
1. Copy the configuration from `config\claude_desktop.json`
2. Add to your Claude Desktop configuration file
3. Restart Claude Desktop
4. The server should appear as "simple-mcp-debug"
## Project Structure
```
MCPDebugTest/
├── CLAUDE.md # Detailed learning documentation
├── README.md # This file
├── setup.bat # Windows setup script
├── requirements.txt # Python dependencies
├── simple_mcp_server/ # Main MCP server code
│ ├── server.py # MCP server implementation
│ ├── tools.py # Tool definitions
│ ├── handlers.py # Tool handlers
│ └── debug_utils.py # Debugging utilities
├── tests/ # Test scripts
│ └── test_server.py # Server validation tests
├── config/ # Configuration files
│ └── claude_desktop.json # Claude Desktop config
├── .vscode/ # VS Code configuration
│ └── launch.json # Debug configurations
└── logs/ # Debug logs (created on first run)
```
## Available Tools
The MCP server exposes these tools for testing:
### 1. hello_world
Simple greeting tool
- **Parameters**: `name` (optional)
- **Purpose**: Basic functionality test
### 2. echo
Echo back messages with optional prefix
- **Parameters**: `message` (required), `prefix` (optional)
- **Purpose**: Input/output testing
### 3. get_time
Get current time in various formats
- **Parameters**: `format` (iso/readable/timestamp), `timezone` (optional)
- **Purpose**: System interaction testing
### 4. math_add
Add two numbers together
- **Parameters**: `a` (required), `b` (required)
- **Purpose**: Parameter validation testing
### 5. debug_info
Get server debug information
- **Parameters**: `include_tools` (boolean), `include_stats` (boolean)
- **Purpose**: Server introspection
## Debugging Features
### Logging
- Detailed MCP protocol message logging
- Performance metrics
- Error tracking with stack traces
- Separate log files for different aspects
### VS Code Integration
- Pre-configured debug launch configurations
- Breakpoint-friendly code structure
- Variable inspection capabilities
- Step-through debugging
### Test Suite
- Automated tool discovery testing
- Parameter validation testing
- Error handling validation
- Handler functionality testing
## Understanding MCP Protocol
### Tool Discovery Flow
1. Client connects to server
2. Client calls `list_tools()` RPC
3. Server returns available tools with schemas
4. Client can now call individual tools
### Tool Execution Flow
1. Client calls `call_tool(name, arguments)` RPC
2. Server validates arguments against schema
3. Server routes to appropriate handler
4. Handler processes request and returns result
5. Server formats response and sends back
### Key Debugging Points
- **Tool Registration**: Set breakpoints in `get_all_tools()`
- **Tool Discovery**: Set breakpoints in `handle_list_tools()`
- **Tool Execution**: Set breakpoints in `handle_call_tool()`
- **Individual Handlers**: Set breakpoints in specific tool handlers
## Common Issues and Solutions
### Issue: Tools Not Appearing in Claude Code
**Debug Steps:**
1. Check Claude Desktop configuration
2. Verify server starts without errors
3. Check `list_tools()` response in logs
4. Restart Claude Desktop
### Issue: Tool Execution Fails
**Debug Steps:**
1. Check parameter validation in logs
2. Set breakpoints in tool handlers
3. Verify handler return format
4. Check error handling paths
### Issue: Server Won't Start
**Debug Steps:**
1. Check Python environment
2. Verify MCP library installation
3. Check import paths
4. Review startup logs
### Issue: Unicode/Emoji Characters in Windows Console
**Problem:** Windows Command Prompt may not display Unicode characters properly
**Solutions:**
1. Use `scripts\test_safe.bat` which redirects output to a file
2. Use Windows Terminal or PowerShell instead of Command Prompt
3. Set console code page: `chcp 65001` before running tests
4. Check `test_output.log` for full test results
### Issue: Test Suite Crashes with UnicodeEncodeError
**Problem:** Python logging fails when trying to output Unicode characters to Windows console
**Solutions:**
1. Run tests with `scripts\test_safe.bat` to redirect output
2. Use the simplified test runner: `python tests\test_simple.py`
3. Check log files in the `logs\` directory for detailed output
4. The server functionality works correctly; only the console output has Unicode issues
## Next Steps
Once you understand this tutorial server:
1. **Build Your Own Server**: Use the same patterns to create your own MCP server
2. **Explore Advanced Features**: Add more complex tools and state management
3. **Deploy to Production**: Follow the production deployment guide in the docs
4. **Contribute Back**: Share improvements and additional examples with the community
## Learning Resources
### Helpful Tutorial
This project includes a complete step-by-step tutorial covering all aspects of MCP development:
**📖 [Complete Tutorial Guide](docs/tutorial/README.md)**
#### Tutorial Chapters:
1. **[Understanding MCP Architecture](docs/tutorial/01_understanding_mcp_architecture.md)**
- MCP protocol fundamentals and client-server communication
- Core concepts: tools, resources, prompts, and protocol flow
- How MCP fits into the AI assistant ecosystem
2. **[Protocol Flow](docs/tutorial/02_protocol_flow.md)**
- Message exchange patterns and protocol handshake
- Tool discovery and execution lifecycle
- Error handling and response formatting
3. **[Tool Registration](docs/tutorial/03_tool_registration.md)**
- Defining tools with JSON Schema validation
- Best practices for tool naming and parameter design
- Advanced tool features and capabilities
4. **[Error Handling](docs/tutorial/04_error_handling.md)**
- Different error handling strategies
- Debugging common failure scenarios
- Protocol-compliant error responses
5. **[Debugging and Testing](docs/tutorial/05_debugging_testing.md)**
- VS Code debugging setup and breakpoint strategies
- Test suite development and automated validation
- Protocol-level debugging techniques
6. **[Authentication and Security](docs/tutorial/06_authentication_security.md)**
- Security considerations for MCP servers
- Authentication patterns and access control
- Best practices for production deployment
7. **[State Management](docs/tutorial/07_state_management.md)**
- Managing server state and session data
- Persistence strategies and data consistency
- Advanced state management patterns
8. **[Claude Integration](docs/tutorial/08_claude_integration.md)**
- Claude Desktop configuration and setup
- Integration troubleshooting and optimization
- Cross-platform deployment considerations
9. **[Production Deployment](docs/tutorial/09_production_deployment.md)**
- Production-ready server configuration
- Monitoring, logging, and maintenance
- Scaling and performance optimization
### Additional Documentation
- **[Debugging Guide](docs/debugging_guide.md)** - Various debugging strategies and troubleshooting
- **[Project Creation Process](docs/project_creation.md)** - Complete development journey and decision rationale
- **[Completion Report](docs/COMPLETION_REPORT.md)** - Project status and implementation details
### External Resources
- [MCP Specification](https://modelcontextprotocol.io/specification)
- [Python MCP SDK](https://github.com/modelcontextprotocol/python-sdk)
- [Claude Desktop Documentation](https://modelcontextprotocol.io/quickstart/user)
- [VS Code Python Debugging](https://code.visualstudio.com/docs/python/debugging)
## Contributing
This is a learning project. Feel free to:
- Add more test tools
- Enhance debugging capabilities
- Improve documentation
- Add more extensive tests
---
*Happy debugging! 🐛🔍*