Altegio Pro MCP

阿尔特吉奥。Pro MCP服务器

官方MCP服务器 阿尔泰吉奥 组织

  

Altegio的MCP服务器。专业企业管理API-为沙龙/水疗中心所有者和管理人员提供B2B集成。

目标用户： 管理Altegio公司的企业主 身份验证： 所有操作都需要用户登录（通过以下方式获得 altegio_login) 集中： 仅限管理B2B操作（无公共预订功能）

特性

• 33个MCP工具 包括10个首次设置的入门向导工具
• CRUD操作 用于员工、服务、预订、日程安排和职位管理
• 对话式入职培训 具有批量CSV/JSON导入和检查点/恢复功能
• 双重运输： 用于Claude Desktop的stdio，用于云部署的HTTP
• TypeScript 具有全型安全和全面测试（157通过）
• 自动部署CI/CD 通过VM cron（git pull+docker compose每2分钟重建一次）
• 速率限制 和 重试逻辑 指数回退
• 安全的凭证存储 在 ~/.altegio-mcp/

可用工具

按类别组织的33种工具 对于完整的业务管理：

🔐 认证

• altegio_login -使用电子邮件/密码进行身份验证
• altegio_logout -清除存储的凭据

🏢 公司管理层

• list_companies -获取托管公司（需要身份验证）

👥 员工管理

• get_staff -查看具有管理员详细信息的员工
• create_staff -添加新员工
• update_staff -修改员工详细信息
• delete_staff -删除员工

📋 职位管理

• get_positions -列出公司职位/角色
• create_position -创建新职位（经理、造型师等）
• update_position -修改职位详细信息
• delete_position -移除位置

🛎️ 服务管理

• get_services -查看所有配置服务
• get_service_categories -查看服务类别
• create_service -添加新服务
• update_service -修改服务详细信息

📅 进度管理

• get_schedule -查看员工工作时间表
• create_schedule -设置员工工作时间
• update_schedule -修改工作计划
• delete_schedule -删除计划条目

📖 预订管理

• get_bookings -查看约会
• create_booking -创建客户预约
• update_booking -修改现有约会
• delete_booking -取消预约

🚀 入职向导

会话型首次设置助手：

• onboarding_start -初始化设置会话
• onboarding_resume -恢复中断的设置
• onboarding_status -检查进度
• onboarding_add_categories -批量创建服务类别
• onboarding_add_staff_batch -批量导入人员（CSV/JSON）
• onboarding_add_services_batch -批量导入服务（CSV/JSON）
• onboarding_import_clients -导入客户端数据库
• onboarding_create_test_bookings -生成样本数据
• onboarding_preview_data -导入前验证
• onboarding_rollback_phase -撤消特定阶段

注： 服务删除操作在Altegio API中不可用。所有写入操作都需要通过以下方式进行用户身份验证 altegio_login。参见 入职指南 用于首次设置工作流。

快速开始

先决条件

• Node.js>=18
• Altegio合作伙伴代币来自 developer.alteg.io

安装

git clone https://github.com/altegio/altegio-pro-mcp.git
cd altegio-mcp
npm install
cp .env.example .env
# Edit .env and add ALTEGIO_API_TOKEN
npm run build

Claude桌面设置

1. 构建服务器： npm run build
2. 添加 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "altegio-pro": {
      "command": "node",
      "args": ["/absolute/path/to/altegio-mcp/dist/index.js"],
      "env": {
        "ALTEGIO_API_TOKEN": "your_partner_token"
      }
    }
  }
}

1. 重新启动克劳德桌面

看 CLAUDE_DESKTOP_SETUP.md 详细设置。

入职向导

v2.0中的新功能： 首次平台设置时的对话助手。通过自然语言或批量CSV上传导入员工、服务和客户。

快速入职流程

// 1. Login and start
altegio_login({ email: "owner@salon.com", password: "..." })
onboarding_start({ company_id: 123456 })

// 2. Create categories
onboarding_add_categories({
  company_id: 123456,
  categories: [
    { title: "Hair Services" },
    { title: "Nail Services" }
  ]
})

// 3. Import staff (CSV or JSON)
onboarding_add_staff_batch({
  company_id: 123456,
  staff_data: `name,specialization,phone
Alice Johnson,Senior Stylist,+1234567890
Bob Smith,Nail Technician,+1234567891`
})

// 4. Add services
onboarding_add_services_batch({
  company_id: 123456,
  services_data: [
    { title: "Haircut", price_min: 50, duration: 60 },
    { title: "Manicure", price_min: 30, duration: 45 }
  ]
})

// 5. Import clients
onboarding_import_clients({
  company_id: 123456,
  clients_csv: `name,phone,email
Sarah Miller,+1234560001,sarah@example.com
John Davis,+1234560002,john@example.com`
})

// 6. Generate test bookings
onboarding_create_test_bookings({ company_id: 123456, count: 5 })

// 7. Check progress
onboarding_status({ company_id: 123456 })

主要特点：

• 检查点/恢复： 自动从错误或中断中恢复
• 混合动力输入： 接受JSON数组或CSV字符串
• 预览模式： 导入前验证数据(onboarding_preview_data)
• 回降： 撤消特定阶段(onboarding_rollback_phase)
• 进度跟踪： 查看完成状态(onboarding_status)

节省时间： 5-10分钟vs 30+分钟手动设置

看 docs/ONBOARDING_GUIDE.md 有关CSV模板、错误处理和故障排除的完整指南。

本地Docker测试

# Create .env with your API token
echo "ALTEGIO_API_TOKEN=your_partner_token" > .env

# Start with Docker Compose (recommended)
docker compose -f docker-compose.local.yml up --build -d

# Health check
curl http://localhost:8080/health

# View logs
docker compose -f docker-compose.local.yml logs -f

# Stop
docker compose -f docker-compose.local.yml down

或者独立运行：

docker build -t altegio-mcp:local .
docker run --rm -p 8080:8080 --env-file .env -e PORT=8080 altegio-mcp:local

MCP端点位于 http://localhost:8080/mcp （流式HTTP传输）。看 测试.md 了解完整的MCP协议测试指南。

生产部署

自动部署到 mcp-servers VM上的PR合并到 main一个cron作业会获取最新的 main 每2分钟进行一次，如有更改，则进行重建。

公共端点： https://mcp.alteg.io/pro/mcp

看 CI-CD.md 了解详情。

配置

发展

npm install          # Install dependencies
npm run dev          # Dev mode with hot reload
npm run build        # Build TypeScript
npm test             # Run tests
npm run test:watch   # Watch mode
npm run lint         # Check code style

项目结构

src/
  config/        # Configuration and validation
  providers/     # API clients (altegio-client.ts)
  tools/         # MCP tool handlers & registry
  types/         # TypeScript interfaces
  utils/         # Logging, errors, helpers
  __tests__/     # Jest unit tests
  index.ts       # stdio server entry
  http-server.ts # HTTP server entry
  server.ts      # Shared MCP server setup

测试

• 157测试 （23套）涵盖身份验证、所有工具、错误处理、分页
• 玩笑 用于模拟API响应的单元测试
• 测试隔离 使用临时凭据目录
• 运行： npm test 或 npm run test:coverage
• 看 测试.md 用于本地Docker和MCP协议测试

集成

• 克劳德桌面： 本地stdio传输（推荐）
• 其他MCP客户端： 通过云运行URL进行流式HTTP传输（MCP规范2025-11-25，带有工具注释和结构化输出）

API 参考

基本URL: https://api.alteg.io/api/v1 文档： developer.alteg.io/api

身份验证：

• 合作伙伴令牌： Authorization: Bearer {token}
• 用户令牌： User-Token: {token} （通过以下方式获得 altegio_login)

贡献

欢迎投稿！看 贡献.md 用于：

• 开发设置
• 编码标准（TypeScript、Prettier、ESLint）
• 测试指南
• 承诺约定

快速捐款流：

1. 分叉并创建特征分支
2. 为新功能添加测试
3. 确保 npm test 和 npm run lint 通过
4. 提交带有清晰描述的PR

许可证

MIT许可证-请参阅 许可证 文件

支持

• 问题：
• 讨论：
• Altegio API： 技术支持.io

致谢

建于 模型上下文协议 由Anthropic和 Altegio API 用于沙龙/水疗管理。