🌐 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.

---

🏆 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)

# 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)

# Install dependencies
npm install

# Start the REST API
npm start

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

---

Option 3: MCP Server (for Claude Desktop)

# 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):

{
  "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):

{
  "jsonrpc": "2.0",
  "id": 42345,
  "method": "tools/call",
  "params": {
    "name": "search_volunteer_opportunities",
    "arguments": {
      "keywords": "tutoring",
      "location": "Toronto",
      "max_results": 5
    }
  }
}

Response (from server):

{
  "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:

{
  "status": "ok",
  "timestamp": "2025-10-05T..."
}

POST /api/search

Search for volunteer opportunities.

Request Body:

{
  "keywords": "tutoring",
  "location": "Toronto",
  "remote_only": false,
  "max_results": 10
}

Response:

{
  "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:

{
  "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:

{
  "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:

{
  "opportunity_id": 43243
}

---

🚀 Deploy to Heroku

Quick Deploy:

# 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 for complete deployment instructions.

---

🧪 Testing

Test REST API:

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

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

Test MCP Server:

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

---

🔗 Integration Examples

Salesforce 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

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

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

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:

npm install

Run REST API (Development):

npm run dev

Run MCP Server (Development):

npm run dev:mcp

Test:

# 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 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
• 💻 MCP Client Demo - Start hybrid server first
• 🤖 Claude Desktop Setup
• 📖 Heroku Deployment Guide
• 🧪 Test the API
• 🔌 MCP Documentation
• 🌐 VolunteerConnector API

---

Built with ❤️ for the volunteer community

Star ⭐ this repo if you find it useful!