geneworks-mcp

v0.2.4

Published

21 days ago

Claude Code セッションを解析して人材プロフィール (skill_listings) を生成する GENE ワークス公式 MCP server

0High
0Medium
0Low

genesis-corp

ryotarogenesisbiz

mcp claude claude-code geneworks talent skill-listings profile-generation

geneworks-mcp

GENE ワークス公式 MCP server。 Claude Code セッションを解析し、公開可能な抽象スキル listing を含む人材プロフィールを生成する。

ステータス: Step 1 (D'' 設計、ローカルプロフィール生成パイプライン) 完成。 Step 2 (TEE / AWS Nitro Enclaves) は別フェーズ。

アーキテクチャ概要

~/.claude/projects/**/*.jsonl              ← Claude Code セッション (parse のみ、 本文は LLM に流さない)
        │
        ▼ collector + analyzer (SHA256 cache、 並列、 LLM 不要)
   vanilla.core                            ← 観測値: edit_log + 4 ヒストグラム + activity_summary
        │
        ▼ overlays (touched path の直接親階層から fetch、 fail-soft)
   vanilla.overlays                        ← README.md / CLAUDE.md / manifest / git log (Author=本人)
        │
        ▼ aggregator (LLM 集約 1 回、 confidence は数式で先算出して LLM に注入)
   interpreted                             ← skill_listings[] + candidate_info + _meta
        │
        ▼ persist (atomic write)
   ~/.geneworks/profile.json
        │
        ▼ MCP tools
   ├─ refresh_profile(cwd_filter?, skip_interpreted?)
   ├─ get_profile(view?)
   └─ list_skill_listings(max_results?)

インストール (Claude Code ユーザー向け)

GENE ワークスの /talent/mcp 画面で 新規発行 ボタンを押すと、「Claude Code に貼るだけ」のセットアップ指示プロンプトが生成される。そのまま Claude Code にコピペすれば、 Claude が以下を自動で行う:

~/.geneworks/token ファイルを作成 (BOM なし、 mode 0600)
.mcp.json に geneworks エントリを追加 (= env block 不要、 token は file 経由で読まれる)
「Claude Code を再起動してください」と案内

手動セットアップする場合 (= 推奨パス):

1. token を ~/.geneworks/token に書き込む (= PowerShell の Set-Content は BOM を付けるので NG、 [IO.File]::WriteAllText を使う):

# Windows PowerShell
New-Item -Path "$HOME\.geneworks" -ItemType Directory -Force | Out-Null
[IO.File]::WriteAllText("$HOME\.geneworks\token", "<your token>")

# macOS / Linux
mkdir -p ~/.geneworks
printf '%s' '<your token>' > ~/.geneworks/token
chmod 600 ~/.geneworks/token

2. ~/.claude.json (or プロジェクトの .mcp.json) に geneworks エントリ追加 (= env block 不要):

{
  "mcpServers": {
    "geneworks": {
      "command": "npx",
      "args": ["-y", "geneworks-mcp"]
    }
  }
}

3. Claude Code を再起動 → refresh_profile / list_skill_listings が見えれば接続成功。

token rotation (再発行)

~/.geneworks/token を新しい値で上書きするだけ。 .mcp.json は触らない (= MCP 自己改変を伴わないので Claude Code が auto-mode で edit を block する事故も起きない)。

後方互換 (= 既存ユーザー)

旧来通り .mcp.json の env: { GENEWORKS_TOKEN: "..." } でも動作する。ただし優先順位は file 優先 → env fallback。 file が書かれた瞬間に file の値が勝つため、古い env を残したまま rotation しても問題ない。

初回利用 (onboarding gate)

geneworks-mcp は初回利用時にロール (talent / buyer / inbox) の選択が必要です。

動作

インストール直後の Claude Code セッションで何か tool を呼ぶ
server gate が ~/.geneworks/onboarded の不在を検出し、 isError + 「getting_started を呼べ」を返す
Claude が getting_started を呼ぶ → 三択メニューが表示される
ユーザーがロールを選ぶ → 該当 tool フローが進む
以降 getting_started は (ユーザーが明示的に呼ばない限り) 起動されない

`~/.geneworks/onboarded` JSON 形式

{
  "v": 1,
  "user_id": "<PAT に紐づく user_id>",
  "completed_at": "ISO8601"
}

PAT を別ユーザーに切り替えた場合 (= user_id 不一致) は再 gate 発火し、 onboarding wizard が再走する。

既存ユーザー (= 本機能リリース前から MCP を使ってる talent ユーザー)

stdio server プロセス起動時 (= 通常 Claude Code セッションごとに 1 回) のマイグレーションが、「onboarded JSON が無い」かつ「profile.json が有る」ユーザーを自動 onboard する。ユーザー操作は不要。

開発

# 依存解決 (monorepo root から)
cd ../../
pnpm install

# 起動 (= dev モード、 tsx watch)
cd apps/mcp-server
pnpm dev

# ビルド (= dist/ 生成)
pnpm build

# 型チェックのみ
pnpm lint

ローカル開発時の手動登録 (npm 公開版を使わずに最新コードで動かす):

{
  "mcpServers": {
    "geneworks": {
      "command": "node",
      "args": ["<path-to>/apps/mcp-server/dist/index.js"]
    }
  }
}

MCP tool 一覧

全 tool が PAT 単体 で動作する (= access_token / user_id を引数で渡す必要なし)。 PAT は ~/.geneworks/token から自動 resolve され、 Edge Function 経由で user_id に展開される。

| tool | 入力 (PAT は自動) | 役割 | |---|---|---| | getting_started | (引数なし) | onboarding wizard。三択 (talent / buyer / inbox) を返して ~/.geneworks/onboarded を touch。詳細は §「初回利用 (onboarding gate)」参照 | | refresh_profile | cwd_filter? (substring)、 skip_interpreted? (bool) | JSONL を全件 parse → vanilla 生成 → LLM 集約で interpreted 生成 → ~/.geneworks/profile.json に persist | | get_profile | view? (vanilla / interpreted / both) | profile.json の中身を返す | | list_skill_listings | max_results? (1〜100)、 view? (human / ai / both) | interpreted.skill_listings を confidence 降順 sort で返す | | upload_profile | (引数なし、 PAT 自動) | profile.json を Supabase の seller_profiles / skill_listings_flat に upsert | | search_talents | project_id? / skill_tags? / domains? / complexity? / min_confidence? / max_results? | skill_listings_flat を絞り、 user 単位で集約して上位を返す | | create_project | title / description / required_skills / budget_*? / deadline? | 案件 (projects) を構造化して作成 | | send_scout | project_id / seller_ids / message | 候補 (1〜20) に一括スカウト | | list_inbound_scouts | limit? (1〜500) | 受注者として自分宛て scout 一覧 | | list_outbound_scouts | limit? (1〜500) | 発注者として自分が送った scout 一覧 | | get_scout_thread | scout_id | scout 1 つの thread (scout 行 + messages 全件) | | draft_reply | scout_id / body / message_type | scout 返信を 下書き で保存 (本人承認前) | | send_reply | message_id | 下書き message を確定 (送信) + thread_status='replied' | | accept_scout | scout_id / body? | seller として scout 受諾 + thread_status='accepted' | | reject_scout | scout_id / body? | seller として scout 拒否 + thread_status='rejected' |

環境変数

| 変数 | デフォルト | 用途 | |---|---|---| | GENEWORKS_TOKEN | (なし) | GENE ワークス Personal Access Token (cm_pat_* 形式)、後方互換用。推奨は ~/.geneworks/token ファイル経由 (= file 優先)。 /talent/mcp で発行 | | GENEWORKS_TOKEN_PATH | ~/.geneworks/token | token ファイルの絶対パス上書き (テスト用)。通常変更不要 | | GENEWORKS_PARALLEL | 4 | session 解析の並列度 (大きすぎると fs / cache 競合) | | GENEWORKS_CLAUDE_BIN | 自動探索 | claude CLI 実行ファイルの絶対パス。探索失敗時に必須 | | GENEWORKS_TIMEOUT_MS | 600000 (10 min) | LLM 集約 1 回あたりの subprocess timeout | | GENEWORKS_CWD_BLACKLIST | (空) | listing 候補から除外する cwd substring のカンマ区切りリスト。デフォルト blacklist (node_modules / worktrees / references_repositories 等) に追加する | | GENEWORKS_GIT_AUTHOR | git config user.email | overlays の git log を絞る author email | | GENEWORKS_NOW_ISO | new Date().toISOString() | テスト時の現在時刻固定 (recency 計算用) | | GENEWORKS_SUPABASE_URL | (本番値) | Supabase URL override (テスト用)。 me Edge Function (/functions/v1/geneworks-me) の URL 解決にも使用 | | GENEWORKS_SUPABASE_PUBLISHABLE_KEY | (本番値) | Supabase publishable key override (テスト用) |

失敗時のデバッグ (= Edge Function error response の読み方)

upload_profile が HTTP エラーで失敗した場合、 Edge Function は 500 系 response に kind + detail_sanitized を含めて返す。 MCP client (Claude Code 等) は raw error 文字列を読むだけで原因把握できる設計。

[upload_profile] FAILED: upload failed (HTTP 500) kind=listings_insert_failed detail="Could not find the 'price_jpy_suggested' column of 'skill_listings_flat' in the schema cache"

kind 一覧

| kind | 意味 | 典型的対処 | |---|---|---| | config_missing | Edge Function の env (SUPABASE_URL / SERVICE_ROLE_KEY) が不在 | Supabase Dashboard → Edge Function settings で env 設定 | | pat_lookup_failed | mcp_pats query 失敗 | DB 接続 / RLS 確認 | | seller_upsert_failed | seller_profiles upsert 失敗 | schema 整合性 / 制約違反確認 | | listings_delete_failed | skill_listings_flat 既存削除失敗 | 権限 / 連鎖 FK 確認 | | listings_insert_failed | skill_listings_flat bulk insert 失敗 | column 名 typo / 制約違反 / schema cache 確認 | | uncaught | 想定外の例外 (= 致命系) | Supabase Dashboard Logs で stack trace |

Troubleshooting: 「upload は成功するのに DB に値が反映されない」

症状

upload_profile 自体は 200 で完了 (= MCP server log に「upload 完了」)、でも DB 側で:

新規追加した field が全 null
リネーム済 field が旧名のまま store されてる
listing 件数や schema_version が古い

真因の構造

upload_profile ツールは ~/.geneworks/profile.json (= local cache) をそのまま Edge Function に送るだけ。 aggregator を走らせない。つまり cache が古いスキーマで生成されたまま居座ってると、 client / server をいくら最新化しても 永遠に旧形式 payload を送り続ける。

ツールごとの責務:

refresh_profile = JSONL parse → vanilla → LLM 集約 → ~/.geneworks/profile.json 生成・上書き (uploadなし)
upload_profile = ~/.geneworks/profile.json 読み取り → Edge Function POST (= 再集約しない)

診断 (= 最短 1 分)

# 1) cache の中身を grep して旧スキーマキー残ってないか確認
Get-Content "$env:USERPROFILE\.geneworks\profile.json" | Select-String "<旧キー名>" | Measure-Object -Line
Get-Content "$env:USERPROFILE\.geneworks\profile.json" | Select-String "<新キー名>" | Measure-Object -Line

# 2) cache の最終更新時刻を確認 (= リリース時刻より古ければ古い schema で生成されてる証拠)
(Get-Item "$env:USERPROFILE\.geneworks\profile.json").LastWriteTime

# macOS / Linux
grep -c "<旧キー名>" ~/.geneworks/profile.json
grep -c "<新キー名>" ~/.geneworks/profile.json
stat ~/.geneworks/profile.json

解決

refresh_profile を実行  ← cache を最新 aggregator で再生成 (= 数十秒〜数分、 LLM 集約 1 回 + 全 session parse)
upload_profile を実行    ← 新 cache を Edge Function に送信

401 系は generic 維持

unauthorized (= PAT 認証失敗) は kind なしの generic response。攻撃者へのヒント漏洩 (= revoked vs not_found の区別等) を防ぐため意図的に詳細を出さない。 PAT 失敗時は /talent/mcp で revoke 状態を本人確認。

detail_sanitized の挙動

200 字に切り詰め
token / pat / secret / key / password / cm_pat_* / bearer * / sbp_* / sk_* 等の禁止語を含むなら <redacted: contains potential secret> に置換
平文 PostgrestError message (= column 名 / table 名 / constraint 名) は通常通り表示 (= info disclosure リスク低い)

Supabase Cloud のログ制約

Edge Function の application log (= console.log / logEvent) は SQL では取れない (= Logflare backed)。詳細追加調査が必要な場合のみ Supabase Dashboard → Edge Functions → Logs タブを参照。基本は client (Claude) が response の kind + detail_sanitized だけで原因把握できる設計。

v0.1.x からの migration (PAT 認証統一)

v1.0.0 (= 仮、実際の version は release-please が決定) 以降、 scout 系 9 tool (create_project / send_scout / list_inbound_scouts / list_outbound_scouts / get_scout_thread / draft_reply / send_reply / accept_scout / reject_scout) の引数から access_token (Supabase JWT) と user_id が削除されました。 PAT (~/.geneworks/token 経由) 1 つで全 tool が動作します。

既存ユーザー: 既存 PAT をそのまま使用可。再発行は不要 (mcp_pats テーブルは無変更)
call site の変更: 引数で access_token / user_id を渡すコードは動かなくなる。引数を削除する
install プロンプト: /talent/mcp の install プロンプトは v1.0.0 で更新済。 caller (Claude Code 等) が旧バージョンのプロンプトを記憶している場合は、新しいプロンプトをコピペし直す
直接 PostgREST を叩いていた caller: 旧 v0.1.x は内部で PostgREST + JWT を直叩きしていたが、 v1.0.0+ は全て Edge Function 経由になった。 user が Supabase JWT を持つ必要は無くなった (= service_role の漏洩リスクが構造的に 0)

cache 運用 (`~/.geneworks/cache/`)

session 解析結果は ~/.geneworks/cache/<sessionId>.core.json に SHA256 cache される。

不変条件: schema_version (現在 core-v2) と source_sha256 の両方が一致した場合のみ cache hit
schema 変更時: analyzer.ts の SCHEMA_VERSION 定数を bump する (例: core-v2 → core-v3)。既存 cache は全 invalidate されて自動再 parse される
手動クリア: Remove-Item -Recurse ~/.geneworks/cache/ で全削除可。次回 refresh_profile で再生成

profile.json 本体には別途 schema_version (interpreted 含む) が埋まる。

ノイズ除去 (cwd blacklist)

list_skill_listings の品質を保つため、以下の cwd は listing 候補から除外される (vanilla.core には残る):

依存・ビルド成果物: node_modules / .next / dist / build / .cache / __pycache__ / .venv / venv
Claude Code worktree: .claude/worktrees/
参考用 OSS clone: references_repositories
一時ディレクトリ: appdata\local\temp / /tmp/ / /temp/ (Claude が smoke / デバッグ用スクリプトを書く場所)

ユーザー環境固有のノイズは GENEWORKS_CWD_BLACKLIST で追加可能。例:

$env:GENEWORKS_CWD_BLACKLIST = "antigravity_vtube,scratch,sandbox"

Buyer Flow (3 ステップ)

buyer は以下 3 つの tool を順に呼ぶことで「要件構造化 → 候補絞込 → 一括スカウト」を完結できる。省人化マッチング (Claude 介在で面談なし) + ココナラ的 listing-as-product モデルが両立する設計。

詳細仕様: docs/buyer_mcp_tools_design_20260523.md

1. `create_project` — 要件を構造化して案件 (projects) を作る

戻り値: { projectId, status, createdAt }

2. `search_talents` — project を起点に候補を絞る

project_id を渡すと projects.required_skills を skill_tags のソースに使う。 public.user_profiles view 経由で PII 安全な公開列のみ返す。

3. `send_scout` — 候補に一括スカウト

cooldown (24h)、 self-scout、 role_invalid を rejected 配列で個別返却。詳細は上記 docs 参照。

Buyer Flow 設計思想

省人化マッチング: Claude が要件ヒアリング → create_project → search_talents → send_scout を代行。 buyer は意思決定だけ
構造化要件: free-form scout message で予算/納期が抜けるリスクを排除
listing-as-product: talent が listing に price_jpy 付けて出品中なら、即発注経路 (= scout 不要) も同じ search で返す
PII 安全: search_talents は public.user_profiles view 経由で users JOIN (公開列のみ。 email / phone / 姓名 / dob 等は anon 経路から完全遮断)

License

UNLICENSED (private)。 GENE ワークス内部利用専用。第三者が独自利用する場合は GENESIS にお問い合わせください。

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

geneworks-mcp

アーキテクチャ概要

インストール (Claude Code ユーザー向け)

token rotation (再発行)

後方互換 (= 既存ユーザー)

初回利用 (onboarding gate)

動作

~/.geneworks/onboarded JSON 形式

既存ユーザー (= 本機能リリース前から MCP を使ってる talent ユーザー)

開発

MCP tool 一覧

環境変数

失敗時のデバッグ (= Edge Function error response の読み方)

kind 一覧

Troubleshooting: 「upload は成功するのに DB に値が反映されない」

症状

真因の構造

診断 (= 最短 1 分)

解決

関連した cache 階層 (= 過去事故踏破済の sibling)

401 系は generic 維持

detail_sanitized の挙動

Supabase Cloud のログ制約

v0.1.x からの migration (PAT 認証統一)

cache 運用 (~/.geneworks/cache/)

ノイズ除去 (cwd blacklist)

Buyer Flow (3 ステップ)

1. create_project — 要件を構造化して案件 (projects) を作る

2. search_talents — project を起点に候補を絞る

3. send_scout — 候補に一括スカウト

Buyer Flow 設計思想

関連

License

`~/.geneworks/onboarded` JSON 形式

cache 運用 (`~/.geneworks/cache/`)

1. `create_project` — 要件を構造化して案件 (projects) を作る

2. `search_talents` — project を起点に候補を絞る

3. `send_scout` — 候補に一括スカウト