@mindops/zapsign-mcp

Model Context Protocol 서버로, ZapSign REST API를 MCP 도구로 노출합니다. MCP를 지원하는 모든 호스트(Claude Desktop, VS Code, Cursor, 자체 SDK 앱)에 연결하면 LLM이 문서 워크플로를 구동하도록 할 수 있습니다: 문서 생성, 서명자 관리, DOCX 템플릿 작성, 배경 조회 실행, 웹훅 관리.

제공 기능

도구는 ZapSign 리소스별로 그룹화됩니다. 이 세트는 공개 REST API와 일대일로 대응하며, 각 도구는 정확히 하나의 엔드포인트를 래핑합니다.

• Documents — PDF URL / base64 / 템플릿으로 생성, 목록, 상세, 업데이트, 삭제, 표시 순서 변경, 서명 배치, oneclick, 추가 문서, 서명자 활동 로그

• Signers — 추가, 업데이트, 상세, 삭제, 일괄 서명, 거부, 사용자별 거부, 인증 시도 재설정, 알림 재전송, 확인 세부 정보, 서명자 그룹

• Templates — DOCX에서 생성, 양식 필드 업데이트, 목록, 상세, 업데이트, 삭제

• Users — 생성, 목록, 삭제, 요금제 정보

• Webhooks — 생성, 삭제(이벤트 페이로드는 API 엔드포인트가 아닌 참조 문서입니다)

• Auth (JWT) — 토큰 가져오기, 토큰 갱신(정적 API 토큰의 대안)

• Background checks — 개인/회사 조회 생성, 목록, 상세

• Timestamp — 서명된 PDF 또는 서명을 변경하지 않고 임의의 PDF에 타임스탬프 적용

• Validation — 서명된 PDF 검증

• Partner — 파트너 회사 관리, 결제 상태 업데이트, 요금제 사용량 CSV 보고서

설치

레지스트리에 게시한 후:

npm install -g @mindops/zapsign-mcp
# or run on demand with npx (no global install):
npx -y @mindops/zapsign-mcp

로컬 설치(게시 전)

cd /path/to/zapsign-mcp
npm install
npm run build
npm link            # exposes `zapsign-mcp` on $PATH globally

처음 게시하기

이 패키지는 npmjs.org의 @mindops 스코프를 대상으로 하며 restricted 액세스 권한을 사용합니다. 게시하려면:

npm login                      # authenticate against registry.npmjs.org
npm publish --access restricted   # or just `npm publish` — restricted is the publishConfig default

@mindops 조직이 npm에 아직 없다면 https://www.npmjs.com/org/create에서 먼저 만드세요.

구성

.env 파일을 만드세요(또는 MCP 호스트 구성에서 환경 변수를 설정하세요):

ZAPSIGN_API_TOKEN=your-permanent-system-user-token
ZAPSIGN_ENV=production       # or 'sandbox' for the test environment

권장 사항: 시스템 사용자 영구 토큰(ZapSign 패널의 Configurações → API → Tokens). 사용자 바인딩 토큰은 만료되어 자동화를 중단시킵니다.

MCP 호스트에서 사용

Claude Desktop / Claude Code

MCP 구성에 추가하세요(일반적으로 ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "zapsign": {
      "command": "npx",
      "args": ["-y", "@mindops/zapsign-mcp"],
      "env": {
        "ZAPSIGN_API_TOKEN": "...",
        "ZAPSIGN_ENV": "production"
      }
    }
  }
}

VS Code / Cursor

동일한 형식 — 설정의 MCP 서버 섹션에 넣으세요.

개발 중 로컬에서

npm install
npm run build
ZAPSIGN_API_TOKEN=... ZAPSIGN_ENV=sandbox node dist/index.js

서버는 stdio를 사용합니다. MCP 클라이언트에 연결하여 도구를 검사하세요.

도구 명명 규칙

• snake_case 이름은 ZapSign의 리소스 용어와 일치합니다(create_document, add_signer, delete_template 등).

• 도구 입력의 필드 이름은 ZapSign API의 철자를 유지합니다(phone_country, phone_number, auth_mode, url_pdf...). 따라서 기본 요청 본문은 API가 기대하는 것과 정확히 일치합니다.

• 경로 매개변수는 동일한 이름의 최상위 필드로 나타납니다(doc_token, signer_token, template_token).

개발

npm install
npm run typecheck
npm run build

새 엔드포인트를 추가하려면 src/tools/<resource>.ts에 정의를 만들고 npm run build를 다시 실행하세요. 각 도구는 얇은 래퍼입니다:

registerTool(server, client, {
  name: 'create_document',
  description: 'Create a new document from a public PDF URL.',
  inputSchema: z.object({ /* fields */ }),
  handler: async (input, { client }) => client.post('/docs/', input),
});

이 헬퍼는 MCP 전송을 위한 오류 봉투 형식과 JSON 문자열화를 처리합니다.

버전 관리

이 패키지는 ZapSign v1 API를 추적합니다. ZapSign은 /api/v1/ 뒤에 엔드포인트를 버전 관리합니다. v2가 출시되면 이 서버는 v1을 그 자리에서 대체하지 않고 병렬 모듈을 추가할 것입니다.

라이선스

사유(MindOps 내부용). 재배포 전에 MindOps에 문의하세요.