{"id":"7df0cbe3-18af-4c0d-bf22-867d874c25dc","slug":"dondetir-simplemcp","kind":"mcp","name":"simpleMCP","summary":"A simple, educational project demonstrating how to integrate with the Anthropic Model Context Protocol (MCP) using both STDIO and HTTP/SSE transports.","owner":"dondetir","repoUrl":"https://github.com/dondetir/simpleMCP","license":"MIT","licenseTier":"permissive","trust":"community","stars":0,"match":null,"fewStars":true,"format":"mcp","createdAt":"2025-10-16T03:00:06.000Z","addedAt":"2026-10-21T05:41:57.248Z","logoUrl":"https://avatars.githubusercontent.com/u/13931987?u=43b5ece3951ff124205056174fe6be7fb607fc9f&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["memory-knowledge"],"tags":["ai-agents","anthropic","education","python"],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-24T06:14:03.971Z","sample":false,"url":"https://conduits.dev/tools/dondetir-simplemcp","language":"Python","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# SimpleMCP - Basic MCP Integration Example\n\nA simple, educational project demonstrating how to integrate with the **Anthropic Model Context Protocol (MCP)** using both **STDIO** and **HTTP/SSE** transports.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)\n\n## 📖 What is This?\n\nSimpleMCP is a minimal example showing how to build an MCP server that works with any MCP-compatible client. It implements a simple story-telling service with **two transport methods**:\n\n1. **STDIO** (stdin/stdout) - for local MCP clients\n2. **HTTP/SSE** (Server-Sent Events) - for remote MCP clients and web applications\n\nPerfect for learning how to build MCP servers and integrate with any MCP client!\n\n## 🎯 What You'll Learn\n\n- How to use the official Anthropic MCP SDK\n- Implementing MCP servers with STDIO transport\n- Implementing MCP servers with HTTP/SSE transport\n- Clean separation between business logic and protocol layer\n- Testing MCP servers\n\n## ⚡ Quick Start\n\n### 1. Install\n\n```bash\n# Clone the repository\ngit clone https://github.com/dondetir/simpleMCP.git\ncd simpleMCP\n\n# Create virtual environment\npython3 -m venv .venv\nsource .venv/bin/activate  # Windows: .venv\\Scripts\\activate\n\n# Install dependencies\npip install -r requirements.txt\n```\n\n### 2. Run Tests\n\n```bash\npytest tests/\n```\n\n### 3. Try It Out\n\n**Option A: STDIO Client (e.g., Claude Desktop)**\n```bash\n# See CLIENT_SETUP.md for full instructions\n# Add to your MCP client configuration and restart\n```\n\n**Option B: HTTP Server**\n```bash\n# Start the HTTP server\npython mcp_http_server.py\n\n# Server runs on http://localhost:8000/sse\n```\n\n**Option C: Test Client**\n```bash\n# Use the example test client\npython examples/test_mcp_client.py --stdio\npython examples/test_mcp_client.py --http\n```\n\n## 🏗️ Project Structure\n\n```\nSimpleMCP/\n├── mcp_server.py              # STDIO transport server\n├── mcp_http_server.py         # HTTP/SSE transport server\n├── story_manager.py           # Core business logic (transport-independent)\n├── stories/stories.json       # Sample data\n├── tests/                     # Unit and integration tests\n├── examples/                  # Example clients and configs\n└── requirements.txt           # Python dependencies\n```\n\n## 🔧 How It Works\n\n### Architecture\n\n```\n┌─────────────────────────┐\n│   Any MCP Client        │\n│ (Desktop/CLI/Web/etc)   │\n└──────────┬──────────────┘\n           │\n           │ MCP Protocol (JSON-RPC 2.0)\n           │\n    ┌──────▼───────┐\n    │  Transport   │\n    │ STDIO or SSE │\n    └──────┬───────┘\n           │\n    ┌──────▼────────┐\n    │  MCP Server   │\n    │ (this project)│\n    └──────┬────────┘\n           │\n    ┌──────▼─────────┐\n    │ Business Logic │\n    │story_manager.py│\n    └────────────────┘\n```\n\n### Available Tools\n\nBoth servers expose the same two MCP tools:\n\n1. **`list_stories`** - Returns all available stories (id and title)\n2. **`get_story`** - Returns a complete story by ID\n\n### Example Stories\n\nThe server includes 5 sample stories:\n- `squirrel_and_owl` - The Curious Squirrel and the Wise Owl\n- `bear_loses_roar` - The Bear Who Lost His Roar\n- `turtle_wants_to_fly` - The Turtle Who Wanted to Fly\n- `lonely_firefly` - The Lonely Firefly\n- `rabbit_and_carrot` - The Rabbit and the Magical Carrot\n\n## 📚 Documentation\n\n- **[QUICK_START_MCP.md](QUICK_START_MCP.md)** - Quick reference guide\n- **[CLIENT_SETUP.md](CLIENT_SETUP.md)** - Detailed MCP client setup guide\n- **[examples/README.md](examples/README.md)** - Example clients and configurations\n\n## 🧪 Testing\n\n```bash\n# Run all tests\npytest tests/\n\n# Run with coverage\npytest tests/ --cov=. --cov-report=term-missing\n\n# Run specific test file\npytest tests/test_mcp_servers.py -v\n```\n\n## 💡 Extending This Example\n\nWant to build your own MCP server? Here's how:\n\n1. **Define your business logic** (like `story_manager.py`)\n2. **Create tool functions** with the `@mcp.tool()` decorator\n3. **Choose your transport** (STDIO for local, HTTP/SSE for remote)\n4. **Test with the MCP Inspector** or example clients\n\nSee the code comments for detailed explanations!\n\n## 🛠️ Tech Stack\n\n- **Python 3.8+**\n- **MCP SDK** (`mcp>=1.17.0`) - Official Anthropic SDK\n- **FastAPI** & **Uvicorn** - For HTTP/SSE server\n- **pytest** - Testing framework\n\n## 🤝 Contributing\n\nThis is an educational example project. Contributions welcome!\n\n- Report bugs via GitHub Issues\n- Submit Pull Requests with improvements\n- Share your own MCP server examples\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n## 📄 License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## 🔗 Resources\n\n- [MCP Documentation](https://modelcontextprotocol.io/)\n- [MCP Python SDK](https://github.com/anthropics/anthropic-sdk-python)\n- [MCP Client Examples](https://modelcontextprotocol.io/clients)\n- [Building MCP Clients](https://modelcontextprotocol.io/tutorials/building-clients)\n\n## 🙋 FAQ\n\n**Q: Do I need a specific MCP client to use this?**\nA: No! This works with any MCP-compatible client including Claude Desktop, Claude Code, or custom implementations.\n\n**Q: Can I add my own tools?**\nA: Yes! Add new functions with the `@mcp.tool()` decorator. See the existing tools for examples.\n\n**Q: What's the difference between STDIO and HTTP/SSE?**\nA: STDIO is for local MCP clients (like desktop applications), HTTP/SSE is for network-based clients (like web apps or remote integrations).\n\n**Q: How do I add more stories?**\nA: Edit `stories/stories.json` and add new story objects with `id`, `title`, and `text` fields.\n\n---\n\n**Built to demonstrate the Anthropic Model Context Protocol** 🚀\n\nQuestions? Open an issue on GitHub!\n"}