AI导哈

JSON-RPC包装器

一个高级、生产就绪的JSON-RPC 2.0包装器，用于EasyVista REST API，提供高性能、安全且易于使用的接口，适用于与LLM代理和其他外部系统的集成。

  • by antuelle78
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 antuelle78/easyvista_advanced

使用说明

EasyVista高级工具 - JSON-RPC封装器

一个高级、可投入生产的JSON-RPC 2.0封装工具，用于EasyVista REST API。此服务提供了一个强大、可扩展且易于使用的接口，用于与EasyVista进行交互，旨在与LLM代理（如Open-WebUI）和其他外部系统集成。

特点/功能

  • 异步且高性能使用FastAPI构建 httpx 用于高性能、非阻塞I/O。
  • 强大的错误处理包括自动重试功能，采用指数退避策略，并将API错误转换为标准的JSON-RPC错误响应。
  • 安全的使用API密钥身份验证保护服务。
  • 丰富的工具集提供了一套全面的工具，用于管理工单和生成报告。
  • 集装箱化使用Docker和Docker Compose实现完全容器化，便于部署和扩展。
  • 包含模拟API随附一个内置的模拟API用于测试和开发，使您能够在没有实际EasyVista实例的情况下运行服务。

建筑

该项目采用了一种简洁、分层的架构，实现了关注点的分离：

  • **API 层（app/api）**所有传入请求的入口点，使用FastAPI构建。
  • **服务层 (app/services）**包含与EasyVista API交互的业务逻辑。
  • **数据模型层 (app/models）**使用 Pydantic 定义应用程序中使用的数据结构。
  • **核心配置（app/core)**管理应用程序级别的设置和环境变量。

入门指南/开始使用

先决条件

  • Docker
  • Docker Compose

安装

  1. 克隆仓库：

    git clone git@github.com:antuelle78/easyvista_advanced.git
cd easyvista_advanced

  2. 配置环境：

    创建一个 .env 在项目根目录下创建文件并添加以下变量。对于本地测试，默认值将与随附的模拟API一起正常工作。

    # The URL of the EasyVista API (or the mock API)
EASYVISTA_URL=http://mock_api:8085

# The API key for the EasyVista API
EASYVISTA_API_KEY=your_api_key

# The account ID for the EasyVista API
EASYVISTA_ACCOUNT_ID=your_account_id

# The API key to secure this service
EASYVISTA_TOOL_API_KEY=a-very-secret-api-key

  3. 构建并运行服务：

    docker compose up --build -d

    这将启动 easyvista_tool 服务（可在 http://localhost:8004）以及 mock_api 服务（可在 http://localhost:8085）。

使用方法

所有工具均通过一个单一的JSON-RPC端点进行访问： http://localhost:8004/api/v1/mcp。

您必须在其中包含您的API密钥 X-API-KEY 所有请求的头部信息。

示例请求（list_tickets):

curl -X POST http://localhost:8004/api/v1/mcp \
     -H "Content-Type: application/json" \
     -H "X-API-KEY: a-very-secret-api-key" \
     -d '{'\
           "jsonrpc": "2.0",
           "method": "list_tickets",
           "params": {"status": "Open"},
           "id": 1
         }'

生产环境配置（连接到真实的EasyVista实例）

要将服务连接到您实际的EasyVista实例，您需要更新 .env 附上您的生产凭据文件：

  1. **EASYVISTA_URL**请将此更改为您的组织的EasyVista API终端节点。

    EASYVISTA_URL=https://your-company.easyvista.com

  2. **EASYVISTA_API_KEY**使用从您的EasyVista帐户生成的有效API密钥（Bearer Token）。

    EASYVISTA_API_KEY=your-real-easyvista-api-key

  3. **EASYVISTA_ACCOUNT_ID**将此设置为您在EasyVista的账户ID。

    EASYVISTA_ACCOUNT_ID=your-account-id

更新后 .env 文件，重启服务：

docker compose up -d --build

对于生产环境的部署，你也可以删除或注释掉 mock_api 来自（某处的）服务 docker-compose.yml 将其存档，因为它将不再需要。

Kubernetes 部署（或“Kubernetes 部署对象”）

这个项目包含一个用于部署的Kubernetes清单文件 easyvista_tool 为单节点 k3s 集群提供服务。

先决条件

  • 一个正在运行的 Kubernetes 集群（例如，k3s、Minikube）。
  • kubectl 配置为连接到您的集群。

部署步骤

  1. 编码你的秘密：

    这个 kubernetes_manifest.yaml 文件要求您的密钥需进行Base64编码。请使用以下命令对您的凭据进行编码：

    echo -n 'your-real-easyvista-api-key' | base64
echo -n 'your-account-id' | base64
echo -n 'a-very-secret-api-key' | base64

  2. 更新清单：

    打开 kubernetes_manifest.yaml 并替换其中的占位符值 Secret 使用Base64编码的凭据作为资源。您还必须更新 EASYVISTA_URL 在……里 ConfigMap 指向您的生产环境EasyVista实例。

  3. 应用清单（或：执行清单）：

    kubectl apply -f kubernetes_manifest.yaml

  4. 访问服务：

    该服务将暴露在端口上 30087 在您的 Kubernetes 节点上。您可以访问它于 http://<your-node-ip>:30087.

API 参考

以下工具可供使用：

方法 描述 参数
create_ticket 创建一个新工单。 title， description， category， priority， support_team （可选）， assigned_to （可选）
assign_ticket 将工单分配给支持人员。 rfc_number， assigned_to
get_ticket 通过RFC编号检索单个工单。 rfc_number
get_ticket_history 获取票务的状态历史记录。 rfc_number
list_tickets 列出票据，可选择过滤。 status， priority， group_id， assigned_to， limit， offset
get_tickets_by_group 获取特定组的票据。 group_id
get_tickets_by_status 获取具有特定状态的票据。 status
get_tickets_by_priority 获取具有特定优先级的工单。 priority
generate_report 生成工单报告。 report_type (summary， csv， html)， filters (status， priority， group_id， assigned_to)
get_resolution_metrics 按团队检索平均解决时间。 （无）

运行测试

该项目包含一整套单元测试。要运行这些测试，请执行以下命令：

docker compose exec easyvista_tool pytest

这将在服务容器内部运行测试，确保测试环境的一致性。

做出贡献

欢迎贡献！请随时提交拉取请求。

许可证

这个项目遵循MIT许可证授权——详见 许可证 详情请参阅文件。

相关 MCP