# 🌐 Volunteer Search MCP Server, Client & REST API

A **Model Context Protocol (MCP)** server, client demo, and REST API for searching volunteer opportunities from the free [VolunteerConnector API](https://www.volunteerconnector.org/api).

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org/)

---

## 🏆 What Makes This Special?

**Most MCP implementations are either servers OR clients. This project has BOTH:**

1. ✅ **MCP Server** (Node.js) - Serves MCP protocol
2. ✅ **MCP Client** (Apex) - **Custom Salesforce MCP client**
3. ✅ **MCP Client** (JavaScript) - Browser-based demo
4. ✅ **REST API** - Traditional HTTP endpoints
5. ✅ **Hybrid Architecture** - All in one deployment

### 💡 Why the Apex MCP Client Matters:

**Salesforce doesn't natively support MCP protocol.** This project implements a **full JSON-RPC 2.0 MCP client from scratch in Apex**, making Salesforce Agentforce a first-class citizen in the MCP ecosystem.

**This demonstrates:**
- Deep understanding of protocol specifications
- Ability to implement AI protocols in enterprise platforms
- Bridge between traditional enterprise (Salesforce) and cutting-edge AI (MCP)

---

## 🎯 Features

- **🔌 MCP Server** - True Model Context Protocol implementation (JSON-RPC 2.0)
- **📱 Multiple MCP Clients** - Apex (Salesforce), JavaScript (Browser), Claude Desktop
- **💻 MCP Client Demo** - Interactive web-based client for testing MCP over SSE
- **🌐 REST API** - HTTP endpoints for traditional integration
- **🔄 Hybrid Mode** - Single server supporting both REST and MCP protocols
- **⚡ Salesforce Agentforce** - Custom Apex MCP client for Agentforce integration
- **💰 FREE** - Uses VolunteerConnector API (no authentication required)
- **🚀 Heroku Ready** - Deploy to Heroku in 5 minutes
- **🧪 Tested** - Includes test scripts and live demos
- **📚 Well Documented** - Complete guides and examples

---

## 📦 What's Included

### **1. MCP Server** (`volunteer-search-server.js`)
- Implements Model Context Protocol (stdio)
- Works with Claude Desktop and other MCP clients
- Exposes 2 tools:
  - `search_volunteer_opportunities` - Search with filters
  - `get_opportunity_details` - Get full details by ID

### **2. MCP Client Demo** (`public/index.html`)
- Interactive web-based MCP client
- Connects to MCP server via SSE (Server-Sent Events)
- Real-time testing interface
- Beautiful, modern UI
- No backend required (pure frontend)

### **3. REST API** (`server.js`)
- Express.js REST API
- Deployable to Heroku/Render/Railway
- Endpoints:
  - `GET /` - API info
  - `GET /health` - Health check
  - `POST /api/search` - Search opportunities
  - `GET /api/opportunity/:id` - Get details

### **4. Hybrid Server** (`server-with-mcp-sse.js`)
- Supports BOTH REST API and MCP over SSE
- Single deployment for multiple protocols
- MCP endpoint: `POST /mcp/message` (JSON-RPC 2.0)
- Serves MCP client demo at `/`
- Perfect for production deployments

### **5. Salesforce Apex MCP Client** (`VTOApexMCPClient.cls`)
- **Custom MCP client written in Apex**
- Implements JSON-RPC 2.0 protocol from scratch
- Calls MCP server via HTTP POST
- Usable in Salesforce Agentforce Agent Builder
- Methods:
  - `searchViaMCPProtocol` - Search using MCP protocol
  - `listMCPTools` - Discover available MCP tools
- **Full protocol compliance** - validates JSON-RPC responses
- **Production-ready** enterprise MCP client

---

## 🚀 Quick Start

### **Option 1: MCP Client Demo (Interactive Web UI)**

```bash
# Install dependencies
npm install

# Start the hybrid server (REST + MCP)
node server-with-mcp-sse.js

# Open in browser
open http://localhost:3000
```

**What you get:**
- Interactive MCP client in your browser
- Test volunteer searches in real-time
- See MCP protocol messages
- Beautiful UI for demos

---

### **Option 2: REST API (for Heroku/Salesforce)**

```bash
# Install dependencies
npm install

# Start the REST API
npm start

# Test locally
curl http://localhost:3000/health
```

---

### **Option 3: MCP Server (for Claude Desktop)**

```bash
# Install dependencies
npm install

# Start the MCP server
npm run start:mcp
```

Then add to Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "volunteer-search": {
      "command": "node",
      "args": ["/absolute/path/to/volunteer-search-mcp/volunteer-search-server.js"]
    }
  }
}
```

---

## ⚡ Salesforce Agentforce Integration

This project includes a **custom Apex MCP client** that allows Salesforce Agentforce to use the Model Context Protocol!

### **How It Works:**

```
Salesforce Agentforce
    ↓
VTOApexMCPClient.cls (Apex MCP Client)
    ↓ JSON-RPC 2.0 Message
POST /mcp/message
    ↓
Hybrid Server (MCP Protocol Handler)
    ↓
VolunteerConnector API
```

### **MCP Message Example:**

**Request (from Apex):**
```json
{
  "jsonrpc": "2.0",
  "id": 42345,
  "method": "tools/call",
  "params": {
    "name": "search_volunteer_opportunities",
    "arguments": {
      "keywords": "tutoring",
      "location": "Toronto",
      "max_results": 5
    }
  }
}
```

**Response (from server):**
```json
{
  "jsonrpc": "2.0",
  "id": 42345,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "🌐 Found 5 volunteer opportunities...\n\n1. ..."
      }
    ]
  }
}
```

### **Key Features:**

- ✅ **Full JSON-RPC 2.0 compliance**
- ✅ **Protocol validation** (checks jsonrpc version, message IDs)
- ✅ **Tool discovery** (`tools/list` method)
- ✅ **Tool execution** (`tools/call` method)
- ✅ **Enterprise logging** (debug logs for troubleshooting)
- ✅ **Error handling** (proper JSON-RPC error responses)

### **Why This Matters:**

**Most Salesforce integrations use REST.** This project demonstrates that Salesforce can implement **cutting-edge AI protocols** like MCP through custom Apex clients.

**This makes Salesforce a first-class citizen in the MCP ecosystem!** 🚀

---

## 🌐 REST API Endpoints

### **GET /**
Returns API information and available endpoints.

### **GET /health**
Health check endpoint.

**Response:**
```json
{
  "status": "ok",
  "timestamp": "2025-10-05T..."
}
```

### **POST /api/search**
Search for volunteer opportunities.

**Request Body:**
```json
{
  "keywords": "tutoring",
  "location": "Toronto",
  "remote_only": false,
  "max_results": 10
}
```

**Response:**
```json
{
  "success": true,
  "total_count": 969,
  "returned_count": 10,
  "opportunities": [
    {
      "id": 43243,
      "title": "Event Planner",
      "organization": "Canadian Network for International Surgery",
      "description": "...",
      "url": "https://...",
      "dates": "September 8, 2025 - November 9, 2025",
      "duration": null,
      "remote": false,
      "location": "British Columbia",
      "activities": "Event Planning, Marketing, Social Media"
    }
  ],
  "formatted_text": "🌐 Found 10 volunteer opportunities..."
}
```

### **GET /api/opportunity/:id**
Get detailed information about a specific opportunity.

**Response:**
```json
{
  "success": true,
  "opportunity": {
    "id": 43243,
    "title": "Event Planner",
    "organization": "Canadian Network for International Surgery",
    "description": "...",
    "url": "https://...",
    "dates": "September 8, 2025 - November 9, 2025",
    "activities": [
      {"name": "Event Planning", "category": "PR, Fundraising, Events"}
    ]
  },
  "formatted_text": "📋 Volunteer Opportunity Details..."
}
```

---

## 🔧 MCP Tools

### **search_volunteer_opportunities**

Search for volunteer opportunities with optional filters.

**Parameters:**
- `keywords` (string, optional) - Search terms
- `location` (string, optional) - City or region
- `remote_only` (boolean, optional) - Filter for remote opportunities
- `max_results` (number, optional) - Max results (1-50, default: 10)

**Example:**
```json
{
  "keywords": "tutoring",
  "location": "Toronto",
  "max_results": 5
}
```

### **get_opportunity_details**

Get detailed information about a specific opportunity.

**Parameters:**
- `opportunity_id` (number, required) - The opportunity ID

**Example:**
```json
{
  "opportunity_id": 43243
}
```

---

## 🚀 Deploy to Heroku

### **Quick Deploy:**

```bash
# Login to Heroku
heroku login

# Create app
heroku create your-app-name

# Deploy
git init
git add .
git commit -m "Initial commit"
git push heroku main

# Open app
heroku open
```

### **Detailed Guide:**
See [HEROKU_DEPLOYMENT.md](HEROKU_DEPLOYMENT.md) for complete deployment instructions.

---

## 🧪 Testing

### **Test REST API:**

```bash
# Test locally
./test-api.sh http://localhost:3000

# Test on Heroku
./test-api.sh https://your-app.herokuapp.com
```

### **Test MCP Server:**

```bash
# Use MCP Inspector
npx @modelcontextprotocol/inspector node volunteer-search-server.js
```

---

## 🔗 Integration Examples

### **Salesforce Apex**

```apex
HttpRequest req = new HttpRequest();
req.setEndpoint('callout:Volunteer_Search_API/api/search');
req.setMethod('POST');
req.setHeader('Content-Type', 'application/json');

Map<String, Object> body = new Map<String, Object>{
    'keywords' => 'tutoring',
    'max_results' => 10
};
req.setBody(JSON.serialize(body));

Http http = new Http();
HttpResponse res = http.send(req);
```

### **JavaScript/Node.js**

```javascript
const response = await fetch('https://your-app.herokuapp.com/api/search', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    keywords: 'tutoring',
    max_results: 10
  })
});

const data = await response.json();
console.log(data.opportunities);
```

### **Python**

```python
import requests

response = requests.post(
    'https://your-app.herokuapp.com/api/search',
    json={
        'keywords': 'tutoring',
        'max_results': 10
    }
)

data = response.json()
print(data['opportunities'])
```

### **curl**

```bash
curl -X POST https://your-app.herokuapp.com/api/search \
  -H "Content-Type: application/json" \
  -d '{"keywords":"tutoring","max_results":10}'
```

---

## 📊 Data Source

This project uses the **VolunteerConnector API**:
- **URL:** https://www.volunteerconnector.org/api/search/
- **Cost:** FREE (no authentication required)
- **Coverage:** 969+ volunteer opportunities across North America
- **Updates:** Real-time
- **Documentation:** https://www.volunteerconnector.org/api

---

## 🏗️ Architecture

### **REST API Flow:**
```
Client (Salesforce/Web/Mobile)
    ↓ HTTP REST
Express.js Server (server.js)
    ↓ HTTP GET
VolunteerConnector API
    ↓
Return formatted results
```

### **MCP Server Flow (stdio):**
```
AI Assistant (Claude Desktop)
    ↓ MCP Protocol (stdio)
MCP Server (volunteer-search-server.js)
    ↓ HTTP GET
VolunteerConnector API
    ↓
Return formatted results
```

### **MCP Client Flow (SSE):**
```
Web Browser (MCP Client Demo)
    ↓ MCP over SSE
Hybrid Server (server-with-mcp-sse.js)
    ↓ HTTP GET
VolunteerConnector API
    ↓
Return formatted results
    ↓ SSE Stream
Display in web UI
```

### **Hybrid Architecture:**
```
┌───────────────────────────────────────────────────┐
│     Hybrid Server (server-with-mcp-sse.js)        │
├───────────────────────────────────────────────────┤
│                                                   │
│  ┌────────────────┐       ┌──────────────────┐   │
│  │   REST API     │       │   MCP Protocol   │   │
│  │   Endpoints    │       │   (JSON-RPC 2.0) │   │
│  │                │       │                  │   │
│  │ /api/search    │       │ /mcp/message     │   │
│  │ /api/opp/:id   │       │                  │   │
│  └────────┬───────┘       └─────────┬────────┘   │
│           │                         │            │
│           └──────────┬──────────────┘            │
│                      │                           │
│            ┌─────────▼──────────┐                │
│            │ VolunteerConnector │                │
│            │        API         │                │
│            └────────────────────┘                │
└───────────────────────────────────────────────────┘
            │                    │
            ▼                    ▼
    ┌──────────────┐     ┌─────────────────────┐
    │  Salesforce  │     │    MCP Clients:     │
    │  (REST API)  │     │  • Apex Client      │
    └──────────────┘     │  • Browser Client   │
                         │  • Claude Desktop   │
                         └─────────────────────┘

🔑 Key Difference:
   REST: Traditional HTTP API calls
   MCP:  JSON-RPC 2.0 protocol messages
```

### **Multiple Integration Patterns:**

| Client Type | Protocol | Endpoint | Use Case |
|-------------|----------|----------|----------|
| **Salesforce (REST)** | HTTP REST | `/api/search` | Standard integration |
| **Salesforce (MCP)** | JSON-RPC 2.0 | `/mcp/message` | Protocol-compliant AI |
| **Web Browser** | JSON-RPC 2.0 | `/mcp/message` | Interactive demo |
| **Claude Desktop** | MCP (stdio) | N/A (stdio) | Native AI assistant |

---

## 📁 Project Structure

```
volunteer-search-mcp/
├── server.js                      # REST API server (Express.js)
├── server-with-mcp-sse.js         # Hybrid server (REST + MCP over SSE)
├── volunteer-search-server.js     # MCP server (stdio for Claude Desktop)
├── public/
│   └── index.html                 # MCP Client Demo (interactive web UI)
├── package.json                   # Dependencies
├── Procfile                       # Heroku configuration
├── test-api.sh                    # Test script
├── GETTING_STARTED.md             # Quick start guide
├── CLAUDE_DESKTOP_DEMO.md         # Claude Desktop setup guide
├── HEROKU_DEPLOYMENT.md           # Deployment guide
├── README.md                      # This file
├── LICENSE                        # MIT License
└── .gitignore                     # Git ignore rules

Salesforce Apex MCP Client (separate repo):
└── VTOApexMCPClient.cls           # Apex MCP client (JSON-RPC 2.0)
    └── VTOApexMCPClient.cls-meta.xml
```

---

## 🛠️ Development

### **Install Dependencies:**
```bash
npm install
```

### **Run REST API (Development):**
```bash
npm run dev
```

### **Run MCP Server (Development):**
```bash
npm run dev:mcp
```

### **Test:**
```bash
# Test REST API
./test-api.sh http://localhost:3000

# Test MCP Server
npx @modelcontextprotocol/inspector node volunteer-search-server.js
```

---

## 🌟 Use Cases

### **For Enterprises:**
- **Salesforce Agentforce** - Add volunteer search to AI agents (REST or MCP)
- **Corporate VTO Programs** - Help employees find volunteer work
- **Volunteer Management Platforms** - Integrate external volunteer opportunities
- **Mobile Apps** - Find local volunteer opportunities
- **Nonprofit Websites** - Display volunteer opportunities

### **For AI/ML Developers:**
- **Claude Desktop** - Native MCP integration via stdio
- **Custom AI Assistants** - Add volunteer search to any MCP-compatible AI
- **Protocol Research** - Study MCP client/server implementation
- **Multi-protocol Architecture** - Learn REST + MCP hybrid patterns

### **For Learning & Demos:**
- **Interactive Demos** - Use web client for presentations and testing
- **Hackathons** - Showcase MCP integration with live demo
- **Protocol Education** - Learn JSON-RPC 2.0 and MCP specification
- **Salesforce Extensions** - Example of custom Apex MCP client

---

## 📚 Resources

- **MCP Documentation:** https://modelcontextprotocol.io/
- **VolunteerConnector API:** https://www.volunteerconnector.org/api
- **Heroku Docs:** https://devcenter.heroku.com/
- **Express.js:** https://expressjs.com/

---

## 🤝 Contributing

Contributions are welcome! Feel free to:
- Report bugs
- Suggest features
- Submit pull requests
- Improve documentation

---

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

---

## 🙏 Acknowledgments

- **VolunteerConnector** for providing the free volunteer opportunities API
- **Anthropic** for creating the Model Context Protocol
- **Heroku** for easy deployment platform

---

## 📞 Support

- **Issues:** Open an issue on GitHub
- **API Status:** Check https://www.volunteerconnector.org/
- **MCP Help:** Visit https://modelcontextprotocol.io/

---

## 🎉 Quick Links

- 🚀 [Getting Started Guide](GETTING_STARTED.md)
- 💻 [MCP Client Demo](http://localhost:3000) - Start hybrid server first
- 🤖 [Claude Desktop Setup](CLAUDE_DESKTOP_DEMO.md)
- 📖 [Heroku Deployment Guide](HEROKU_DEPLOYMENT.md)
- 🧪 [Test the API](./test-api.sh)
- 🔌 [MCP Documentation](https://modelcontextprotocol.io/)
- 🌐 [VolunteerConnector API](https://www.volunteerconnector.org/api)

---

**Built with ❤️ for the volunteer community**

**Star ⭐ this repo if you find it useful!**