travel-platform-mcp

travel-platform-mcp 是面向旅游业务的 MCP Server。它以单个 PyPI 包分发，提供平台初始化、模型配置、Skill 同步，以及稳定的旅游站点自动化能力。

本 README 只说明安装、接入和首次使用。架构、开发、贡献与运维资料请从 文档索引 查阅。

给 Agent 的可复制初始化 Skill

将以下完整内容复制给需要安装或更新本项目的 Agent。它会先把初始化 Skill 安装到 Agent 自己的 Skill 目录，再安装 MCP 包、配置 MCP Host、初始化工作区并同步其余内置 Skill。

---
name: travel-platform-initialization
description: 安装、升级和初始化 PyPI 包 travel-platform-mcp，并同步全部内置 Skill；首次收到本 Skill、连接 MCP、升级 MCP 包或更新内置 Skill 时使用。
---

# travel-platform-mcp 自举安装、初始化与 Skill 同步

本 Skill 是 `travel-platform-mcp` 随包分发的初始化入口。必须先将本 Skill 安装到当前 Agent 自己的 Skill 目录，确认安装成功后，才开始 MCP 包安装、MCP Host 接入和其他平台操作。

## 一、自举安装本 Skill

这是所有后续步骤的前置条件，不依赖 `platform.skills.sync`，也不依赖已连接的 MCP Host。

1. 识别当前 Agent 实际提供的 Skill 根目录，必须是绝对路径；不得猜测其他 Agent 的目录，也不得使用本项目源码目录。
2. 从已安装包内的 `travel_platform_mcp.resources.platform.skills/travel-platform-initialization` 资源目录，使用当前 Agent 的原生 Skill 安装或复制能力，将整个 `travel-platform-initialization` 目录安装到该根目录。
3. 验证 `<当前 Agent Skill 根目录>/travel-platform-initialization/SKILL.md` 存在且可读。

仅在以上验证成功后，继续下列 MCP 完整安装流程。若 Agent 无法确认自己的 Skill 根目录或无法执行原生安装，应停止并向用户说明原因；不得以 `platform.skills.sync`、项目源码目录或相对路径替代自举安装。

## 二、新用户首次安装 MCP

### 1. 确保 uv 可用

```bash
uv --version
```

若尚未安装 uv，使用当前系统适用的官方安装方式；安装后重新打开终端并再次执行 `uv --version`。

### 2. 安装 PyPI 包

```bash
uv tool install travel-platform-mcp
```

### 3. 配置 MCP Host

将 MCP Host 的唯一 Server 启动命令配置为：

```text
travel-platform-mcp
```

重新加载 MCP Host，并确认可发现 `platform.setup`、`platform.health`、`platform.configure` 和 `platform.skills.sync`。不要从 Git 仓库复制源码，也不要为该包启动第二个 MCP Server。

### 4. 初始化工作区

```text
platform.setup({})
```

`platform.setup` 只补齐缺失的工作区文件和目录，不覆盖已有 `.env`、平台配置、浏览器 Profile 或历史 Artifact。

### 5. 询问并配置模型 API Key

工作区初始化成功后，询问用户是否提供模型 API Key。说明 API Key 仅写入本地工作区 `.env`，不会在回复、日志、Artifact 或 Tool 返回中回显。

用户提供非空 API Key 时，调用：

```text
platform.configure({"api_key": "<用户当前明确提供的密钥>"})
```

确认返回 `api_key_configured: true` 后，立即执行真实模型验证：

```text
platform.health({"verify_model": true})
```

只报告脱敏后的验证状态、延迟和错误类别。若 `platform.configure` 写入失败或验证失败，不回显密钥；请用户提供修正后的密钥，或允许其跳过模型配置。

用户选择不提供 API Key 时，继续基础安装与 Skill 同步，并执行：

```text
platform.health({"verify_model": false})
```

明确告知模型能力尚未配置。不得猜测、复用历史消息、日志或本地文件中的密钥。

### 6. 全量同步包内 Skill

仅在 MCP 已可用、且用户已授权安装或更新 Skill 后，调用：

```text
platform.skills.sync({
  "target_skills_directory": "<当前 Agent 实际 Skill 根目录的绝对路径>",
  "overwrite": true
})
```

`target_skills_directory` 必须由当前 Agent 的运行环境确定，且必须是绝对路径；不得传入包内 Skill 资源目录、其子目录或项目源码目录。`platform.skills.sync` 不提供默认路径。

`overwrite: true` 会以包内版本完整替换目标目录中同名 Skill。调用前说明该覆盖影响；调用后仅当返回 `status: "ready"` 时视为完成，并检查 `copied`、`updated`、`skipped` 与 `warnings`。

## 三、已有用户更新

1. 先按“自举安装本 Skill”更新当前 Agent 中的初始化 Skill。
2. 升级包：

```bash
uv tool upgrade travel-platform-mcp
```

3. 重新加载 MCP Host。
4. 在用户授权覆盖后，按上节调用 `platform.skills.sync`，始终使用 `overwrite: true`。
5. 运行以下检查：

```text
platform.health({"verify_model": false})
```

确认 `healthy` 为 `true`。

## 四、安全与失败处理

- 默认只运行 `platform.health({"verify_model": false})`；仅当用户明确提供模型 API Key 并要求真实验证时，才传入 `verify_model: true`。
- 不在回复、日志、Artifact、Tool 参数或同步结果中输出 API Key、登录凭证或其他 Secret。
- 自举安装、包安装或同步失败时，保留当前可用版本和已有 Skill；不要删除目标目录或擅自修改其他 Agent 配置。

手动安装摘要

若你不通过 Agent 安装，可先确保 uv 已可用，再执行：

uv tool install travel-platform-mcp

在 MCP Host 中只配置一个 Server，启动命令为：

travel-platform-mcp

重新加载 Host 后，按上面的初始化 Skill 执行 platform.setup、API Key 配置与 Skill 同步。

文档

• 完整文档索引：架构、Tool 契约、配置、安全、发布和开发资料。
• 分发与 Agent 集成：安装、升级与 Host 集成的设计说明。
• MCP Tool 与 Provider：可用 Tool 的职责与边界。

许可证

Apache License 2.0