pnlcs-mcp

一个用于 PNLCS（开源计费面板）的 Model Context Protocol 服务器。将 Claude Code、Claude Desktop、Cursor、VS Code 或任何其他 MCP 客户端连接到你的 PNLCS 安装，并用自然语言与之交互：

"哪些发票已逾期？" — "显示这个客户的服务和 域名。" — "今天有被标记为欺诈的订单吗？" — "为 ada@example.com 开一个关于她域名续费的工单。"

零依赖。 服务器是一个小型 Node 进程，与你已有的 PNLCS 管理 API 通信。PNLCS 端无需安装任何东西。

• npm：pnlcs-mcp

• 要求：运行 AI 客户端的机器上需安装 Node 18+

• 传输方式：stdio（由你的客户端启动——无需端口，无需托管）

1. 在 PNLCS 中创建 API 凭据

1. 登录你的 PNLCS 安装的管理后台。

2. 进入配置 → API 凭据。

3. 点击创建，给它起一个类似 mcp 的名称，然后复制它显示的两个值：

   • 标识符 — 该凭据的用户名

   • 密钥 — 仅显示一次；请将其存放在安全的地方

服务器只需要这一对凭据，通过三个环境变量传入：

Related MCP server: WHMCS MCP Server

2. 连接你的客户端

Claude Code (CLI)

一条命令：

claude mcp add pnlcs \
  --env PNLCS_URL=https://billing.example.com \
  --env PNLCS_IDENTIFIER=your_identifier \
  --env PNLCS_SECRET=your_secret \
  -- npx -y pnlcs-mcp

如果你还需要写入工具，请添加 --env PNLCS_ALLOW_WRITES=1。使用 --scope project 可通过 .mcp.json 与团队共享该条目（将密钥放在你的 shell 环境中，而不是提交的文件中）。用 claude mcp list 检查；用 claude mcp remove pnlcs 移除。

Claude Desktop

编辑 claude_desktop_config.json（macOS：~/Library/Application Support/Claude/，Windows：%APPDATA%\Claude\）：

{
  "mcpServers": {
    "pnlcs": {
      "command": "npx",
      "args": ["-y", "pnlcs-mcp"],
      "env": {
        "PNLCS_URL": "https://billing.example.com",
        "PNLCS_IDENTIFIER": "your_identifier",
        "PNLCS_SECRET": "your_secret"
      }
    }
  }
}

重启 Claude Desktop；工具会出现在锤子图标下。

Cursor

设置 → MCP → 添加新的全局 MCP 服务器，或在你的项目中创建 .cursor/mcp.json（JSON 格式与上面的 Claude Desktop 相同）。

VS Code (Copilot agent mode)

创建 .vscode/mcp.json：

{
  "servers": {
    "pnlcs": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "pnlcs-mcp"],
      "env": {
        "PNLCS_URL": "https://billing.example.com",
        "PNLCS_IDENTIFIER": "your_identifier",
        "PNLCS_SECRET": "your_secret"
      }
    }
  }
}

其他客户端（Windsurf、Cline、Zed 等）

任何能够启动 stdio 服务器的 MCP 客户端都使用相同的三部分：命令 npx、参数 ["-y", "pnlcs-mcp"] 以及上面的环境变量。从 git 检出中，node mcp/server.js 的工作方式完全相同。

3. 工具

读取工具 — 始终可用

写入工具 — 仅在设置 PNLCS_ALLOW_WRITES=1 时可用

未设置该标志时，写入工具不仅仅是隐藏——调用它们会在任何 HTTP 请求发生之前就被拒绝。一个为报表而配置的助手甚至看不到暂停按钮。只需不设置该标志，即可让报表环境保持只读。

4. 安全说明

• 密钥只会在运行 AI 客户端的机器与你的 PNLCS 安装之间传输，走的是你的管理界面所使用的同一个 HTTPS API。它绝不会发送给模型提供商；模型看到的只是工具的结果。

• 建议为 MCP 使用专用的 API 凭据，这样你可以单独撤销它。

• PNLCS 对 API 凭据进行速率限制（每个凭据每分钟 300 次请求），因此失控的代理无法冲击你的安装。

• 除非你确实希望助手对你的账目进行操作，否则请保持 PNLCS_ALLOW_WRITES 关闭；在批准会创建或更改内容的工具调用之前，请先阅读它提出的方案。

5. 故障排查

6. 测试

npm test 运行离线测试套件：它会启动真实的服务器进程，以真实协议与之通信，并对照本地桩检查每个工具的 HTTP 形态——此外还测试双向的写入门控、来自旧协议版本的批量请求、版本协商、超时和关闭排空。

node test/live.mjs 针对真实安装运行每一个工具——请将其指向演示环境，切勿指向生产账目；它会为写入工具创建命名清晰的一次性数据，并为每个工具打印一行 PASS/FAIL。

开发

本包在 PNLCS 单仓库 的 mcp/ 目录下开发；本仓库是其独立分发镜像，始终与 npm 上发布的版本保持一致。