Metadata-Version: 2.5
Name: kcsc-design-mcp
Version: 0.2.1
Summary: 국가건설기준(KDS·KCS) 원문 조회와 설계 결정트리를 AI 대화창에서 바로 쓰는 MCP 서버
Project-URL: Homepage, https://github.com/lhs1152-lgtm/kcsc-design-mcp
Project-URL: Repository, https://github.com/lhs1152-lgtm/kcsc-design-mcp
Project-URL: Issues, https://github.com/lhs1152-lgtm/kcsc-design-mcp/issues
Project-URL: Changelog, https://github.com/lhs1152-lgtm/kcsc-design-mcp/blob/main/CHANGELOG.md
Author: (주)하이드로코리아
License: MIT
License-File: LICENSE
License-File: NOTICE
Keywords: kcs,kcsc,kds,korean-construction-standards,mcp,model-context-protocol,강구조,건설기준,교량,구조설계
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: Korean
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: beautifulsoup4>=4.12
Requires-Dist: mcp>=1.2.0
Requires-Dist: openpyxl>=3.1
Requires-Dist: pyyaml>=6.0
Description-Content-Type: text/markdown

# 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 가 값을 정하지 않은 자리에는 **만든 조직이 채택한 값**이 들어 있습니다.
  자기 조직 기준으로 바꿔 쓰셔야 하고, 그 판단의 책임은 쓰는 설계자에게 있습니다.
- **최종판단은 설계자가 합니다.** 교량 하중 하나가 틀리면 인명 사고입니다.

---

## 설치

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

### Claude Desktop / Claude Code

`claude_desktop_config.json` (또는 `.mcp.json`) 에 아래 한 덩어리를 넣습니다.

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

`uvx` 가 없으면 [uv](https://docs.astral.sh/uv/) 를 먼저 설치합니다. 별도 설치 과정은 없습니다.

설정 파일 위치 — Claude Desktop(Windows): `%APPDATA%\Claude\claude_desktop_config.json`,
Claude Code: 프로젝트의 `.mcp.json`. 넣은 뒤 앱을 다시 켜면 도구 14개가 잡힙니다.

### 소스에서 바로 쓰기

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

---

## 도구

### 원문

| 도구 | 하는 일 |
| --- | --- |
| `kcsc_search(query, code_type, limit)` | 기준을 **이름**으로 찾는다 (약 3,570건) |
| `kcsc_outline(code, code_type, depth)` | 목차 — 조항번호 계층 |
| `kcsc_read(code, section, code_type, max_chars)` | 절 원문 (**표 보존**) |
| `kcsc_formula(code, section, code_type, max_images)` | ★그 절의 **수식을 이미지 그대로** |
| `kcsc_grep(code, keyword, code_type, limit)` | **본문**에서 그 말이 있는 절을 찾는다 |
| `kcsc_audit(text, code)` | **계산 답변의 인용을 기계로 검증** (아래 참고) |
| `kcsc_version(code, code_type)` | 버전·개정일 (개정 여부 확인) |

### 설계 보조 — 결정트리

| 도구 | 하는 일 |
| --- | --- |
| `design_flows()` | 쓸 수 있는 트리 목록 (부재·단면·**설계법**·검증상태) |
| `design_map()` | ★트리 **이음 지도** — 어디로 이어지고 **무엇이 아직 없는지** |
| `design_flow(member, shape, method)` | 설계 흐름 + **각 단계의 근거 조항 원문을 함께 조회** |
| `design_sheet(member, shape, method)` | **빈** 단면검토 엑셀 생성 → 파일 경로 |
| `design_validate(tree_yaml \| path)` | 트리 검사 — **근거 조항이 실재하는지 API 로 확인** |
| `design_template(member, shape, method)` | 새 부재용 YAML 뼈대 |
| `design_stamp(path \| all_confirmed)` | 확정 트리에 **확정 시점 기록**(`검증일`·`검증기준`) — 기준이 개정되면 검사가 "구판으로 확정된 트리"를 잡는다 |

코드는 `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/`](https://github.com/lhs1152-lgtm/kcsc-design-mcp/tree/main/flows) 를 내려받아 `~/.kcsc-mcp/flows/` 에 넣거나,
`KCSC_FLOWS_DIR` 로 그 폴더를 가리키면 됩니다.
같은 (부재·단면·설계법)이면 **사용자 폴더가 동봉 견본을 이깁니다.**

> ★**받은 트리를 그대로 쓰지 마십시오.** KDS 가 값을 정하지 않은 자리에는
> **만든 조직이 채택한 값**(처짐 한계 L/600 · 진동수 회피대역 · 이음효율 75%/90% 등)이
> 들어 있습니다. 어느 값이 그런 것인지는 [`flows/README.md`](https://github.com/lhs1152-lgtm/kcsc-design-mcp/blob/main/flows/README.md)
> 의 표에 정리했습니다. **자기 조직 기준으로 바꿔 쓰십시오.**
>
> 트리는 **설계 근거 자료이지 검증된 설계도서가 아닙니다.** 흐름이 실무와 맞는지는
> 기계가 확인하지 못합니다. 설계자가 한 단계씩 펼쳐 보고 판단해야 합니다.

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

### ★트리는 서로 이어집니다

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

```yaml
분기:
  - {조건: "약축 휨이다",     결과: "약축 조항으로", 다음트리: "휨부재 / 약축 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)뿐 아니라
기관별 전문시방서가 함께 들어 있습니다.

| 종류 | 뜻 | 건수 |
| --- | --- | --- |
| KDS | 설계기준 | 561 |
| KCS | 표준시방서 | 769 |
| SMCS | 서울시 전문시방서 | 853 |
| LHCS | LH 전문시방서 | 544 |
| EXCS | 한국도로공사 전문시방서 | 328 |
| KRCCS | 한국철도공단 전문시방서 | 226 |
| KWCS | 한국수자원공사 전문시방서 | 189 |
| NHCS | 한국농어촌공사 전문시방서 | 76 |
| KRACS | 한국공항공사 전문시방서 | 26 |

---

## 환경변수

| 변수 | 기본값 | 뜻 |
| --- | --- | --- |
| `KCSC_API_KEY` | (필수) | KCSC OpenAPI 인증키 |
| `KCSC_HOME` | `~/.kcsc-mcp` | 캐시·결정트리·엑셀이 들어가는 곳 |
| `KCSC_FLOWS_DIR` | `~/.kcsc-mcp/flows` | 결정트리 폴더만 따로 지정 |
| `KCSC_INSECURE` | `0` | TLS 검증 우회 (아래 참고) |
| `KCSC_TIMEOUT` | `90` | 응답 대기(초) |
| `KCSC_CATALOG_TTL` | `86400` | 카탈로그 캐시 수명(초) |
| `KCSC_DOC_TTL` | `604800` | 본문 캐시 수명(초) |
| `KCSC_DOMAIN` | `교량` | **분야 기본값.** 밝히지 않았을 때 어느 계열로 볼지 |
| `KCSC_MAX_CHARS` | `20000` | 도구 한 번의 출력 상한 |

### 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`](https://github.com/lhs1152-lgtm/kcsc-design-mcp/blob/main/docs/KCSC_API.md) 에 있습니다.
판올림 내역은 [`CHANGELOG.md`](https://github.com/lhs1152-lgtm/kcsc-design-mcp/blob/main/CHANGELOG.md) 를 봅니다.

## 라이선스

| 대상 | 라이선스 |
| --- | --- |
| 코드 (`src/`) | **MIT** — [LICENSE](https://github.com/lhs1152-lgtm/kcsc-design-mcp/blob/main/LICENSE) |
| 결정트리 (`flows/`) | **CC BY-SA 4.0** — [flows/LICENSE](https://github.com/lhs1152-lgtm/kcsc-design-mcp/blob/main/flows/LICENSE). 고쳐서 배포하면 같은 조건으로 공개해야 합니다 |
| 기준 원문 | 국가건설기준센터(KCSC). 이 패키지는 **동봉하거나 재배포하지 않습니다** — 각자 자기 인증키로 조회합니다. [NOTICE](https://github.com/lhs1152-lgtm/kcsc-design-mcp/blob/main/NOTICE) |

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

## 문의

질문·버그·**트리의 조항번호 오류 제보**는 [GitHub Issues](https://github.com/lhs1152-lgtm/kcsc-design-mcp/issues) 로 주세요.
트리 오류는 「트리 오류 제보」 서식을 쓰시면 어느 단계·어느 조항인지 빠뜨리지 않고 적을 수 있습니다.
