Helpdesk MCP Server

IT帮助台代理

用于管理IT帮助台服务和服务请求的MCP（模型上下文协议）服务器应用程序。此应用程序提供了一个REST API，用于跟踪IT设备/服务库存和管理员工的服务请求。

🚀 特性

• 服务管理：跟踪IT服务/设备的数量
• 服务请求管理：处理员工对IT服务的请求
• 数据库集成：带有SQLModel ORM的PostgreSQL数据库
• MCP协议：使用FastMCP构建，与AI助手无缝集成
• Docker支持：容器化应用程序，易于部署
• 现代Python：使用Python 3.13+和现代异步模式构建

📋 API终点

该应用程序公开了以下MCP工具：

服务管理

• read_services() -获取所有可用服务
• modify_service_quantity(service_id, quantity) -更新服务库存数量

服务请求管理

• read_service_requests() -获取所有服务请求
• create_new_service_request(request) -创建新的服务请求
• modify_service_request_status(request_id, status) -更新请求状态

🏗️ 建筑

数据库模型

服务模式：

• id：主键
• name：服务名称（索引，最多100个字符）
• description：可选服务描述（最多500个字符）
• quantity：可用数量（≥0）
• created_at, updated_at：时间戳

服务请求模型：

• id：主键
• service_id：服务的外键
• requester_name：请求者姓名（最多100个字符）
• request_date：提出请求时
• status：枚举(pending, approved, returned)
• created_at, updated_at：时间戳

项目结构

├── server/
│   ├── main.py              # MCP server entry point
│   ├── config.py            # Configuration settings
│   ├── models/              # SQLModel database models
│   │   ├── service.py
│   │   └── service_request.py
│   ├── schemas/             # Pydantic schemas for API
│   │   ├── service.py
│   │   └── service_request.py
│   ├── crud/                # Database operations
│   │   ├── service.py
│   │   └── service_request.py
│   └── db/
│       └── init_db.py       # Database initialization
├── Dockerfile               # Multi-stage Docker build
├── compose.yaml             # Docker Compose configuration
├── pyproject.toml           # UV package management
└── requirements.txt         # Python dependencies

🐳 Docker入门

先决条件

• Docker和Docker Compose
• PostgreSQL数据库

环境设置

1. 创建一个 .env 项目根目录中的文件：

POSTGRES_DATABASE_URL=postgresql://username:password@localhost:5432/helpdesk_db

运行应用程序

1. 使用Docker Compose（推荐）：

docker-compose up --build

1. 直接使用Docker：

# Build the image
docker build -t it-helpdesk-agent .

# Run the container
docker run -p 8000:8000 --env-file .env it-helpdesk-agent

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

🛠️ 开发设置

本地先决条件

• Python 3.13+
• 紫外线 包管理器
• PostgreSQL数据库

地方发展

1. 使用uv安装依赖项：

uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -r requirements.txt

1. 设置环境变量：

export POSTGRES_DATABASE_URL="postgresql://username:password@localhost:5432/helpdesk_db"

1. 运行服务器：

python -m server.main --port 8000

📦 依赖项

UV管理的关键依赖关系：

• FastMCP：MCP服务器框架
• SQL模型：Python的现代SQL工具包
• 快速 API：高性能web框架
• asyncpg/psycopg2：PostgreSQL驱动程序
• 优维康：用于生产的ASGI服务器

🔧 配置

应用程序使用环境变量进行配置：

🚀 部署

生产部署

1. 设置PostgreSQL数据库
2. 配置环境变量
3. 使用Docker Compose进行部署：

docker-compose up -d --build

健康检查

应用程序自动：

• 启动时创建数据库表
• 验证数据库连接
• 提供结构化错误响应

📝 使用示例

创建服务请求

# Example service request payload
{
    "service_id": 1,
    "requester_name": "John Doe",
    "status": "pending"
}

更新服务数量

# Example quantity update
{
    "quantity": 50
}

🤝 贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 彻底测试
5. 提交拉取请求

📄 许可证

该项目根据MIT许可证获得许可。

🆘 支持

有关支持和问题：

• 检查文档
• 查看中的API架构 /server/schemas/
• 检查中的模型 /server/models/

______________________________________________________________________

内置于❤️ 使用Python、FastMCP和Docker