内容
# papercut-mcp
TypeScript MCP（模型上下文协议）服务器，暴露由PaperCut NG/MF XML Web服务（XML-RPC）API支持的工具。
> 状态：积极开发中。问题和拉取请求均欢迎！
## 要求
- Node.js 18+
- 已启用Web服务的PaperCut NG/MF
- 在管理员界面中设置 `auth.webservices.auth-token`
- 如果不是localhost，请在“允许的XML Web服务调用者”下添加您的调用者IP地址
## 安装
```powershell
# 在PowerShell（Windows）上
Set-Location "c:\Users\jeperez\repos\papercut-mcp"
Copy-Item .env.example .env
# 编辑.env以设置PAPERCUT_XMLRPC_URL和PAPERCUT_AUTH_TOKEN
npm install
npm run build
```
## 本地运行
```powershell
npm run start
```
服务器通过stdio（无监听端口）进行通信。它通常由MCP客户端（例如Cursor）启动。
## Cursor配置（示例）
在Cursor用户设置（JSON）中，添加类似以下内容：
```json
{
"mcpServers": {
"papercut": {
"command": "node",
"args": [
"c:\\Users\\jeperez\\repos\\papercut-mcp\\dist\\index.js"
],
"env": {
"PAPERCUT_XMLRPC_URL": "http://localhost:9191/rpc/api/xmlrpc",
"PAPERCUT_AUTH_TOKEN": "替换为您的令牌",
"PAPERCUT_TIMEOUT_MS": "10000"
}
}
}
}
```
## 可用工具
- `papercut_get_total_users`: 通过 `api.getTotalUsers` 返回用户总数。返回 `{ totalUsers }`。
- `papercut_get_user_property`: 调用 `api.getUserProperty(username, property)`。返回 `{ value }`。
- `papercut_get_user_properties`: 调用 `api.getUserProperties(username, properties[])`。返回 `{ values: { property: value } }`。
- `papercut_list_user_properties`: 返回本地记录的用户属性列表（无需服务器调用）。
- `papercut_list_printers`: 通过 `api.listPrinters(offset, limit)` 列出打印机并分页。返回 `{ printers: string[] }`，其中每个条目为 `ServerName\PrinterName`。
- `papercut_get_user_stats_total`: 使用 `api.getUserProperties` 返回用户的生命周期总计（页数，作业数）。
- `papercut_get_user_account_balance`: 通过 `api.getUserAccountBalance` 返回用户的账户余额（默认为主要账户）。
- `papercut_list_user_accounts`: 通过 `api.listUserAccounts(offset, limit)` 分页列出用户账户。
- `papercut_get_user_groups`: 通过 `api.getUserGroups(username)` 返回用户的组。
- `papercut_get_printer_property`: 通过 `api.getPrinterProperty(serverName, printerName, property)` 获取打印机属性。
- `papercut_get_group_members`: 通过 `api.getGroupMembers(groupName, offset, limit)` 分页列出组的成员。
注意：确切的属性名称和权限取决于您的安装。官方文档：https://www.papercut.com/help/manuals/ng-mf/common/tools-web-services/
## 环境变量
- `PAPERCUT_XMLRPC_URL`（例如，`http://localhost:9191/rpc/api/xmlrpc` 或 `https://<host>:9192/rpc/api/xmlrpc`）
- `PAPERCUT_AUTH_TOKEN`（必需）
- `PAPERCUT_TIMEOUT_MS`（可选，默认为 `10000`）
## 开发
```powershell
npm run dev
```
编辑 `src/` 目录中的文件。MCP工具位于 `src/tools/papercut.api.tool.ts`，XML-RPC客户端位于 `src/papercut.ts`。
