🌐 志愿者搜索MCP服务器、客户端及REST API

A. 模型上下文协议（MCP） 服务器、客户端演示以及用于从免费资源中搜索志愿者机会的REST API 志愿者连接器API.

![License: MIT](https://opensource.org/licenses/MIT) ](https://nodejs.org/)

______________________________________________________________________

🏆 为什么这很特别？

大多数MCP（可能是指某种通信协议或中间件平台的缩写）实现都是服务器或客户端中的一个。而这个项目同时具备两者：

✅ MCP服务器 (Node.js) - 提供MCP协议服务
✅（对号，表示正确、同意或确认） MCP 客户端 (Apex) -（巅峰） 自定义Salesforce MCP客户端
✅ MCP 客户端 (JavaScript) - 基于浏览器的演示
✅（对勾符号，通常表示正确、同意或完成） REST API（Representational State Transfer Application Programming Interface，表述性状态传递应用程序编程接口） - 传统的HTTP端点
✅ 混合架构 - 一体化部署

💡 为何Apex MCP客户端至关重要：

Salesforce原生不支持MCP协议。 这个项目实现了 在Apex中从零开始构建完整的JSON-RPC 2.0 MCP客户端这使得Salesforce Agentforce在MCP生态系统中成为了一流的存在。

这表明：

对协议规范的深入理解
在企业平台上实施AI协议的能力
传统企业（Salesforce）与前沿人工智能（MCP）之间的桥梁

______________________________________________________________________

🎯 特点

🔌 MCP 服务器 - 真实模型上下文协议实现（JSON-RPC 2.0）
📱 多个MCP客户端 - Apex（Salesforce）、JavaScript（浏览器）、Claude 桌面版
💻 MCP客户端演示 - 基于Web的交互式客户端，用于通过SSE测试MCP
🌐 REST API - 用于传统集成的HTTP端点
🔄 混合模式 - 单服务器支持REST和MCP协议
⚡ Salesforce Agentforce（可译为“Salesforce智能客服助手”或根据具体语境调整） - 用于Agentforce集成的定制Apex MCP客户端
💰 免费 - 使用VolunteerConnector API（无需认证）
🚀 Heroku 准备就绪 - 5分钟内部署到Heroku
🧪 已测试 - 包含测试脚本和现场演示
📚 文档齐全 - 完整的指南和示例

______________________________________________________________________

📦 包含内容

1. MCP 服务器 (`volunteer-search-server.js`）

实现了模型上下文协议（stdio）
与Claude Desktop及其他MCP客户端兼容
介绍两种工具：

- search_volunteer_opportunities - 带过滤器的搜索 - get_opportunity_details - 通过ID获取完整详情

2. MCP 客户端演示 (`public/index.html`）

基于网页的交互式MCP客户端
通过SSE（服务器发送事件）连接到MCP服务器
实时测试界面
美观、现代的用户界面
无需后端（纯前端）

3. REST API (`server.js`)

Express.js REST API
可部署到Heroku/Render/Railway
终点（或：评估指标）：

- GET / API信息 - GET /health - 健康检查 - POST /api/search - 寻找机会 - GET /api/opportunity/:id - 获取详细信息

4. 混合服务器 (`server-with-mcp-sse.js`)

支持REST API和通过SSE的MCP
单一部署支持多种协议
MCP终端： POST /mcp/message (JSON-RPC 2.0)
在（某处）提供MCP客户端演示服务 /
非常适合生产环境部署

5. Salesforce Apex MCP 客户端 (`VTOApexMCPClient.cls`)

用Apex编写的自定义MCP客户端
从头开始实现JSON-RPC 2.0协议
通过HTTP POST调用MCP服务器
可在Salesforce Agentforce Agent Builder中使用
方法：

- searchViaMCPProtocol - 使用MCP协议进行搜索 - listMCPTools - 发现可用的MCP工具

完全遵守协议规范 - 验证JSON-RPC响应
已准备好投入生产 企业MCP客户端

______________________________________________________________________

🚀 快速入门

选项1：MCP客户端演示（交互式网页用户界面）

# Install dependencies
npm install

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

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

你将获得：

浏览器中的交互式MCP客户端
测试志愿者进行实时搜索
查看MCP协议消息
演示版的美观用户界面

______________________________________________________________________

选项2：REST API（适用于Heroku/Salesforce）

# Install dependencies
npm install

# Start the REST API
npm start

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

______________________________________________________________________

选项3：MCP服务器（用于Claude桌面版）

# Install dependencies
npm install

# Start the MCP server
npm run start:mcp

然后添加到Claude Desktop配置中（~/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 集成

这个项目包括一个 自定义Apex MCP客户端 这使得Salesforce Agentforce能够使用模型上下文协议！

工作原理：

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

MCP消息示例：

请求（来自Apex）：

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

响应（来自服务器）：

{
  "jsonrpc": "2.0",
  "id": 42345,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "🌐 Found 5 volunteer opportunities...\n\n1. ..."
      }
    ]
  }
}

主要特点：

✅ 完全符合JSON-RPC 2.0规范
✅ 表示“正确”或“确认”。 协议验证 （检查jsonrpc版本，消息ID）
✅ 工具发现 （tools/list 方法)
✅ 工具执行 (tools/call （方法）
✅ 企业日志记录 （用于故障排除的调试日志）
✅ 错误处理 （正确的 JSON-RPC 错误响应）

为何这很重要：

大多数Salesforce集成使用REST。 这个项目证明了Salesforce能够实现 尖端的人工智能协议 通过自定义Apex客户端实现类似MCP的功能。

这使得Salesforce在MCP生态系统中成为了一流的参与者！ 🚀 表示火箭或快速上升的意象，常用于比喻快速发展、进步或某种事物迅速崛起。在中文中，可以直接用“🚀”这个符号来表达，或者根据上下文用相应的描述来传达其含义，如“火箭腾飞”、“迅速发展”等。但直接翻译时，“🚀”通常没有对应的中文文字，保留符号形式更为常见。

______________________________________________________________________

🌐 REST API 接口

GET /

返回API信息和可用的终端节点。

GET /health 翻译为中文是：“获取/健康（信息）”

健康检查端点。

回答：

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

POST /api/search 翻译为中文是：“向 /api/search 发送 POST 请求”

寻找志愿者机会。

请求体：

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

回答：

{
  "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..."
}

获取 /api/opportunity/:id（这里的“:id”表示一个动态参数，代表具体的机遇或机会的唯一标识符）

获取特定机会的详细信息。

回答：

{
  "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 工具

寻找志愿者机会

搜索志愿者机会，并可选择应用筛选条件。

参数：

keywords （字符串，可选）- 搜索词
location （字符串，可选）- 城市或地区
remote_only (布尔值，可选) - 远程机会过滤器
max_results （数字，可选）- 最大结果数（1-50，默认：10）

示例：

{
  "keywords": "tutoring",
  "location": "Toronto",
  "max_results": 5
}

获取机会详情

获取特定机会的详细信息。

参数：

opportunity_id （数字，必填）- 机会ID

示例：

{
  "opportunity_id": 43243
}

______________________________________________________________________

🚀 部署到Heroku

快速部署：

# 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

详细指南：

看 HEROKU_DEPLOYMENT.md 翻译为中文是：“HEROKU 部署指南.md” 或 “在 HEROKU 上的部署说明.md”（具体翻译可能根据上下文有所调整，但基本意思是指向关于如何在 HEROKU 平台上进行部署的文档或指南文件）以获取完整的部署说明。

______________________________________________________________________

🧪 测试

测试REST API：

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

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

测试MCP服务器：

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

______________________________________________________________________

🔗 集成示例

Salesforce Apex（可译为“Salesforce 阿佩克斯”或根据具体语境简化为“Salesforce Apex语言/开发平台”，但通常直接保留“Salesforce Apex”这一名称，因其已成为专有名词）

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

Map body = new Map{
    '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}'

______________________________________________________________________

📊 数据来源

这个项目使用了 志愿者连接器API:

网址： https://www.volunteerconnector.org/api/search/ 翻译为中文是：“https://www.志愿者连接器.org/api/搜索/”。但需要注意的是，实际翻译网址时，通常不会直接翻译网址中的内容，而是保留原网址不变，因为网址是全球通用的，不需要翻译。不过，如果只是翻译网址中的文字部分，如“search”可以翻译为“搜索”，那么上述翻译就是合理的。在实际应用中，我们仍然会使用原网址
成本： 免费（无需认证）
覆盖范围： 北美地区969+个志愿服务机会
更新： 实时
文档： https://www.volunteerconnector.org/api 翻译为中文是：“https://www.志愿者连接器.org/应用程序编程接口（或‘API’）”。不过，通常在中文语境中，我们可能会更简洁地表述为“志愿者连接器网站的API”或直接保留原网址（因为网址本身在中文中也是通用的）。所以，一个更自然的翻译可能是：“志愿者连接器网站的API（网址：https://www.volunteerconnector.org/api）”

______________________________________________________________________

🏗️ 建筑

REST API 流程：

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

MCP服务器流量（标准输入输出）：

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

MCP客户端流（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 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

多种集成模式：

客户端类型	协议	端点	使用场景
Salesforce（REST）	HTTP REST	`/api/search`	标准集成
Salesforce（MCP）	JSON-RPC 2.0	`/mcp/message` 符合协议的人工智能
网页浏览器	JSON-RPC 2.0	`/mcp/message`	互动演示
克劳德桌面版	MCP（标准输入输出）	不适用（标准输入输出）	本地AI助手

______________________________________________________________________

📁 项目结构

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

______________________________________________________________________

🛠️ 开发

安装依赖项：

npm install

运行REST API（开发）：

npm run dev

运行MCP服务器（开发版）：

npm run dev:mcp

测试：

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

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

______________________________________________________________________

🌟 应用场景

对于企业：

Salesforce Agentforce（可译为“Salesforce 代理力量”或根据具体语境调整为更贴切的表述，但直接翻译保持原名结构） - 为AI代理（REST或MCP）添加志愿者搜索功能
企业虚拟试穿（VTO）项目 - 帮助员工寻找志愿工作
志愿者管理平台 - 整合外部志愿者机会
手机应用程序 - 寻找当地的志愿者机会
非营利组织网站 - 展示志愿者机会

对于AI/ML开发者：

克劳德桌面版 - 通过stdio实现原生MCP集成
定制化人工智能助手 - 为任何兼容MCP的人工智能添加志愿者搜索功能
协议研究 - 研究MCP客户端/服务器实现
多协议架构 - 学习REST + MCP混合模式

用于学习和演示：

交互式演示 - 使用网页客户端进行演示和测试
黑客马拉松（或编程马拉松） - 展示MCP集成的现场演示
协议教育 - 学习JSON-RPC 2.0和MCP规范
Salesforce 扩展 - 自定义Apex MCP客户端的示例

______________________________________________________________________

📚 资源

MCP 文档： https://modelcontextprotocol.io/ 的中文翻译可以是：“https://模型上下文协议.io/”（注：实际网址翻译中，网址本身通常保持不变，这里的翻译只是为了说明网址内容的大致含义，即“模型上下文协议”的网站）。在实际应用中，网址一般直接使用英文原样，不进行翻译
志愿者连接器API： https://www.volunteerconnector.org/api（该网址本身不直接翻译，但可表述为“志愿者连接器组织的API网址”）
Heroku 文档： https://devcenter.heroku.com/ 翻译为中文是：https://devcenter.heroku.com/（注：网址本身在中文语境下通常不翻译，保持原样即可，但这里为了符合问题要求，仅说明其含义为“Heroku开发者中心”的网址）。不过，更常见的表述方式是直接保留网址，因为网址是全球通用的，无需翻译
Express.js:（可翻译为）Express框架（或简称Express） https://expressjs.com/（中文可表述为）：https://expressjs.com/（Express.js 官方网站）

______________________________________________________________________

🤝 贡献

欢迎投稿！请随意：

报告错误
建议功能
提交拉取请求
改进文档

______________________________________________________________________

📄 许可证

MIT 许可证 - 请参阅许可证详情请参阅文件。

______________________________________________________________________

🙏 致谢

志愿者连接器 提供免费志愿者机会的API
Anthropic（公司名，可译为“安萨蒂克”或根据具体语境保留原名） 用于创建模型上下文协议
Heroku 便于部署的平台

______________________________________________________________________

📞 支持

问题： 在GitHub上打开一个议题（或问题）
API状态： 请访问 https://www.volunteerconnector.org/
MCP 帮助： 访问 https://modelcontextprotocol.io/

______________________________________________________________________

🎉 快捷链接

🚀 表情符号“🚀”在中文中通常被翻译为“火箭”或保持原样作为表情使用，不直接对应具体文字含义，但在这里可以理解为“火箭”的意象。所以，可以翻译为“🚀（火箭）”。不过，在实际应用中，这个表情符号往往直接作为表情使用，不翻译成具体文字。入门指南
💻（电脑） MCP 客户端演示 - 首先启动混合服务器
机器人 Claude 桌面版安装
📖 书籍的符号，常用于表示阅读或书籍相关内容。 Heroku 部署指南
🧪 表示“实验器材”或“科学实验”的意思。测试API
🔌 电源插头/插座 MCP 文档
🌐 代表“地球/互联网/网络”的符号志愿者连接器API

______________________________________________________________________

为志愿者社区倾心打造

如果你觉得这个仓库有用，请给它加个星⭐！

volunteermcp (Satishtamilan)

快速接入

详细介绍

🌐 志愿者搜索MCP服务器、客户端及REST API

🏆 为什么这很特别？

💡 为何Apex MCP客户端至关重要：

🎯 特点

📦 包含内容

1. MCP 服务器 (volunteer-search-server.js）

2. MCP 客户端演示 (public/index.html）

3. REST API (server.js)

4. 混合服务器 (server-with-mcp-sse.js)

5. Salesforce Apex MCP 客户端 (VTOApexMCPClient.cls)

🚀 快速入门

选项1：MCP客户端演示（交互式网页用户界面）

选项2：REST API（适用于Heroku/Salesforce）

选项3：MCP服务器（用于Claude桌面版）

⚡ Salesforce Agentforce 集成

工作原理：

MCP消息示例：

主要特点：

为何这很重要：

🌐 REST API 接口

GET /

GET /health 翻译为中文是：“获取/健康（信息）”

POST /api/search 翻译为中文是：“向 /api/search 发送 POST 请求”

获取 /api/opportunity/:id（这里的“:id”表示一个动态参数，代表具体的机遇或机会的唯一标识符）

🔧 MCP 工具

寻找志愿者机会

获取机会详情

🚀 部署到Heroku

快速部署：

详细指南：

🧪 测试

测试REST API：

测试MCP服务器：

🔗 集成示例

Salesforce Apex（可译为“Salesforce 阿佩克斯”或根据具体语境简化为“Salesforce Apex语言/开发平台”，但通常直接保留“Salesforce Apex”这一名称，因其已成为专有名词）

JavaScript/Node.js

python

curl（注：这是一个命令行工具的名称，在中文中通常直接音译，不翻译其功能或用途）

📊 数据来源

🏗️ 建筑

REST API 流程：

MCP服务器流量（标准输入输出）：

MCP客户端流（SSE）：

混合架构：

多种集成模式：

📁 项目结构

🛠️ 开发

安装依赖项：

运行REST API（开发）：

运行MCP服务器（开发版）：

测试：

🌟 应用场景

对于企业：

对于AI/ML开发者：

用于学习和演示：

📚 资源

🤝 贡献

📄 许可证

🙏 致谢

📞 支持

🎉 快捷链接

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

1. MCP 服务器 (`volunteer-search-server.js`）

2. MCP 客户端演示 (`public/index.html`）

3. REST API (`server.js`)

4. 混合服务器 (`server-with-mcp-sse.js`)

5. Salesforce Apex MCP 客户端 (`VTOApexMCPClient.cls`)