# Poke MCP Examples

Complete, production-ready examples demonstrating all authentication patterns for building MCP (Model Context Protocol) integrations for [Poke](https://poke.com).

## 🚀 Getting Started

```bash
# Clone this repository
git clone https://github.com/InteractionCo/poke-mcp-examples.git
cd poke-mcp-examples

# Pick an example and follow its README
cd iss-tracker  # or weather-api, whoop-integration, bookmark-manager
```

Each example is self-contained with its own dependencies and documentation.

## 📚 Examples

| Example | Authentication | Setup Time | What You'll Build |
|---------|---------------|------------|-------------------|
| [ISS Tracker](./iss-tracker) | None | 5 min | Real-time ISS location - perfect first integration |
| [Weather API](./weather-api) | API Key | 10 min | Weather data with bearer token auth |
| [WHOOP Integration](./whoop-integration) | OAuth Proxy | 20 min | Health data from existing OAuth API |
| [Bookmark Manager](./bookmark-manager) | Remote OAuth + DCR | 15 min | Full multi-user service with WorkOS |
| [Template](./mcp-server-template) | - | 5 min | Basic server structure and patterns |

## 🎯 Choose Your Path

**New to MCP?** Start with [ISS Tracker](./iss-tracker) - no authentication needed, 5 minutes to deploy.

**Learning the basics?** Check the [Template](./mcp-server-template) for basic server patterns and structure.

**Building for production?** Jump to [Bookmark Manager](./bookmark-manager) for full OAuth + Dynamic Client Registration.

## 🏗️ Repository Structure

```
poke-mcp-examples/
├── iss-tracker/          # No auth example
├── weather-api/          # API key auth example
├── whoop-integration/    # OAuth proxy example
├── bookmark-manager/     # Full OAuth + DCR example
└── mcp-server-template/  # Reference implementation
```

Each directory contains:
- `src/server.py` - Server implementation
- `requirements.txt` - Python dependencies  
- `.env.example` - Environment variables (if needed)
- `README.md` - Detailed documentation

## 📖 What These Examples Teach

### No Authentication: ISS Tracker
- Building tools for public APIs
- Deploying to Render with HTTPS
- Connecting to Poke without auth
- Rate limiting for public endpoints

### API Key: Weather API  
- Validating bearer tokens on every request
- Returning proper 401 errors
- Per-API-key rate limiting
- Secure credential handling

### OAuth Proxy: WHOOP Integration
- Wrapping existing OAuth providers
- Token forwarding to upstream APIs
- Handling refresh tokens
- Per-user data access

### Remote OAuth + DCR: Bookmark Manager
- Building new services from scratch
- Full MCP spec compliance
- JWT validation with JWKS
- Per-user data isolation

## 🚢 Deployment

All examples can be deployed to Render:

1. Fork this repository on GitHub
2. Create a new Web Service on Render
3. Connect your forked repository
4. Set the **Working Directory** to the specific example (e.g., `iss-tracker`)
5. Configure build and start commands (see each example's README)
6. Deploy

Poke requires HTTPS. Render provides this automatically.

## 🔒 Authentication Patterns

| Your Scenario | Use This Pattern | Example |
|--------------|------------------|---------|
| Public data, no user context | No auth | ISS Tracker |
| Simple API with keys | API Key | Weather API |
| Wrapping existing OAuth service | OAuth Proxy | WHOOP |
| Building new user service | Remote OAuth + DCR | Bookmarks |

## 🛠️ Requirements

All examples use:
- Python 3.12+
- Conda for environment management
- FastMCP framework
- Manual Render deployment (no render.yaml)

## 🤝 Contributing

These examples are educational resources. Contributions welcome:
- Bug fixes
- Documentation improvements
- New authentication patterns
- Better practices

## 📄 License

MIT - Use these examples as starting points for your own integrations.

## 🔗 Resources

- [Poke Documentation](https://docs.poke.com)
- [MCP Specification](https://modelcontextprotocol.io)
- [FastMCP Framework](https://github.com/jlowin/fastmcp)

---

Built with ❤️ by the Interaction team to help you create amazing MCP integrations.