kcsc-design-mcp

국가건설기준(KDS·KCS 등) 원문을 AI 대화창에서 바로 꺼내 쓰는 MCP 서버.

국가건설기준센터(KCSC) OpenAPI 를 그대로 붙입니다. 자기 인증키를 넣으면 Claude Desktop·Claude Code·Cursor 등 MCP 를 쓰는 어떤 도구에서도 씁니다.

"KDS 14 31 10 의 압축부재 폭두께비 표 보여줘"
→ 표 4.2-2 를 마크다운 표 그대로 인용

⚠️ 이 도구가 하지 않는 것

구조계산을 대신하지 않습니다.

• 수식·기호(λr·Fcr 등)는 KCSC 원문이 이미지라 텍스트로 오지 않습니다. 이 도구는 그 자리를 〔그림 N〕 으로 표시하고, 식을 지어내지 않습니다.
• 식이 필요하면 kcsc_formula 로 그림을 그대로 받으세요. 진짜 기준의 진짜 식입니다. 그림을 안 보고 계산하면 그 식은 원문이 아니라 AI의 기억에서 나온 것이고, 맞을 때도 틀릴 때도 있는데 출력만 봐서는 구분되지 않습니다. → 그 경우 kcsc_audit 으로 인용을 검증하고 그 사실을 밝히세요.
• 동봉된 결정트리는 검증된 설계도서가 아닙니다. 검토 순서와 근거 조항일 뿐이고, KDS 가 값을 정하지 않은 자리에는 만든 조직이 채택한 값이 들어 있습니다. 자기 조직 기준으로 바꿔 쓰셔야 하고, 그 판단의 책임은 쓰는 설계자에게 있습니다.
• 최종판단은 설계자가 합니다. 교량 하중 하나가 틀리면 인명 사고입니다.

설치

MCP 서버를 처음 붙이시는 분도 따라 할 수 있도록 하나씩 적었습니다. 준비물은 둘뿐입니다 — 인증키와 uv.

1단계 · 인증키 받기

국가건설기준센터 https://kcsc.re.kr 에서 OpenAPI 를 신청합니다. 이 서버는 자기 키로 KCSC 에 직접 물어보는 구조라, 키가 없으면 아무것도 못 합니다. 발급까지 시간이 걸리니 먼저 신청해 두시는 편이 좋습니다.

2단계 · uv 깔기

uv 는 파이썬 도구를 알아서 내려받아 실행해 주는 프로그램입니다. 이것만 있으면 이 서버를 따로 설치하지 않아도 됩니다(uvx 가 알아서 받아 옵니다).

이미 있는지부터 확인하십시오. 판 번호가 찍히면 이 단계는 건너뜁니다.

uv --version

command not found · 'uv'은(는) ... 인식되지 않습니다 가 나오면 아래 중 하나를 고릅니다.

Windows (PowerShell 을 열고)

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

macOS · Linux (터미널에서)

curl -LsSf https://astral.sh/uv/install.sh | sh

파이썬이 이미 깔려 있다면 — 어느 환경이든 이 한 줄로도 됩니다.

pip install uv

이미 쓰는 꾸러미 관리자가 있으면 그것을 쓰셔도 됩니다 — macOS 는 brew install uv, Windows 는 winget install --id=astral-sh.uv -e.

★깔고 나면 터미널을 껐다 새로 여십시오. 설치 프로그램이 PATH 를 고치는데, 이미 열려 있던 창은 예전 PATH 를 그대로 들고 있어 방금 깐 uv 를 못 찾습니다. 새 창에서 uv --version 이 찍히면 됩니다.

uv 를 깔고 싶지 않으시면 아래 「uv 없이 쓰기」 로 가십시오. 그 길도 됩니다.

3단계 · 쓰는 도구에 등록하기

Claude Code — 명령 한 줄이면 끝납니다.

claude mcp add kcsc --env KCSC_API_KEY=발급받은_키 -- uvx kcsc-design-mcp

-- 뒤가 서버를 띄우는 명령이고, 그 앞은 Claude Code 에게 주는 옵션입니다. 잘 붙었는지는 claude mcp list 로 봅니다(✔ Connected 이면 된 것입니다).

Claude Desktop · Cursor 등 — 설정 파일에 아래 한 덩어리를 넣습니다.

{
  "mcpServers": {
    "kcsc": {
      "command": "uvx",
      "args": ["kcsc-design-mcp"],
      "env": { "KCSC_API_KEY": "발급받은_키" }
    }
  }
}

설정 파일 자리 —

파일이 없으면 새로 만들어 위 내용을 그대로 넣으시면 됩니다. 파일이 이미 있고 mcpServers 가 들어 있다면, 바깥 괄호를 또 만들지 말고 "kcsc": { ... } 한 덩어리만 그 안에 넣으십시오 — 그리고 앞 항목 끝에 쉼표를 찍으십시오. JSON 에서 제일 흔한 실수가 이 쉼표입니다(빠뜨려도, 마지막에 하나 더 붙여도 파일 전체가 무시됩니다).

4단계 · 되는지 확인

앱을 완전히 껐다 다시 켭니다(창만 닫으면 안 되고 프로그램을 끝내야 합니다). 그다음 대화창에 이렇게 물어보십시오.

KDS 14 31 10 목차 보여줘

목차가 나오면 된 것입니다. 도구 목록에는 13개가 잡힙니다.

uv 없이 쓰기

pip 만으로도 됩니다. 파이썬 3.10 이상이 필요합니다.

pip install kcsc-design-mcp

그다음 설정에서 command 를 파이썬으로 바꿉니다.

{
  "mcpServers": {
    "kcsc": {
      "command": "python",
      "args": ["-m", "kcsc_mcp"],
      "env": { "KCSC_API_KEY": "발급받은_키" }
    }
  }
}

★한 컴퓨터에 파이썬이 여러 개 깔려 있으면 python 이 엉뚱한 것을 가리켜 "모듈이 없다"는 말이 나옵니다. 그럴 때는 전체 경로를 적으십시오. 경로는 where python (Windows) · which python3 (macOS·Linux) 로 확인합니다.

소스에서 바로 쓰기 (직접 고쳐 쓰실 분)

pip install -e .
KCSC_API_KEY=발급받은_키 python -m kcsc_mcp

잘 안 될 때

도구

원문

설계 보조 — 결정트리

코드는 KDS 14 31 10 · 14 31 10 · 143110 을 다 받습니다. kcsc_grep 과 kcsc_version 은 쉼표로 여러 코드를 받습니다 — grep 은 문서를 통째로 받아 훑기 때문에 한 번에 10건까지입니다.

kcsc_formula — 수식을 이미지 그대로

KCSC 원문의 수식은 GIF 이미지입니다. alt 도 MathML 도 없어 텍스트로는 존재하지 않습니다. 인증키와 무관합니다 — 키는 접근 권한만 줍니다.

그런데 이미지 자체는 또렷합니다. 그래서 이 도구는 그림을 그대로 돌려줍니다.

kcsc_formula('KDS 14 31 10', '4.2.3')

→ 텍스트 1개 + 이미지 17개
  〔그림 2〕  Pn = Fcr·Ag                    (4.2-1)
  〔그림 6〕  Fcr = [0.658^(Fy/Fe)]·Fy       (4.2-2)
  〔그림 9〕  Fcr = 0.877·Fe                 (4.2-3)
  〔그림 11〕 Fe = π²E/(KL/r)²               (4.2-4)

번호는 kcsc_read 본문의 〔그림 N〕 과 같습니다. 본문을 읽다가 필요한 식만 골라 볼 수 있습니다.

비용은 절당 27~216 비전토큰 정도로 거의 들지 않습니다. 다만 한 절에 이미지가 71개인 곳도 있어 기본 40개까지만 보냅니다(max_images 로 조절).

※ 이미지를 읽는 것도 인식이라 첨자를 잘못 볼 수 있습니다. 다만 설계자가 같은 그림을 볼 수 있어 대조가 됩니다 — 기억으로 채운 식은 대조할 대상조차 없습니다.

kcsc_audit — 계산 답변의 인용을 기계로 검증

계산을 막는 대신 추적 가능하게 만드는 도구입니다. 계산 답변을 통째로 넣으면 안에서 기준·조항·식 번호·표 번호를 뽑아 하나씩 확인합니다.

## 인용 검증 — 6건 중 6건 확인 · 0건 실패

| 종류 | 기준 | 인용 | 확인 |
| 조항 | KDS 143110 | 4.3.2.1.1.4 | ✅ 강축 휨을 받는 기타 H형강…  ⚠️수식이미지 |
| 식   | KDS 143110 | 4.3-11      | ✅ 4.3.2.1.1.4 절에 있음 |
| 표   | KDS 143105 | 표 3.4-1    | ✅ 3.4.1 절에 있음 |

★4.3.2.1.1.4 절의 식은 원문이 이미지입니다. 도구가 읽지 못했습니다.
  → 이 계산에 쓰인 식·계수는 원문에서 온 것이 아니라 모델이 채운 것입니다.

왜 필요한가 — 실제로 있었던 일입니다. 비정형 H형강 휨강도 검토 답변이 KDS 14 31 10 4.3.2.1.1.4 를 근거로 φMn=83.8 kN·m 를 냈고, 검산해 보니 전부 맞았습니다. 그런데 그 절의 원문에는 식이 하나도 텍스트로 없었습니다. 계산에 쓴 식과 계수는 기준을 읽어서 나온 게 아니라 AI가 외운 것이었습니다.

이번엔 맞았습니다. 문제는 맞았는지 틀렸는지 출력만 봐서는 구분이 안 된다는 것입니다.

확인하지 못하는 것 (반드시 함께 읽어야 합니다)

• 식의 내용이 맞는지 — 원문이 이미지라 못 읽습니다
• 그 조항이 이 부재·이 조건에 맞는지 — 판단의 영역입니다
• 계산이 맞는지

확인되는 것은 "그 번호가 그 자리에 실재한다"는 사실뿐입니다. 그 이상으로 읽으면 이 도구가 새로운 거짓 안심을 만듭니다.

결정트리 — 35개가 함께 있습니다

설계 흐름은 코드에 박혀 있지 않고 YAML 한 장 = 부재 하나로 바깥에 있습니다.

저장소 flows/   결정트리 35개 — LRFD 18 · 한계상태 9 · 허용응력 8 (이음 118개, 끊긴 곳 0)
패키지 동봉     형식 견본 1개 — `검증: 예제` 로 박아 둠. 그대로 쓰라는 게 아님
사용자 폴더     ~/.kcsc-mcp/flows/*.yaml   ← 여기에 두면 도구가 읽는다

flows/ 를 내려받아 ~/.kcsc-mcp/flows/ 에 넣거나, KCSC_FLOWS_DIR 로 그 폴더를 가리키면 됩니다. 같은 (부재·단면·설계법)이면 사용자 폴더가 동봉 견본을 이깁니다.

★받은 트리를 그대로 쓰지 마십시오. KDS 가 값을 정하지 않은 자리에는 만든 조직이 채택한 값(처짐 한계 L/600 · 진동수 회피대역 · 이음효율 75%/90% 등)이 들어 있습니다. 어느 값이 그런 것인지는 flows/README.md 의 표에 정리했습니다. 자기 조직 기준으로 바꿔 쓰십시오.

트리는 설계 근거 자료이지 검증된 설계도서가 아닙니다. 흐름이 실무와 맞는지는 기계가 확인하지 못합니다. 설계자가 한 단계씩 펼쳐 보고 판단해야 합니다.

자기 트리를 새로 만들려면 design_template 로 뼈대를 받아 채우고, design_validate 로 검사합니다.

★트리는 서로 이어집니다

구조계산서는 트리 하나로 끝나지 않습니다. 자기 범위 끝에서 그냥 끊기면 안 되고, 다음 트리나 다음 기준으로 넘겨야 합니다.

분기:
  - {조건: "약축 휨이다",     결과: "약축 조항으로", 다음트리: "휨부재 / 약축 H형강"}
  - {조건: "블록전단 검토",   결과: "연결부 기준",   다음기준: "KDS 14 31 25  4.1.4.3"}

• 다음트리 에 설계법을 생략하면 현재 트리의 설계법을 물려받습니다 — 설계법이 다르면 다른 트리라는 원칙이 이음에서도 깨지지 않아야 하기 때문입니다.
• 가리킨 트리가 아직 없으면 "없다"고 드러냅니다. 조용히 끊지 않습니다. 그 목록이 곧 "구조계산서를 완성하려면 뭘 더 만들어야 하는가" 입니다.

design_map() 이 그 지도를 냅니다 — 어느 트리가 어디로 이어지고, 가리켰는데 없는 트리가 무엇인지까지. 동봉된 35개는 이음 118개가 전부 이어져 있어 끊긴 곳이 0 입니다. 자기 트리를 더할 때 이 지도가 "구조계산서를 완성하려면 뭘 더 만들어야 하는가" 를 알려 줍니다.

design_validate 가 잡는 것

• 스키마 누락 · 단계 식별자 중복
• 분기가 없는 단계를 가리키는 것 — 트리가 거기서 끊깁니다
• 지어낸/오타난/폐지된 조항번호 — 기준에 그 절·표가 실제로 있는지 API 로 확인합니다
• 설계법과 근거 기준의 불일치 — 아래 참고
• 확정 이후 기준 개정 — 검증기준(확정 당시 판)과 지금 판을 대조. 개정됐으면 ❌ (확정 자체가 유효하지 않을 수 있다)

트리는 사람이 쓰고, 근거가 실재하는지는 기계가 검사합니다. 지어낸 조항번호가 그대로 남는 것이 제일 위험하기 때문입니다.

★분야 기본값은 교량 입니다

건축 강구조(KDS 14 3x)와 교량(KDS 24 xx)은 기준 계열이 통째로 다릅니다. 하중조합·설계하중까지 각각 따로 있습니다.

교량   한계상태설계법  KDS 24 14 31 강교   (+ 하중조합 24 12 11 · 설계하중 24 12 21)  ← 도로교
교량   허용응력설계법  KDS 24 14 30 강교   (+ 하중조합 24 12 10 · 설계하중 24 12 20)  ← ★철도교
건축   하중저항계수설계법(LRFD)  KDS 14 31 xx
건축   허용응력설계법(ASD)       KDS 14 30 xx   ← 「하중저항계수설계법 규정이 없는 강구조」의 일반 ASD

개념으로는 LRFD 도 한계상태설계법의 하나지만, 기준 이름으로는 별개 계열입니다. 섞으면 교량 설계자에게 건축 기준을 내주게 됩니다.

★KDS 24 「일반설계법(허용응력)」 계열은 원문 1.1 이 「철도교」 기준입니다 — 24 14 30 "일반철도와 고속철도의 강교", 24 12 10/24 12 20 "철도교량". KDS 안에 도로교·보도교의 허용응력설계법 기준은 없습니다(도로교는 한계상태만). 이 도구는 그 사실을 트리에 그대로 적고, 보도교 ASD 는 부재 = KDS 14 30 xx, 하중조합·증가계수 = 24 12 10 준용(회사 결정) 으로 갑니다. 원문을 읽지 않고 24 14 30 을 "도로교 ASD" 로 쓰면 근거가 서지 않습니다.

그래서 분야를 밝히지 않으면 교량으로 봅니다.

• design_flow(..., domain='건축') — 건축구조물일 때 명시
• kcsc_search(..., domain='건축') / domain='전체' — 검색도 같은 규칙
• 검색 결과에는 분야가 표시되고, 기본 분야가 아닌 것은 뒤로 밀리며 경고가 붙습니다
• 기본값은 KCSC_DOMAIN 환경변수로 바꿉니다 (예: 건축 위주 회사면 KCSC_DOMAIN=건축)

★설계법이 다르면 트리가 다릅니다

같은 부재·같은 단면이라도 설계법이 갈리면 근거 기준 자체가 다릅니다.

한계상태설계법(LRFD)  → KDS 14 31 10  강구조 부재 설계기준 (하중저항계수설계법)
허용응력설계법(ASD)   → KDS 14 30 10  강구조 부재 설계기준(허용응력설계법)

• method 를 지정하지 않으면 어느 설계법 트리로 답했는지 머리에 표시합니다.
• 트리가 여럿이면 되묻습니다 — 임의로 고르지 않습니다.
• 없는 설계법을 요구하면 없다고 답합니다. 있는 것처럼 내주지 않습니다.

code_type 은 다음 9종입니다 — KCSC 카탈로그에는 국가기준(KDS·KCS)뿐 아니라 기관별 전문시방서가 함께 들어 있습니다.

환경변수

TLS 검증에 대해

이 서버는 TLS 를 검증합니다. 과거 일부 환경에서 KCSC 인증서 체인이 시스템 CA 번들에 없어 검증이 실패한 사례가 있습니다(2026-08-05 재확인 시점에는 정상 검증됨).

검증이 실패하면 조용히 우회하지 않고 멈추고 알립니다. 읽기 전용 공공 API 라 위험은 낮지만, 우회 여부는 쓰는 사람이 정할 일입니다. 우회하려면 KCSC_INSECURE=1 을 직접 켭니다.

알아 둘 것

• 이름 검색은 본문을 보지 못합니다. 예를 들어 "강관"은 본문 수십 개 기준에 나오지만 기준 이름에는 다섯 건뿐입니다. 본문까지 보려면 kcsc_grep 을 씁니다.
• 수식은 검색되지 않습니다. λr·Fcr 같은 기호는 원문이 이미지라 텍스트가 없습니다. kcsc_grep 으로 기호를 찾을 수 없습니다 — 말(예: "세장판")로 찾아야 합니다.
• 6자리 코드는 종류가 다르면 겹칩니다. 143110 하나가 KDS(강구조 부재 설계기준)·KCS· SMCS·EXCS·LHCS(모두 '제작')에 다 있습니다. 종류를 안 주면 국가기준(KDS→KCS)을 먼저 읽되 골랐다는 사실과 나머지 후보를 출력 머리에 반드시 표시합니다.
• 상위 분류 노드는 본문이 없습니다. KDS 100000(공통설계기준) 같은 항목은 목록용 umbrella 라 조항이 없습니다. 그렇게 안내합니다.
• 조항번호가 문서 안에서 겹칠 수 있습니다. 부록에서 번호가 1. 부터 다시 시작하는 기준(예: KCS 14 31 10)이 있어, section="1" 이 본문과 부록을 함께 낼 수 있습니다.
• 데이터를 재배포하지 않습니다. 패키지에 기준 원문을 넣지 않고, 받은 문서는 사용자 컴퓨터의 ~/.kcsc-mcp/cache 에만 둡니다.

개발 메모

API 실측 사실과 그동안 부딪힌 함정은 docs/KCSC_API.md 에 있습니다. 판올림 내역은 CHANGELOG.md 를 봅니다.

라이선스

Copyright (c) 2026 (주)하이드로코리아

문의

질문·버그·트리의 조항번호 오류 제보는 GitHub Issues 로 주세요. 트리 오류는 「트리 오류 제보」 서식을 쓰시면 어느 단계·어느 조항인지 빠뜨리지 않고 적을 수 있습니다.