# MCP Community Tools - Model Context Protocol Server

A professional-grade MCP (Model Context Protocol) server that provides tools for querying community and world databases. Designed with clean architecture patterns and ready for integration with GitHub Copilot.

## 🎯 Quick Start

### 1. **Connect to GitHub Copilot** (3 steps)

See [QUICK_START.md](QUICK_START.md) for instant setup.

**TL;DR:**
1. Open VS Code Settings (Cmd+,)
2. Add this to `settings.json`:
```json
{
  "github.copilot.mcp": [
    {
      "name": "mcp-community-tools",
      "command": "${workspaceFolder}/.venv/bin/python3",
      "args": ["${workspaceFolder}/hello_mcp.py"],
      "env": {"PYTHONPATH": "${workspaceFolder}"}
    }
  ]
}
```
3. Restart VS Code

### 2. **Ask Copilot**

Now you can ask Copilot to use your tools:
- "Get the top 10 highest comments"
- "Show me 5 countries from Europe"
- "Generate a random name"

---

## 📚 Available Tools

| Tool | Description | Example |
|------|-------------|---------|
| `get_random_name()` | Generate a random name | `get_random_name()` |
| `get_top_10_highest_comments()` | Get top 10 users by message count | Returns: Top 10 chatters |
| `fetch_countries()` | Query countries by region and limit | `fetch_countries(region="Asia", limit=5)` |

---

## 🏗️ Project Structure

```
mcp-course/
├── hello_mcp.py                    # Main entry point (50 lines - clean!)
├── setup-copilot.sh               # Auto-generate config helper
├── QUICK_START.md                 # 3-step Copilot integration
├── SETUP_COPILOT.md              # Detailed setup guide
├── ARCHITECTURE.md                # Design patterns & structure
├── INTEGRATION_DIAGRAM.md         # Visual flow diagrams
├── REFACTORING_SUMMARY.md         # Before/after comparison
│
├── db_connection/
│   └── connection.py              # Database Connection Factory
│
├── repositories/
│   ├── base_repository.py         # Abstract Base Class
│   ├── chatters_repository.py     # Community data queries
│   └── countries_repository.py    # World data queries
│
├── tools/
│   └── tools.py                   # Tool implementations (DI)
│
└── db/
    ├── community.db               # Chatters data (251 records)
    └── world.db                   # Countries data (250 records)
```

---

## ✨ Key Features

### 🎯 Clean Architecture
- **Repository Pattern**: Database access abstraction
- **Dependency Injection**: Loose coupling between layers
- **Factory Pattern**: Centralized connection management
- **SOLID Principles**: All five principles applied

### 🛡️ Professional Code
- ✅ Type hints throughout
- ✅ Comprehensive error handling
- ✅ Well-documented with docstrings
- ✅ Easy to test and extend

### 🚀 Ready for Production
- ✅ Works with GitHub Copilot
- ✅ Works with Claude Desktop
- ✅ Works with any MCP-compatible client
- ✅ Secure local execution

---

## 📖 Documentation

| Document | Purpose |
|----------|---------|
| [QUICK_START.md](QUICK_START.md) | Get Copilot working in 3 steps |
| [SETUP_COPILOT.md](SETUP_COPILOT.md) | Detailed setup & troubleshooting |
| [ARCHITECTURE.md](ARCHITECTURE.md) | Design patterns & principles |
| [INTEGRATION_DIAGRAM.md](INTEGRATION_DIAGRAM.md) | Visual flows and connections |
| [REFACTORING_SUMMARY.md](REFACTORING_SUMMARY.md) | Before/after code comparison |

---

## 🚀 Running Locally

### Prerequisites
- Python 3.11+
- Virtual environment (`venv`)

### Setup
```bash
# Clone and enter directory
cd /Users/souravkumar/WebstormProjects/mcp-course

# Activate virtual environment
source .venv/bin/activate

# Install dependencies (if needed)
pip install -r requirements.txt
```

### Run Server
```bash
python3 hello_mcp.py
```

Output should show:
```
Server started on stdio
```

---

## 🔌 Integration Options

### Option 1: GitHub Copilot in VS Code ✅ **RECOMMENDED**
See [QUICK_START.md](QUICK_START.md)

### Option 2: Claude Desktop App
See [SETUP_COPILOT.md](SETUP_COPILOT.md) - Claude Desktop section

### Option 3: Manual Testing
```bash
# Terminal 1: Start server
python3 hello_mcp.py

# Terminal 2: Test tools
curl -X POST http://localhost:3000/call \
  -H "Content-Type: application/json" \
  -d '{"tool": "get_top_10_highest_comments"}'
```

---

## 💾 Databases

### community.db
```sql
SELECT * FROM chatters;
-- id, name, messages, last_message_at
```
**251 community members** with activity tracking

### world.db
```sql
SELECT * FROM countries;
-- id, name, iso2, iso3, capital, region, subregion, currency, currency_symbol, phonecode, emoji
```
**250 countries** with detailed information

---

## 🛠️ Example Usage with Copilot

### Example 1: Get Top Commenters
```
You: "Who are the top 10 most active community members?"

Copilot:
✓ Calls: get_top_10_highest_comments()
✓ Returns: Top 10 users with message counts
✓ Shows: Their last activity timestamps
```

### Example 2: Find Countries
```
You: "Show me all European countries and their capitals"

Copilot:
✓ Calls: fetch_countries(region="Europe")
✓ Returns: All 50 European countries
✓ Shows: Capital, currency, phone code, flag emoji
```

### Example 3: Generate Names
```
You: "Give me 5 random names"

Copilot:
✓ Calls: get_random_name() (5 times)
✓ Returns: 5 random names from the list
```

---

## 🏛️ Architecture at a Glance

```
┌─────────────────────────────────────────┐
│      GitHub Copilot / Claude            │
└──────────────────┬──────────────────────┘
                   │ MCP Protocol (JSON-RPC)
                   ▼
┌─────────────────────────────────────────┐
│  hello_mcp.py (Tool Registration)       │
│  ├─ @mcp.tool() decorators             │
│  └─ Dependency injection setup          │
└──────────────────┬──────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────┐
│  tools/tools.py (Business Logic)        │
│  ├─ TopCommentsTool                    │
│  ├─ CountriesTool                      │
│  └─ RandomNameTool                     │
└──────────────────┬──────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────┐
│  repositories/ (Data Access)            │
│  ├─ ChattersRepository                 │
│  ├─ CountriesRepository                │
│  └─ BaseRepository (Abstract)          │
└──────────────────┬──────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────┐
│  db_connection/ (Connection Factory)    │
└──────────────────┬──────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────┐
│  db/ (SQLite Databases)                 │
│  ├─ community.db                       │
│  └─ world.db                           │
└─────────────────────────────────────────┘
```

---

## 📊 SOLID Principles Applied

✅ **S**ingle Responsibility: Each class has one reason to change  
✅ **O**pen/Closed: Open for extension, closed for modification  
✅ **L**iskov Substitution: Repositories are interchangeable  
✅ **I**nterface Segregation: Minimal required interfaces  
✅ **D**ependency Inversion: Depend on abstractions, not concretions  

---

## 🔐 Security

- ✅ **Local Execution**: Runs on your machine only
- ✅ **No Data Upload**: All data stays local
- ✅ **No Authentication**: Local database access
- ✅ **Read-Only**: Tools only query, don't modify data

---

## 🧪 Testing

### Run Tests (when available)
```bash
pytest tests/
```

### Manual Testing
```python
from repositories.chatters_repository import ChattersRepository
from db_connection.connection import DatabaseConnection

conn = DatabaseConnection.get_connection("community.db")
repo = ChattersRepository(conn)
results = repo.get_top_highest_comments(10)
print(results)
repo.close()
```

---

## 🤝 Contributing

To add a new tool:

1. **Create a Repository** (if needed):
   ```python
   # repositories/my_data_repository.py
   class MyDataRepository(BaseRepository):
       def get_data(self): 
           return self.execute_query("SELECT * FROM my_table")
   ```

2. **Create a Tool**:
   ```python
   # In tools/tools.py
   class MyDataTool:
       def __init__(self, repository):
           self.repository = repository
       def execute(self):
           return self.repository.get_data()
   ```

3. **Register in hello_mcp.py**:
   ```python
   @mcp.tool()
   def my_data_tool() -> list[dict]:
       conn = DatabaseConnection.get_connection("my_db.db")
       repo = MyDataRepository(conn)
       tool = MyDataTool(repo)
       return tool.execute()
   ```

---

## 📞 Troubleshooting

### Common Issues

| Issue | Solution |
|-------|----------|
| "Tool not found" in Copilot | Restart VS Code completely (Cmd+Q) |
| "ModuleNotFoundError" | Check PYTHONPATH in config |
| Connection timeout | Verify `hello_mcp.py` runs without errors |
| Tools not available | Wait 10 seconds after restart for extension load |

For detailed troubleshooting, see [SETUP_COPILOT.md](SETUP_COPILOT.md#troubleshooting)

---

## 📝 License

MIT License - Feel free to use, modify, and distribute.

---

## 🎓 Learning Resources

- [MCP Protocol Documentation](https://modelcontextprotocol.io)
- [Design Patterns](https://refactoring.guru/design-patterns)
- [SOLID Principles](https://en.wikipedia.org/wiki/SOLID)
- [Repository Pattern](https://martinfowler.com/eaaCatalog/repository.html)

---

## ✅ Quick Checklist

- [ ] Read [QUICK_START.md](QUICK_START.md)
- [ ] Copy configuration to `settings.json`
- [ ] Restart VS Code
- [ ] Test with Copilot
- [ ] Read [ARCHITECTURE.md](ARCHITECTURE.md) to understand design
- [ ] Check [INTEGRATION_DIAGRAM.md](INTEGRATION_DIAGRAM.md) for visuals

---

## 🚀 You're Ready!

Your MCP server is production-ready. Enjoy using it with GitHub Copilot! 🎉

**Questions?** Check the documentation files or the troubleshooting section above.