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으로 인용을 각 검증하고 사실을 밝히십시오.

• 만들어진 Excel 파일은 빈 템플릿입니다. 계산식을 넣지 않습니다 — 원문이 이미지라 식을 알 수 없고, 모르는 식을 넣으면 그것이 사고입니다.

• 동봉된 결정트리는 검증된 설계도서가 아닙니다. 검토 순서와 근거 조항일 뿐이며, KDS가 값을 정하지 않은 자리에는 작성 조직이 채택한 값이 들어 있습니다. 자기 조직의 기준으로 바꿔 Use야 하며, 그 판단의 책임은 사용하는 설계자에 있습니다.

• 최종 판단은 설계자가 합니다. 교량 하중 하나가 틀린면 인명 사고입니다.

Related MCP server: KJH Law MCP

설치

인증키가 우선 필요합니다 — 국가건설기준센터 https://kcsc.re.kr 에서 OpenAPI를 신청합니다.

Claude Desktop / Claude Code

claude_desktop_config.json(확장자 .mcp.json)에 아래 한 덩어리를 넣습니다.

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

uvx 가 없하면 uv 를 먼저 설치합니다. 별도 처리 절차는 없습니다.

설정 파일 위치 — Claude Desktop(Windows): %APPDATA%\Claude\claude_desktop_config.json, Claude Code: 프로젝트 의 .mcp.json. 넣은 뒤 재시작하면 도구 14개가 준비됩니다.

소스에서 바로 쓰기

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가 기억한 것입니다.

이번에는 정확했습니다. 문제는 맞았는지 틀렸는지 출력만으로는 구분되지 않는다는 점입니다.

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

• 식의 내용이 정확한지 — 원문이 이미지가 아니므로 읽지 못합니다

• 해당 조항 기능이 이 부재·이 조건에 맞는지 — 판단의 영역입니다

• 계산이 맞는지

확인되는 것은 "그 번호가 그 곳에 실제로 존재한다는 것"뿐입니다. 더 읽어버리면 이 도구가 새롭게 거짓된 안심을 만들어냅니다.

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

설계 흐름은 코드에 고정되어 있지 않고 YAML 한 장 = 부재 하나로 외부에 있습니다.

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

flows/ 를 내려받아 ~/.kcsc-mcp/flows/ 에 넣거나 KCSC_FLOWS_DIR 로 그 폴더를 가리키면 됩니다. (element·단면·설계役) 같으면 사용자 폴더가 동봉 샘플에 우선합니다.

★받은 트리를 그대로 사용하지 마십시오. KDS가 값을 정하지 않은 부분에는 만든 조직이 채택한 값(휨 한도 L/600 · 주파수 회피 대역 · 접합 효율 75%/90% 등)이 들어 있습니다. 어떤 값이 그러한지 [flows/README.md](https://github.com/lhs1152-lgtm/ko draft-design-mcp/blob/main/flows/README.md) 의 표에 정리했습니다. 자기 조직 기준으로 바꿔 사용하십시오.

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

자기 도구를 새로 만들려면 design_template 로 뼈대를 확보해 채우고, design_validate 로 검증합니다.

★트리는 서로 이어집니다

구조계산서는 트리 하나로 끝나지 않습니다. 자신의 범위가 끝나면 거기서 끊지 않고, 다음 트리 또는 다음 기준으로 넘어가야 합니다.

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

• 다음트리 에 설계 방법을 생략하면 현재 트리의 설계법을 상속받습니다 — 설계법이 다르면 다른 트리라는 원리가 이음에서도 무너지지 않아야 하기 때문입니다.

• 지정한 트리가 아직 없으면 "없다"고 표시합니다. 조용히 끊어버리지 않습니다. 그 목록이 즉 "구조계산서를 완성하려면 무엇을 더 만들어야 하는가" 입니다.

design_mark() 가 그 지도를 만듭니다 — 어느 트리가 어디로 이어지고, 지정했지만 존재하지 않는 트리까 까지. 동봉된 23개 중에서 이어짐 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 를 직접 켜십시오.

알아 둘 것

• 이름 검색은 본문을 보지 않습니다. 예를 들어 "강관"은 본문에 수 10건 이상 있지만 기준 이름에는 몇 싸저 있습니다. 본문까지 찾으려면 kcsc_grep를 사용합니다.

• 수식은 검색할 수 없습니다. λr·Fcr 등의 기호는 원문이 이미지이므로 텍스트로 존재하지 않습니다. ${kcsc_grep} 로 기호를 검색할 수 없습니다 — **말(예: "세장판")**로 찾아야 합니다.

• 여섯 자리 코드는 유형이 다르면 겹칩니다. 143110 을 KDS(강구조 부재 설계기준)·KCS·SMCS·EXCS·LHCS (모두 "제작") 에 지정할 수 있습니다. 유형이 지정되지 않으면 국가기준(KDS→KCS)을 먼저 읽습니다. 단 선택한 전체 루션과 나머지 후보를 출력 위쪽에 반드시 표시.

• 카탈로그 분류 node 는 본문이 없습니다. KDS 100000과 같은 항목은 목록 전용 umbrella 노드므로 절차가 없습니다. 그렇게 설명되어 있습니다.

• 조위 번호가 문서 안에서 경합할 수 있습니다. 부록에서 번호가 다시 시작하는 기준(KCS 14 31 10 등)이 있어 section="1" 이 본문과 부록 양쪽에 나올 수 있습니다.

• 데이터를 재배포하지 않습니다. 패키지에 원문을 포함하지 않고, 취득한 문서는 사용자 컴퓨터의 ~/.kcsc-mcp/cache 에만 저장합니다.

개발 메모

API를 직접 조사한 사실과 그동안 접한 전개점은 docs/KCSC_API.md 에 정리되어 있습니다. 변경 내역은 CHANGELOG.md 를 확인하세요.

라이선스

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

문의

질문·버그·트리의 조항번호 잘못으로 보고에 대해서 GitHub Issues 로 보내시기 바랍니다. 트리의 오류는 「트리 오류 제출」 폼을 사용하면 어느 단계·어느 조건인지 빠뜨 없이 쓸 수 있습니다.