Dixa MCP服务器

模型上下文协议（MCP）服务器，提供对Dixa API的访问，允许人工智能助手与Dixa组织数据和服务交互。

：警告：Beta免责声明

该项目目前处于测试阶段，按原样提供。

通过使用此存储库，您承认：

它可能包含错误、不完整的功能或破坏性的更改
使用风险完全由您自行承担
这是一个开源项目 Dixa的官方支持渠道不支持

对于问题或贡献，请使用 .

特性

组织信息：从Dixa API检索组织详细信息
灵活的身份验证：提供API密钥的多种方式（环境变量、命令行参数、客户端身份验证）
多种运输方式：支持子进程（适用于Claude Desktop）和HTTP/SSE传输
错误处理：具有详细错误消息的全面错误处理

先决条件

Python 3.8或更高版本
Dixa API密钥
（可选）用于MCP客户端集成的Claude Desktop

安装

1.克隆存储库

git clone https://github.com/Dixa-public/dixa-mcp-public.git
cd dixa-mcp-public

或者使用SSH：

git clone git@github.com:Dixa-public/dixa-mcp-public.git
cd dixa-mcp-public

2.创建虚拟环境

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3.安装依赖项

pip install fastmcp requests

或者从项目中安装：

pip install -e .

本地运行

启动服务器

安装后，您可以在本地运行服务器：

子进程模式（Claude Desktop的默认模式）

source venv/bin/activate
python server.py

或者通过命令行使用API键：

source venv/bin/activate
python server.py --api-key your-dixa-api-key-here

HTTP/SSE模式（用于远程访问）

在特定端口上启动HTTP服务器：

source venv/bin/activate
python server.py --http 8000

服务器将在以下时间可用 http://localhost:8000/mcp.

备注：对于本地HTTP服务器，您需要使用 mcp-remote 随着 --allow-http 配置Claude Desktop时标记。

Claude桌面配置

Dixa MCP服务器可以在Claude Desktop中通过三种方式进行配置：

1.dixa本地（本地子流程）

将项目作为子进程在本地运行。这是本地开发最简单的设置。

配置文件: ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%\Claude\claude_desktop_config.json （Windows）

{
  "mcpServers": {
    "dixa-local": {
      "command": "
/python",
      "args": [
        "
/dixa-mcp-public/server.py",
        "--api-key",
        ""
      ]
    }
  }
}

示例（macOS）：

{
  "mcpServers": {
    "dixa-local": {
      "command": "/Users/username/dixa-mcp-public/venv/bin/python",
      "args": [
        "/Users/username/dixa-mcp-public/server.py",
        "--api-key",
        "your-dixa-api-key-here"
      ]
    }
  }
}

替代：您还可以使用环境变量而不是命令行参数：

{
  "mcpServers": {
    "dixa-local": {
      "command": "/Users/username/dixa-mcp-public/venv/bin/python",
      "args": [
        "/Users/username/dixa-mcp-public/server.py"
      ],
      "env": {
        "DIXA_API_KEY": "your-dixa-api-key-here"
      }
    }
  }
}

2.dixa本地远程（本地HTTP服务器）

在本地复制远程设置。服务器在您的计算机上作为HTTP服务器运行，Claude Desktop通过以下方式连接 mcp-remote.

步骤1：在本地启动HTTP服务器：

cd dixa-mcp-public
source venv/bin/activate
python server.py --http 8000

步骤2：配置克劳德桌面：

{
  "mcpServers": {
    "dixa-local-remote": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:8000/mcp",
        "--header",
        "Authorization: Bearer ",
        "--allow-http"
      ]
    }
  }
}

备注：The --allow-http 本地HTTP服务器需要标志（HTTPS不需要）。

3.dixa远程（实时远程设置）

连接到实时远程服务器（例如，部署在FastMCP Cloud或您自己的服务器上）。

{
  "mcpServers": {
    "dixa-remote": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://dixa-mcp-public.fastmcp.app/mcp",
        "--header",
        "Authorization: Bearer "
      ]
    }
  }
}

备注：如果您在自己的服务器上运行MCP服务器，请更换 https://dixa-mcp-public.fastmcp.app/mcp 使用您的实际远程服务器URL。

配置摘要

方法	用例	服务器命令	注释
`dixa-local`	地方发展	`python server.py --api-key`	最简单的设置，作为子流程运行
`dixa-local-remote`	在本地测试远程设置	`python server.py --http 8000`	需要 `--allow-http` 旗帜
`dixa-remote`	生产/远程部署	服务器远程运行	不需要本地服务器

认证方法

服务器支持通过多种方法（按优先级顺序）对API密钥进行身份验证：

HTTP授权标头：自动提取自 Authorization: Bearer ... 标头（用于HTTP/SSE传输）
命令行参数：通过 --api-key 标志（用于子流程传输）
环境变量：设置 DIXA_API_KEY 环境变量

备注：对于远程HTTP/SSE服务器，API密钥自动从发送的授权头中提取 mcp-remote。您不需要将其作为工具参数传递。

运行服务器

子进程模式（默认）

对于Claude Desktop或其他基于子流程的MCP客户端：

source venv/bin/activate
python server.py

HTTP/SSE模式

对于基于HTTP的客户端：

source venv/bin/activate
python server.py --http [port]

如果未指定，默认端口为8000。

带命令行API密钥

source venv/bin/activate
python server.py --api-key your-dixa-api-key-here

可用工具

Dixa MCP服务器通过组织的工具类别提供对Dixa API的全面访问。所有工具都会自动从授权头或配置中提取API密钥。

组织工具

fetch_organization_details：从Dixa API检索组织信息。

代理工具

fetch_agent_by_id：通过ID获取特定的代理/管理员。
list_agents：列出组织中的所有代理/管理员。
list_agents_presence：列出所有代理的存在状态。
list_agent_teams：列出代理人所属的团队。
add_agent：创建新代理/管理员。
modify_agent_partial：部分更新代理（PATCH）。
update_agent_full：完全更新代理（PUT）。
set_agent_working_channel：为代理设置工作通道。

最终用户工具

list_end_users：列出组织中的所有最终用户（客户）。
fetch_end_user_by_id：通过ID获取特定的最终用户。
add_end_user：创建新的最终用户。
add_end_users_bulk：批量创建多个最终用户。
modify_end_user_partial：部分更新最终用户（PATCH）。
modify_end_users_bulk：批量部分更新多个最终用户。
update_end_user_full：完全更新最终用户（PUT）。
update_end_users_bulk：批量完全更新多个最终用户。
list_end_user_conversations：列出特定最终用户的所有对话。
anonymize_end_user：匿名化最终用户（GDPR合规性，通常不可逆转）。

对话工具

fetch_conversation_by_id：按ID获取特定对话。
search_conversations：使用过滤器（策略、条件、分页）搜索对话。
list_conversation_flows：列出对话的对话流。
list_conversation_activity_log：列出对话的活动日志条目。
list_conversation_notes：列出对话笔记。
list_linked_conversations：列出链接到父对话的对话。
list_conversation_messages：列出对话中的消息。
list_organization_activity_log：列出整个组织的活动日志条目。
list_conversation_ratings：列出对话的评级。
start_conversation：创建新对话。
import_conversations：批量导入对话。
add_conversation_note：在对话中添加注释。
add_conversation_notes_bulk：批量为对话添加多个注释。
tag_conversation：在对话中添加标签。
tag_conversation_bulk：批量为多个对话添加标签。
remove_tag_from_conversation：从对话中删除标签。
assign_conversation_to_agent：将对话分配/声明给代理。
close_conversation：结束对话。
reopen_conversation：重新开始一段闭门对话。
link_conversation_to_parent：将对话链接到父对话。
set_conversation_followup_status：设置对话的后续状态。
anonymize_conversation：将对话匿名化（GDPR合规性，通常不可逆转）。
anonymize_conversation_message：在对话中匿名特定消息（GDPR合规性，通常不可逆转）。

自定义属性工具

list_custom_attributes：列出所有自定义属性定义。
fetch_custom_attribute_by_id：按ID获取特定的自定义属性定义。
update_conversation_custom_attributes：更新对话的自定义属性。
update_end_user_custom_attributes：更新最终用户的自定义属性。

标记工具

list_tags：列出组织中的所有标签。
fetch_tag_by_id：按ID获取特定标签。
list_conversation_tags：列出特定对话的标签。
add_tag：创建新标签。
activate_tag：激活标签。
deactivate_tag：停用标签。
remove_tag：删除标记。

团队工具

list_teams：列出组织中的所有团队。
fetch_team_by_id：按ID获取特定团队。
list_team_agents：列出团队中的代理人。
list_team_presence：列出团队中代理的存在状态。
add_team：创建一个新团队。
add_agents_to_team：将代理添加到团队中。
remove_agents_from_team：从团队中删除代理。
remove_team：删除团队。

队列工具

list_queues：列出组织中的所有队列。
fetch_queue_by_id：按ID获取特定队列。
check_queue_availability：检查队列是否可用。
check_conversation_queue_position：检查对话在队列中的位置。
list_queue_agents：列出分配给队列的代理。
add_queue：创建新队列。
assign_agents_to_queue：将代理分配到队列。
remove_agents_from_queue：从队列中删除代理。

知识库工具

list_knowledge_articles：列出所有知识库文章。
fetch_knowledge_article_by_id：按ID获取特定的知识库文章。
list_knowledge_categories：列出所有知识库类别。
add_knowledge_article：创建新的知识库文章。
modify_knowledge_article：更新知识库文章。
remove_knowledge_article：删除知识库文章。
add_knowledge_category：创建新的知识库类别。

设置工具

list_contact_endpoints：列出所有联系人端点（通道）。
fetch_contact_endpoint_by_id：通过ID获取特定的联系端点。
check_business_hours_status：检查营业时间当前是否有效。
list_business_hours_schedules：列出所有营业时间安排。

分析工具

prepare_analytics_metric_query：通过发现可用的指标、过滤器、聚合和过滤器值来准备分析指标查询。打电话前使用此功能 fetch_aggregated_data.
fetch_aggregated_data：获取指标的聚合（摘要）分析数据。提供计数、百分比、平均值等汇总统计数据。 始终从这个工具开始 在考虑未汇总数据之前。

备注：未汇总数据工具(prepare_analytics_record_query 和 fetch_unaggregated_data)当前已禁用以防止对话长度错误。仅使用聚合数据工具。

工具类别摘要

类别	只读工具	修改工具	总计
组织	1	0	1
代理人	4	4	8
最终用户	3	7	10
对话	9	11	20
自定义属性	2	2	4
标签	3	4	7
团队	4	4	8
队列	5	3	8
知识库	3	4	7
设置	4	0	4
分析	2	0	2
总计	40	39	79

重要说明

修改工具：所有修改工具（创建、更新、删除操作）都会修改数据，并在执行前需要明确的用户确认。
API密钥：所有工具都会自动从授权标头（对于HTTP/SSE）或配置（对于子流程）中提取API密钥。
ID要求：大多数工具都需要实体id（会话id、代理id等），必须首先使用相应的“列表”或“获取”工具获取这些id。
分析工作流：始终以开头 prepare_analytics_metric_query 要发现可用指标，请使用 fetch_aggregated_data 用于汇总统计。

本地测试

测试1：直接Python测试

直接测试API包装：

from dixa_api import DixaClient
import os

# Set API key
os.environ["DIXA_API_KEY"] = "your-api-key-here"

# Create client and test
client = DixaClient()
org_info = client.get_organization()
print(org_info)

测试2：测试服务器工具

import os
os.environ["DIXA_API_KEY"] = "your-api-key-here"

from server import get_organization_info

# Test the tool
result = get_organization_info()
print(result)

测试3：测试服务器作为子进程

创建测试脚本 test_server.py:

import subprocess
import json
import sys

# Test with environment variable
env = os.environ.copy()
env["DIXA_API_KEY"] = "your-api-key-here"

result = subprocess.run(
    [sys.executable, "server.py"],
    env=env,
    capture_output=True,
    text=True
)
print(result.stdout)
print(result.stderr)

测试4：测试HTTP服务器

启动服务器：

python server.py --http 8000

在另一个终端中，使用curl进行测试：

# Test the MCP endpoint
curl http://localhost:8000/mcp

或者使用Python客户端：

import requests

response = requests.get(
    "http://localhost:8000/mcp",
    headers={"Authorization": "Bearer your-api-key-here"}
)
print(response.json())

测试5:MCP检查员测试

您可以使用MCP检查器工具测试您的服务器：

# Install MCP Inspector (if available)
npm install -g @modelcontextprotocol/inspector

# Test subprocess server
mcp-inspector python server.py

# Test HTTP server (after starting it)
mcp-inspector --url http://localhost:8000/mcp

项目结构

dixa-mcp-public/
├── server.py          # FastMCP server with tools
├── dixa_api.py        # Dixa API client wrapper
├── pyproject.toml     # Project dependencies
├── venv/              # Virtual environment (not in git)
└── README.md          # This file

API包装

这 DixaClient 上课中 dixa_api.py 为Dixa API提供了一个干净的接口：

from dixa_api import DixaClient

# Initialize with API key
client = DixaClient(api_key="your-key")

# Or use environment variable
client = DixaClient()  # Uses DIXA_API_KEY env var

# Get organization info
org_info = client.get_organization()

错误处理

客户端提供详细的错误消息：

HTTP错误：用于HTTP 4xx/5xx错误和响应详细信息
请求异常：网络/请求错误
值错误：如果缺少API密钥

故障排除

ModuleNotFoundError:没有名为“fastmcp”的模块

确保您已激活虚拟环境并安装了依赖项：

source venv/bin/activate
pip install fastmcp requests

找不到API密钥

请确保您的API密钥是通过支持的方法之一提供的：

用于子流程运输（本地）:

环境变量： export DIXA_API_KEY="your-key" （在Claude Desktop配置中设置 env 部分）
命令行： python server.py --api-key your-key （在Claude Desktop配置中设置 args 部分）

用于HTTP/SSE传输（远程）:

授权头：在Claude Desktop配置中使用配置 --header "Authorization: Bearer your-key" 在 mcp-remote 参数
服务器使用FastMCP的 get_http_headers() 功能

备注：对于远程服务器，Claude Desktop不会传递环境变量，因此必须使用Authorization标头方法。

服务器无法启动

检查是否安装了Python 3.8+： python3 --version
验证虚拟环境是否已激活
检查是否安装了所有依赖项： pip list
查看控制台中的错误消息

连接问题（HTTP/SSE）

确保服务器正在运行： python server.py --http 8000 （或 python server.py --http 8000 http 用于HTTP传输）
检查客户端配置中的URL是否与服务器URL匹配（应以结尾 /mcp)
验证授权标头的格式是否正确： Authorization: Bearer your-api-key-here
对于本地HTTP服务器，请确保 --allow-http 旗帜包含在 mcp-remote 参数
验证防火墙设置是否允许连接到端口
检查服务器日志中的身份验证错误（查找 [get_organization_info] 消息）
确保 npx 已安装并可以运行 mcp-remote

发展

添加新工具

在中添加您的工具功能 server.py:

@mcp.tool
def my_new_tool(param: str) -> str:
    """Tool description."""
    # Your implementation
    return result

使用 DixaClient 对于API调用：

from dixa_api import DixaClient

@mcp.tool
def my_tool() -> Dict[str, Any]:
    client = DixaClient()  # Uses configured API key
    # Make API calls
    return result

添加新的API端点

扩展 DixaClient 在 dixa_api.py:

def get_new_endpoint(self, param: str) -> Dict[str, Any]:
    """Get data from new endpoint."""
    url = f"{self.base_url}/new-endpoint"
    response = requests.get(url, headers=self.headers, params={"param": param})
    response.raise_for_status()
    return response.json()

安全说明

永远不要提交API密钥 到版本控制
使用环境变量或安全配置管理
对于生产，使用安全身份验证方法
考虑对API密钥使用秘密管理服务

许可证

此项目使用以下依赖关系和服务：

FastMCP

该项目是使用 FastMCP，一个用于构建模型上下文协议服务器的框架。

网站: https://gofastmcp.com
许可证：请参阅 FastMCP许可证获取许可证信息

FastMCP云

对于远程部署，此项目可以托管在 FastMCP云.

网站: https://fastmcp.app
服务：FastMCP Cloud为MCP服务器提供托管

Dixa API

该项目与Dixa API集成，以提供对Dixa组织数据和服务的访问。

API文档: https://docs.dixa.io/docs/
许可证：有关特定于API的许可和条款，请参阅Dixa API文档

支持

对于问题和疑问：

检查故障排除部分
审查 Dixa API文件
查阅FastMCP文档：https://gofastmcp.com
审查MCP文件：https://modelcontextprotocol.io

Dixa MCP Public

快速接入

详细介绍