volunteermcp by satishtamilan - MCP Server

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

✅ MCP Server (Node.js) - Serves MCP protocol
✅ MCP Client (Apex) - Custom Salesforce MCP client
✅ MCP Client (JavaScript) - Browser-based demo
✅ REST API - Traditional HTTP endpoints
✅ 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 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 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

🚀
💻 MCP Client Demo - Start hybrid server first
🤖
📖
🧪
🔌 MCP Documentation
🌐 VolunteerConnector API

Built with ❤️ for the volunteer community

Star ⭐ this repo if you find it useful!

satishtamilan/volunteermcp

🌐 Volunteer Search MCP Server, Client & REST API

🏆 What Makes This Special?

💡 Why the Apex MCP Client Matters:

🎯 Features

📦 What's Included

1. MCP Server (volunteer-search-server.js)

2. MCP Client Demo (public/index.html)

3. REST API (server.js)

4. Hybrid Server (server-with-mcp-sse.js)

5. Salesforce Apex MCP Client (VTOApexMCPClient.cls)

🚀 Quick Start

Option 1: MCP Client Demo (Interactive Web UI)

Option 2: REST API (for Heroku/Salesforce)

Option 3: MCP Server (for Claude Desktop)

⚡ Salesforce Agentforce Integration

How It Works:

MCP Message Example:

Key Features:

Why This Matters:

🌐 REST API Endpoints

GET /

GET /health

POST /api/search

GET /api/opportunity/:id

🔧 MCP Tools

search_volunteer_opportunities

get_opportunity_details

🚀 Deploy to Heroku

Quick Deploy:

Detailed Guide:

🧪 Testing

Test REST API:

Test MCP Server:

🔗 Integration Examples

Salesforce Apex

JavaScript/Node.js

Python

curl

📊 Data Source

🏗️ Architecture

REST API Flow:

MCP Server Flow (stdio):

MCP Client Flow (SSE):

Hybrid Architecture:

Multiple Integration Patterns:

📁 Project Structure

🛠️ Development

Install Dependencies:

Run REST API (Development):

Run MCP Server (Development):

Test:

🌟 Use Cases

For Enterprises:

For AI/ML Developers:

For Learning & Demos:

📚 Resources

🤝 Contributing

📄 License

🙏 Acknowledgments

📞 Support

🎉 Quick Links

1. MCP Server (`volunteer-search-server.js`)

2. MCP Client Demo (`public/index.html`)

3. REST API (`server.js`)

4. Hybrid Server (`server-with-mcp-sse.js`)

5. Salesforce Apex MCP Client (`VTOApexMCPClient.cls`)