AI导哈

狩猎平台MCP服务器

Book The Wild狩猎平台的MCP服务器，提供搜索狩猎套餐、查看详情、预订套餐和用户认证管理功能。

  • by meho99
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 meho99/btw-mcp

使用说明

预订The Wild-MCP服务器

一个用于与Book The Wild狩猎平台交互的综合模型上下文协议（MCP）服务器。此服务器提供用于搜索狩猎、查看详细信息、预订套餐以及使用基于会话的登录管理用户身份验证的工具。

🚀 快速开始

  1. 安装依赖项:

    npm install

  2. 跑

    npm run dev

🔧 配置

创建 .env 文件：

PORT=3005

🎯 可用工具

服务器提供五个MCP工具：

1. find-hunts -搜索狩猎套餐

  • 描述：在Book The Wild上搜索狩猎套餐。您可以按日期范围进行筛选。要预订一些狩猎，首先使用“获取狩猎细节”工具找到可用的套餐。
  • 参数:
    • dateFrom （可选）-开始日期筛选器（字符串）
    • dateTo （可选）-结束日期筛选器（字符串）

2. get-hun-details -获取狩猎详情

  • 描述：检索特定狩猎的详细信息。它包括可供预订的套餐列表。
  • 参数:
    • huntId （必填）-用于检索详细信息的狩猎ID（字符串）

3. book-package -预订狩猎套餐

  • 描述：在Book The Wild上预订选定的狩猎套餐（需要身份验证）
  • 参数:
    • bookingDate （必填）-预订日期（字符串）
    • huntId （必填）-狩猎ID（字符串）
    • packageId （必填）-要预订的包裹的ID（字符串）
    • numberOfGuests （必填）-预订的客人数量（个）

4. get-user -获取用户信息

  • 描述：检索当前登录用户的信息
  • 参数：无

5. log-out -注销用户

  • 描述：注销当前登录的用户
  • 参数：无

🔐 认证

服务器对需要用户授权的工具使用基于会话的身份验证(book-package, get-user, log-out).

登录进程

  1. 当在没有身份验证的情况下访问受保护的工具时，服务器将提供登录URL
  2. 导航至 http://localhost:3005/login?sessionId=<SESSION_ID>
  3. 输入您的Book The Wild凭据（电子邮件和密码）
  4. 登录后，您可以在该会话中使用所有受保护的工具

会话管理

  • 每个MCP客户端连接都会获得一个唯一的会话ID
  • 每个会话都会维护登录状态
  • 用户可以通过以下方式检查其登录状态 get-user 工具
  • 用户可以使用注销 log-out 工具

备注：登录表单使用模拟令牌进行开发。在生产环境中，这应该被适当的OAuth 2.1流程所取代。

📁 项目结构

src/
├── server.ts          # Express server with MCP endpoints
├── session.ts         # Session management and transport handling
├── parsers.ts         # Query parsing utilities
├── types.ts           # TypeScript type definitions
└── tools/             # MCP tool implementations
    ├── index.ts       # Tool registration
    ├── find-hunts.ts  # Hunt search functionality
    ├── get-hunt-details.ts  # Hunt details retrieval
    ├── book-package.ts      # Package booking (auth required)
    ├── get-user.ts          # User info (auth required)
    └── log-out.ts           # User logout (auth required)

🌐 HTTP端点

/mcp （发布、获取、删除）

  • 发布：用于工具调用的主MCP通信端点
  • 获取：通过服务器发送事件（SSE）发送服务器到客户端的通知
  • 删除：会话终止
  • 标头:
    • mcp-session-id：用于维护状态的会话标识符
    • Content-Type: application/json

/login （获取、发布）

  • 获取：提供登录表单UI
    • 查询参数： sessionId -要进行身份验证的会话ID
  • 发布：处理登录凭据
    • 表单数据： email, password, sessionId
    • 返回成功确认和模拟身份验证令牌

🧪 测试

  1. 启动服务器:

    npm run dev

  2. 服务器将在: http://localhost:3005/mcp

  3. 测试身份验证流程:

    • 使用MCP客户端调用 get-user 工具
    • 按照提供的登录URL进行身份验证
    • 身份验证后重试工具调用

  4. 可用的npm脚本:

    • npm run dev -使用tsx开发
    • npm run dev:watch -自动重启开发
    • npm run build -将TypeScript构建为JavaScript
    • npm run build:clean -清理构建目录并重建
    • npm run start -运行内置JavaScript
    • npm run start:prod -生产开始
    • npm run type-check -检查TypeScript类型（仅限生产环境）
    • npm run type-check:all -检查TypeScript类型（包括测试）
    • npm run lint -运行ESLint
    • npm run lint:fix -自动修复ESLint问题
    • npm run format -使用Prettier格式化代码
    • npm run format:check -检查代码格式
    • npm run test -在监视模式下运行测试
    • npm run test:run -运行一次测试
    • npm run test:coverage -使用覆盖率报告运行测试

🎉 特性

  • ✅ 使用流式HTTP传输实现完整的MCP协议
  • ✅ 使用web登录表单进行基于会话的身份验证
  • ✅ 狩猎包管理的五个综合工具
  • ✅ TypeScript支持，具有正确的类型定义和单独的测试配置
  • ✅ 具有适当错误处理功能的Express.js服务器
  • ✅ ESLint+代码质量和格式的预处理
  • ✅ Vitest用于测试TypeScript支持
  • ✅ 开发和生产构建脚本

对于生产部署，考虑实施适当的OAuth 2.1流程和安全会话管理。

相关 MCP