{"id":50320055,"url":"https://github.com/unlock-the-world/keyvox-mcp","last_synced_at":"2026-05-29T03:03:07.772Z","repository":{"id":361045140,"uuid":"1252036463","full_name":"Unlock-the-World/keyvox-mcp","owner":"Unlock-the-World","description":"KEYVOXのスマートロックを自然言語で操作する Claude Skills コレクション","archived":false,"fork":false,"pushed_at":"2026-05-29T01:48:55.000Z","size":65,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-29T02:21:31.791Z","etag":null,"topics":["access-control","anthropic","claude-code","claude-skills","hospitality","japanese","keyvox","mcp","oauth2","smart-lock"],"latest_commit_sha":null,"homepage":"https://developers.keyvox.co","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Unlock-the-World.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-28T06:12:59.000Z","updated_at":"2026-05-29T01:46:40.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Unlock-the-World/keyvox-mcp","commit_stats":null,"previous_names":["unlock-the-world/keyvox-mcp"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/Unlock-the-World/keyvox-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Unlock-the-World%2Fkeyvox-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Unlock-the-World%2Fkeyvox-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Unlock-the-World%2Fkeyvox-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Unlock-the-World%2Fkeyvox-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Unlock-the-World","download_url":"https://codeload.github.com/Unlock-the-World/keyvox-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Unlock-the-World%2Fkeyvox-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33634611,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-29T02:00:06.066Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["access-control","anthropic","claude-code","claude-skills","hospitality","japanese","keyvox","mcp","oauth2","smart-lock"],"created_at":"2026-05-29T03:03:04.231Z","updated_at":"2026-05-29T03:03:07.761Z","avatar_url":"https://github.com/Unlock-the-World.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# KEYVOX MCP Skills\n\nKEYVOX アクセス管理サービスを **自然言語で操作する** ための [Claude Skills](https://docs.claude.com/en/docs/claude-code/skills) コレクション。\n\n予約管理・チェックイン確認・滞在中サポート・清掃計画の4業務領域をカバーします。\n\n## なぜ作ったか\n\nKEYVOX API には 70近いエンドポイントがあり、業務と API の紐付けには熟練が必要です。\n本スキル群を `~/.claude/skills/` に配置すると、Claude に以下のような自然言語で依頼するだけで業務が完結します。\n\n- 「今日の BCLtest の予約見せて」 → `keyvox-reservation`\n- 「101 号室のゲスト入った？」 → `keyvox-checkin-status`\n- 「ゲストが鍵忘れた」 → `keyvox-onsite-support`\n- 「今日の清掃対象は？」 → `keyvox-housekeeping`\n\nAPI キー覚える必要なし、コマンド覚える必要なし、自然な日本語で。\n\n## スキル一覧\n\n| スキル名 | 役割 | カバー業務 | SKILL.md |\n|---|---|---|---|\n| `keyvox-reservation` | 予約管理 | 新規予約 / 確認 / 延長 / 変更 / キャンセル | [リンク](./skills/keyvox-reservation-SKILL.md) |\n| `keyvox-checkin-status` | チェックイン確認 | 本日の状況 / 個別確認 / 未チェックイン抽出 | [リンク](./skills/keyvox-checkin-status-SKILL.md) |\n| `keyvox-onsite-support` | 滞在中サポート | 鍵忘れ対応 / 緊急解錠 / 状況確認 | [リンク](./skills/keyvox-onsite-support-SKILL.md) |\n| `keyvox-housekeeping` | 清掃計画 | 本日の清掃対象 / 今すぐ入れる部屋 / 利用統計 | [リンク](./skills/keyvox-housekeeping-SKILL.md) |\n\n## 必要なもの\n\n- [Claude.ai](https://claude.ai)（Pro / Max / Team / Enterprise プラン）または [Claude Code](https://docs.claude.com/en/docs/claude-code)\n- KEYVOX アカウント（管理画面 BACS にログインできる）\n- KEYVOX MCP コネクタの **OAuth2 クライアント ID**\n  - [KEYVOX サポートポータル](https://support.keyvox.co) からチケットで発行依頼してください\n  - 依頼時に必要な情報: `redirect_uri = https://claude.ai/api/mcp/auth_callback`\n\n\u003e **環境別の動作**\n\u003e - **Claude.ai (Web版) / Claude Desktop**: 公式サポート対象。Claude Desktop は Claude.ai の Web 設定を共有するので同じコネクタ設定が使えます。\n\u003e - **Claude Code (CLI/IDE)**: Claude.ai のコネクタは Claude Code には自動同期されません。Claude Code から使う場合は別途 `.mcp.json` 等で MCP server を設定する必要があります。\n\n---\n\n## 🚀 非エンジニア向けクイックスタート (Claude Desktop / Claude.ai)\n\n\u003e ターミナル / git / コマンドライン操作なしで使う方法です。Claude.ai の **Project 機能** にスキルを「知識」として読み込ませます。\n\u003e Pro / Max / Team / Enterprise プランが必要 (Project 機能はFreeプラン非対応)。\n\n### ステップ 1: KEYVOX MCP コネクタを接続する (5〜10 分)\n\n1. [KEYVOX サポートポータル](https://support.keyvox.co) で **「Claude 連携用の OAuth2 クライアント ID 発行希望」** とチケットを投げる\n   - 伝える情報: `redirect_uri = https://claude.ai/api/mcp/auth_callback`\n   - 返ってくるもの: クライアント ID (英数字の文字列)\n2. Claude Desktop または Claude.ai を開く → **設定 → コネクタ → カスタムコネクタを追加**\n   - 名前: `keyvoxMCP`\n   - URL: `https://eco.blockchainlock.io/mcp/sse`\n   - クライアント ID: ステップ 1 で取得した値\n3. **「連携」** → BACS にログイン → 同意画面で **対象組織を必ず明示的に選択** (デフォルトのままだと業務データを操作できません)\n\n### ステップ 2: このリポジトリを ZIP でダウンロード (1 分)\n\n1. このページ右上の **緑色の「Code」ボタン** → **「Download ZIP」** をクリック\n   ![Download ZIP](https://docs.github.com/assets/cb-13128/mw-1440/images/help/repository/code-button.webp)\n2. ダウンロードした `keyvox-mcp-main.zip` を解凍\n3. フォルダの中に `skills/` と `references/` があることを確認\n\n### ステップ 3: Claude の Project にスキルを読み込ませる (5 分)\n\n1. Claude Desktop / Claude.ai のサイドバー → **「Projects」** → **「Create project」**\n2. プロジェクト名: `KEYVOX 業務` (任意)\n3. **「Project knowledge」** エリアに、解凍したフォルダから以下 9 ファイルをドラッグ\u0026ドロップ:\n   ```\n   skills/keyvox-reservation-SKILL.md\n   skills/keyvox-checkin-status-SKILL.md\n   skills/keyvox-onsite-support-SKILL.md\n   skills/keyvox-housekeeping-SKILL.md\n   references/keyvox-mcp-setup.md\n   references/keyvox-entities.md\n   references/keyvox-tool-map.md\n   references/keyvox-id-resolution.md\n   references/keyvox-enums.md\n   ```\n4. **「Project instructions」** 欄に以下をコピペ:\n   ```\n   あなたは KEYVOX アクセス管理サービスの業務アシスタントです。\n   Project knowledge にアップロードされている 4 つの SKILL.md と\n   5 つの references/*.md を必ず参照してください。\n\n   - ユーザーの発話から該当スキル (reservation / checkin-status /\n     onsite-support / housekeeping) を判定し、対応する SKILL.md の\n     手順に従って MCP ツール (keyvoxMCP コネクタ) を呼び出す\n   - 不可逆操作 (createReservation, cancelReservation, unlock,\n     createLockPin 等) は必ずユーザーの最終承認を取ってから実行\n   - 401 / E2003 エラー時は keyvox-mcp-setup.md の「定型応答」を\n     そのままユーザーに出力 (要約・言い換え禁止)\n   ```\n5. **保存** して、このプロジェクト内で新しいチャットを開始\n\n### ステップ 4: 動作確認 (1 分)\n\nプロジェクト内のチャットで以下を試す:\n\n```\n今日の予約見せて\n```\n\n→ Claude が `keyvoxMCP` コネクタの `listReservations` を呼んで、本日の予約一覧を返せば成功 🎉\n\n### ❓ うまく動かないとき\n\n| 症状 | 対処 |\n|---|---|\n| Claude が「ツールが見つからない」と言う | コネクタが接続済みか確認 (設定 → コネクタ → `keyvoxMCP` が「接続済み」になっているか) |\n| 「権限がない」「データがない」と言われる | 対象組織の選択ミス。コネクタを一度「切断」して再連携、同意画面で正しい組織を選ぶ |\n| Project knowledge にアップロードできない | ファイル数 / サイズ上限の可能性。Free プランでは Project 自体が使えないので Pro 以上か確認 |\n| その他 | [Discord](https://discord.gg/Etd3vZPKhb) または [KEYVOX サポート](https://support.keyvox.co) へ |\n\n### 💡 アップデートの取り込み方\n\nこのリポジトリが更新されたら、再度 ZIP をダウンロードして Project knowledge のファイルを上書きしてください。手作業ですが「git の使い方を覚える」より圧倒的に早いです。\n\n---\n\n## セットアップ手順 (エンジニア向け)\n\n### Step 1: KEYVOX MCP コネクタを Claude.ai に追加\n\n1. [KEYVOX サポートポータル](https://support.keyvox.co) で OAuth2 クライアント ID を申請して取得\n2. \u003chttps://claude.ai/customize/connectors\u003e を開く\n3. 右上 **「+」** → カスタムコネクタ追加:\n   - **名前**: `keyvoxMCP` (任意。本READMEと各SKILL.md ではこの名前で参照しているので、別名にする場合は読み替えてください)\n   - **URL**: `https://eco.blockchainlock.io/mcp/sse`\n   - **クライアント ID**: Step 1 で取得した値\n4. **「連携」** ボタンで OAuth 認可フロー → BACS ログイン → 同意\n   - ⚠️ **対象組織の選択を間違えないこと**。デフォルトのままだと認証は通っても `E2003 権限不足` で API が失敗します\n5. 接続確認: 「`keyvoxMCP` に接続しました」のトーストが出れば OK\n\n### Step 2: スキルを配置\n\nClaude Code は `~/.claude/skills/\u003cskill-name\u003e/SKILL.md` という構造を期待するので、本リポのフラットな `skills/keyvox-*-SKILL.md` から **個別フォルダ + SKILL.md** にマッピングする必要があります。\n\n#### A. シンボリックリンク方式（推奨・編集が即反映）\n\n```bash\ngit clone https://github.com/Unlock-the-World/keyvox-mcp.git ~/keyvox-mcp\n\nfor skill in reservation checkin-status onsite-support housekeeping; do\n  mkdir -p ~/.claude/skills/keyvox-$skill\n  ln -sf ~/keyvox-mcp/skills/keyvox-$skill-SKILL.md \\\n         ~/.claude/skills/keyvox-$skill/SKILL.md\ndone\n```\n\n#### B. 単純コピー方式\n\n```bash\ngit clone https://github.com/Unlock-the-World/keyvox-mcp.git\n\nfor skill in reservation checkin-status onsite-support housekeeping; do\n  mkdir -p ~/.claude/skills/keyvox-$skill\n  cp ./keyvox-mcp/skills/keyvox-$skill-SKILL.md \\\n     ~/.claude/skills/keyvox-$skill/SKILL.md\ndone\n```\n\n\u003e 💡 **なぜマッピングが必要か**: 本リポは Claude Project (knowledge アップロード時にファイル名衝突を避ける必要) と Claude Code (フォルダ + `SKILL.md` 規約) の両方をサポートするため、内部ではフラットな `keyvox-*-SKILL.md` 形式で保持しています。Claude Code への配置時のみ、上記スクリプトで規約形式に展開します。\n\n### Step 3: 動作確認\n\nClaude.ai または Claude Code を **新規セッションで起動** し、以下のような発話を試す:\n\n```\nKEYVOX のテストして\n```\n\n`keyvox-reservation` 等のスキルが発火し、`place_list` を叩いて物件情報を返せば成功。\n\n## 利用例\n\n\u003e 以下の例に登場する物件名 (`BCLtest`)、ゲスト名 (山田 / 佐藤 / 鈴木)、予約 ID、PIN コード、電話番号などは **すべて架空のサンプル** です。実際の挙動はあなたの環境のデータに置き換わります。\n\n### 例1: 朝のルーチン確認\n\n```\nYou: 今日の BCLtest 予約見せて\n\nClaude:\n[keyvox-reservation 発火]\n本日 (05/28) BCLtest 予約一覧 (3件)\n| # | 時刻        | 部屋 | ゲスト | 状態 |\n|---|-------------|------|--------|------|\n| 1 | 14:00-17:00 | 101  | 山田   | 確定 |\n| 2 | 15:00-18:00 | 102  | 佐藤   | 確定 |\n| 3 | 10:00-13:00 | 103  | 鈴木   | 確定 |\n```\n\n### 例2: チェックイン状況確認\n\n```\nYou: 101 号室の山田さん入った？\n\nClaude:\n[keyvox-checkin-status 発火]\n山田太郎さん (予約 ABCDEFGHI / 101 号室 14:00-17:00)\n状態: ✅ チェックイン済\n- 初回解錠: 14:05 (QR 経由)\n- 直近解錠: 16:42\n- 解錠回数: 3 回\n```\n\n### 例3: 鍵忘れ対応\n\n```\nYou: 102 号室の佐藤さんが鍵を紛失したらしい\n\nClaude:\n[keyvox-onsite-support 発火]\n状況確認します:\n- 佐藤さんの既存 PIN: 836241 (有効期間 15:00-18:00)\nこのPINを SMS / LINE で再送するのが最速です。\nそれでも開かない場合、新規一時 PIN 発行か、リモート解錠を提案できます。\n\n新規 PIN を発行しますか？ (Y/N)\n```\n\n### 例4: 清掃計画\n\n```\nYou: 今日の清掃対象は？\n\nClaude:\n[keyvox-housekeeping 発火]\n本日の清掃対象 (BCLtest)\n| # | 部屋 | チェックアウト | 次チェックイン | 清掃可能時間枠 |\n|---|------|----------------|----------------|----------------|\n| 1 | 101  | 11:00          | 14:00 (今日)   | 3 時間         |\n| 2 | 102  | 12:00          | 翌日 10:00     | 22 時間        |\n\n合計 2 件 (うちノーショウ除外 1 件)\n```\n\n## 共通リファレンス\n\nスキル群は以下のドキュメントを参照する設計です。\n\n| ファイル | 内容 |\n|---|---|\n| [`references/keyvox-mcp-setup.md`](./references/keyvox-mcp-setup.md) | コネクタ環境前提・再認証手順・典型エラー対処 (全スキル共通) |\n| [`references/keyvox-entities.md`](./references/keyvox-entities.md) | 7 リソース（place / unit / lock / pin / card / user / reservation）の仕様 + ER 図 |\n| [`references/keyvox-tool-map.md`](./references/keyvox-tool-map.md) | 業務シナリオ → MCP ツール対応表 |\n| [`references/keyvox-id-resolution.md`](./references/keyvox-id-resolution.md) | 自然言語 → ID 解決パターン集 |\n| [`references/keyvox-enums.md`](./references/keyvox-enums.md) | `orderStateCode` 等の enum 値辞書 |\n\n## トラブルシューティング\n\n| 症状 | 対処 |\n|---|---|\n| スキルが発火しない | セッション再起動。SKILL.md の `description` が業務文脈に合っているか確認 |\n| `401 Unauthorized` | コネクタの OAuth トークン期限切れ。[`references/keyvox-mcp-setup.md`](./references/keyvox-mcp-setup.md) の再認証手順を参照 |\n| `E2003 権限不足` | OAuth 同意時の「対象組織」が間違っている。再認証して正しい組織を選択 |\n| `E0043 データが存在しません` | `placeId` / `orderId` の typo or 他組織の ID |\n| `Failed to start OAuth flow: ... DCR` | Claude Code の自動 OAuth は KEYVOX 非対応。Claude.ai 経由で接続すること |\n\n## アーキテクチャ\n\n```\n[あなた]\n   ↓ 自然言語\n[Claude.ai / Claude Code]\n   ↓ (1) Skills 発火 (description で判別)\n   ↓ (2) スキル内手順に従い MCP ツールを選択\n[KEYVOX MCP コネクタ (eco.blockchainlock.io)]\n   ↓ OAuth2 認可済みリクエスト\n[KEYVOX API]\n   ↓ 業務データ取得・更新\n[ロック・PIN・予約システム]\n```\n\nスキル本体は **MCP ツールの応用レシピ**。MCP ツール直叩きでも同じことはできますが、業務手順を覚えなくていい・自然言語で済むのが利点です。\n\n## ライセンス\n\n[MIT](./LICENSE) — Copyright © 2026 Blockchain Lock Inc. / KEYVOX Contributors\n\n## Contributing\n\nIssue / PR 歓迎です。特に以下のシナリオでの実利用フィードバックを募集中:\n\n- 本番物理ロックでの `unlock` 動作確認\n- バックトゥバック予約での清掃計画運用\n- マルチ place（複数物件）運営での発火精度\n\nコントリビュート手順の詳細は [CONTRIBUTING.md](./CONTRIBUTING.md) を参照してください。すべての参加者は [行動規範 (Code of Conduct)](./CODE_OF_CONDUCT.md) に従ってください。\n\n## セキュリティ\n\n物理スマートロックを操作する性質上、脆弱性報告は最優先で扱います。**GitHub Issues に公開で投稿せず**、[SECURITY.md](./SECURITY.md) の手順で非公開報告してください。\n\n## 関連リンク\n\n- [KEYVOX サービスサイト](https://keyvox.co)\n- [KEYVOX 開発者ポータル](https://developers.keyvox.co)\n- [KEYVOX サポートポータル](https://support.keyvox.co)\n- [KEYVOX Discord コミュニティ](https://discord.gg/Etd3vZPKhb)\n- [Claude Skills 公式ドキュメント](https://docs.claude.com/en/docs/claude-code/skills)\n- [Model Context Protocol (MCP)](https://modelcontextprotocol.io/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funlock-the-world%2Fkeyvox-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Funlock-the-world%2Fkeyvox-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funlock-the-world%2Fkeyvox-mcp/lists"}