使用说明
卤虫mcp
基于Rust的 模型上下文协议 服务器 Halopsa通过符合标准的MCP接口，使AI助手能够通过身份验证访问HaloPSA票证、操作和工作流。
服务器将OAuth 2.1中继到HaloPSA自己的授权端点，这意味着用户直接通过HaloPSA进行身份验证，所有API调用都带有他们的真实权限。服务器永远不会看到密码或直接处理凭据。
特性
- OAuth 2.1中继 双腿完全支持PKCE（S256）
- 18个MCP工具 涵盖票证、操作、工作流、参考数据和语义搜索
- 工作流感知操作 --仅显示票当前步骤中有效的转换
- 语义搜索 对每个经过身份验证的用户进行权限过滤
- 加密令牌存储 --HaloPSA代币与AES-256-GCM一起存储在SQLite中
- 托管和内部部署 支持HaloPSA实例
- 两个MCP传输：SSE（经典）和流式HTTP（POST）
- 可插拔嵌入提供商：本地fastembed、兼容OpenAI的API或Ollama
建筑
带有四个板条箱的货物工作区：
| 板条箱 | 类型 | 用途 |
|---|---|---|
hmcp-common |
库 | 共享类型，HaloPSA API客户端，DB特征，票证分块 |
hmcp-db-postgres |
库 | 用于身份验证令牌和语义嵌入的Postgres+pgvector后端 |
hmcp-server |
二进制 | MCP服务器：OAuth 2.1中继、SSE+流式HTTP传输、工具处理程序 |
hmcp-embedder |
binary | 嵌入sidecar：fastembed/OpenAI/Ollama，作业队列工作者 |
嵌入器作为单独的服务运行。它使用服务帐户（客户端凭据流）对票证进行索引，从而完成嵌入语料库。在查询时，每个结果在返回之前都会根据请求用户的令牌进行验证，因此用户只能看到他们有权访问的票证。
语义搜索使用 pg向量 具有HNSW余弦相似性指数。Docker Compose文件引脚 pgvector/pgvector:pg16，它捆绑了Postgres 16和扩展——不需要额外的设置。
快速入门（Docker）
复制 .env.example 到 .env 并填写所需值（参见 配置 下面），然后：
docker compose up -d
服务器在端口上启动 8080嵌入器从它旁边开始，并在后台开始索引票证。
要在Claude Desktop或其他MCP客户端上使用SSE传输，请将其指向：
http://your-host:8080/sse
对于流式HTTP传输：
http://your-host:8080/mcp
配置
复制 .env.example 到 .env.必需变量：
| 变量 | 描述 |
|---|---|
HMCP_HALO_URL |
HaloPSA实例URL（例如。 https://psa.example.com) |
HMCP_HALO_CLIENT_ID |
OAuth应用程序客户端ID（授权码流） |
HMCP_HALO_CLIENT_SECRET |
OAuth应用程序客户端密钥 |
HMCP_HALO_TENANT |
托管HaloPSA的租户名称；留空供内部使用 |
HMCP_ENCRYPTION_KEY |
AES-256-GCM令牌加密的32+字符密钥 |
HMCP_PUBLIC_DOMAIN |
用于OAuth重定向URI和链接生成的公共域 |
服务器默认值：
| 变量 | 默认值 | 描述 |
|---|---|---|
HMCP_HOST |
0.0.0.0 |
绑定地址 |
HMCP_PORT |
8080 |
监听端口 |
HMCP_DATABASE_URL |
（必填） | Postgres连接URL。在Compose中，它来自 HMCP_DB_USER/HMCP_DB_PASSWORD/HMCP_DB_NAME 自动。 |
语义搜索（可选）：
| 变量 | 默认值 | 描述 |
|---|---|---|
HMCP_SEMANTIC_SEARCH |
false |
启用语义搜索工具 |
HMCP_EMBEDDER_URL |
http://hmcp-embedder:8081 |
嵌入器sidecar URL |
HMCP_EMBED_CLIENT_ID |
用于索引的服务帐户客户端ID | |
HMCP_EMBED_CLIENT_SECRET |
服务帐户客户端密码 | |
HMCP_EMBED_TENANT |
服务帐户租户（仅托管） | |
HMCP_WEBHOOK_SECRET |
用于事件通知的HaloPSA webhook秘密 | |
HMCP_EMBED_PROVIDER |
local |
嵌入提供程序： local, openai，或 ollama |
HMCP_EMBED_MODEL |
BAAI/bge-base-en-v1.5 |
型号名称（特定于提供商） |
对于OpenAI兼容的提供商，也设置 HMCP_EMBED_API_KEY 并且可选 HMCP_EMBED_API_URL为Ollama准备 HMCP_EMBED_OLLAMA_URL.
看 .env.example 对于所有带有注释的选项。
MCP工具
门票
| 工具 | 说明 |
|---|---|
list_tickets |
列出带有可选过滤器的门票（代理人、团队、客户、状态、关键字、仅开放） |
get_ticket |
获取完整的工单详细信息，包括可用的工作流操作 |
create_ticket |
创建新票证 |
update_ticket |
更新现有票证上的字段 |
search_tickets |
在机票摘要和详细信息中进行关键字搜索 |
行动
| 工具 | 说明 |
|---|---|
list_actions |
列出工单上的所有操作（注释、回复、转换） |
create_action |
添加注释或回复，并可选择工作流转换 |
工作流程
| 工具 | 说明 |
|---|---|
get_available_actions |
使工作流程转换在工单的当前步骤有效 |
execute_workflow_action |
执行工作流转换，将工单移动到下一步 |
参考数据
| 工具 | 说明 |
|---|---|
list_statuses |
列出所有带有ID的票证状态 |
list_teams |
列出所有团队和队列 |
list_ticket_types |
列出所有门票类型 |
get_client |
按ID获取客户详细信息 |
用户
| 工具 | 说明 |
|---|---|
get_me |
获取有关已验证代理的信息 |
get_ticket_assets |
列出与票证关联的资产 |
语义搜索（可选，需要 HMCP_SEMANTIC_SEARCH=true)
| 工具 | 说明 |
|---|---|
semantic_search |
对所有索引门票进行自然语言搜索，根据用户权限进行过滤 |
embedding_status |
检查嵌入索引的运行状况和进度 |
reembed |
触发所有票或特定票的重新索引 |
语义搜索
当启用语义搜索时，嵌入器sidecar会维护所有票的向量索引。每张票都被分为摘要/元数据块和细节块，并为票历史添加了每个动作块。嵌入器使用具有广泛读取权限的服务帐户来保持索引的完整性。
在查询时， semantic_search 通过向量相似度检索候选块，然后根据请求用户自己的HaloPSA令牌验证每个匹配的票。在返回响应之前，用户无法访问的结果会被过滤掉。这意味着索引是共享的，但每个用户的访问都是强制的。
支持的提供商：
- 本地 （默认）-- 禁食 运行过程中，不需要外部API。默认型号：
BAAI/bge-base-en-v1.5. - 开放人工智能 -任何与OpenAI兼容的嵌入API。集
HMCP_EMBED_API_KEY并可选择覆盖HMCP_EMBED_API_URL对于自托管模型。 - 奥拉玛 --当地Ollama实例。集
HMCP_EMBED_OLLAMA_URL.
OAuth流
服务器实现了一个两条腿的OAuth 2.1中继：
- MCP客户端启动授权。服务器重定向到HaloPSA
/auth/authorize使用PKC。 - 用户直接通过HaloPSA进行身份验证。HaloPSA向服务器的回调发出代码。
- 服务器将代码交换为HaloPSA令牌，用AES-256-GCM对其进行加密，并将其映射到新的MCP访问令牌进行存储。
- 后续的工具调用使用存储的HaloPSA令牌。MCP客户端只能看到MCP访问令牌。
服务器支持托管的HaloPSA（需要租户标识符）和内部部署实例（ HMCP_HALO_TENANT 为空）。
从源代码构建
需要Rust 1.82或更高版本。
git clone https://github.com/bees-roadhouse/halopsa-mcp
cd halopsa-mcp
cargo build --release
二进制文件被写入 target/release/hmcp-server 和 target/release/hmcp-embedder.
发布配置文件支持LTO、二进制剥离和大小优化(opt-level = "z").
要直接构建Docker镜像：
# Server image
docker build --target server -t halopsa-mcp-server .
# Embedder image
docker build --target embedder -t halopsa-mcp-embedder .
状态
早期发展。第1阶段的脚手架已经到位（工单、动作、工作流和语义工具被删除；OAuth中继和SSE/Streamable HTTP传输已连接），但服务器尚未在实时HaloPSA实例上端到端运行。计划用于后期阶段：资产、客户、合同和发票。
许可证
麻省理工学院
