Opportunity Mcp

Opportunity MCP

一个 Model Context Protocol 服务，让任何 AI 助手都能搜索面向青年的机会——奖学金、奖助金、实习、会议和交流项目。数据实时汇总自领先的机会发现网站。

状态： alpha（v0.1.x）。随着适配器逐渐成熟，架构、工具接口和来源列表可能会发生变化。生产环境中请固定使用次要版本。

---

概览

依赖第三方奖学金聚合网站的学生，通常会打开十几个标签页，从几十条无关帖子中筛选信息，再把截止日期复制到个人电子表格中——但最终仍可能错过申请窗口，因为没有聚合网站能可靠地追踪截止日期。Opportunity MCP 将这一整套工作流浓缩为一次对话式查询。

你： 查找未来 60 天内截止、面向巴基斯坦公民且涵盖全部费用的欧洲硕士奖学金。

Claude： （返回从索引来源实时获取并去重的结构化列表，按截止日期排序，每项均附有指向原文的链接。）

该服务通过 stdio 在本地运行，附带 SQLite + FTS5 索引，每六小时通过 CI 刷新一次，并通过 PyPI、官方 MCP Registry 和 Smithery 分发。

---

分发渠道

渠道	标识符	状态
PyPI	opportunity-mcp	✅ 已上线
MCP Registry	io.github.revolutionarybukhari/opportunity-mcp	✅ 已发布
Smithery	sayedhusnainhader/opportunity-mcp	✅ 已发布
GitHub	revolutionarybukhari/opportunity-mcp	权威来源
GitHub Releases	每 6 小时刷新一次的 SQLite DB index-N 快照	由 CI 自动发布

---

安装

Claude Desktop

pip install opportunity-mcp
opportunity-mcp-refresh           # build the local index (one-off, ~30 seconds)

将以下内容添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "opportunities": {
      "command": "opportunity-mcp"
    }
  }
}

重启 Claude Desktop。模型即可使用以下六个工具。

Cursor、Windsurf、Continue 和其他 MCP 客户端

大多数客户端使用相同的 mcpServers 结构。将 command 指向 opportunity-mcp（安装 pip install 后），或使用 uvx 实现免安装运行：

{
  "mcpServers": {
    "opportunities": {
      "command": "uvx",
      "args": ["opportunity-mcp"]
    }
  }
}

Smithery（一键安装）

https://smithery.ai/server/sayedhusnainhader/opportunity-mcp — Smithery 会为你处理安装命令。

从源代码安装

git clone https://github.com/revolutionarybukhari/opportunity-mcp
cd opportunity-mcp
uv sync                           # or: pip install -e ".[dev]"
uv run opportunity-mcp-refresh
uv run opportunity-mcp            # speaks MCP over stdio

---

工具

该服务提供六种工具。每种工具都接受 JSON 参数，并返回经 Pydantic 类型验证的结果。

工具	签名	描述
search_opportunities	(query, type?, funded_only?, deadline_before?, limit=20)	在所有已索引的机会中进行全文搜索，并支持可选筛选条件。
get_opportunity	(id)	根据 ID 获取单个机会的完整详情。
list_latest	(type?, limit=20)	列出所有来源中最新的机会，按发布日期排序。
list_upcoming_deadlines	(within_days=30, type?)	列出 N 天内截止的机会，按截止日期排序。
list_sources	()	列出已索引的来源、条目数量和上次刷新时间戳。
refresh_index	(source?)	按需重新抓取来源。可选的 source 参数可将刷新范围限定为一个网站。

type 可取 scholarship、fellowship、internship、conference、exchange、competition、grant、award 或 other。

---

已索引来源

已通过各网站的 RSS feed 验证为可用。

来源	机制	状态
Opportunities Corners	RSS	✅ 可用
Opportunities for Youth	RSS	✅ 可用
Opportunity Desk	RSS	✅ 可用
Scholarships Corner	RSS	✅ 可用
Opportunities Circle	RSS	✅ 可用
Opportunities for Africans	RSS	✅ 可用
Scholars4Dev	RSS	✅ 适配器可用（上游 feed 当前为空）
Youth Opportunities	HTML	计划中
After School Africa	HTML	计划中

各来源的 robots.txt 合规情况、服务条款说明和 CI 注意事项已记录在 docs/SOURCES.md 中。

---

提示词示例

Find fully-funded master's scholarships in Europe with deadlines in the next 60 days.

What conferences are happening in Africa in the next three months?

List the ten newest internships indexed today.

Show me everything closing in the next seven days that an undergraduate could apply to.

Get full details for opportunity 7733b95a81e3239d.

---

架构

AI client  ──MCP──▶  FastMCP server  ──▶  SQLite + FTS5  ◀──  refresh job  ──▶  source adapters  ──▶  opportunity sites

两个清晰分离的职责：

1. 适配器负责读取单个网站，并生成原始 Opportunity 对象（通过 Pydantic 验证）。
2. 查询引擎不需要了解任何网站，只需搜索规范化索引。

添加新来源通常只需提交一个约 50 行的拉取请求。请参阅 docs/ADAPTER_GUIDE.md。完整的架构设计理由请参阅 docs/ARCHITECTURE.md。

---

隐私与伦理

• 不跟踪用户。 所有查询都在本地处理；除定期刷新来源网站外，不会有任何数据离开用户的设备。
• 所有已索引数据均为公开信息。 摘要最多 500 个字符，且每条记录都会链接回原始文章。
• 礼貌标识。 HTTP User-Agent 中包含项目 URL，方便网站所有者直接联系我们。
• 保守的刷新频率。 通过 CI 每六小时最多轮询一次来源，不会因用户查询而刷新。
• 应要求移除来源，并在 24 小时内处理，不作协商。
• 每个适配器在抓取前都会遵守 robots.txt。

---

路线图

• 阶段 2 — 支持按国家、级别和语言提取信息（目前由 AI 客户端负责）。
• 阶段 3 — 添加首个 HTML 适配器（Youth Opportunities），并扩大 Tier-2/Tier-4 来源的覆盖范围。
• 阶段 4 — 提供托管的 Streamable-HTTP 端点，供倾向使用远程 MCP 服务的客户端使用。
• 阶段 5 — 可选的每周摘要，依据已保存的个人资料生成。

带有 add a source 标签的未解决问题适合作为首次贡献。

---

贡献

欢迎提交拉取请求。最快的参与方式是添加我们尚未索引的来源——请阅读 docs/ADAPTER_GUIDE.md 并提交 PR。开发环境设置、测试规范和行为准则要求请参阅 docs/CONTRIBUTING.md。

git clone https://github.com/revolutionarybukhari/opportunity-mcp
cd opportunity-mcp
uv sync
uv run pytest
uv run ruff check .

---

许可证

MIT © Opportunity MCP Contributors。