centerfield-visitor-mcp

Centerfield Visitor MCP

Centerfield ビルの来訪者予約（www.centerfield.co.kr）を自動化するMCP（Model Context Protocol）サーバーです。 MCP に対応したあらゆるエージェント（Kiro CLI / Kiro IDE / KiroCrew、Claude Code、Claude Desktop、 Codex CLI、Cursor、Strands Agents（ローカル stdio）、およびAmazon Quick やその他のリモートクライアント（streamable HTTP））から利用でき、 自然言語で来訪者を登録できます。個別の登録、貼り付けたテキスト、アンケートのエクスポートデータ、Excel/CSV ファイルに対応しています。

센터필드 빌딩 방문예약을 자동화하는 MCP 서버입니다. 로컬 에이전트(Kiro, Claude Code, Codex, Cursor …)는 stdio로, Amazon Quick 같은 원격 에이전트는 streamable HTTP로 같은 서버를 씁니다.

stdio サーバーは完全にローカルで実行されます。uvxがマシン上でサーバーをダウンロードして実行し、www.centerfield.co.krと直接通信します。ローカルエージェントではバックエンドサービスは不要です。

クイックスタート

mkdir -p ~/.config/centerfield-visitor-mcp
cp .env.example ~/.config/centerfield-visitor-mcp/.env   # fill CF_COMPANY_NAME, CF_PERSON_IN_CHARGE_MOBILE
uvx centerfield-visitor-mcp                               # stdio; every client below can launch this

~/.config/centerfield-visitor-mcp/.envは自動的に読み込まれるため、クライアントの設定にシークレットを含める必要はありません。

クライアントのセットアップ

クライアント	方法	詳細
Kiro CLI	~/.kiro/settings/mcp.json	clients/kiro/mcp.json
Kiro IDE	.kiro/settings/mcp.json（ワークスペース）	同じファイル
KiroCrew	エージェント JSON の mcpServers + tools	clients/kirocrew/agent-snippet.json
Claude Code	claude mcp add centerfield-visitor --scope user -- uvx centerfield-visitor-mcp	clients/claude-code/
Claude Desktop	claude_desktop_config.json	clients/claude-desktop/
Codex CLI	~/.codex/config.toml [mcp_servers.centerfield-visitor]	clients/codex/config.toml
Cursor	.cursor/mcp.json	clients/cursor/mcp.json
Strands Agents	MCPClient(stdio_client(...))	clients/strands/example.py
Amazon Quick	リモート streamable HTTP + OAuth 2LO	clients/remote/README.md

エージェントスキル（Agent Skills 仕様。Claude Code / Kiro / KiroCrew で動作）：SKILL.md — プロジェクトのスキル .claude/skills/centerfield-visitor/SKILL.md としても同梱されています。

ツール

ツール	副作用	備考
validate_configuration()	なし	会社、承認連絡先、フロア一覧を稼働中のサイトと照合します
preview_visitors_from_text(text, default_visit_date, default_visit_time, default_floor, default_purpose, participation)	なし	貼り付けた CSV/TSV を解析・検証します
register_visitor(..., dry_run)	予約を作成します	dry_run=trueでは、送信せずに（入力とサイトを）検証します
register_visitors_from_text(text, defaults…, participation, dry_run)	予約を作成します	順次処理し、概要を 1 つの文字列で返します
preview_visitors_from_file(file_path, defaults…, participation)	なし	stdio のデプロイのみ（共有ファイルシステムが必要です）
register_visitors_from_file(file_path, defaults…, participation, dry_run)	予約を作成します	stdio のデプロイのみ

推奨フロー：validate_configurationを一度実行 → preview_* → 人が確認 → register_*。 default_*引数は、通常、参加者一覧にない列（訪問日／時刻／フロア）を補完します。 participationを指定すると、出席区分の列に指定したテキストを含む行だけが対象になります（以下を参照）。

入力制約

フィールド	ルール
visit_time	HH:MM、30 分間隔、08:00～20:00（スプレッドシートの HH:MM:SS も許容）
visit_date	YYYY-MM-DD、今日以降
floor	12 または 18。省略した場合は CF_DEFAULT_FLOOR（デフォルトは 12）
visit_purpose	meeting（デフォルト）、visit_business、interview、tour、construction、others
visitor_mobile	韓国の携帯電話番号。010-1234-5678、010 1234 5678、+82 10-1234-5678 は 01012345678 に正規化されます。空欄または携帯電話番号以外は拒否されます
visitor_email	有効なメールアドレス
重複	1 回のリクエスト内で携帯電話番号、日付、時刻が同じ行はスキップされ、報告されます

ファイル／テキスト形式

韓国語または英語のヘッダー行に対応します。アンケートのエクスポート用ヘッダーも認識されます （Full Name、Email、연락처(…)、소속/회사 (…)）。認識されない列は無視されます。

이름,회사,전화번호,이메일,방문일,방문시간,층
홍길동,ABC주식회사,01012345678,[email protected],2026-11-15,10:00,12

日付列／時刻列がないリストの場合は、default_visit_date="2026-11-15"、default_visit_time="10:00" を指定します。

参加形態（アンケートのエクスポート）：참석 형태／어떤 형태로 참석하시나요?／Participation などの列が検出され、プレビューに集計結果が表示されます（참석 형태 컬럼 감지: 온라인 7, 오프라인 3）。participation="오프라인" を指定すると、値にそのテキストを含む行のみを処理します（大文字・小文字と空白を区別しません。値が空の行は除外され、件数が記録されます）。フィルターを指定した入力に該当列がない場合、register_* は全員を登録するのではなく処理を拒否し、preview_* は警告とともにフィルターなしの行を表示します。

設定

変数	説明	デフォルト	必須
CF_COMPANY_NAME	Centerfield に登録されているテナント企業名	(empty)	✅
CF_PERSON_IN_CHARGE_MOBILE	Centerfield に登録されている承認担当者の携帯電話番号	(empty)	✅
CF_BUILDING / CF_BUILDING_KEY	ビルコード／表示キー	east / East
CF_DEFAULT_FLOOR	行で省略された場合の階数（12 または 18）	12
CF_TRANSPORT	stdio または streamable-http	stdio
CF_HTTP_HOST / CF_HTTP_PORT / CF_HTTP_PATH	HTTP のバインドアドレスとパス	127.0.0.1 / 8000 / /mcp
CF_HTTP_STATELESS / CF_HTTP_JSON_RESPONSE	Streamable HTTP モード	true / true
CF_HTTP_ALLOWED_HOSTS	DNS リバインディング対策のホスト許可リスト（host:* は任意のポート）。空欄の場合、ループバックにバインドすると組み込みの localhost リストが使用されます。それ以外のバインドでは保護が無効になり、警告がログに記録されます	(empty)
CF_EXPOSE_FILE_TOOLS	ファイルツールを強制的に有効／無効にする	stdio では有効、HTTP では無効
CF_CENTERFIELD_BASE_URL	Centerfield のベース URL	https://www.centerfield.co.kr
CF_REQUEST_TIMEOUT	HTTP タイムアウト（秒）	30
CF_BULK_MAX_VISITORS	一括リクエストあたりの最大来訪者数（Amazon Quick の 60 秒制限には 10 を使用）	200
CF_REQUEST_DELAY	送信間の遅延（秒）	0.5
CF_ENV_FILE	読み込む追加の .env ファイル	(unset)

.env の読み込み順（後の設定が前の設定を上書きします）：~/.config/centerfield-visitor-mcp/.env → ./.env → $CF_ENV_FILE。プロセスの環境変数は常に優先されます。起動ログ（stderr）には読み込んだファイルと問題が記録されます。

CF_PERSON_IN_CHARGE_MOBILE には、テナントの承認担当者として登録されている携帯電話番号を指定する必要があります。 セットアップ後に validate_configuration を実行してください。予約を作成せずに、両方の値が有効かをオンラインで確認します。

リモートモード（Amazon Quick、ホスト型デプロイ）

CF_TRANSPORT=streamable-http CF_HTTP_HOST=0.0.0.0 uvx centerfield-visitor-mcp    # http://host:8000/mcp
docker build --platform linux/arm64 -t centerfield-visitor-mcp .                 # or the container image

AgentCore Runtime + Cognito の設定手順と Amazon Quick コネクターの手順については、clients/remote/README.md を参照してください。mcp SDK 1.x および 2.x で動作します。

開発とテスト

uv sync --group dev
uv run pytest                          # offline unit tests (mocked HTTP)
uv run --with "mcp<2" pytest           # same suite on mcp SDK 1.x
uv run python scripts/smoke_http.py    # streamable-http transport smoke test
uv run pytest -m live                  # read-only checks against the live site (needs a real .env)
CF_LIVE_REGISTER=1 CF_TEST_VISITOR_NAME=... CF_TEST_VISITOR_MOBILE=... CF_TEST_VISITOR_EMAIL=... uv run pytest -m live

最後のコマンドは実際の予約を 1 件作成します。Centerfield のモバイルアプリで予約を確認し、そこでキャンセルしてください（キャンセル API はありません）。

仕組み

サーバーは Centerfield サイトとの単一セッションを保持し、CSRF トークンを管理して、テナント企業と承認連絡先を検証し、フロアキーを解決してから、予約フォームを送信します。一括リクエストは、設定可能な遅延を挟んで順次処理されます。

MCP Registry

io.github.hmkim/centerfield-visitor-mcp として登録されています（server.json を参照）。

mcp-name: io.github.hmkim/centerfield-visitor-mcp

ライセンス

MIT