How to Build a Scholarship Research MCP Server with Node.js, Express, and MongoDB

docker run -d --name mongo -p 27017:27017 mongo:7

MCP 主机 (Cursor 或 Claude Desktop)
        |
        |  Streamable HTTP  POST /mcp
        v
Express 应用  (createMcpExpressApp)
        |
        |  createMcpHandler 工厂
        v
McpServer  工具 / 资源 / 提示
        |
        v
奖学金服务
        |
        v
MongoDB  奖学金、savedScholarships、researchnotes

mkdir scholarship-research-mcp-server
cd scholarship-research-mcp-server
npm init -y

npm install @modelcontextprotocol/server @modelcontextprotocol/express @modelcontextprotocol/node express mongoose dotenv zod

MONGODB_URI=mongodb://127.0.0.1:27017/scholarship_research
PORT=3000
HOST=127.0.0.1

node_modules/
.env

src/
  index.js
  config.js
  db.js
  models/
  services/
  mcp/
  utils/
data/
  scholarships.json
scripts/
  seed.js
  smoke-test.js

export const config = {
  mongodbUri: process.env.MONGODB_URI ?? "mongodb://127.0.0.1:27017/scholarship_research",
  port: Number(process.env.PORT ?? 3000),
  host: process.env.HOST ?? "127.0.0.1",
};

import mongoose from "mongoose";
import { config } from "./config.js";

export async function connectDatabase() {
  mongoose.set("strictQuery", true);
  await mongoose.connect(config.mongodbUri);
  return mongoose.connection;
}

import mongoose from "mongoose";

const scholarshipSchema = new mongoose.Schema(
  {

    provider: { type: String, required: true, trim: true },
    description: { type: String, required: true },
    amountMin: { type: Number, default: 0 },
    amountMax: { type: Number, default: 0 },
    currency: { type: String, default: "USD" },
    deadline: { type: Date, default: null },
    rolling: { type: Boolean, default: false },
    educationLevels: { type: [String], default: ["undergraduate"] },
    fieldsOfStudy: { type: [String], default: ["any"] },
    gpaMinimum: { type: Number, default: null },
    citizenship: { type: [String], default: ["any"] },
    countries: { type: [String], default: ["any"] },
    firstGenerationOnly: { type: Boolean, default: false },
    womenOnly: { type: Boolean, default: false },
    numberOfAwards: { type: Number, default: 1 },
    renewable: { type: Boolean, default: false },
    applicationUrl: { type: String, required: true },
    applicationRequirements: { type: [String], default: [] },
  },
  { timestamps: true },
);

scholarshipSchema.index({

  provider: "text",
  description: "text",
  fieldsOfStudy: "text",
});
scholarshipSchema.index({ deadline: 1 });
scholarshipSchema.index({ amountMax: -1 });

export const Scholarship = mongoose.model("Scholarship", scholarshipSchema);

const savedScholarshipSchema = new mongoose.Schema(
  {
    researcherId: { type: String, required: true, default: "default" },
    scholarship: {
      type: mongoose.Schema.Types.ObjectId,
      ref: "Scholarship",
      required: true,
    },
    status: {
      type: String,
      enum: ["saved", "applying", "submitted", "won", "rejected"],
      default: "saved",
    },
  },
  { timestamps: true },
);

savedScholarshipSchema.index({ researcherId: 1, scholarship: 1 }, { unique: true });

const researchNoteSchema = new mongoose.Schema(
  {
    researcherId: { type: String, required: true, default: "default" },
    scholarship: {
      type: mongoose.Schema.Types.ObjectId,
      ref: "Scholarship",
      required: true,
    },
    body: { type: String, required: true, trim: true },
  },
  { timestamps: true },
);

const OPEN_DEADLINE_FILTER = {
  $or: [{ rolling: true }, { deadline: null }, { deadline: { $gte: new Date() } }],
};

export async function searchScholarships(filters) {
  const query = { ...OPEN_DEADLINE_FILTER };
  const and = [query];

  if (filters.keyword) {
    and.push({
      $or: [
        { title: { $regex: escapeRegex(filters.keyword), $options: "i" } },
        { provider: { $regex: escapeRegex(filters.keyword), $options: "i" } },
        { description: { $regex: escapeRegex(filters.keyword), $options: "i" } },
        { fieldsOfStudy: { $regex: escapeRegex(filters.keyword), $options: "i" } },
      ],
    });
  }

  if (filters.fieldOfStudy) {
    and.push({
      $or: [
        { fieldsOfStudy: { $regex: `^any$`, $options: "i" } },
        { fieldsOfStudy: { $regex: escapeRegex(filters.fieldOfStudy), $options: "i" } },
      ],
    });
  }

  // educationLevel, citizenship, country, minAmount, gpa, flags...

  const results = await Scholarship.find({ $and: and })
    .sort({ deadline: 1, amountMax: -1 })
    .limit(100)
    .lean();

  return rankByFieldMatch(results, filters.fieldOfStudy).slice(0, filters.limit ?? 10);
}

import { McpServer } from "@modelcontextprotocol/server";
import { registerPrompts } from "./prompts.js";
import { registerResources } from "./resources.js";
import { registerTools } from "./tools.js";

export function createScholarshipServer() {
  const server = new McpServer({
    name: "scholarship-research",
    version: "1.0.0",
  });

  registerTools(server);
  registerResources(server);
  registerPrompts(server);

  return server;
}

import * as z from "zod/v4";

将描述视为模型唯一能获取的文档。Zod 字段上的 .describe() 在转换为 JSON Schema 时会保留。这是主机告诉模型 fieldOfStudy 含义的方式。

title 是给人看的标签，description 是模型面对的契约，它们不是相同的字符串。

### 注解

注解不会改变 SDK 运行工具的方式。主机使用它们来决定需要多谨慎。

- readOnlyHint: 搜索、获取、匹配、列表、比较和截止日期设为 true

- readOnlyHint: 保存和添加备注设为 false

- idempotentHint: 保存设为 true，因为有唯一索引

- openWorldHint: 设为 false，因为这个服务器连接的是你的数据库，而不是开放网络

主机可以自动批准只读搜索，但在写入操作前询问用户。这在配置中值得增加五个额外的键。

### 返回结构

每个工具都返回 MCP 内容块：

对于领域错误（如“未找到奖学金”）返回 isError: true。仅对意外失败抛出异常。规范对此类错误的处理方式不同。来自 Zod 的验证错误永远不会到达你的处理程序，SDK 已将其转换为 isError 结果。

为快速浏览聊天记录的人格式化列表。在每一行都包含 MongoDB 的 id。后续工具需要这个 id，而模型无法生成有效的 ObjectId。

### 完整工具集

服务器注册了九个工具：

工具

功能描述

筛选目录

返回完整记录

根据学生档案对奖项进行评分

收藏奖项

显示备选列表

添加备注

读取备注

截止日期窗口

并排比较两个或三个 id

这足以完成研究循环：查找、检查、匹配、保存、标注和比较。

抵制添加 delete_everything 工具的冲动。破坏性工具需要额外确认，不属于此工作流程。

## 如何暴露资源和提示

工具不是主机获取上下文的唯一方式。

### 资源

静态资源是一个固定的 URI。目录符合这个定义：

资源模板可以覆盖一组 URI。使用 scholarship://item/{id} 而不是 scholarship://{id}。如果模式是 scholarship://{id}，URI scholarship://catalog 就会变得模棱两可。

模板需要定义 list 方法。如果无法列举实例，请传入 undefined。在此场景下可以列举，因此主机可以显示选择器。

### 提示

提示是您希望用户启动的工作流程。研究计划提示本身不会查询 MongoDB。它告诉模型使用工具，然后构建答案。

注意指令 "使用奖学金研究工具"。提示不能替代工具。它是一个脚本，能提高工具使用概率并使输出格式更一致。

第二个提示 application-checklist 会接收奖学金 id，并要求生成文档列表和倒序日历。这就是 MCP 提示擅长处理的重复性工作类型。

在许多主机中，提示参数即使值为数字也都是字符串类型。将 gpa 定义为字符串可避免在斜杠命令表单中出现"期望数字却收到字符串"的错误。

## 如何通过 Express 提供 MCP 服务

这是曾经用于处理会话的页面代码部分。在 SDK v2 中，它被替换为一个工厂加一个路由。

逐个解释每个辅助函数的作用。

createMcpHandler 接受一个返回新 McpServer 的函数。它暴露了一个符合 Web 标准的 fetch 接口。这与你从 Cloudflare Worker 导出的处理器是相同的。

toNodeHandler 将这个 fetch 接口适配为 Express 的 (req, res) 形式。你需要将 req.body 作为第三个参数传递，因为 createMcpExpressApp 已经运行了 express.json()。如果你省略了 body，适配器会尝试读取 Express 已经消费的流。

createMcpExpressApp 是 express() 的增强版，增加了两个功能：JSON 解析和 Host/Origin 检查。这些检查是为了解决 DNS 重绑定问题。恶意页面可以将自身的域名指向 127.0.0.1，如果没有 Host 检查，你的浏览器会将本地 MCP 服务器视为同源。因此默认绑定地址是 127.0.0.1。Express 服务指南中对此有更详细的说明。

app.all("/mcp", ...) 是有意为之的设计。Streamable HTTP 使用 POST 处理 JSON-RPC，使用 GET 处理 SSE 流。只注册 POST 会破坏部分客户端的兼容性。

在接收到 SIGINT 信号时关闭处理器：

close() 会等待正在进行的请求完成。之后才能安全退出。

添加 npm 脚本：

node --watch 对本地开发已经足够。这个项目不需要使用 nodemon。

## 如何填充目录

当 MCP 工具面对空数据库时，会返回 "no scholarships matched"。这是正确的，但会给用户留下不好的第一印象。

在 data/scholarships.json 中放入 20 到 30 条真实的数据记录。混合以下类型：

- 本科和研究生奖项
- STEM 领域和面向所有领域的奖项
- 针对特定国家的项目和面向全球的项目
- 滚动截止日期和固定截止日期
- 首代学生专属和仅限女性的标记

种子脚本应该替换目录而不是追加数据：

运行命令：

将 JSON 视为示例数据。知名项目的名称能让教程显得更真实。它们也要求明确说明学生必须在官方网站上核实所有数字和日期。applicationUrl 字段的存在是为了让提醒信息有地方指向。

如果之后用实时数据源替换 JSON，请保持相同的数据结构。MCP 工具不应关心文档的来源。

## 如何测试服务器

启动 MongoDB，填充数据，然后启动服务：

你应该看到：

### 健康检查

返回 JSON 状态：ok 表示 Express 已启动。但这不代表 MCP 连接正确。要验证连接，请发送 JSON-RPC 请求。

### 列出工具

响应是一个 SSE 事件，其 data: 行包含 JSON-RPC 结果。你应该看到所有九个工具，每个工具都带有从 Zod 派生的 JSON Schema。

Accept 请求头很重要。MCP Streamable HTTP 可以返回 JSON 或事件流。同时请求两者是兼容的选择。

### 调用工具

你应该得到一个编号列表，包含 id、截止日期和 GPA 最低要求。复制其中一个 id 并传递给 get_scholarship 使用。

一旦你开始调用多个方法，用 Node 编写一个小的烟雾测试比直接使用 curl 更加友好。解析 data: 行，然后打印 result.content[0].text。仓库中包含 scripts/smoke-test.js 用于此目的。

### 检查工具

MCP 检查工具是服务器的官方 GUI。将其指向 http://127.0.0.1:3000/mcp，你可以列出工具、填写参数，并在没有主机应用干扰的情况下读取资源。

当主机“看不到”你的服务器时使用检查工具。如果检查工具能工作但主机不能，问题出在主机配置中。如果检查工具失败，问题出在你的进程。

## 如何连接 Cursor 和 Claude Desktop

保持 npm start 运行。HTTP 上的 MCP 是一个实时服务器，而不是一次性 CLI。

### Cursor

在 Cursor 的 MCP 设置中添加一个服务器条目。Streamable HTTP 服务器的配置如下：

如果 Cursor 缓存了之前的失败连接，请重新启动 MCP 会话。然后提问：

> 我是一名在美国攻读计算机科学的新生，GPA 3.6。使用奖学金研究工具创建一个简短列表和一个六周计划。

你应该看到主机调用了 match_scholarships 或 search_scholarships，然后对感兴趣的结果调用 get_scholarship，最后可能调用 save_scholarship。如果从未调用过任何工具，说明服务器实际上并未连接。在修改代码前，请先在 Cursor 中检查 MCP 日志。

如果提示菜单中出现相关提示，也可以从主机的提示菜单中调用 research-plan 提示。

### Claude Desktop

Claude Desktop 的配置文件位于：

- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json

Claude Desktop 优先使用 stdio。通过 mcp-remote 连接 HTTP 服务器：

保存文件后重启 Claude Desktop。奖学金工具应该会出现在工具列表中。

不要在 Claude 配置中填写 MongoDB 凭据。Node 进程已经加载了 .env 文件。主机只需要 URL 即可。

## 研究会话的执行流程

以下是一个针对种子目录的真实会话示例。学生是计算机科学专业的一名第一代本科生，美国公民，GPA 3.6。

主机使用该档案调用 match_scholarships。服务器返回排名结果。由于不同原因，女性科技奖项和第一代计划都得分较高，而仅限研究生的奖项从未出现。

主机随后对前两名 ID 调用 get_scholarship。每个结果都包含官方 URL、要求列表和截止日期。这时应该告诉学生打开 URL。模型不应是资格判断的最终依据。

如果某个奖项值得申请，主机将使用研究员 ID（如 ada）和状态 saved 调用 save_scholarship。之后可以设置 applying 状态。list_saved_scholarships 是新聊天恢复短名单的方式。MongoDB 的持久性正是此处的关键。没有它，每次对话都必须从零开始。

add_research_note 用于处理复杂的人类细节："请在10月1日前向陈博士请求推荐信"。get_upcoming_deadlines 是每周的截止日期扫描。compare_scholarships 用于学生有两名最终候选人时，需要同时查看金额、GPA 和要求的场景。

research-plan 提示封装了这个流程。它会将档案注入用户消息，指示模型先调用工具，再生成每周计划。如果在未连接服务器时调用该提示，会得到一篇通用文章。如果在运行此服务器时调用，会得到具体奖项和真实日期。

这就是产品：一个模型可查询的目录，一个不会遗忘的短名单，以及让工作流程可重复的提示。

## 匹配逻辑的运作方式

有必要放慢匹配过程的节奏，因为这是人们容易直接交给模型处理的部分。

假设学生情况如下：

- GPA 3.6
- 计算机科学专业
- 本科生
- 美国公民
- 第一代
- 女性

匹配器会遍历所有开放奖项。

一个要求最低 GPA 3.3、列出计算机科学领域且面向美国的女性科技奖学金得分很高：教育背景、GPA、公民身份、女性专属标志和领域都符合。一个面向所有领域的第一代计划也得分很高，因为任何领域都算匹配。即使标题相关，仅限研究生的奖项也会被跳过。即使其他条件都符合，GPA 3.8 的门槛也会被跳过。

工具随后会返回带有原因的排名结果：

模型仍然可以围绕这一点撰写一段温暖的文字。它不应该成为决定资格的决定性因素。

如果以后需要扩展，保持相同的拆分方式。新的资格规则应放在服务中。新的文字内容应放在提示中。

## 下一步可以构建的内容

你目前拥有的服务器已经足够使用。它也可以作为更严肃的研究工具的基础。

首先，你可以将种子文件替换为实时数据源。官方渠道如 Grants.gov 和高校维护的列表比抓取商业聚合器更安全。保持你的数据结构。编写一个导入器，通过稳定的外部 ID 进行插入或更新。

你也可以添加身份验证。createMcpExpressApp 可以与 requireBearerAuth 配合使用。从经过验证的令牌中映射 researcherId，而不是通过工具参数。Express 适配器记录了该中间件。

尝试添加全文搜索功能。数据结构中已经包含了文本索引。对于大型目录，Atlas Search 或专用搜索引擎的效果会优于一堆正则表达式过滤器。

你可以跟踪文档，而不仅仅是备注。为转录稿、推荐状态和文章草稿创建一个文档集合，可以将短名单转变为申请跟踪器。

你还可以围绕匹配器编写测试。资格代码是那些无声错误影响用户的区域。一个包含个人资料和预期包含/排除列表的表格将物超所值。

你还可以部署它。在笔记本电脑上绑定到 127.0.0.1。如果你将这个服务部署到网络中，请设置 allowedHosts、终止 TLS 并要求 bearer token。一个开放的 MCP 服务器相当于一个带有友好英文界面的开放数据库。

## 结论

在本指南中，你构建了一个奖学金研究 MCP 服务器，它不仅仅是一个玩具工具列表。

你将奖项、短名单和备注存储在 MongoDB 中。你通过 MCP 工具暴露了搜索、匹配和研究跟踪功能，其中 Zod 模式允许主机向模型广告这些功能。你为目录添加了资源，为可重复的工作流添加了提示。你通过 Streamable HTTP 使用 Express 提供了所有功能，包括 SDK 为本地主机启用的 Host 头检查。

这种模式可以迁移。任何包含目录和个人工作集的研究流程都可以使用相同的三层结构：一个拥有规则的服务、一个注册原语的 McpServer 工厂，以及一个小型 Express 应用程序来实现协议。

如果你从本教程中只带走一个想法，请带走这个：让模型撰写计划，让你的服务器决定什么才是真实的。

示例目录仅用于学习。在申请任何奖学金之前，请务必在其官方申请页面上确认每个奖学金的信息，并在告诉其他人申请之前也进行确认。

阅读更多文章。

如果这篇文章对你有帮助，请分享它。

免费学习编程。freeCodeCamp 的开源课程已帮助超过 40,000 人成为开发者。立即开始

ADVERTISEMENT