topdesk-mcp

# topdesk-mcp 该项目是一个用Python实现的模型上下文协议（MCP）服务器，通过TOPdeskPy SDK暴露TOPdesk API。 ## 项目目的 - 作为MCP服务器，桥接MCP客户端与TOPdesk API。 - 使用[TOPdeskPy SDK](https://github.com/TwinkelToe/TOPdeskPy)（经过一些修改）进行所有TOPdesk API交互。 ## MCP 配置 JSON ``` { "servers": { "topdesk-mcp": { "type": "stdio", "command": "uvx", "args": [ "topdesk-mcp" ], "env": { "TOPDESK_URL": "<您的 TOPdesk URL>", "TOPDESK_USERNAME": "<您的 TOPdesk 用户名>", "TOPDESK_PASSWORD": "<您的 TOPdesk API 密钥>" } } } } ``` ## 环境变量 * `TOPDESK_URL`: 您的TOPdesk实例的基本URL。例如：`https://yourcompany.topdesk.net` * `TOPDESK_USERNAME`: 您为API令牌生成的用户名。 * `TOPDESK_PASSWORD`: 您的API令牌 * `TOPDESK_MCP_TRANSPORT`: （可选）要使用的传输方式：'stdio'、'streamable-http'、'sse'。默认为'studio'。 * `TOPDESK_MCP_HOST`: （可选）监听的主机（适用于'streamable-http'和'sse'）。默认为'0.0.0.0'。 * `TOPDESK_MCP_PORT`: （可选）监听的端口（适用于'streamable-http'和'sse'）。默认为'3030'。 ### 文档转换环境变量 Topdesk 附件可以通过工具转换为 Markdown 格式。 默认情况下，它将尝试使用简单的 MarkItDown 库，但通常不够用。 这些变量配置附件到 Markdown 的转换功能，以利用 Docling 或 OpenAI 实例： * `DOCLING_ADDRESS`: （可选）用于文档转换的 Docling API 服务器的 URL。例如：`http://localhost:8080` * `DOCLING_API_KEY`: （可选）用于 Docling API 身份验证的 API 密钥 * `DOCLING_USERNAME`: （可选）用于 Docling API 基本身份验证的用户名（备用，如果没有 API 密钥） * `DOCLING_PASSWORD`: （可选）用于 Docling API 基本身份验证的密码（备用，如果没有 API 密钥） * `OPENAI_API_BASE`: （可选）用于文档转换的 OpenAI 兼容 API 的基本 URL。例如：`https://api.openai.com` * `OPENAI_API_KEY`: （可选）用于 OpenAI API 身份验证的 API 密钥 * `OPENAI_MODEL_NAME`: （可选）用于 OpenAI API 调用的模型名称。默认为'gpt-4.1' * `SSL_VERIFY`: （可选）启用/禁用 API 调用的 SSL 验证。设置为'false'以禁用。默认为'true'。 ## 本地开发设置 1. 确保已安装 Python 3.11+。 2. 创建并激活虚拟环境： ```bash pip install uv uv venv uv pip install -e . uv pip install -e ".[dev]" ``` 4. 运行： ```bash python -m topdesk_mcp.main ``` ### 注意： * 服务器骨架是使用官方MCP服务器模板生成的。 * 欢迎贡献。 ## 包结构 ``` topdesk_mcp/ # MCP服务器包目录 __init__.py # 标记为Python包 main.py # MCP服务器入口点 _topdesk_sdk.py # TOPdeskPy SDK _incident.py # 事件 API _operator.py # 操作员 API _person.py # 人员 API _utils.py # 请求助手方法 tests/ (单元测试) ``` ## 暴露的工具 - **topdesk_get_fiql_query_howto** 获取如何构造FIQL查询的提示，并附有示例。 - **topdesk_get_object_schemas** 获取TOPdesk事件和所有子字段的完整对象模式。 - **topdesk_get_incident** 通过UUID或事件编号（I-xxxxxx-xxx）获取TOPdesk事件。两种格式均可接受。 - **topdesk_get_incidents_by_fiql_query** 通过FIQL查询获取TOPdesk事件。 - **topdesk_get_incident_user_requests** 获取某个TOPdesk事件的所有用户请求。 - **topdesk_create_incident** 创建一个新的TOPdesk事件。 - **topdesk_archive_incident** 存档一个TOPdesk事件。 - **topdesk_unarchive_incident** 取消存档一个TOPdesk事件。 - **topdesk_get_timespent_on_incident** 获取某个TOPdesk事件的所有时间记录。 - **topdesk_register_timespent_on_incident** 在TOPdesk事件上注册时间记录。 - **topdesk_escalate_incident** 升级一个TOPdesk事件。 - **topdesk_get_available_escalation_reasons** 获取某个TOPdesk事件的所有可用升级原因。 - **topdesk_get_available_deescalation_reasons** 获取某个TOPdesk事件的所有可用降级原因。 - **topdesk_deescalate_incident** 降级一个TOPdesk事件。 - **topdesk_get_progress_trail** 获取某个TOPdesk事件的进度跟踪。 - **topdesk_get_incident_attachments** 获取某个TOPdesk事件的所有附件，以base64编码的数据返回。 - **topdesk_get_incident_attachments_as_markdown** 下载并转换某个TOPdesk事件的所有附件为Markdown格式。使用智能文档转换，支持PDF、Office文档、图像和其他文件类型。尝试使用OpenAI API（如果配置），然后使用Docling API（如果配置），并在本地处理时使用MarkItDown作为备用。 - **topdesk_get_complete_incident_overview** 获取某个TOPdesk事件的综合概述，包括其详细信息、进度跟踪和转换为Markdown的附件。该工具将`topdesk_get_incident`、`topdesk_get_progress_trail`和`topdesk_get_incident_attachments_as_markdown`的结果合并为一个响应，以便于访问所有事件信息。 - **topdesk_get_operatorgroups_of_operator** 获取操作员所属的TOPdesk操作员组列表，可选按FIQL查询或留空返回所有组。 - **topdesk_get_operator** 通过ID获取TOPdesk操作员。 - **topdesk_get_operators_by_fiql_query** 通过FIQL查询获取TOPdesk操作员。 - **topdesk_add_action_to_incident** 向TOPdesk事件添加操作（即回复/评论）。 - **topdesk_get_incident_actions** 获取某个TOPdesk事件的所有操作（即回复/评论）。 - **topdesk_delete_incident_action** 删除某个TOPdesk事件的特定操作（即回复/评论）。 - **topdesk_get_person_by_query** 通过FIQL查询获取TOPdesk人员。 - **topdesk_get_person** 通过ID获取TOPdesk人员。 - **topdesk_create_person** 创建新的TOPdesk人员。 - **topdesk_update_person** 更新现有的TOPdesk人员。 - **topdesk_archive_person** 存档TOPdesk人员。 - **topdesk_unarchive_person** 取消存档TOPdesk人员。 ## 参考 - [MCP 协议文档](https://modelcontextprotocol.io/llms-full.txt) - [TOPdeskPy SDK](https://github.com/TwinkelToe/TOPdeskPy) - [FastMCP](https://github.com/jlowin/fastmcp) ## 许可证 MIT 许可证。