AI导哈

黑客马拉松搜索引擎

一个基于Python的Model Context Protocol (MCP)服务器，用于发现和管理Unstop黑客马拉松，支持搜索、详情获取、基于位置的发现和缓存管理。

  • by Abhinav-Prabhakar
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 CodeDreamer06/UnstopMCP

使用说明

卸载MCP服务器

unstop-mcp 是Python 模型上下文协议（MCP） 用于发现Unstop黑客马拉松的服务器。

它揭示了：

  • MCP工具，用于搜索黑客马拉松、获取事件详细信息、运行基于位置的发现和管理缓存状态
  • 用于只读快照和每次黑客马拉松查找的MCP资源
  • MCP提示，帮助LLM计划搜索、比较黑客马拉松并推荐相关活动

此存储库现在是MCP优先。旧的直接导入Python包装器API不再是受支持的公共接口。

它所支持的

  • stdio 仅限运输
  • 仅限v1的Unstop黑客马拉松
  • 自动缓存开放式黑客马拉松，以实现快速重复查找
  • 描述、轮次、联系人、注册计数和视图的详细信息丰富
  • 使用地理编码进行可选的基于位置的搜索
  • 具有模拟上游行为的确定性单元测试
  • 可选的活烟测试与默认套件分开

需求

  • Python 3.12+
  • uv 推荐用于当地发展
  • 真实Unstop通话的网络接入

安装

选项1： uv 工作流

git clone https://github.com/your-org/unstop-mcp.git
cd unstop-mcp
uv venv
source .venv/bin/activate
uv pip install -e .

选项2：纯 pip

git clone https://github.com/your-org/unstop-mcp.git
cd unstop-mcp
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .

验证安装

unstop-mcp --help

你应该看看 stdio 运输选项。

运行服务器

在本地运行服务器 stdio:

unstop-mcp

等效模块形式：

python -m unstop_mcp

服务器有意只支持：

unstop-mcp --transport stdio

MCP表面

工具

search_hackathons

使用过滤器、排序、分页和可选缓存使用情况搜索Unstop黑客马拉松。

论据：

  • oppstatus: open | recent | expired | closed
  • region: online | offline
  • payment: paid | unpaid
  • teamsize: 1 | 2 | 3
  • usertype: college_students | fresher | professionals | school_students
  • sort: prize | days_left
  • direction: asc | desc
  • search：自由文本关键字搜索
  • page: >= 1
  • per_page: 1-100
  • use_cache: true | false

返回一个结构化对象：

  • items：标准化的黑客马拉松摘要
  • pagination：总计/当前页/最后一页/每页/有更多
  • cache：缓存新鲜度元数据
  • applied_filters：用于呼叫的已验证输入

get_hackathon_details

通过数字ID获取单个黑客马拉松的完整详细信息。

论据：

  • hackathon_id

退货：

  • item：规范化局部视图
  • cache：描述当前服务器缓存状态的元数据

search_hackathons_by_location

使用地理编码和半径过滤查找位置附近的离线黑客马拉松。

论据：

  • location
  • radius_km
  • region
  • payment
  • teamsize
  • usertype
  • search
  • sort: prize | days_left | distance
  • direction
  • page
  • per_page

返回与相同的规范化结构 search_hackathons，加上：

  • location.search_location
  • location.search_radius_km
  • location.search_coordinates

refresh_cache

强制重建缓存的开放黑客马拉松数据集。

退货：

  • cache

get_cache_info

在不重建完整数据集的情况下检查缓存状态。

退货：

  • cache

资源

unstop://cache/info

缓存新鲜度、TTL和项目计数的只读JSON视图。

unstop://hackathons/open

所有缓存的开放黑客马拉松的只读JSON快照。

unstop://hackathons/{hackathon_id}

特定黑客马拉松的只读JSON详细视图。服务器在可能的情况下提供缓存数据，并在需要时回退到直接获取细节。

鼓励

find_relevant_hackathons

指导LLM收集缺失的用户偏好，调用正确的搜索工具，并总结最佳匹配。

论据：

  • user_goal

compare_hackathons

指导LLM获取多个黑客马拉松并进行比较。

论据：

  • hackathon_ids

plan_hackathon_search

指导法学硕士为发现任务调用哪些工具和资源，以什么顺序调用。

论据：

  • user_request

输出形状

工具和资源结果被标准化为稳定的JSON友好字段，而不是返回原始的上游Unstop有效载荷作为主要合约。

每个黑客马拉松项目包括：

  • id
  • title
  • status
  • region
  • is_paid
  • public_url
  • description
  • prize_amount
  • prize_summary
  • filters
  • required_skills
  • organisation
  • address
  • registration
  • rounds
  • contacts
  • distance_km 适用时

即使上游响应形状不同，这也能使MCP合同保持可预测性。

客户端设置

通用MCP客户端

将您的MCP客户端指向以下命令：

unstop-mcp

如果您的客户端需要一个绝对命令路径，请使用您环境中的路径，例如：

/absolute/path/to/.venv/bin/unstop-mcp

克劳德桌面版

示例 claude_desktop_config.json 条目：

{
  "mcpServers": {
    "unstop": {
      "command": "/absolute/path/to/.venv/bin/unstop-mcp",
      "args": []
    }
  }
}

法典

配置启动的本地MCP服务器条目：

{
  "command": "/absolute/path/to/.venv/bin/unstop-mcp",
  "args": []
}

如果您的Codex设置通过单独的配置文件或UI管理MCP服务器，请使用相同的命令，不要使用额外的参数。

发展

项目布局

  • src/unstop_mcp/server.py：FastMCP服务器定义和MCP注册
  • src/unstop_mcp/service.py：不稳定获取、缓存、规范化和地理编码逻辑
  • src/unstop_mcp/schemas.py：经过验证的输入和标准化的输出模型
  • src/unstop_mcp/config.py：环境驱动的运行时配置
  • tests/：单元、MCP注册、stdio烟雾和可选的现场测试

环境变量

这些是可选的：

  • UNSTOP_MCP_TIMEOUT
  • UNSTOP_MCP_MAX_RETRIES
  • UNSTOP_MCP_RETRY_DELAY
  • UNSTOP_MCP_CACHE_TTL_SECONDS
  • UNSTOP_MCP_DETAIL_WORKERS
  • UNSTOP_MCP_DETAIL_DELAY
  • UNSTOP_MCP_GEOCACHE_PATH
  • UNSTOP_MCP_USER_AGENT

缓存的工作原理

  • 搜索开放式黑客马拉松可以使用内存中的快照，而不是在每次调用时都点击Unstop
  • 快照过时时会自动重建
  • refresh_cache 迫使立即重建
  • 地理编码缓存被持久化到磁盘上，因此重复的位置查找不会不必要地重新查询地理编码器

地理编码行为

  • 位置搜索取决于 geopy
  • 直接使用具有明确坐标的离线黑客马拉松
  • 当坐标丢失时，服务器会尝试多个地址变量并缓存结果
  • 除非查询明确要求，否则仅在线黑客马拉松将被排除在半径搜索之外 region="online"

测试

运行默认测试套件：

python -m pytest -q

默认套件包括哪些内容：

  • 验证和解析
  • 标准化搜索响应
  • 缓存元数据与过时行为
  • 位置过滤
  • MCP工具/资源/提示注册
  • 基本端到端 stdio 启动和工具列表

可选的活烟测试

默认情况下，这些选项被排除在外：

UNSTOP_MCP_RUN_LIVE_TESTS=1 python -m pytest -q -m live

仅当您想根据真实网络验证当前的Unstop集成时，才使用实时测试。

本地验证

有用的本地检查：

python -m pytest -q
python -m unstop_mcp --help

如果您已经使用了MCP检查器，请将其指向本地 unstop-mcp 命令和 stdio 传输以交互方式检查已注册的工具、资源和提示。

错误处理

服务器在进行上游调用之前验证输入。

常见故障案例：

  • 枚举值无效，例如不受支持 oppstatus 或 sort
  • 空或无法解析的位置输入
  • 瞬态或永久性上游不稳定故障
  • 缺少位置搜索的地理编码支持

在可能的情况下，工具故障会表现为MCP面临验证或请求错误。

局限性

  • stdio 仅在v1中
  • 仅限v1的黑客马拉松
  • 上游Unstop字段和可用性可能会发生变化
  • 位置精度取决于源地址质量和地理编码质量
  • 缓存刷新可能比简单的细节获取需要更长的时间，因为它大量丰富了开放式黑客马拉松

扩展服务器

如果你想在以后添加更多的Unstop机会类型，请保持此分割：

  • 在中添加新的上游获取/解析逻辑 service.py
  • 在中定义新的已验证合同 schemas.py
  • 在中注册新的MCP曲面 server.py

这使得传输问题与域逻辑分开。

许可证

麻省理工学院

相关 MCP