centerfield-visitor-mcp

Name: centerfield-visitor-mcp
Author: hmkim

本地服务

github.com/hmkim商业与营销05 周前更新

代码仓库

关于 centerfield-visitor-mcp

centerfield-visitor-mcp 用于自动处理首尔 Centerfield 大楼的访客预登记。它面向处理单个访客或批量名单的 Agent，并支持在提交预约前预览和校验数据。

主要功能

01校验租户及审批联系人配置
02预览并校验访客信息
03登记单个或批量访客
04解析粘贴文本及 CSV 或 Excel 文件
05按参与类型筛选问卷名单

适用场景

01根据粘贴的参会名单准备预约
02导入并检查文件中的访客信息
03仅登记符合参与类型的访客
04提交前检查配置并预览名单

MCP 相关

该 MCP 服务提供配置校验、访客预览和预约登记工具。本地客户端通过 stdio 连接，远程客户端可使用 streamable HTTP。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "hmkim-centerfield-visitor": {
      "command": "uvx",
      "args": [
        "centerfield-visitor-mcp"
      ],
      "env": {
        "CF_ENV_FILE": "<CF_ENV_FILE>",
        "CF_COMPANY_NAME": "<CF_COMPANY_NAME>",
        "CF_PERSON_IN_CHARGE_MOBILE": "<CF_PERSON_IN_CHARGE_MOBILE>",
        "CF_DEFAULT_FLOOR": "<CF_DEFAULT_FLOOR>"
      }
    }
  }
}

启动命令uvx centerfield-visitor-mcp

需要配置的环境变量

CF_ENV_FILEAbsolute path to a .env holding CF_COMPANY_NAME and CF_PERSON_IN_CHARGE_MOBILE (optional if ~/.config/centerfield-visitor-mcp/.env exists)

CF_COMPANY_NAMETenant company name exactly as registered in Centerfield

CF_PERSON_IN_CHARGE_MOBILE密钥Mobile number of the approval contact registered in Centerfield

CF_DEFAULT_FLOORFloor used when a row omits it (12 or 18)

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

pypicenterfield-visitor-mcp0.2.1stdio

工具

收录的工具列表 · 更新于 3 周前

此工具无需参数。

详细介绍

Centerfield Visitor MCP

一个 MCP（模型上下文协议）服务，用于自动办理 Centerfield 大楼（www.centerfield.co.kr）的访客预约。可通过任何兼容 MCP 的 Agent 使用——Kiro CLI / Kiro IDE / KiroCrew、Claude Code、Claude Desktop、 Codex CLI、Cursor、Strands Agents（本地 stdio），以及Amazon Quick 或任何远程客户端（可流式传输的 HTTP）—— 通过自然语言登记访客：单条记录、粘贴的文本、问卷导出内容或 Excel/CSV 文件。

用于自动办理 Centerfield 大楼访客预约的 MCP 服务。本地 Agent（Kiro、Claude Code、Codex、Cursor …）通过 stdio 连接，Amazon Quick 等远程 Agent 则通过可流式传输的 HTTP 使用同一服务。

stdio 服务完全在本地运行——uvx 会在你的计算机上下载并运行它，且它会直接与 www.centerfield.co.kr 通信。本地 Agent 无需后端服务。

快速开始

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	Agent 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	远程可流式传输的 HTTP + OAuth 2LO	`clients/remote/README.md`

Agent 技能（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)`	创建预约	依次处理，并返回一条汇总字符串
`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`	有效的电子邮件地址
重复项	同一请求中手机号、日期和时间相同的行会被跳过并报告

文件 / 文本格式

标题行可以使用韩语或英语；也可识别问卷导出文件的标题（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

最后一条命令会创建一条真实预约；请在 Centerfield 移动应用中确认并取消（没有取消 API）。

工作原理

服务会与 Centerfield 网站保持单个会话，管理 CSRF 令牌，验证租户公司和审批联系人，解析楼层密钥，然后提交预约表单。批量请求会按顺序处理，并采用可配置的延迟。

MCP Registry

已列为 io.github.hmkim/centerfield-visitor-mcp（参见 server.json）。

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

许可证

MIT

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。