pnlcs-mcp

Model Context Protocol 서버로, 오픈소스 결제 패널 PNLCS용입니다. Claude Code, Claude Desktop, Cursor, VS Code 또는 다른 MCP 클라이언트를 PNLCS 설치본에 연결하고 일상적인 영어로 작업하세요:

"어떤 인보이스가 연체되었나요?" — "이 고객의 서비스와 도메인을 보여주세요." — "오늘 사기로 보류된 주문이 있나요?" — "ada@example.com의 도메인 갱신에 관한 티켓을 열어주세요."

의존성 제로. 서버는 이미 보유한 PNLCS 관리자 API와 통신하는 하나의 작은 Node 프로세스입니다. 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을 추가하세요. .mcp.json을 통해 팀과 항목을 공유하려면 --scope project를 사용하세요. (비밀 키는 커밋된 파일이 아닌 셸 환경에 넣으세요). 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을 만드세요(위의 Claude Desktop과 동일한 JSON 형태).

VS Code (Copilot 에이전트 모드)

.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, args ["-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에 게시된 버전과 일치합니다.