使用说明

矩阵预订MCP服务器

用于矩阵预订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

⚙️ 配置

环境变量

所需配置

变量	必填	描述	示例
`MATRIX_USERNAME`	✅	Matrix预订用户名	`john.doe@company.com`
`MATRIX_PASSWORD`	✅	矩阵预订密码	`your-secure-password`
`MATRIX_PREFERED_LOCATION`	⚠️	预订的默认位置ID	`12345`

高级配置

变量	必填	默认	描述	示例
`MATRIX_API_TIMEOUT`	❌	`5000`	API请求超时（以毫秒为单位）	`10000`
`CACHE_ENABLED`	❌	`true`	启用/禁用缓存以提高性能	`false`
`MATRIX_DEFAULT_DURATION_MINUTES`	❌	`15`	时间点查询的默认预订持续时间	`30`
`MATRIX_ORGANIZATION_RESOLUTION_STRATEGY`	❌	`user_preferred`	如何解决组织冲突	`location_preferred`, `strict`
`MATRIX_ENABLE_CROSS_ORG_ACCESS`	❌	`true`	允许跨组织预订	`false`
`MATRIX_ORG_VALIDATION_CACHE_TTL_MS`	❌	`300000`	组织验证缓存TTL（5分钟）	`600000`

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

矩阵API配置

服务器自动配置：

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

🔌 MCP集成

Claude桌面设置

更新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存储库运行服务器，而无需在本地克隆或构建。

重新启动克劳德桌面

矩阵预订工具现在将在您的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

支持

如需额外支持：

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

📚 api参考

可用的MCP工具

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

预订操作

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

位置发现

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

系统信息

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

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

🤝 贡献

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

开发工作流程

分叉和克隆

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

设置开发环境

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

创建特征分支

git checkout -b feature/your-feature-name

发展

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

质量检查

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

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

编码标准

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社区，提供出色的工具

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

使用说明

矩阵预订MCP服务器

🚀 特性

核心预订功能

高级搜索和定位

技术卓越

📋 需求

📦 安装

1.克隆存储库

2.安装依赖项

3.环境配置

4.建设项目

⚙️ 配置

环境变量

所需配置

高级配置

矩阵API配置

🔌 MCP集成

Claude桌面设置

其他MCP客户端

🛠️ 用法

发展模式

生产模式

可用操作

1.检查房间可用性

2.预约

智能默认值

🏗️ 架构概述

核心组件

🧪 测试

运行所有测试

测试覆盖率

测试类别

性能测试

🔍 故障排除

常见问题

1.身份验证错误

2.未找到位置

3.超时问题

4.日期/时间验证错误

5.组织ID映射问题

6.空位置层次结构

7.日期范围验证错误

8.MCP连接问题

调试模式

支持

📚 api参考

可用的MCP工具

预订操作

位置发现

系统信息

🤝 贡献

开发工作流程

编码标准

拉取请求要求

测试要求

📄 许可证

👥 维护者

📈 项目状态

🙏 致谢

相关 MCP

PowerPoint操作服务器

Flomo笔记服务

文档格式转换服务

3D资产生成服务

文档搜索服务

Microsoft 365命令行管理服务器