wfirma-mcp

wFirma MCP

非官方、只读的 wFirma API v2（api2.wfirma.pl）MCP 服务 。它为兼容 MCP 的 AI 助手提供对公司数据、发票、承包商、费用和付款的类型化只读访问权限，凭据绝不会离开你的计算机，你与 wFirma 之间也没有商业中间件。

与 wFirma 无关。“wFirma”是其各自所有者的商标。

工具（9 个，全部只读）

工具	端点
wfirma_list_companies	GET /user_companies/find
wfirma_list_invoices	GET /invoices/find
wfirma_get_invoice	GET /invoices/get/{id}
wfirma_list_contractors	GET /contractors/find
wfirma_get_contractor	GET /contractors/get/{id}
wfirma_list_expenses	GET /expenses/find
wfirma_get_expense	GET /expenses/get/{id}
wfirma_list_payments	GET /payments/find
wfirma_get_payment	GET /payments/get/{id}

每个按公司范围限定的工具都需要 wfirma_list_companies 返回的内部 companyId。波兰 NIP 不能用作公司 ID。

为什么采用只读模式

该服务有意不包含新增、编辑、删除、发送、财政认证、KSeF 或付款变更操作。根据官方文档 doc.wfirma.pl 审查后排除的类别完整列表，记录在 coverage-manifest.json 中。如果你需要写入操作，请使用 wFirma 自有工具，而不是此服务。

设置

凭据

wFirma API 密钥在你的 wFirma 面板中创建（Integrations → API）。 必需的环境变量：

• WFIRMA_ACCESS_KEY
• WFIRMA_SECRET_KEY
• WFIRMA_APP_KEY

请参阅 .env.example。切勿提交真实值。

构建

pnpm install
pnpm build      # → dist/index.js (self-contained esbuild bundle)
pnpm test       # all HTTP traffic is mocked; no live account needed

Claude Desktop / 任意 stdio MCP 客户端

{
  "mcpServers": {
    "wfirma": {
      "command": "node",
      "args": ["/absolute/path/to/wfirma-mcp/dist/index.js"],
      "env": {
        "WFIRMA_ACCESS_KEY": "your-access-key",
        "WFIRMA_SECRET_KEY": "your-secret-key",
        "WFIRMA_APP_KEY": "your-app-key"
      }
    }
  }
}

Claude Code / Cursor（范围：项目）

claude mcp add wfirma -- node /absolute/path/to/wfirma-mcp/dist/index.js

设计说明

• 除 MCP SDK 和 zod 外，没有其他运行时依赖。 客户端使用 Node 内置的 https，设置了严格的 20s 超时和有界响应大小保护。
• 故障关闭式错误分类。 凭据缺失、非数字公司 ID、响应过大和身份验证失败，都会分别触发不同的 wfirma_* 错误代码，而不是通用故障。
• 日志中不含 PII。 工具参数绝不会被记录。
• 覆盖清单。 coverage-manifest.json 将每个工具映射到其 端点、风险类别和证明它的测试；CI 测试会确保清单与源代码保持同步。

许可证

MIT