matrixbookingmcp

矩阵预订MCP服务器

  ](https://github.com/chrisns/matrixbookingmcp)  ](https://nodejs.org/) 

用于矩阵预订API集成的TypeScript MCP（模型上下文协议）服务器，使人工智能助手能够自动检查房间可用性，并通过自然语言交互创建预订。

🚀 特性

核心预订功能

• 房间和桌子可用性：检查房间、桌子和桌库的可用性
• 智能预订创建：使用与会者管理和通知创建预订
• 预订搜索和发现：按用户、日期、地点或类型搜索预订
• 同事日历发现：查找同事何时在办公室（隐私意识）
• 预定管理：使用通知选项取消和管理现有预订
• 用户预订：查看和跟踪您自己的预订和定期日程

高级搜索和定位

• 自然语言搜索：使用会话查询查找位置
• 基于设施的发现：按要求搜索（屏幕、白板、容量）
• 位置层次结构：浏览建筑物、楼层、区域和桌面库
• 智能定位分辨率：智能房间/桌子名称和编号匹配
• 跨组织支持：无缝处理多个组织环境

技术卓越

• 全面验证：输入净化和XSS预防
• 智能缓存：使用可配置的TTL进行性能优化
• 组织环境解决方案：具有回退功能的智能组织ID映射
• 安全第一：基于环境的凭证管理
• 错误恢复：优雅的降级和替代建议
• 综合测试：单元、集成和性能测试覆盖率

📋 需求

• Node.js: ≥22.0.0
• 程序包管理器：npm（支持）
• 矩阵预订账户：需要有效的凭据

📦 安装

1.克隆存储库

git clone https://github.com/chrisns/matrixbookingmcp.git
cd matrixbookingmcp

2.安装依赖项

使用pnpm（推荐）：

pnpm install

使用npm：

npm install

3.环境配置

创建一个 .env 项目根目录中的文件：

cp .env.example .env

配置所需的环境变量：

# Matrix Booking Credentials
MATRIX_USERNAME=your-matrix-username
MATRIX_PASSWORD=your-matrix-password

# Default Location (optional but recommended)
MATRIX_PREFERED_LOCATION=your-preferred-location-id

4.建设项目

pnpm build

⚙️ 配置

环境变量

所需配置

高级配置

安全说明：永远不要将凭据提交到版本控制。这 .env 文件通过以下方式自动排除 .gitignore.

矩阵API配置

服务器自动配置：

• 基本URL: https://app.matrixbooking.com/api/v1
• 认证：采用Base64编码的HTTP基本身份验证
• 超时：所有API调用为5秒
• 时区：欧洲/伦敦（可通过配置 x-time-zone 头球
• 标头：自动包含所需的特定于Matrix的标头

🔌 MCP集成

Claude桌面设置

1. 更新Claude桌面配置

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "matrix-booking": {
      "command": "npx",
      "args": ["--yes", "github:chrisns/matrixbookingmcp"],
      "env": {
        "MATRIX_USERNAME": "your-username",
        "MATRIX_PASSWORD": "your-password",
        "MATRIX_PREFERED_LOCATION": "your-location-id"
      }
    }
  }
}

备注：这将直接从GitHub存储库运行服务器，而无需在本地克隆或构建。

1. 重新启动克劳德桌面

矩阵预订工具现在将在您的Claude桌面会话中可用。

其他MCP客户端

要与其他MCP客户端集成，请使用：

• 运输：stdio
• 命令: node dist/index.js
• 环境：设置所需的环境变量

🛠️ 用法

发展模式

pnpm dev

生产模式

pnpm start

可用操作

1.检查房间可用性

// Check availability for today at preferred location
checkAvailability()

// Check availability for specific date and location  
checkAvailability({
  date: "2024-01-15",
  locationId: "12345",
  startTime: "09:00",
  endTime: "17:00"
})

2.预约

// Book a room with basic details
bookAppointment({
  title: "Team Meeting",
  date: "2024-01-15", 
  startTime: "14:00",
  endTime: "15:00",
  roomId: "67890"
})

// Book with attendees and notifications
bookAppointment({
  title: "Project Review",
  date: "2024-01-15",
  startTime: "10:00", 
  endTime: "11:00",
  roomId: "67890",
  attendees: ["john@company.com", "jane@company.com"],
  sendNotifications: true
})

智能默认值

服务器包括智能默认值：

• 日期：未指定时默认为今天
• 位置：用途 MATRIX_PREFERED_LOCATION 从环境
• 时间范围：全天（00:00-23:59）进行可用性检查
• 时区：自动处理为欧洲/伦敦

🏗️ 架构概述

graph TB
    A[AI Assistant/Client] --> B[MCP Server]
    B --> C[Matrix Booking API]
    
    B --> D[Configuration Manager]
    B --> E[Authentication Manager] 
    B --> F[Service Layer]
    B --> G[Input Validation]
    B --> H[Organization Context Resolver]
    
    F --> F1[Availability Service]
    F --> F2[Booking Service]
    F --> F3[Location Service]
    F --> F4[Organization Service]
    F --> F5[Search Service]
    
    H --> H1[Organization Validation]
    H --> H2[Context Resolution]
    H --> H3[Fallback Logic]
    H --> H4[Validation Cache]
    
    D --> I[Environment Variables]
    E --> J[Base64 Credentials]
    
    style A fill:#e1f5fe
    style B fill:#f3e5f5
    style C fill:#fff3e0
    style F fill:#e8f5e8
    style H fill:#ffe0e6

核心组件

• MCP服务器：使用TypeScript实现 @modelcontextprotocol/sdk
• 认证管理器：采用Base64编码的安全凭证处理
• 服务层：可用性、预订和位置操作的业务逻辑
• 组织上下文解析器：使用回退逻辑和缓存处理组织ID映射
• 配置管理器：基于环境的配置和验证
• 输入验证：全面的消毒和验证系统
• 错误处理：通过错误策略保留矩阵API响应

🧪 测试

运行所有测试

pnpm test

测试覆盖率

pnpm test:coverage

测试类别

• 单元测试：组件和服务测试
• 集成测试：端到端MCP协议测试
• 安全测试：凭证处理和验证
• 性能测试：使用K6进行负载测试

性能测试

# Quick performance test
pnpm test:k6:quick

# Full load test
pnpm test:k6

# Timeout testing
pnpm test:k6:timeout

🔍 故障排除

常见问题

1.身份验证错误

症状: 401 Unauthorized 错误

解决方案:

• 验证 MATRIX_USERNAME 和 MATRIX_PASSWORD 在……里面 .env
• 确保凭证对Matrix Booking有效
• 检查环境变量中的尾随空格

2.未找到位置

症状: Location not found 错误

解决方案:

• 验证 MATRIX_PREFERED_LOCATION 是有效的位置ID
• 使用位置服务获取可用位置
• 确保位置ID是数字（不是位置名称）

3.超时问题

症状: Request timeout 错误

解决方案:

• 检查网络连接 app.matrixbooking.com
• 验证矩阵API是否可以从您的网络访问
• 考虑防火墙或代理配置

4.日期/时间验证错误

症状：日期格式错误无效

解决方案:

• 使用ISO日期格式： YYYY-MM-DD
• 使用24小时时间格式： HH:MM
• 确保日期不是过去的

5.组织ID映射问题

症状: NaN 组织ID错误或“无效的组织上下文”错误

解决方案:

• 验证您的用户帐户在Matrix Booking中具有适当的组织访问权限
• 检查一下 MATRIX_PREFERED_LOCATION 属于您的组织
• 集 MATRIX_ORGANIZATION_RESOLUTION_STRATEGY=user_preferred 更喜欢用户的组织
• 通过以下方式启用跨组织访问 MATRIX_ENABLE_CROSS_ORG_ACCESS=true 如果你需要多个组织的支持

6.空位置层次结构

症状: get_locations 返回空数组或预订搜索失败

解决方案:

• 确保您的组织在Matrix Booking中配置了位置
• 验证API身份验证是否正常工作
• 检查您的用户是否有查看位置的权限
• 尝试设置不同的组织解决方案策略

7.日期范围验证错误

症状：“日期范围无效：结束时间必须在开始时间之后”表示相同的时间

解决方案:

• 系统现在允许时间点查询的开始/结束时间相同
• 用途 MATRIX_DEFAULT_DURATION_MINUTES （默认值：15）延长相同的时间
• 对于明确的范围，确保结束时间在开始时间之后

8.MCP连接问题

症状：Claude Desktop中没有可用的工具

解决方案:

• 验证 claude_desktop_config.json 语法
• 检查构建服务器的文件路径(dist/index.js)
• 确保项目建成(pnpm build)
• 配置更改后重新启动Claude Desktop

调试模式

通过设置启用详细日志记录：

export NODE_ENV=development

支持

如需额外支持：

1. 检查 故障排除指南
2. 查看中的测试示例 tests/ 目录
3. 在GitHub上打开一个包含详细错误信息的问题

📚 api参考

可用的MCP工具

该服务器为Matrix Booking操作提供了11个全面的工具：

预订操作

1. check_availability -检查房间/桌子的可用性
2. book_appointment -与与会者创建新的预订
3. cancel_booking -取消现有预订
4. get_user_bookings -查看您的预订和日程安排
5. search_bookings -搜索所有预订（包括同事）

位置发现

1. get_locations -浏览位置层次结构
2. find_location_by_name -按名称/编号查找位置
3. find_location_by_requirements -按设施和容量搜索
4. find_location_by_id -获取具体位置详细信息

系统信息

1. get_booking_types -列出可用的预订类别
2. get_organization_info -查看组织详细信息

有关详细参数和示例，请参阅 API使用指南

🤝 贡献

我们欢迎捐款！请遵循以下指南：

开发工作流程

1. 分叉和克隆

   git fork https://github.com/chrisns/matrixbookingmcp.git
   git clone https://github.com/your-username/matrixbookingmcp.git

1. 设置开发环境

   cd matrixbookingmcp
   pnpm install
   cp .env.example .env
   # Configure your .env file

1. 创建特征分支

   git checkout -b feature/your-feature-name

1. 发展

   pnpm dev  # Start development server
   pnpm test # Run tests in watch mode

1. 质量检查

   pnpm lint        # Check code style
   pnpm typecheck   # Verify TypeScript
   pnpm test        # Run all tests

1. 提交拉取请求

- 确保所有测试通过 - 包括新功能的测试覆盖率 - 遵循常规提交消息 - 必要时更新文档

编码标准

• TypeScript：严格模式已启用
• ESLint：遵循配置的规则
• 测试：将测试覆盖率保持在50%以上
• 承诺：使用常规提交格式
• 文档：更新API更改

拉取请求要求

• \[\]测试通过(pnpm test)
• \[\]林亭传球(pnpm lint)
• \[\]类型检查通行证(pnpm typecheck)
• \[\]保持测试覆盖率（50%+）
• \[\]文件已更新
• \[\]已解决安全问题

测试要求

• 所有新功能的单元测试
• API端点的集成测试
• 凭证处理的安全测试
• 关键路径的性能测试

📄 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

👥 维护者

• 专案管理：矩阵预订MCP服务器团队
• 电子邮件: maintainers@example.com
• GitHub: @chrisns/matrixbookingmcp

📈 项目状态

• ✅ 核心功能：完成
• ✅ API集成：稳定
• ✅ 测试覆盖率: 54%
• ✅ 文档：完成
• ✅ 安全：已审核
• 🔄 演出：持续监控

🙏 致谢

• 模型上下文协议 对于MCP规范
• 矩阵预订 用于API平台
• TypeScript和Node.js社区，提供出色的工具

______________________________________________________________________

*有关更多详细信息，请参阅 技术文档 和 规范文件.*