wFirma MCP

wFirma API v2 (api2.wfirma.pl)용 비공식, 읽기 전용 MCP 서버입니다. MCP 호환 AI 어시스턴트에게 회사 데이터, 인보이스, 거래처, 비용, 지급에 대한 타입이 지정된 읽기 전용 액세스를 제공합니다 — 자격 증명은 사용자의 컴퓨터를 절대 떠나지 않으며, 사용자와 wFirma 사이에 상업적 미들웨어가 없습니다.

wFirma와 제휴 관계가 아닙니다. "wFirma"는 해당 소유주의 상표입니다.

도구 (9개, 모두 읽기 전용)

모든 회사 범위 도구는 wfirma_list_companies가 반환하는 내부 companyId가 필요합니다. 폴란드 NIP는 회사 ID로 허용되지 않습니다.

Related MCP server: InvoiceNinja MCP Server

읽기 전용인 이유

이 서버는 의도적으로 추가, 편집, 삭제, 전송, fiscalization, 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 외에는 런타임 종속성이 없습니다. 클라이언트는 20초 하드 타임아웃과 응답 크기 상한 가드를 갖춘 Node의 표준 라이브러리 https를 사용합니다.

• Fail-closed 오류 분류법. 자격 증명 누락, 숫자가 아닌 회사 ID, 크기가 큰 응답, 인증 실패는 각각 일반적인 실패 대신 고유한 wfirma_* 오류 코드를 발생시킵니다.

• 로그에 PII가 없습니다. 도구 매개변수는 절대 기록되지 않습니다.

• 커버리지 매니페스트. coverage-manifest.json은 각 도구를 엔드포인트, 위험 등급, 검증 테스트에 매핑합니다. CI 테스트는 매니페스트가 소스와 동기화된 상태를 유지하도록 강제합니다.

라이선스

MIT