适用于 MCP 的虚拟旅行机器人环境

English / Japanese

这是一个 MCP 服务器，它为头像在 Google 地图上进行虚拟旅行创建环境。

通过 Claude Desktop 等 MCP 客户端，您可以向头像发出指令，并通过照片报告其旅程的进展情况。

<img alt="img_5.png" src="https://raw.githubusercontent.com/mfukushim/map-traveler-mcp/for_image/tools/img_5.png" width="400"/>

现在支持 librechat https://www.librechat.ai/。

<img alt="libre0.png" src="https://raw.githubusercontent.com/mfukushim/map-traveler-mcp/for_image/tools/libre0.png" width="400"/>

功能

MCP 服务器工具功能

以下功能可以用作 MCP 服务器。 可用功能因设置和执行状态而异。

您可以直接指定函数名称，但 Claude LLM 会自动识别它，因此您可以用通用术语指定操作。

示例： “你现在在哪里？” “我们去东京站吧。”

• get_traveler_view_info(includePhoto:boolean,includeNearbyFacilities:boolean)
  获取有关当前旅行头像位置的信息。
  • includePhoto：获取附近的 Google 街景照片。 如果您设置了图像生成 AI，它将合成头像。
  • includeNearbyFacilities：获取有关附近设施的信息。
• get_traveler_location()
  获取有关当前旅行头像的地址和附近设施的信息。
• reach_a_percentage_of_destination() 到达指定百分比的目的地（仅限 moveMode=skip） timeElapsedPercentage：到达目的地的百分比进度（0~100）
• set_traveler_location(address: string)
  设置当前旅行头像的位置。
  • address：地址信息（确切地址，或 Google 地图或 Claude 可以识别的通用名称等）
• get_traveler_destination_address
  获取您设置的旅行头像的目的地
• set_traveler_destination_address(address: string)
  设置旅行头像的目的地
  • address：地址信息（确切地址，或 Google 地图或 Claude 可以识别的通用名称等）
• start_traveler_journey
  在目的地开始旅程。（仅限 moveMode=realtime）
• stop_traveler_journey
  停止旅程。（仅限 moveMode=realtime）
• set_traveler_info(settings:string)
  设置旅行者的属性。 设置您想要动态更改的旅行者的个性，例如姓名和个性。 但是，如果您使用角色脚本，则脚本更稳定。
  • settings：设置信息，例如姓名和个性。
• get_traveler_info
  获取旅行者的属性。 获取旅行者的个性。
• set_avatar_prompt(prompt:string)
  设置生成旅行头像图像时的提示。 默认设置为动漫风格的女性。 强制使用动漫风格是为了防止伪造图像。
  • prompt
• reset_avatar_prompt
  将头像生成提示重置为默认值。
• get_sns_feeds
  获取指定自定义 feed（包含特定标签的 feed）的 Bluesky SNS 文章。
• get_sns_mentions
  获取最近提及（喜欢、回复）您自己发布的 Bluesky SNS 帖子的信息。
• post_sns_writer(message:string)
  使用指定的自定义 feed 将文章发布到 Bluesky SNS。 设置一个特定的标签，以便可以确定该帖子是由旅行机器人生成的。
  • message：文章
• reply_sns_writer(message:string,id:string)
  回复具有指定 id 的文章。 设置一个特定的标签，以便可以确定该帖子是由旅行机器人生成的。
  • message：回复
  • id：要回复的帖子的 ID
• add_like(id:string)
  为指定的帖子添加喜欢。
  • id：要喜欢的帖子的 ID
• tips
  指导您如何设置尚未设置的功能。
• get_setting
  获取环境和图像设置。

MCP 资源

有两个自定义提示示例。 当您使用 Claude Desktop 导入提示时，Claude 将充当旅行者。 与 SNS 兼容的版本在进行旅行对话时控制 SNS 的输入和输出。

• role.txt
  Claude 将充当旅行者。

• roleWithSns.txt
  Claude 将充当旅行者。 它还控制读取和发布到 SNS。

• carBattle.txt
  这是一个关于从横滨到东京运送秘密文件的故事的小说游戏。 场景会自动生成。 设置 moveMode=skip 来玩。

设置

您需要获取并设置多个 API 的访问密钥，例如用于访问多个 Google 地图和生成图像。 使用 API 可能会产生费用。

与 Claude Desktop 一起使用的设置

claude_desktop_config.json

{
  "mcpServers": {
    "traveler": {
      "command": "npx",
      "args": ["-y", "@mfukushim/map-traveler-mcp"],
      "env":{
        "MT_GOOGLE_MAP_KEY":"(Google Map API key)",
        "MT_MAP_API_URL": "(可选：Map API 自定义端点。示例：direction=https://xxxx,places=https://yyyy )",
        "MT_TIME_SCALE": "(可选：真实道路持续时间的旅行时间比例。默认为 4)",
        "MT_SQLITE_PATH":"(db 保存路径：例如 %USERPROFILE%/Desktop/traveler.sqlite ,$HOME/traveler.sqlite )",
        "MT_REMBG_PATH": "(已安装的 rembg cli 的绝对路径)",
        "MT_REMBG_URL": "(rembg API URL)",
        "MT_PIXAI_KEY":"(pixAi API key)",
        "MT_SD_KEY":"(或 Stability.ai 图像生成 API 密钥",
        "MT_PIXAI_MODEL_ID": "(可选：pixAi ModelId，如果未设置，则使用默认模型 1648918127446573124 ",
        "MT_COMFY_URL": "(选项：使用指定 URL 上的 ComfyUI API 生成图像。示例：http://192.168.1.100:8188)",
        "MT_COMFY_WORKFLOW_T2I": "(可选：使用 ComfyUI 进行文本到图像时 API 工作流文件的路径。如果未指定：assets/comfy/t2i_sample.json)",
        "MT_COMFY_WORKFLOW_I2I": "(可选：ComfyUI 中图像到图像时 API 工作流文件的路径。如果未指定：assets/comfy/i2i_sample.json)",
        "MT_COMFY_PARAMS": "(可选：通过 comfyUI API 发送到工作流的变量值)",
        "MT_FIXED_MODEL_PROMPT": "(可选：固定的头像生成提示。您将无法在对话期间更改您的头像。)",
        "MT_BODY_AREA_RATIO": "(可选：可接受的头像图像区域比率。默认为 0.042)",
        "MT_BODY_HW_RATIO": "(可选：可接受的头像图像宽高比。默认为 1.5~2.3)",
        "MT_BODY_WINDOW_RATIO_W": "(可选：头像合成窗口水平比率。默认为 0.5)",
        "MT_BODY_WINDOW_RATIO_H": "(可选：头像合成窗口宽高比。默认为 0.75)",
        "MT_BS_ID":"(Bluesky sns 注册地址)",
        "MT_BS_PASS":"(bluesky sns 密码)",
        "MT_BS_HANDLE":"(bluesky sns 句柄名称：例如 xxxxxxxx.bsky.social )",
        "MT_FILTER_TOOLS": "(可选：直接过滤要使用的工具。如果未指定，则所有工具都可用。例如 tips,set_traveler_location)",
        "MT_MOVE_MODE": "(选项：指定移动模式是 realtime 还是 skip。默认为 realtime)",
        "MT_IMAGE_WIDTH": "(选项：输出图像宽度（像素）默认为 512)"
      }
    }
  }
}

注意：环境变量已重命名为标准蛇形命名法。 添加 MT_ 前缀是因为它们可能与其他环境变量结合使用，例如在 librechat 中。 旧名称仍然可以用于向后兼容。

请为 Google Map API 设置以下三个凭据。

• Street View Static API
• Places API (New)
• Time Zone API
• Directions API

https://developers.google.com/maps/documentation/streetview/get-api-key

如果您想使用图像生成 AI，请设置 pixAi_key 或 sd_key。 您还需要在您的 PC 上安装 python3.7~3.11 并安装 rembg cli（建议使用虚拟环境）。

https://platform.pixai.art/docs https://platform.stability.ai/docs/api-reference#tag/SDXL-1.0-and-SD1.6/operation/textToImage

bluesky SNS 地址/密码是可选的。 建议您创建一个专用帐户，因为它会自动发布。

https://bsky.app/

您也可以在练习模式下运行它，该模式不需要 API 密钥进行验证。

练习模式设置

claude_desktop_config.json

{
  "mcpServers": {
    "traveler": {
      "command": "npx",
      "args": ["-y", "@mfukushim/map-traveler-mcp"]
    }
  }
}

如何使用

使用练习模式

1. 安装 nodejs 22。

2. 设置 Claude Desktop 以供使用。

3. 在 claude_desktop_config.json 中反映上述设置之一。

4. 重新启动 Claude Desktop。 设置可能需要一些时间（如果发生错误，请尝试再次重新启动 Claude Desktop。如果不起作用，请参阅下面的注释）。 确保以下标记出现在屏幕的右下角。

<img alt="img_1.png" src="https://raw.githubusercontent.com/mfukushim/map-traveler-mcp/for_image/tools/img_1.png" width="150"/>

5. 询问“你现在在哪里？” 和“去旅行吧。” 对话将开始。 使用 API 时，将出现一个确认屏幕，因此请选择“允许”。

<img alt="img_4.png" src="https://raw.githubusercontent.com/mfukushim/map-traveler-mcp/for_image/tools/img_4.png" width="200"/>

6. 从 MCP 中选择“附加”，然后选择 role.txt。

<img alt="img_2.png" src="https://raw.githubusercontent.com/mfukushim/map-traveler-mcp/for_image/tools/img_2.png" width="200"/>

<img alt="img_3.png" src="https://raw.githubusercontent.com/mfukushim/map-traveler-mcp/for_image/tools/img_3.png" width="200"/>

7. 已经内置了旅行提示，所以请随意与它交谈。

使用完整功能

1. 获取 Google Map API 访问密钥，并设置 Street View Static API、Places API (New)、Time Zone API 和 Directions API 的权限。 在 claude_desktop_config.json 的 env 中设置此项并重新启动。 此时，旅行日志将基于真实地图。 如果未叠加，也会输出旅行图像。
2. 确定一个不会干扰磁盘的路径，并在 claude_desktop_config.json 的 env 的 sqlite_path 中设置它。 （示例：%USERPROFILE%/Desktop/traveler.sqlite $HOME/Documents/traveler.sqlite 等） 此时，您的旅行日志将被保存，即使您关闭 Claude Desktop，您也可以继续您的旅程。
3. 安装 python 3.7 到 3.11 并使用 cli 安装 rembg。 我们建议使用虚拟环境，例如 venv。

python3 -m venv venv
. venv/bin/activate or .\venv\Scripts\activate
pip install "rembg[cpu,cli]"

使用示例图像文件检查 rembg cli 是否正常工作。 输入一张有人物的图像，如果人物在输出文件中被剪掉，则表示正常。

rembg i source_image_file dest_image_file

4. rembg cli 将安装在 python exe 位置，因此获取该路径。 文件位置因操作系统和 python 安装状态而异，但在 venv 的情况下，它是您设置的目录上方的 (虚拟环境名称)\Scripts\rembg.exe 或 (虚拟环境名称)/bin/rembg。 如果您找不到它，请使用文件搜索软件搜索路径。 将该路径设置为 claude_desktop_config.json 中 env 的 rembg_path。 （示例："rembg_path": "C:\Users\xxxx\Documents\rembg_venv\venv\Scripts\rembg.exe"）
5. 从 pixAI 或 Stability.ai 站点获取图像生成 API 密钥。 将密钥设置为 claude_desktop_config.json 中 env 的 pixAi_key 或 sd_key。 现在，头像将叠加在旅行图像上。
6. 获取 bluesky SNS 地址/密码和句柄名称。 分别在 claude_desktop_config.json 的 env 中的 bs_id、bs_pass 和 bs_handle 中设置这些。 导入旅行知识提示 roleWithSns.txt 以将旅行操作报告给 SNS（它将自动以机器人的身份发布，因此我们建议分配一个专用帐户）

除了使用 cli 准备 rembg 之外，我们还添加了一个设置，允许您将 rembg 作为服务 API 处理。 如果您配置以下 rembg 服务，您可以通过在 remBgUrl 中设置 URL 来使用 rembg。

https://github.com/danielgatis/rembg?tab=readme-ov-file#rembg-s

如果您使用 Docker 版本启动容器并访问它，则设置很简单。

https://github.com/danielgatis/rembg?tab=readme-ov-file#usage-as-a-docker

使用外部 ComfyUI（适用于更高级的用户）

您还可以使用本地 ComfyUI 作为图像生成服务器。 您可以详细配置图像生成特征，以降低 API 成本。

但是，配置将非常复杂，并且图像生成可能需要更长的时间。

1. 配置 ComfyUI 以在 API 模式下运行。
2. 在 env 中将服务器 URL 设置为 comfy_url。
3. 以 json 字符串的形式在 env 中设置详细的配置值，例如要使用的模型。 示例。

{
  "env": {
    "comfy_url": "http://192.168.1.100:8188",
    "comfy_workflow_t2i": "C:\\Documents\\t2itest.json",
    "comfy_workflow_i2i":"C:\\Documents\\i2itest.json",
    "comfy_params":"ckpt_name='animagineXL40_v40.safetensors',denoise=0.65"
  }
}

4. 默认工作流可以使用包中的 assets/comfy/t2i_sample.json 和 assets/comfy/i2i_sample.json。 您可以使用 % 指定变量，并在 comfy_params 中指定变量。

使用 libreChat

它已经过调整，可以与 libreChat 一起使用。 这使得它更容易使用，但需要一些额外的设置。 此外，除非您使用的 PC 具有相当的性能水平，例如可以稳定运行 Docker 的 PC，否则它似乎不稳定。

安装 libreChat

请确保它按照官方网站上的描述工作。 在这种情况下，由于需要额外的设置，我们建议使用 Docker 配置。

https://www.librechat.ai/docs/local/docker

使用官方程序配置 librechat.yaml。 我认为您需要添加本地或 API LLM 服务。

https://www.librechat.ai/docs/configuration/librechat_yaml

添加一个用户以进行登录。

https://www.librechat.ai/docs/configuration/authentication#create-user-script

请将其设置为您可以进行一般的聊天对话。

添加一个带有附加设置的 rembg 容器

要将 rembg 与 Docker 一起使用，请添加拉取和运行 rembg Docker 容器。

docker-compose.override.yml

 services:
   api:
     volumes:
       - type: bind
         source: ./librechat.yaml
         target: /app/librechat.yaml

   rembg:
     image: danielgatis/rembg:latest
     restart: always
     command: "s --host 0.0.0.0 --port 7000 --log_level info"

将 map-traveler-mcp 添加到 MCP 服务

添加 librechat.yaml

mcpServers:
  traveler:
    type: stdio
    command: npx
    args:
      - -y
      - "@mfukushim/map-traveler-mcp"

添加 .env（与 claude_desktop_config.json 中的 env 相同）

# map-traveler-mcp
GoogleMapApi_key=(Google Map API key)
sqlite_path=/home/run_test.sqlite (例如，librechat 在容器内不显眼的位置，或在您不想挂载的外部目录中。)
remBgUrl=http://rembg:7000 (rembg 服务 API URL，容器 URL)
(其他设置，例如图像生成 AI 设置、PixAI 密钥、stability.ai API 密钥、ComfyUI 设置等)

设置后，重新启动容器。 在速度较慢的 PC 上，mcp 初始化可能会失败。 多次重新启动可能会起作用，但这可能难以运行...

llibreChat 设置

要在 libreChat 中使用 MCP 功能，请使用 Agents 功能。

1. 在对话屏幕上，选择“代理”。 <img alt="libre1.png" src="https://raw.githubusercontent.com/mfukushim/map-traveler-mcp/for_image/tools/libre1.png" width="200"/>
2. 从屏幕右侧的面板中选择“代理构建器”并配置您的代理。 <img alt="libre2.png" src="https://raw.githubusercontent.com/mfukushim/map-traveler-mcp/for_image/tools/libre2.png" width="200"/>
3. 选择“添加工具”以使用 map-traveler。 <img alt="libre3.png" src="https://raw.githubusercontent.com/mfukushim/map-traveler-mcp/for_image/tools/libre3.png" width="200"/>
4. 将出现代理工具屏幕，因此选择并添加所有 map-traveler-mcp 工具（如果未列出 map-traveler-mcp 工具，则 MCP 初始化失败，因此请重新启动容器或通过检查日志等来查看设置）。 <img alt="libre4.png" src="https://raw.githubusercontent.com/mfukushim/map-traveler-mcp/for_image/tools/libre4.png" width="200"/> <img alt="libre5.png" src="https://raw.githubusercontent.com/mfukushim/map-traveler-mcp/for_image/tools/libre5.png" width="200"/>
5. 在指令区域中输入其他脚本。 由于 libreChat 没有 MCP 资源功能，因此请将以下 URL 的内容文本输入到指令区域中。 https://github.com/mfukushim/map-traveler-mcp/blob/main/assets/scenario/role.txt <img alt="libre7.png" src="https://raw.githubusercontent.com/mfukushim/map-traveler-mcp/for_image/tools/libre7.png" width="200"/>
6. 单击“创建”按钮以保存代理。 <img alt="libre6.png" src="https://raw.githubusercontent.com/mfukushim/map-traveler-mcp/for_image/tools/libre6.png" width="200"/>
7. 开始新的聊天。

安装指南（日语，但有很多照片）

1. 介绍和练习模式 https://note.com/marble_walkers/n/n7a8f79e4fb30
2. DB、Google Map API、Image gen API https://note.com/marble_walkers/n/n765257c27f3b
3. 头像提示 https://note.com/marble_walkers/n/nc7273724faea
4. SNS 集成 https://note.com/marble_walkers/n/na7c956befe7b
5. 应用 1 https://note.com/marble_walkers/n/n3c86edd8e817
6. ComfyUI API https://note.com/marble_walkers/n/ncefc7c05d102
7. 应用 2 https://note.com/marble_walkers/n/ne7584ed231c8
8. LibreChat 设置 https://note.com/marble_walkers/n/n339bf7905324

关于源代码的补充说明

我使用 Effect.ts 来简化错误管理并用于我自己的学习。 我们还使用 Effect Service，但由于 MCP 调用的工作方式，我们认为使用 Service 合并它不是最佳的。 我认为直接在 Effect 中处理 MCP 调用会更简单。

关于最新更新的说明

已将 image_width 添加到 env。 默认为 512。 将其设置得更小可能会降低 LLM API 的成本。