JobMojito

JobMojito MCP 服务

欢迎

JobMojito 提供 3 种由 AI 主导的对话体验。它们之间的差异很重要，因为其中一个工具可以创建其中两种：

• 面试 — 用于招聘的评分问答。根据职位描述生成问题，或自行提供问题；可使用纯语音面试官、实时视频虚拟形象或预录虚拟形象进行面试，支持 30 多种语言，并提供完全品牌化的候选人体验。
• 模拟角色 — 虚拟形象不会按问题列表提问，而是在自由对话中扮演一个设定好的角色——持怀疑态度的买家、愤怒的客户、难以应对的利益相关者等——并根据受测者的应对方式进行评分。其邀请、计费和结果流程与面试相同，因此结果会与其他内容一起显示在招聘人员的结果列表中。
• 辅导 — 同一角色引擎用于练习，而非评估。学习者从可浏览的目录中自行开始会话，按秒扣除个人辅导时长，结果不会向招聘人员公开。可通过目录、标签筛选器和 Markdown 页面进行管理。

唯一需要注意的陷阱。 create_persona 可创建第二种和第三种产品，具体由其 portal 参数决定——而该参数默认为 coaching。凡是用于评估或筛选的场景，都必须显式传入 portal="interview"，否则会悄无声息地创建错误的产品：扣错额度，招聘人员也看不到结果。

这三种体验都支持：批量登记候选人并为每人提供专属链接；向 AI 使用的知识库上传文档；读取文字记录、结构化分析以及可分享的 HTML 或 PDF 报告；管理不同商户及子商户的工作区、额度和分析数据。

平台生成的所有内容仅供具备资质的人工审核人员辅助决策——绝不会替代招聘决策本身，并且会告知候选人流程中涉及 AI。

产品相关资源：管理控制台位于 app.jobmojito.com，开发者/API 文档位于 developer.jobmojito.com，帮助中心位于 help.jobmojito.com，本仓库提供支持的托管 MCP 端点位于 https://mcp.jobmojito.com/mcp。

本仓库是 MCP 服务，可将上述所有功能接入 Claude 和 ChatGPT 等 AI 助手。

---

这是一个用于 JobMojito API 的 MCP 服务，使用 FastMCP 构建，旨在部署到 Prefect Horizon（FastMCP 团队推出的 MCP 平台——app.prefect.cloud → Horizon）。

它提供：

• 32 个 API 工具，根据 JobMojito 实时 OpenAPI 规范自动生成（面试、模拟角色和辅导目录、候选人与结果、知识库、商户列表/分析数据、自定义报告）。所有端点——包括 GET 列表——都会以工具形式提供，并采用简洁且经过整理的名称，每个工具都带有标题及只读/破坏性操作注解。
• 2 个文档工具（search_documentation、get_documentation），可实时读取开发者文档和帮助中心——文档仍以现有平台为唯一来源；本仓库不会复制任何内容。
• Supabase OAuth，让最终用户可以直接通过 Claude、ChatGPT 等客户端登录。每次调用都会将已登录用户的 Supabase JWT 转发给 JobMojito API。

---

整体运作方式

MCP client (Claude / ChatGPT)
        │  OAuth login (Supabase OAuth Server, DCR)
        ▼
JobMojito MCP server (this repo, on Horizon)
        │  forwards the user's Supabase JWT
        ▼
JobMojito API  (https://cool.jobmojito.com/functions/v1)

关注点	方案
API → 工具	FastMCP.from_openapi(...)，所有路由都映射为工具，通过注入的 operationId 设置精选名称
规范时效性	启动时实时获取；运行时缓存和已提交的快照作为备用
身份验证	SupabaseProvider（远程 OAuth）；每次请求都将 JWT 转发给上游 API
文档	内置工具从 developer.jobmojito.com/llms.txt 和 .md 以及 help.jobmojito.com（Featurebase）帮助中心读取内容

文件

文件	用途
server.py	入口点 — 构建并公开 mcp（将 Horizon 指向 server.py:mcp）
config.py	由环境变量驱动的设置
openapi_loader.py	实时获取 + 缓存/快照回退 + 注入 operationId
naming.py	为每个端点设置精选的工具名称、标题、提示和注释
upstream.py	将用户的 Supabase JWT 转发给 API 的 httpx 客户端
middleware.py	调用日志记录、改写上游错误、结果大小限制、补充注释
merchants.py	商家选择器（MCP App UI）+ list_my_merchants 文本回退
docs_tools.py	search_documentation / get_documentation
featurebase.py	Featurebase REST 客户端（帮助中心文章）
mintlify.py	Mintlify 开发者文档 MCP 代理 + 客户端凭证身份验证
tests/	test_smoke.py（清单、架构放宽、文档）+ test_listing_readiness.py（目录契约）
docs/	开发者文档：架构、开发、部署
scripts/update_snapshot.py	刷新已提交的备用规范
scripts/try_docs.py	文档工具的本地冒烟测试
data/openapi.snapshot.json	离线备用规范（在你的机器上重新生成）
lazy_auth.py	未经身份验证的能力发现 + 401 挑战中的 scope=
wellknown.py	/healthz、OpenAI 域名挑战、Smithery 服务卡片
server.json	官方 MCP Registry 条目
.github/workflows/publish-registry.yml	当推送到 main 的更改涉及 server.py:SERVER_VERSION 时（或手动触发时），将 server.json 发布到 MCP Registry

---

本地开发与测试（macOS）

# 1. Set up a virtualenv and install deps
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# 2. Configure secrets in .env (auto-loaded; gitignored)
cp .env.example .env        # then fill in your keys/credentials

# 3. Static check — see exactly what Horizon will deploy
fastmcp inspect server.py:mcp

# 4. Run the unit tests (offline; uses the snapshot fallback)
ENABLE_AUTH=false pytest -q --asyncio-mode=auto

# 5. Smoke-test the docs tools live (Featurebase + Mintlify federation)
ENABLE_AUTH=false python scripts/try_docs.py "how do I create an interview"

# 6. Run the server and connect a client
ENABLE_AUTH=false python server.py        # → http://localhost:8000/mcp
#   then, in another terminal, open the MCP Inspector:
npx @modelcontextprotocol/inspector
#   transport: "Streamable HTTP", URL: http://localhost:8000/mcp

测试说明：

• 文档工具（search_documentation，以及挂载的 Mintlify search_*_developer_* / query_docs_filesystem_*）可在 ENABLE_AUTH=false 时使用，无需登录 Supabase。scripts/try_docs.py 是最快的检查方式。
• API 工具（create_interview、list_candidates 等）会调用真实的 JobMojito API，需要 Supabase 用户令牌。本地测试时，在 .env 中设置 JOBMOJITO_DEV_BEARER_TOKEN，并填入有效的 Supabase 访问令牌；当 ENABLE_AUTH=false 时，该令牌会被转发。（切勿在生产环境中设置此项——生产环境中的令牌 来自用户的 OAuth 会话。）
• 在本地运行完整 OAuth 的情况很少见；如需使用，请在运行时设置 ENABLE_AUTH=true、设置 BASE_URL=http://localhost:8000，并连接支持 OAuth 的客户端 （客户端会将你重定向到 Supabase）。

从可访问该 API 的网络刷新备用快照： python scripts/update_snapshot.py（此仓库中已提交的快照只是一个精简的结构备用版本； 运行此命令会将其替换为完整的实时规范）。

---

Supabase OAuth 配置

此服务使用 Supabase 的 OAuth Server 功能（支持动态客户端注册，因此 MCP 客户端会自行注册）。MCP 服务是 OAuth 资源服务器——负责验证令牌；令牌由 Supabase 签发。

项目： https://momsbvnltsydezmoesqt.supabase.co SupabaseProvider 根据此项目 URL 推导出所有端点：

端点	URL
授权	…/auth/v1/oauth/authorize
令牌	…/auth/v1/oauth/token
JWKS	…/auth/v1/.well-known/jwks.json
OIDC 发现	…/auth/v1/.well-known/openid-configuration

步骤：

1. Supabase Dashboard → Authentication → OAuth Server
   • 启用 OAuth Server 和 Allow Dynamic OAuth Apps
   • Site URL： https://app.jobmojito.com
   • Authorization Path： /oauth/consent
2. 环境变量：SUPABASE_PROJECT_URL=https://momsbvnltsydezmoesqt.supabase.co， BASE_URL=https://mcp.jobmojito.com（公开的基础 URL，不含 /mcp）， SUPABASE_JWT_ALGORITHM=ES256（如果 JWKS 显示 RSA 密钥，则切换为 RS256）。
3. 如果 JobMojito Edge Functions 需要 apikey 标头，请设置 SUPABASE_ANON_KEY。

授权由 Supabase / 你的应用处理，而非此服务。 由于 Site URL 是 app.jobmojito.com，Supabase 会在 https://app.jobmojito.com/oauth/consent 提供批准/拒绝页面，用户在此处已经拥有 Supabase 会话。此 MCP 服务仅充当 OAuth 资源服务器——不会提供授权页面。SITE_URL 和 OAUTH_CONSENT_PATH 仅供参考，应与 Supabase OAuth Server 设置一致。

令牌说明：SupabaseProvider 无法验证令牌的受众（Supabase Auth 尚未实现 RFC 8707 资源指示符）。这是预期行为，启动时会记录此信息。

---

身份验证模型

每次工具调用都要求用户通过 Supabase OAuth 登录—— 包括 search_documentation 和 get_documentation。请保持 ENABLE_AUTH=true； 已登录用户的令牌会转发到 JobMojito API，确保调用遵循该用户的权限。

唯一有意设置的例外是能力发现：当 ENABLE_LAZY_AUTH （默认值为 true）启用时，initialize、ping 和 */list 方法无需令牌即可响应，以便目录爬虫呈现工具列表。通过这种方式无法访问任何数据——每次 tools/call、资源读取和提示词仍需经过验证的 JWT。

部署到 Prefect Horizon

1. 将此仓库推送到 GitHub。
2. 在 horizon.prefect.io 使用 GitHub 登录并 选择此仓库。
3. 配置：
   • Entrypoint： server.py:mcp
   • Dependencies： 根据 requirements.txt 自动检测
   • Horizon Authentication： off —— 此服务提供自己的 Supabase OAuth，因此应由它充当身份验证层。
4. 设置环境变量 / 密钥：
   • ENABLE_AUTH=true
   • BASE_URL=https://mcp.jobmojito.com —— 至关重要。 这必须是服务的 公开基础 URL，不含 /mcp，且末尾不带斜杠。SupabaseProvider 会将其作为 OAuth 资源公布；如果保留默认值 http://localhost:8000，客户端会收到 401 invalid_token。启动 日志会输出 base_url=…，并在 URL 指向 localhost 时发出警告。
   • SUPABASE_PROJECT_URL=https://momsbvnltsydezmoesqt.supabase.co
   • 如果 Edge Functions 需要 apikey 标头，则设置 SUPABASE_ANON_KEY。
   • 用于帮助中心文档的 FEATUREBASE_API_KEY。
5. 部署。 你的 MCP 端点为 https://mcp.jobmojito.com/mcp。Horizon 会在每次推送到 main 时重新部署。

测试登录

initialize 返回 401 是 MCP OAuth 正常的第一步——客户端应读取发现元数据并执行 Supabase 登录。Horizon 的 Inspector / ChatMCP 不会执行该登录，因此会显示一个单独的 401。可通过在 Claude.ai 中添加 https://mcp.jobmojito.com/mcp 作为自定义连接器来测试，该连接器会运行完整的 OAuth 流程并提示进行 Supabase 登录。

请确保已配置 Supabase 端（否则无论如何都会出现 401）：启用 OAuth Server 和 Dynamic Client Registration；Site URL 设置为 https://app.jobmojito.com，Authorization Path 设置为 /oauth/consent；并在应用上托管该授权同意页面。

由于 OpenAPI 规范会在启动时实时获取，每次重新部署都会自动采用最新的 JobMojito API。

---

保持文档单一来源

这里不会重复存放文档。search_documentation 会构建实时索引，get_documentation 会按需获取页面，两者都直接读取源平台。只需在源平台编辑文档，MCP 就会在缓存 TTL 内反映更改（DOCS_CACHE_TTL_MINUTES，默认值为 60）。

来源	读取方式	凭据
developer.jobmojito.com（Mintlify）	将 Mintlify MCP 挂载到此服务中（客户端凭据已设置时使用语义 search + query_docs_filesystem，包括导入的 OpenAPI）；否则通过内置工具读取公开的 llms.txt/.md	MCP 客户端 ID/密钥（用于联合接入）
help.jobmojito.com（Featurebase）	如果设置了 FEATUREBASE_API_KEY，则使用 REST API（结构化文章，包括正文）；否则抓取公开 HTML	API 密钥（可选）

为什么既需要此服务，也需要 Mintlify

Mintlify 会导入 OpenAPI，但其 MCP 是只读文档——它允许 Agent 搜索和阅读 API 参考文档，但无法调用 API。此服务会将同一份 OpenAPI 转换为经过身份验证、可调用的工具（以已登录的 Supabase 用户身份执行）。因此，Mintlify 回答“它是如何工作的？”，而此服务则“实际执行操作”。联合接入会将 Mintlify 的文档搜索工具与操作工具一并挂载，让最终用户通过一个连接器同时获得两者。

开发者文档：Mintlify 联合接入

developer.jobmojito.com 是一个 Mintlify 网站，其 MCP 提供 search + query_docs_filesystem 工具（包括导入的 OpenAPI）。此服务会将其作为代理挂载。启用联合接入后，内置的开发者 llms.txt 来源会被禁用，以避免重复。

默认公开（无需凭据）。 Mintlify 在 /mcp 提供公开的 MCP。由于开发者文档是公开的，DEVELOPER_DOCS_MCP_URL 默认设为 https://developer.jobmojito.com/mcp，且挂载时不进行身份验证——开箱即用。

经过身份验证的端点（可选）。 Mintlify 还提供带有 OAuth 客户端凭据的 /authed/mcp 端点，用于访问受群组限制的内容。默认未启用——在启用前，网站的 /.well-known/mcp 只会公布 public 服务。使用方法：

1. 在 Mintlify 控制面板中，前往 MCP server page → Enable MCP Server（否则 /authed/mcp/oauth/token 会返回 404）。
2. 在那里创建客户端凭据（MCP client credentials，不是 Mintlify API 密钥）→ 设置 DEVELOPER_DOCS_MCP_CLIENT_ID / _CLIENT_SECRET。
3. 设置 DEVELOPER_DOCS_MCP_URL=https://developer.jobmojito.com/authed/mcp。

只有当 URL 包含 /authed 且两个凭据都已设置时，才会附加身份验证；随后服务会在 {url}/oauth/token 处交换凭据，并缓存/刷新令牌。

Featurebase：各凭据的用途

Featurebase 以三种方式提供文档——凭据的形式可以告诉你是哪一种：

• REST API → 单个 API 密钥（通过 Authorization: Bearer <key> 和 X-API-Key 发送），基址为 https://do.featurebase.app。在 Featurebase 控制面板中创建：登录 auth.featurebase.app/choose-org → 设置 → 高级 → API → 复制密钥。（直接访问 /settings/api 会返回 404——必须先进入你的组织。）本服务使用此凭据访问帮助中心（设置 FEATUREBASE_API_KEY）。
• 托管 MCP（mcp-read.featurebase.app，Reader 连接器）→ 交互式 OAuth（授权码 + PKCE，无客户端密钥）。设计用途是让用户在 Claude/ChatGPT 中点击“连接”。最好在 AI 客户端中直接将其添加为连接器，而不是通过本服务代理（没有机器令牌 / 客户端凭据授权）。
• 公共网页 → llms.txt / .md（开发者文档），无需身份验证。

Client ID + Client secret 组合不是 Featurebase 文档凭据—— REST API（API 密钥）和 MCP（PKCE，无密钥）都不使用这种形式。 如果你有这类凭据，它很可能属于 Featurebase SSO/身份 OAuth 应用，或来自其他 系统。访问文档请使用上面的 REST API 密钥。

Featurebase Reader MCP（未联合）

与 Mintlify 不同，Featurebase 的 Reader MCP（mcp-read.featurebase.app）仅 支持交互式 OAuth（不支持客户端凭据），因此未在此处挂载。如果你想使用其原生搜索功能，请在 AI 客户端中直接将其添加为连接器。 配置中的 HELP_DOCS_MCP_URL 仅供参考。

---

目录列表与可发现性

本服务已构建完成，无需进一步修改代码即可满足 Anthropic 连接器目录、OpenAI 插件目录（ChatGPT + Codex）和官方 MCP Registry 的要求。具体如下：

要求	所在位置
每个工具都有 title 和 readOnlyHint/destructiveHint，并附有书面说明	naming.py::TOOL_META，由 server.py::_customize_component 应用，并由 middleware.ToolMetadataBackfillMiddleware 补全
读取和写入是分开的工具（没有包罗万象的工具）	naming.py — 在 tests/test_listing_readiness.py 中断言
tools/list 无需凭据即可运行，让爬虫能够显示工具列表	lazy_auth.py
受保护资源元数据中的 scopes_supported，以及 401 响应中的 scope=	server.py::_build_auth + lazy_auth.WWWAuthenticateScopeMiddleware
提供可执行操作的错误信息，而非空泛的 4xx/5xx	middleware.UpstreamErrorMiddleware
结果大小不超过客户端的上限	middleware.ResultSizeGuardMiddleware
用于运行时间监控的健康探测	GET /healthz
OpenAI 域名验证	GET /.well-known/openai-apps-challenge（设置 OPENAI_APPS_CHALLENGE_TOKEN）
MCP Registry 条目	server.json + 发布工作流

生成 OpenAI 提交时要求的注释说明：

python -c "import naming,json;print(json.dumps(naming.annotation_justifications(),indent=2))"

每次部署或更改主机名后，验证公开身份——这是原本健康的服务却对所有客户端返回 401 的最常见原因：

curl -s https://mcp.jobmojito.com/.well-known/oauth-protected-resource/mcp
# "resource" MUST equal "https://mcp.jobmojito.com/mcp"
curl -s https://mcp.jobmojito.com/healthz

收录平台

目录	状态
官方 MCP Registry（com.jobmojito/jobmojito）	已发布 — 当 main 上的 server.py:SERVER_VERSION 发生变化时，publish-registry.yml 会触发，而非在 git 标签变更时触发。Registry 版本不可变，因此更改描述需要提升版本号。
OpenAI 插件目录（ChatGPT + Codex）	已收录
Anthropic 连接器目录	审核中
Glama	已收录
Smithery	已收录

此仓库之外仍需处理的事项

代码已准备就绪；以下问题与代码无关：

1. 在 MCP 主机以及 Supabase 前面的所有设施上，将 Anthropic 的出站 IP 范围 160.79.104.0/21 加入允许列表。拦截请求的 WAF 是 Anthropic 文档中最常见的失败原因。
2. 对 /.well-known/*、llms.txt 和 *.md 绕过 CDN 缓存，并确认服务器前面没有任何设施会缓冲 SSE。
3. 确保审核人员的测试账户可用。两个目录都可能在收录后重新测试；如果账户用完额度，失败表现会像是服务故障。