AI 도구에서 PDComm 문서 사용하기

pdcomm-docs는 PDComm 문서를 검색하고 읽는 명령줄 도구(CLI)입니다. 같은 프로그램이 MCP(Model Context Protocol) 서버로도 동작합니다. Claude Code, Cursor 같은 AI 도구에 연결하면 AI가 PDComm 문서와 API 레퍼런스를 직접 찾아 답합니다.

pdcomm-docs는 내려받은 문서 색인을 읽습니다. 인터넷 연결이 없어도 동작합니다.

준비

오프라인 문서 묶음(bundle)을 내려받아 원하는 폴더에 압축을 풉니다. 묶음은 다음과 같이 구성됩니다.

pdcomm-docs/
├── bin/
│   └── pdcomm-docs        Windows에서는 pdcomm-docs.exe
└── site/                  오프라인 문서 사이트(index.html이 문서 홈)
    └── search-index.json  CLI와 MCP 서버가 읽는 검색 색인

bin/pdcomm-docs는 같은 묶음의 site/search-index.json을 자동으로 찾습니다. 프로그램을 다른 위치로 옮겼다면 --index 옵션으로 색인 파일을 지정합니다.

설치를 확인합니다.

pdcomm-docs --version

이 문서의 예시는 묶음을 /opt/pdcomm-docs에 풀었다고 가정합니다. Windows에서는 C:\PDComm\pdcomm-docs처럼 실제 경로로 바꿉니다.

명령줄에서 문서 검색하기

search 명령은 관련도가 높은 절(section)부터 제목, URL, 본문 일부를 보여 줍니다.

pdcomm-docs search 보유 레지스터 읽기
pdcomm-docs search "holding registers" --product modbus

검색어에 한글이 있으면 한국어 문서를, 없으면 영어 문서를 검색합니다. 언어를 직접 고르려면 --lang ko 또는 --lang en을 지정합니다. 항상 같은 언어를 쓰려면 환경 변수 PDCOMM_DOCS_LANG을 ko 또는 en으로 설정합니다.

검색 결과의 URL이나 ID로 본문을 Markdown으로 읽습니다. URL에 #으로 절을 지정하면 그 절과 하위 절만 출력합니다.

pdcomm-docs get /docs/modbus/quickstart/
pdcomm-docs get /docs/modbus/quickstart/ --lang en

자주 쓰는 명령은 다음과 같습니다.

명령	설명
`search <검색어>`	문서를 검색합니다. `--product`, `--lang`, `--limit`로 범위를 좁힙니다.
`get <URL 또는 ID>`	페이지나 절을 Markdown으로 출력합니다. `--lang`으로 다른 언어 판을 엽니다.
`api <이름 또는 패턴>`	C, C++, .NET API의 시그니처, 매개변수, 반환값을 보여 줍니다. `*`와 `?` 패턴을 지원합니다.
`list`	제품별 페이지와 절 목록을 사이드바 순서로 보여 줍니다.
`serve`	오프라인 문서 사이트를 이 컴퓨터에서 엽니다.
`mcp`	MCP 서버로 동작합니다. AI 도구가 실행합니다.

search, get, api, list 명령에 --json을 지정하면 JSON을 출력합니다. 스크립트에서 결과를 처리할 때 사용합니다. 모든 옵션, 출력 형식, 종료 코드는 pdcomm-docs 명령 레퍼런스에서 설명합니다.

pdcomm-docs api 'pdcomm_modbus_*' --surface c
pdcomm-docs list --product modbus --json

오프라인 문서 사이트 열기

serve 명령은 묶음의 site/ 폴더를 이 컴퓨터에서만 접속할 수 있는 웹 서버로 제공합니다. --open을 지정하면 브라우저도 엽니다.

pdcomm-docs serve --open

기본 주소는 http://127.0.0.1:8787/입니다. 포트가 사용 중이면 --port로 다른 포트를 지정합니다. 서버를 끝내려면 터미널에서 Ctrl+C를 누릅니다.

AI 도구에 MCP 서버 연결하기

MCP 서버는 다음 도구(tool)를 제공합니다. 모든 도구는 문서를 읽기만 하며 파일이나 장비를 바꾸지 않습니다.

도구	하는 일
`docs_search`	한국어나 영어로 문서를 검색하고 URL과 본문 일부를 돌려줍니다.
`docs_get_page`	페이지나 절을 Markdown으로 돌려줍니다. 긴 페이지는 나누어 읽습니다.
`docs_api_lookup`	API 심볼을 이름이나 패턴으로 찾아 시그니처와 설명을 돌려줍니다.
`docs_list_sections`	제품별 페이지와 절 목록을 돌려줍니다.

각 페이지는 pdcomm-docs://ko/docs/modbus/quickstart 형식의 리소스(resource)로도 제공됩니다.

터미널에서 서버를 등록합니다.

claude mcp add --transport stdio pdcomm-docs -- /opt/pdcomm-docs/bin/pdcomm-docs mcp

기본 범위(scope)는 현재 프로젝트에서 나만 쓰는 local입니다. 모든 프로젝트에서 쓰려면 --scope user를, 저장소의 .mcp.json에 기록해 팀과 공유하려면 --scope project를 지정합니다. .mcp.json에 직접 쓸 수도 있습니다.

{
  "mcpServers": {
    "pdcomm-docs": {
      "type": "stdio",
      "command": "/opt/pdcomm-docs/bin/pdcomm-docs",
      "args": ["mcp"],
      "env": { "PDCOMM_DOCS_LANG": "ko" }
    }
  }
}

claude mcp list를 실행하거나 세션에서 /mcp를 입력해 연결 상태를 확인합니다.

모든 프로젝트에서 쓰려면 ~/.cursor/mcp.json에, 한 프로젝트에서만 쓰려면 프로젝트의 .cursor/mcp.json에 다음 내용을 추가합니다.

{
  "mcpServers": {
    "pdcomm-docs": {
      "type": "stdio",
      "command": "/opt/pdcomm-docs/bin/pdcomm-docs",
      "args": ["mcp"],
      "env": { "PDCOMM_DOCS_LANG": "ko" }
    }
  }
}

Cursor 설정의 MCP 화면에서 pdcomm-docs가 켜져 있는지 확인합니다.

stdio 전송을 지원하는 MCP 클라이언트라면 모두 연결할 수 있습니다. 명령은 pdcomm-docs, 인수는 mcp입니다. 대부분의 클라이언트는 다음 형식을 사용합니다.

{
  "mcpServers": {
    "pdcomm-docs": {
      "command": "/opt/pdcomm-docs/bin/pdcomm-docs",
      "args": ["mcp", "--index", "/opt/pdcomm-docs/site/search-index.json"]
    }
  }
}

--index는 프로그램을 묶음 밖으로 옮겼을 때만 필요합니다. 서버는 표준 입출력(stdio)으로 줄 단위 JSON-RPC 메시지를 주고받으며 프로토콜 버전 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05를 지원합니다.

Windows에서는 JSON 경로의 역슬래시를 두 번 씁니다. 예를 들어 "command": "C:\\PDComm\\pdcomm-docs\\bin\\pdcomm-docs.exe"처럼 씁니다.

연결한 뒤 AI 도구에 “PDComm Modbus 빠른 시작에서 연결하는 방법을 알려 줘”처럼 질문합니다. AI 도구가 docs_search와 docs_get_page를 호출해 문서를 근거로 답합니다.

문제 해결

no search index found 오류가 납니다. 프로그램이 묶음의 bin/ 폴더 밖에 있습니다. --index로 search-index.json을 지정하거나 환경 변수 PDCOMM_DOCS_INDEX를 설정합니다.

AI 도구가 서버에 연결하지 못합니다. 설정의 command가 실제 실행 파일의 절대 경로인지 확인합니다. 터미널에서 pdcomm-docs search test를 실행해 오류 메시지를 확인합니다. MCP 서버는 표준 출력을 프로토콜 메시지에만 사용하고 오류는 표준 오류로 출력합니다.

검색 결과가 다른 언어로 나옵니다. --lang을 지정하거나 MCP 설정의 env에 PDCOMM_DOCS_LANG을 추가합니다.

AI 도구에서 PDComm 문서 사용하기

준비

명령줄에서 문서 검색하기

오프라인 문서 사이트 열기

AI 도구에 MCP 서버 연결하기

최신 온라인 색인 사용하기

문제 해결