关键词

业务管理沙龙管理预约系统Altegio.ProLLM工具集成

项目简介

Altegio.Pro MCP 服务器是一个基于 Model Context Protocol (MCP) 构建的应用后端，旨在将 Altegio.Pro 的业务管理功能（如员工、服务、预约的创建、读取、更新、删除操作）通过标准化的 MCP 接口暴露给大型语言模型（LLM）客户端。它支持多种传输协议，并为 LLM 应用提供上下文信息和工具调用能力，使得 LLM 能够直接与 Altegio.Pro 平台互动，执行业务任务。

主要功能点

  • 业务管理工具： 提供了 16 种 MCP 工具，用于管理 Altegio.Pro 平台的员工、服务、预约等，包括：
    • 认证： 登录、注销 Altegio 账户。
    • 数据查询： 列出公司、获取预约详情、获取员工列表、获取服务列表、获取服务类别、查询员工日程。
    • 数据管理 (CRUD)： 创建、更新、删除员工；创建、更新服务；创建、更新、删除预约。
  • 多传输协议支持： 支持 Stdio (适用于桌面应用如 Claude Desktop) 和 HTTP (支持 SSE 和 Streamable HTTP，适用于云部署) 两种通信协议，确保与不同 LLM 客户端的灵活集成。
  • 安全认证与会话管理： 所有敏感操作都需要用户登录认证。服务器能安全存储用户凭证在本地（如 '~/.altegio-mcp/' 目录下），并支持会话管理。
  • 可扩展与可配置： 提供灵活的配置选项，支持自定义 Altegio API 基础 URL、日志级别、API 速率限制和重试逻辑等，易于部署和维护。
  • 全面的类型安全与测试： 使用 TypeScript 开发，确保代码质量和可维护性，并配有详细的测试用例。

安装步骤

在您的开发环境中部署此 MCP 服务器，您需要先安装 Node.js (推荐版本 18 或更高)。

  1. 克隆仓库： 
    git clone https://github.com/petroff/altegio-pro-mcp.git
  2. 进入项目目录： 
    cd altegio-pro-mcp
  3. 安装依赖： 
    npm install
  4. 配置环境变量：
    • 复制 '.env.example' 文件并重命名为 '.env'： 
      cp .env.example .env
    • 编辑新创建的 '.env' 文件，务必添加您的 'ALTEGIO_API_TOKEN'。此令牌可从 developer.alteg.io 获取。 
      # .env 示例
ALTEGIO_API_TOKEN="您的Altegio合作伙伴API令牌"
# 其他可选配置：
# ALTEGIO_API_BASE="https://api.alteg.io/api/v1"
# LOG_LEVEL="info"
# NODE_ENV="development"
  5. 构建项目： 
    npm run build

服务器配置（供 MCP 客户端使用）

MCP 服务器可以以两种模式运行：Stdio（标准输入输出）模式或 HTTP 模式。不同的 LLM 客户端支持不同的连接方式。

1. Claude Desktop 客户端配置 (Stdio 模式)

Claude Desktop 支持通过 Stdio 协议直接启动和通信 MCP 服务器。

  • 配置步骤：
    1. 确保您已完成上述“安装步骤”。
    2. 找到您的 Claude Desktop 配置文件 'claude_desktop_config.json'。在 macOS 上，通常位于 '~/Library/Application Support/Claude/'。
    3. 将以下 JSON 片段添加到 'claude_desktop_config.json' 文件中的 '"mcpServers"' 对象内。请根据您的实际路径替换 '/absolute/path/to/altegio-mcp/dist/index.js'。 
      {
  "mcpServers": {
    "altegio-pro": {
      // MCP 服务器的唯一标识符
      "command": "node", // 启动服务器的执行命令
      "args": ["/absolute/path/to/altegio-mcp/dist/index.js"], // 传递给命令的参数，指向编译后的服务器主文件路径
      "env": {
        // MCP 服务器运行所需的环境变量
        "ALTEGIO_API_TOKEN": "您的Altegio合作伙伴API令牌" // 替换为您的 Altegio 合作伙伴 API Token
        // "CREDENTIALS_ENCRYPTION_KEY": "一个强密钥，用于加密凭证" // 可选，用于加密本地存储的 Altegio 用户凭证
      }
    }
  }
}
    4. 重启 Claude Desktop 以加载新的服务器配置。

2. 云部署 LLM 客户端配置 (HTTP 模式)

对于部署在云端或支持 HTTP/SSE 协议的 LLM 客户端 (如 OpenAI/ChatGPT 或其他平台)，服务器可以作为 HTTP 服务运行。

  • 启动 HTTP 服务器： 在项目根目录运行以下命令来启动 HTTP 服务器（默认监听端口 8080）： 
    npm run start:http
    您可以在 '.env' 文件中设置 'PORT' 环境变量来更改端口，例如 'PORT=3000'。
  • LLM 客户端配置： MCP HTTP 服务器将在 '/mcp' 路径上提供服务（例如：'http://localhost:8080/mcp'）。LLM 客户端需要配置其连接到此 HTTP 地址。
    • OpenAI/ChatGPT (自定义工具功能)： 在配置自定义工具时，您需要提供服务器的 OpenAPI 规范或直接描述工具功能。这个 MCP 服务器本质上是一个工具提供者。客户端将通过 HTTP POST 请求发送 MCP JSON-RPC 请求到 '/mcp' 端点，并通过 SSE (Server-Sent Events) 接收通知。
    • 其他 LLM 平台： 具体配置方法请参考您所使用的 LLM 平台的文档，通常涉及提供一个 HTTP/S 端点，LLM 将通过该端点与 MCP 服务器进行 JSON-RPC 通信。

基本使用方法

  1. 启动 MCP 服务器：
    • 根据您的 LLM 客户端和部署方式，通过 'npm start' (Stdio) 或 'npm run start:http' (HTTP) 启动服务器。
  2. 在 LLM 客户端中连接：
    • 按照上述“服务器配置”部分，在您的 LLM 客户端中正确配置 Altegio.Pro MCP 服务器。
  3. 通过 LLM 客户端调用工具：
    • 一旦连接成功，您的 LLM 客户端将能够发现并调用 Altegio.Pro MCP 服务器提供的 16 个工具。
    • 例如：
      • 当您向 LLM 提问“我需要登录 Altegio 来管理我的沙龙”时，LLM 可能会提示您提供 Altegio 账户的电子邮件和密码，然后自动调用 'altegio_login' 工具进行认证。
      • 当您请求“列出我管理的所有公司”时，LLM 会调用 'list_companies' 工具并向您展示结果。
      • 您可以让 LLM 帮您“创建一名新员工叫张三，职位是造型师，电话 13812345678”等，LLM 将自动调用相应的 'create_staff' 或其他管理工具来执行操作。
    • LLM 将根据您的问题自动选择并执行合适的工具，并以自然语言向您呈现结果或请求进一步信息。

信息

分类

商业系统

访问项目