joblet-mcp-grok

MCP のスタンドアロンサーバーで、読み取り専用の joblet.ai 求人検索を Grok およびその他の標準準拠 MCP ホストに公開します。独立したデプロイであり、Joblet の他のコネクタとはインフラストラクチャ、ブランチ、リリーストレインを一切共有しません。

2つのツールを提供します。どちらも読み取り専用です（readOnlyHint: true）：

• search_jobs — 実際にアップストリームで適用される勤務地フィルターを備えたキーワード検索。MCP レイヤーでの関連性フィルタリング（タイトル/カテゴリ/業界/職種のトークン一致。説明のみの一致は拒否）、expVer/類似重複の重複排除、結果は最大8件にハードキャップされます。テキストと structuredContent を返し、さらにレンダリング対応ホスト向けの MCP Apps 求人カードウィジェットも提供します。

• get_job_details — ジョブ ID による完全な掲載内容（説明、応募要件、担当業務、判明している場合は給与と勤務地、応募リンク）。

応募 URL はバイト単位でそのまま渡されます（Joveo のトラッキングは保持され、プロキシやリダイレクトはありません）。雇用形態は意図的に表示もフィルタリングもされません。アップストリームの検索では信頼できるフィールドが提供されないためです。

要件

• Node.js 18+（Node 24 で開発およびテスト済み）

• API キーやシークレットは不要 — アップストリームの joblet.ai API は公開されています

ローカルセットアップ

npm ci
npm run build        # bundles the widget to dist/mcp-app.html (required before start)
PORT=3010 npm start  # MCP endpoint at http://localhost:3010/mcp

ヘルスチェック：

# GET /health  ->  {"status":"ok","version":"1.1.0"}

MCP エンドポイント：POST /mcp — Streamable HTTP、JSON レスポンス、ステートレス（セッション ID なし）。仕様標準の Accept: application/json, text/event-stream ヘッダーが必要です。GET / はサービスバナーを返します。

MCP 契約をローカルで検証する

MCP_URL="http://localhost:3010/mcp" node test_client.mjs
MCP_URL="http://localhost:3010/mcp" node test_widget.mjs

または対話的に：npm run inspect（MCP Inspector → Streamable HTTP → /mcp の URL）。

開発

npm run typecheck    # server + widget/tests configs
npm test             # vitest suites (server pipeline, widget, a11y, logging)
npm run build        # production widget bundle

設定

.env.example を参照してください。すべてオプションで、デフォルトは本番環境に適した値です。MCP_REQUEST_LOG=1 を設定すると、呼び出しごとのサニタイズ済みログが有効になります（ハッシュ、長さ、件数のみ。生のクエリテキスト、勤務地、応募 URL、認証情報は決してログに含まれません）。

ウィジェットの注記

求人カードウィジェットは、MCP Apps の sendSizeChanged 通知を介して固有の高さをホストに報告します（高さのみ。requestAnimationFrame 後に計測。リサイズループを避けるため、変更時のみ通知）。また、ホストコンテナの固定高さが宣言されている場合は、それに従います。ホストがそれに応じて iframe をリサイズするかどうかは、ホスト側の挙動です。「表示＆応募」CTA は、標準準拠の ui/open-link リクエストを使用し、ホストが拒否するかサポートしていない場合には、カード内の可視かつアクセシブルなフォールバック（リンクとコピー操作）を常に提供します — 黙って失敗することはありません。