Konnect 딥다이브
— AI의 한마디를 안전한 회로 편집으로 바꾸는 Rust

1프로젝트 한줄 요약

Konnect는 AI가 보낸 구조화된 요청을 받아 KiCad 프로젝트를 읽고, 편집하고, 검사하는 도구 서버입니다. 사용자가 “저항을 추가하고 두 핀을 연결해 줘”라고 말하면 AI가 필요한 도구와 인자를 고르고, Konnect가 그 요청을 실제 파일 조작이나 KiCad 명령으로 옮깁니다.

AI가 무엇을 할지 결정하더라도, 무엇을 실제로 바꿔도 되는지는 실행 프로그램이 다시 확인해야 합니다. 이 경계를 배우는 것이 이 저장소를 읽는 가장 좋은 이유입니다. AI의 문장 생성 능력과 회로 편집의 정확성은 서로 다른 문제이기 때문입니다.

1-1. 한 번의 요청이 도달하는 세 갈래

일부 PCB 작업에는 닫힌 보드 파일을 직접 편집하는 대체 경로도 있습니다. 다만 실시간 통신이 실패했다고 항상 파일을 수정하는 것은 아닙니다. 이 구분은 4절에서 가장 중요하게 다룹니다.

1-2. 도구 호출은 이런 모양이다

다음은 sch_components 도구 묶음을 불러온 뒤 사용할 수 있는 요청 예입니다. JSON의 필드 이름은 crates/konnect-core/src/tools/sch_components.rs의 입력 스키마에 대응합니다. 경로는 실제 설계 파일을 가리켜야 합니다.

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "add_schematic_component",
    "arguments": {
      "schematic": "/designs/blink/blink.kicad_sch",
      "lib_id": "Device:R",
      "x": 100.0,
      "y": 80.0,
      "reference": "R1",
      "value": "10k"
    }
  }
}

lib_id는 부품 기호의 라이브러리 식별자이고, 좌표는 회로도 기준 mm입니다. 도구 설명에는 1.27 mm 격자로 맞춘다고 적혀 있습니다. “저항 하나”라는 자연어도 실행 단계에서는 파일, 종류, 위치, 참조명이라는 구체적인 데이터로 바뀝니다.

2왜 주목받는가

2026-10-23의 GitHub Trending Rust Weekly #4로 선정된 프로젝트입니다. 같은 날 GitHub 기준 스타 1,375개, 포크 165개입니다. 아래의 관심 요인은 README와 설계 구조에 근거한 해석입니다. 스타 증가의 원인을 분석한 통계나 사용자 조사 결과로 읽어서는 안 됩니다.

2-1. 대화형 AI가 물리적인 설계 작업으로 이어진다

텍스트 편집을 넘어 부품 배치, 배선, 전기 규칙 검사, 제조용 출력까지 도구화합니다. crates/konnect-core/src/tools/sch_wiring.rs, crates/konnect-core/src/tools/pcb_routing.rs, crates/konnect-core/src/tools/manufacturing.rs를 나란히 보면 하나의 설계가 여러 단계의 산출물을 거친다는 점이 드러납니다. 이 경로들의 공통 상위 디렉토리는 crates/konnect-core/src/입니다.

관심을 끄는 지점은 대화창 자체보다, 대화의 결과가 검증 가능한 설계 변경으로 연결되는 과정입니다. 초보 개발자는 여기서 “AI 기능 추가”가 실제로는 기존 소프트웨어의 입력·출력·실패 조건을 정리하는 작업임을 배울 수 있습니다.

2-2. 앞선 구현에서 겪은 문제를 Rust 구조로 다시 푼다

README는 이 프로젝트를 KiCAD-MCP-Server의 후속 프로젝트라고 설명합니다. 전작의 TypeScript → Python 자식 프로세스 → SWIG 바인딩 경로를 줄이는 것이 재구현의 동기입니다. 전작의 구성과 유지 상태에 관한 설명은 Konnect README 기준이며, 아래 표는 성능 벤치마크가 아닙니다.

장점은 배포 대상과 오류 경계를 줄일 수 있다는 점입니다. 다만 README의 “도구 호출은 함수 호출”은 서버 내부 경로에 관한 설명입니다. KiCad IPC, kicad-cli, 선택적인 외부 라우터까지 한 프로세스로 합쳐졌다는 뜻은 아닙니다.

2-3. 도구가 많아질 때의 AI 사용 비용을 설계한다

모든 도구 설명을 매번 AI에게 전달하면 대화 문맥을 많이 차지합니다. Konnect는 project와 config만 먼저 활성화하고 필요한 묶음을 나중에 추가합니다. README는 기본 목록 약 2K 토큰, 전체 목록 약 23K 토큰으로 설명합니다. 이 수치는 문서의 추정치이며 실제 토크나이저나 클라이언트별 측정값은 아닙니다.

2-4. 소개의 숫자와 실제 범위를 구분하자

도구 개수만으로 프로젝트의 완성도를 판단하기는 어렵습니다. 같은 저장소에서도 소개 문구와 등록부의 갱신 시점이 다를 수 있습니다. 학습할 때는 실제 도구 정의와 입력 스키마를 확인하는 습관이 더 유용합니다.

3기술 스택 전체 지도

루트 Cargo.toml의 워크스페이스에는 7개 crates/ 패키지와 xtask, 총 8개 멤버가 있습니다. Tauri 뷰어는 명시적으로 제외되어 별도로 빌드됩니다. 같은 저장소에 있다는 사실과 같은 실행 파일에 포함된다는 사실은 구분해서 읽어야 합니다.

아래 “선언”은 의존성 파일에 적힌 허용 범위이고, “잠금”은 해당 커밋의 Cargo.lock에 기록된 선택 버전입니다. 예를 들어 tokio = "1"은 정확히 1.0.0을 고정한다는 뜻이 아닙니다.

3-1. 백엔드: Rust가 맡는 실행·데이터 계층

이 표의 의존성 선언은 루트 Cargo.toml과 각 패키지의 Cargo.toml에서 확인할 수 있습니다. konnect-core가 도메인 기능을 조립하고, konnect가 설정·실행·통신 방식을 담당합니다.

3-2. 프론트엔드: 서버와 분리된 Tauri 뷰어

이 뷰어는 브라우저 기반 SaaS 대시보드가 아닙니다. 이 커밋에는 package.json, pyproject.toml, go.mod, Dockerfile이 없으며, 뷰어에 React나 TypeScript 빌드 파이프라인도 없습니다. 화면 기능의 학습 범위를 실제 코드에 맞추어 잡을 수 있습니다.

3-3. 플러그인과 인프라·빌드

.github/workflows/ci.yml은 protoc@3.23.4 설치와 Python 플러그인 테스트용 3.11을 명시합니다. 패키징 검사는 Python 3.12를 사용합니다. CI의 버전은 검증 환경의 기록이며 모든 사용자에게 그 Python 버전을 별도 설치하라는 뜻은 아닙니다.

4아키텍처 심화 분석

4-1. 먼저 전체 요청 경로를 그려 보자

핵심 처리는 crates/konnect-core/src/mcp/handler.rs에 있습니다. handle_message()가 JSON을 요청 자료형으로 바꾸고, dispatch()가 MCP 메서드를 나눕니다. execute_tool()은 호출 시간과 결과 상태를 기록하고, dispatch_tool()이 관리 도구·업무 도구·오류를 구분합니다.

통신 성공, 명령 접수, 설계 변경 완료는 서로 다른 상태이므로 각각의 경계에서 확인해야 합니다. 이 한 문장을 기억하면 아래의 복잡한 코드가 왜 필요한지 이해하기 쉽습니다.

패턴 ① 어댑터 분리: 통신 방식과 업무 로직을 떼어 낸다

crates/konnect/src/main.rs는 설정을 읽고 McpHandler를 만든 뒤 Stdio·Http·Both 중 하나를 선택합니다. 표준 입출력과 HTTP는 같은 handle_message()를 호출합니다. 업무 도구는 요청이 어느 통로로 들어왔는지 몰라도 됩니다.

이를 어댑터 관점으로 읽어 보세요. 표준 입출력 어댑터는 줄 단위 JSON을 읽고 응답에 줄바꿈을 붙입니다. HTTP 어댑터는 같은 JSON 결과를 HTTP 응답으로 감쌉니다. 형식 변환은 바깥쪽에, 부품을 옮기는 규칙은 안쪽에 둡니다.

crates/konnect-core/src/tools/mod.rs의 tool! 매크로는 비동기 핸들러를 공통 타입으로 감싸 ToolDef::new()에 넣습니다. 그 생성자는 스키마의 허용 필드를 정리하고 검증기를 한 번 컴파일합니다. dispatch_tool()은 필수 인자와 스키마를 검사한 다음에 핸들러를 호출합니다.

// ToolDef의 중요한 필드만 보여 주는 학습용 축약
struct ToolDef {
    name: &'static str,
    input_schema: Value,
    input_validator: Arc<jsonschema::Validator>,
    handler: ToolHandlerFn,
    board_access: BoardAccess,
}

// 개념적 실행 순서: 실제 오류 응답 코드는 생략
validate_required_fields(&tool.input_schema, &args)?;
tool.input_validator.validate(&args)?;
(tool.handler)(&args, context).await

이 예에서 보조 함수 이름은 흐름을 설명하기 위한 것입니다. 실제 필수 인자 검사 함수는 first_missing_required()입니다. 광고한 스키마와 실행할 때의 검증기를 같은 정의에서 만들면 문서와 동작이 어긋날 가능성을 줄일 수 있습니다.

패턴 ② 필요한 기능부터 공개: 카탈로그와 활성 상태를 분리한다

crates/konnect-core/src/router/registry.rs의 ALL_TOOLSETS는 전체 공구함 목록이고, STARTER_KIT는 ["project", "config"]입니다. ToolRouter는 전체 등록부와 현재 활성 도구를 따로 관리합니다. 활성 묶음은 HashSet, 이름별 도구는 HashMap에 담습니다.

ToolRouter::load()는 해당 묶음의 정의를 활성 맵에 넣습니다. 카탈로그는 OnceLock으로 한 번 만들고, 검증기는 Arc로 공유합니다. “나중에 불러오기”는 여기서 주로 AI에게 공개하는 목록을 확장하는 것이지, 매번 별도 플러그인 파일을 내려받거나 동적 라이브러리를 여는 것은 아닙니다.

// MCP 도구 호출의 인자 부분 예: 배선 도구 묶음 공개 요청
{
  "name": "load_toolset",
  "arguments": { "name": "sch_wiring" }
}

// 서버가 목록 갱신을 알리는 메서드
notifications/tools/list_changed

McpHandler::notify_tools_list_changed()는 HTTP의 SSE 수신자와 표준 입출력의 알림 채널 양쪽으로 변경을 전달합니다. 클라이언트가 목록을 다시 읽어야 새 입력 스키마를 알 수 있으므로, 서버 안에서 도구를 활성화하는 것만으로는 충분하지 않습니다.

McpHandler::adapt_to_client()는 이름이 claude-ai로 시작하는 클라이언트를 목록 캐시 예외로 취급하여 처음부터 전체 묶음을 활성화합니다. 모든 클라이언트가 동적 목록을 잘 지원한다고 가정하지 않는, 실제 호환성 설계의 사례입니다.

패턴 ③ 변경 전제를 확인하는 파일 저장

회로도 계층에는 서로 다른 두 표현이 있습니다. crates/konnect-sexp/src/parser.rs의 SexpNode는 읽기용 구문 트리이고, 같은 패키지의 crates/konnect-sexp/src/writer.rs는 지정한 문자열 구간만 고칩니다. 한편 crates/konnect-schematic-editor/src/schematic/mod.rs는 Schematic·Symbol 같은 타입으로 편집하고 다시 직렬화합니다.

crates/konnect-core/src/tools/sch_components.rs의 일반 CRUD는 타입 기반 편집기를 사용하며 핀 좌표 계산 등에는 konnect-sexp 기능을 함께 씁니다. 따라서 “모든 쓰기가 문자열 치환이다” 또는 “모든 편집이 파일 전체의 바이트를 보존한다”고 설명하면 틀립니다.

부분 편집에서 중요한 구현은 apply_edits()의 뒤쪽 바이트 위치부터 적용하는 정렬입니다. 앞에서 긴 문자열을 삽입하면 뒤쪽 위치가 밀리지만, 뒤에서 고치면 앞쪽 기준 위치는 유지되기 때문입니다.

// crates/konnect-sexp/src/writer.rs의 실제 구현
pub fn apply_edits(mut content: String, mut edits: Vec<SexpEdit>) -> String {
    edits.sort_by_key(|e| std::cmp::Reverse(e.start));
    for edit in edits {
        assert!(edit.start <= edit.end, "Edit start > end");
        assert!(edit.end <= content.len(), "Edit end out of bounds");
        content.replace_range(edit.start..edit.end, &edit.replacement);
    }
    content
}

이 함수의 인덱스는 글자 번호가 아니라 바이트 위치입니다. UTF-8 문자의 중간을 잘라서는 안 되며, 겹치는 편집 구간의 타당성도 호출 쪽에서 보장해야 합니다. 정렬 하나가 모든 입력을 안전하게 만들어 주지는 않습니다.

여러 파일의 트랜잭션은 운영체제가 모든 파일을 동시에 바꾸는 기능이 아닙니다. recover_file_transactions()는 이미 새 내용인 파일은 두고, 이전 내용인 파일은 변경을 마저 적용합니다. 예상 밖으로 달라진 내용은 덮어쓰지 않고 충돌로 남깁니다. 즉 재시작 후 앞으로 복구할 수 있는 저널 방식입니다.

패턴 ④ 실행 상태의 권위: 열린 보드와 저장 파일을 혼동하지 않는다

열린 KiCad 보드에는 아직 저장하지 않은 변경이 있을 수 있습니다. 통신 장애를 “KiCad가 없다”고 단정하고 디스크 파일을 편집하면 화면과 파일이 서로 다른 설계가 됩니다. crates/konnect-core/src/tools/board_session.rs의 BoardSessionMemory는 보드를 실시간으로 관찰한 사실을 기억합니다.

실제 IPC 구현의 KiCadIpcClient::run_commit()은 begin_commit()으로 변경 묶음을 열고 작업 성공 시 push_commit()으로 반영하며, 확인된 실패에는 drop_commit()을 시도합니다. 다만 IpcOutcomeUnknown처럼 반영 여부가 불확실하면 취소 요청도 보내지 않으며, LateReply는 별도의 복구 경로를 거칩니다. 이 묶음은 KiCad의 되돌리기 단위와 연결됩니다. 마지막 응답을 받지 못한 경우처럼 반영 여부가 모호한 상황은 일반적인 사전 거부와 구별해야 합니다.

crates/konnect-core/src/outcome.rs에는 complete·partial·failed·uncertain 상태가 있습니다. 이 공통 결과 형식을 채택한 도구는 해당 커밋에서 4개로 한정됩니다. 저장소 전체의 모든 도구가 이미 동일한 결과 계약을 갖는다고 일반화해서는 안 됩니다.

5디렉토리 구조 해부

폴더 이름을 외우기보다 요청 한 개가 통과하는 파일을 연결하면 큰 저장소도 읽을 수 있습니다. 처음부터 모든 도구 구현을 읽으려 하면 비슷한 JSON 스키마와 긴 테스트에 묻히기 쉽습니다.

5-1. 실제 줄 수로 보는 무게중심

커밋 9488e5f에서 Git이 추적하는 파일의 물리적 줄 수입니다. 빈 줄·주석·단위 테스트·통합 테스트를 모두 포함하며, 빌드 산출물은 포함하지 않습니다. 줄 수는 실행 성능이나 구현 품질의 점수가 아니라 읽을 범위를 가늠하는 지표입니다.

Rust 중 konnect-core가 124,553줄, konnect-ipc가 16,517줄, konnect-sexp가 12,474줄입니다. 기능 구현과 실패 재현 테스트가 업무 계층에 집중되어 있습니다. 반면 konnect-vcs는 84줄의 기반 코드이므로 완성된 버전 관리 제품처럼 설명하면 안 됩니다.

# 저장소 루트에서 읽기만 하며 Rust 물리적 줄 수 재기
git ls-files -z '*.rs' | python3 -c '
import sys
from pathlib import Path
paths = [p for p in sys.stdin.buffer.read().split(b"\0") if p]
print(sum(len(Path(p.decode()).read_bytes().splitlines()) for p in paths))
'

이 방식은 인라인 테스트를 “구현 코드”와 자동으로 나누지 않습니다. 테스트 비중을 알고 싶다면 파일명뿐 아니라 #[cfg(test)] 내부까지 분석해야 합니다. 여기서는 전체 물리적 줄 수라는 일관된 기준만 사용합니다.

6학습 포인트 (기술별)

기술을 배웠다는 기준은 코드를 따라 쓰는 것이 아니라, 실패 사례를 하나 더 설명할 수 있게 되는 것입니다. 다음 여섯 주제는 각각 작은 읽기 과제와 독립적인 실습으로 확장할 수 있습니다.

6-1. Rust: 데이터를 함께 쓰는 비용을 드러내는 타입

McpHandler는 Arc<ToolContext>를 공유합니다. ToolRouter는 RwLock<HashMap<String, ToolDef>>로 활성 도구 맵을 보호합니다. ToolDef를 복제해도 컴파일한 검증기는 Arc로 공유하므로 검증기를 매 호출마다 새로 만드는 구조가 아닙니다.

배울 것: 소유권과 복사 비용, 읽기·쓰기 잠금의 차이, 트레이트 객체로 서로 다른 비동기 함수를 같은 칸에 담는 방법입니다. ToolHandlerFn의 Pin<Box<dyn Future...>>는 비동기 계산을 공통 반환 타입으로 감싸기 위한 표현부터 이해하면 됩니다.

6-2. 비동기: 오래 기다리는 코드의 위치를 정한다

NNG 클라이언트는 동기식 API를 사용합니다. crates/konnect-core/src/tools/mod.rs::with_ipc_classified()는 이 일을 tokio::task::spawn_blocking()으로 보내 비동기 실행 스레드에서 직접 오래 기다리는 일을 줄입니다. 반면 kicad-cli는 Tokio의 자식 프로세스 API로 기다립니다.

crates/konnect-ipc/src/client.rs에는 기본 명령 수신 대기 30초, 송신 대기 5초, 층 이름 조회 전체 대기 예산 10초가 있습니다. 도구마다 필요한 제한이 다르며, 여러 작은 조회가 누적되면 전체 지연은 커집니다.

실습 아이디어: “요청 전에 연결 실패”, “명령을 보낸 뒤 시간 초과”, “KiCad가 명시적으로 거부”를 세 칸으로 나누세요. 각각을 재시도해도 되는지, 어떤 상태 확인이 필요한지 적으면 비동기 문법보다 중요한 실패 모델을 익힐 수 있습니다.

6-3. 파서와 좌표: 문법이 맞아도 도메인 의미는 틀릴 수 있다

crates/konnect-sexp/src/parser.rs의 구문 트리는 Atom·Str·List의 재귀 구조입니다. 예를 들어 (at 10 5 90)은 단순한 문자열 네 조각이 아니라 위치와 방향을 나타내는 한 노드입니다. 구문 분석 뒤에는 단위와 좌표계를 해석하는 단계가 남습니다.

// 실제 SexpNode의 세 가지 경우
pub enum SexpNode {
    Atom(String),
    Str(String),
    List(Vec<SexpNode>),
}

// 기호 로컬 좌표 → 회로도 좌표의 처리 순서
Y축 방향 전환 → 회전 → 미러 → 부품 원점만큼 이동

crates/konnect-sexp/src/geometry.rs::transform_pin()은 라이브러리의 위쪽이 양수인 Y축을 화면의 아래쪽이 양수인 Y축으로 바꾼 뒤 회전합니다. 미러는 회전 뒤에 적용합니다. 순서를 바꾸면 90도·270도 배치에서 다른 핀 위치가 나올 수 있습니다.

또한 crates/konnect-sexp/src/schematic.rs::extract_lib_pins_for_unit()은 Name_N_M 형식의 하위 기호에서 공통 유닛 0과 선택한 유닛의 핀만 모읍니다. 기호 바로 아래의 핀과 이 접미사가 없는 하위 기호의 핀은 항상 포함합니다. 이름의 숫자 의미를 모르면 다른 증폭기 유닛의 핀을 같은 위치에 겹쳐 해석할 수 있습니다. 자료형의 정확성과 전자회로 의미의 정확성을 함께 살펴보세요.

6-4. 스키마와 오류: AI도 검증이 필요한 클라이언트다

add_schematic_component는 schematic·lib_id·x·y를 필수로 요구하고 unit의 최솟값을 1로 둡니다. 좌표에 문자열 "100"을 보내는 것과 숫자 100을 보내는 것은 다릅니다. 입력을 조용히 기본값으로 바꾸는 대신 잘못된 필드를 알려 주어야 AI도 올바르게 복구할 수 있습니다.

배울 것: JSON이 문법적으로 파싱되는지, 입력 스키마에 맞는지, 실제 설계에서 수행 가능한지는 서로 다른 검사입니다. 예를 들어 숫자 좌표가 유효해도 대상 기호가 존재하지 않으면 작업은 성립하지 않습니다.

실습 아이디어: 필수 키 누락, 타입 오류, 범위 오류, 존재하지 않는 라이브러리, 변경 후 검증 실패를 분리해 기대 응답을 적으세요. crates/konnect-core/src/mcp/error.rs의 구조화된 오류와 crates/konnect-core/src/outcome.rs의 수행 상태를 함께 읽으면 “오류 문구”와 “실제 변경 여부”의 차이를 볼 수 있습니다.

6-5. 화면 갱신과 재현 가능한 시각 비교

crates/schematic-viewer/src/main.rs의 QUIET_WINDOW는 600 ms입니다. drain_until_quiet()는 연속 저장 이벤트를 모으고, 600 ms의 조용한 구간과 최대 대기 기준인 5초에 따라 렌더링 시점을 정합니다. is_relevant_sch_change()는 자동 저장·잠금 이름을 걸러 내고, 계층 시트 순회는 최대 깊이 20과 조상 집합으로 순환을 막습니다.

별도의 crates/konnect-render/src/lib.rs::svg_to_png()는 화면에 표시되는 텍스트 요소가 있는 SVG를 거부하고, KiCad가 글자를 경로로 내보낸 SVG를 일정한 렌더러로 처리합니다. RENDERER_ID는 resvg-0.48.1입니다. 렌더러 버전이나 글꼴이 달라 생긴 픽셀 차이를 설계 수정으로 오인하지 않으려는 선택입니다.

실습 아이디어: 파일 이벤트가 0 ms, 200 ms, 500 ms에 왔을 때 600 ms의 조용한 구간이 언제 완성되는지 시간선을 그리세요. 마지막 이벤트 뒤 약 600 ms가 기준이므로 작업 시간 등을 제외하면 1,100 ms 무렵입니다. 첫 이벤트 직후부터 재는 방식과 구별해 보세요.

6-6. 검증 증거에 설계의 신원을 붙인다

crates/konnect-core/src/design_hash.rs::design_state_hash()는 설계 파일 경로를 정렬하고 줄바꿈을 LF로 정규화한 뒤 SHA-256을 계산합니다. 각 파일은 path\0content\0 형태로 구분해 합칩니다. Windows의 CRLF와 다른 운영체제의 LF 때문에 같은 설계를 다른 것으로 보는 일을 줄입니다.

.konnect/의 파생 상태는 설계 해시에서 제외합니다. 검사 결과가 설계 해시를 기록했는데 그 기록 때문에 설계 해시가 다시 바뀌면 순환 문제가 생기기 때문입니다. “어떤 설계에 대한 검사 결과인가”를 명확히 하는 원리는 문서 빌드·데이터 처리·AI 평가에도 적용할 수 있습니다.

7하드웨어 / 시스템 요구사항

README에는 CPU 코어 수나 RAM의 공식 최소 수치가 명시되어 있지 않습니다. 서버 바이너리만의 요구와 KiCad GUI·부품 데이터·외부 라우터를 포함한 전체 환경을 분리해 판단해야 합니다. 다음 표는 기능별 의존 조건입니다.

릴리스 워크플로에 적힌 대상은 x86_64-unknown-linux-gnu, x86_64-pc-windows-msvc, x86_64-apple-darwin, aarch64-apple-darwin입니다. 이 목록이 ARM Linux 등 모든 조합의 지원을 의미하지는 않습니다. 패키징 메타데이터는 KiCad 범위를 10.0부터 10.99로 선언합니다.

GPU는 Konnect 서버가 요구하는 구성 요소로 명시되어 있지 않습니다. 이 서버는 LLM 가중치를 로컬에 올리는 추론 서버가 아닙니다. 로컬 모델을 연결하면 그 모델의 하드웨어 요구가 별도로 생기며, KiCad의 큰 보드·3D 작업도 설계 크기에 따라 자원을 사용합니다.

7-1. 설정 한 항목이 실제로 무엇을 바꾸는가

# 설정 형식을 이해하기 위한 예
transport = "stdio"
kicad_cli = "kicad-cli"
auto_load_toolsets = false
eager_toolsets = false

# transport를 "http" 또는 "both"로 바꿀 때 쓰는 기본 주소
http_address = "127.0.0.1:3000"

crates/konnect/src/config.rs::default_config_paths()는 현재 디렉토리의 konnect.toml, settings.json, 실행 파일 주변 설정, 사용자 설정 순으로 후보를 만듭니다. 기본 정책은 처음 존재하는 파일 하나를 읽는 것이며 여러 설정을 합치지 않습니다. --config는 명시적 경로를 선택합니다.

HTTP 계층은 기본적으로 루프백 주소에 묶이며 Origin이 있으면 로컬 출처인지 검사합니다. validate_origin()에서 출처 없는 네이티브 요청은 통과합니다. 이 검사를 사용자 인증이나 공개 인터넷 서비스용 접근 제어와 같은 것으로 이해하면 안 됩니다.

8직접 해볼 수 있는 실습 과제

실습의 결과물은 실행 화면 한 장보다, 입력과 기대 결과와 실패 조건을 설명한 작은 기록이면 좋습니다. 아래 과제는 대부분 소스 읽기와 종이 위 추적으로 시작할 수 있습니다. 구현 실험으로 확장할 때는 독립된 연습용 데이터와 프로젝트를 사용하세요.

8-1. 구현하기 전에 검색으로 사실 확인하기

# 다음은 파일을 바꾸지 않는 읽기 명령
rg -n 'STARTER_KIT|ALL_TOOLSETS' crates/konnect-core/src/router/registry.rs
rg -n 'dispatch_tool|first_missing_required' crates/konnect-core/src/mcp/handler.rs
rg -n 'write_atomic_if_unchanged|Conflict' crates/konnect-sexp/src/writer.rs
rg -n 'recover_file_transactions' crates/konnect-sexp/src/transaction.rs
rg -n 'transform_pin|mirror_x' crates/konnect-sexp/src/geometry.rs

검색 결과 한 줄만 보고 결론 내리지 말고 함수 전체와 호출 지점까지 읽으세요. 특히 오류가 반환되는 시점이 변경 전인지 후인지 확인하면 재시도 정책을 더 정확하게 정할 수 있습니다.

9관련 기술 심화 학습 로드맵

주차는 학습 순서의 예시입니다. Rust가 처음이면 1주차를 더 길게 잡고, 전자회로 경험이 없다면 저항·기호·넷·풋프린트의 차이를 먼저 익히세요. 매주 새로운 기능을 더하기보다, 같은 요청의 입력·실행·저장·검증을 차례로 깊게 이해해 보세요.

9-1. 테스트를 읽을 때는 검증 환경도 같이 읽는다

.github/workflows/ci.yml은 cargo test --workspace --locked --lib --tests와 문서 테스트를 분리합니다. 뷰어는 워크스페이스 밖이므로 별도 작업에서 검사합니다. “워크스페이스 전체 테스트”라는 말이 저장소의 모든 코드 검사를 뜻하지 않는 사례입니다.

crates/konnect-core/tests/conformance_test.rs는 KiCad가 만든 데모 회로도를 기준으로 읽기·쓰기 동작을 확인하는 테스트 모음입니다. KiCad 데모가 없으면 건너뛸 수 있으므로, 테스트 파일이 존재한다는 사실만으로 실제 KiCad 검증이 수행되었다고 판단해서는 안 됩니다.

.github/workflows/e2e-kicad.yml은 KiCad 10.0.5를 설치한 Windows 환경에서 설계 생성·배선·ERC·Gerber·DRC 경로를 다루도록 구성되어 있습니다. 릴리스 워크플로도 이 별도 검증을 호출합니다. 이는 워크플로의 의도와 설정에 대한 설명이며 특정 실행의 통과 기록을 뜻하지 않습니다.

9-2. 작은 도구 하나로 다시 설명해 보기

이 흐름을 자신의 작은 파일 변환기에도 적용해 보세요. 전자회로 전용 지식은 달라도, 입력 계약과 안전한 저장과 검증 증거를 나누는 방법은 그대로 가져갈 수 있습니다.

10핵심 키워드 사전

이 용어를 모두 외운 뒤 시작할 필요는 없습니다. 먼저 “도구 요청 → 파일 또는 IPC 변경 → 검증 결과”를 설명해 보고, 막히는 단어만 이 표로 돌아와 확인하면 됩니다.

11참고 링크

11-1. 저장소와 설계 문서

• Konnect 공식 저장소 — 설치 안내·현재 이슈·릴리스로 가는 출발점
• 분석 대상 커밋 9488e5f — 본문의 파일·설정·버전 설명 기준
• v0.13.0 릴리스 — 실행 파일과 PCM 패키지 확인
• 개발자 개요 — 구성 요소와 읽는 순서
• 아키텍처 문서 — 계층과 데이터 흐름
• 도구 개발 문서 — 도구 등록·스키마·핸들러의 연결
• 신뢰성 계약 — 입력·상태·변경·증거·복구 원칙과 점진적 전환 범위
• 테스트·릴리스 문서 — 일반 검사와 실제 KiCad 검증의 관계
• 도구 디렉토리 — 개별 기능과 묶음 탐색
• 라이선스 원문 · 상업용 라이선스 안내

11-2. 핵심 구현 바로가기

• McpHandler — 메시지와 도구 실행의 경계
• 도구 등록부 · 관리 도구 — 도구 수와 노출 조건
• 부분 편집·조건부 저장 · 여러 파일의 저널·복구
• 타입 기반 회로도 모델 — 미모델링 노드 보존과 저장 전제
• KiCad IPC 클라이언트 · 실시간 보드 관찰 기록
• 결정적 이미지 렌더링 · Tauri 뷰어

11-3. 관련 기술의 공식 학습 자료

• KiCad 10 공식 설명서 · KiCad IPC API 개발 문서
• MCP 2025-06-18 명세 — 서버가 초기화 응답에 선언하는 프로토콜 버전
• Rust 공식 입문서 · Cargo 워크스페이스
• Tokio 공식 학습 자료 · Axum 0.8.9 문서
• Protocol Buffers 공식 개요 · NNG 공식 문서
• JSON Schema Draft 2020-12 · Serde 공식 문서
• Tauri 2 공식 문서 · GitHub Rust 주간 트렌딩

현재 상태 (2026-10-23 확인)

GitHub 상태 수치는 2026-10-23 기준입니다. 코드 내부의 수치와 동작은 커밋 9488e5f에 고정되어 있습니다. 최근 push 날짜와 분석 대상 커밋 날짜는 서로 다른 범위를 나타냅니다.