Engineering Knowledge MCP

코딩 에이전트(Claude Code, GitHub Copilot 등)가 공유 엔지니어링 지식 베이스를 검색하고 업데이트할 수 있게 해주는 초경량 로컬 MCP 서버 — 내부 컨벤션, API 세부 사항, 인프라 설정, 인증 흐름, 로컬 개발 환경 구성 등을 다룹니다.

지식은 이 Git 저장소의 일반 Markdown 파일로 저장됩니다. MCP 서버는 파일시스템 위의 얇고 상태 없는 읽기/쓰기 계층일 뿐입니다 — 그 이상도 이하도 아닙니다.

1. 이 도구가 하는 일

• 코딩 에이전트가 내부 컨벤션을 추측하거나 사용자에게 반복해서 묻는 대신 지식 베이스를 검색할 수 있습니다.

• 에이전트가 거의 마찰 없이(도구 호출 한 번, 사실이 어디에 속하는지 알 필요 없이) 새로운 사실을 캡처할 수 있습니다.

• 에이전트가 구조화된 지식 문서를 결정적으로 생성하고 업데이트할 수 있습니다.

• 모든 것이 Git의 Markdown이므로 MCP 서버 없이도 유용합니다 — grep으로 검색하고, 읽고, 편집하고, diff를 검토하고, 커밋하고, PR을 보내는 것이 코드와 똑같이 가능합니다.

Related MCP server: bikky

2. 아키텍처

engineering-knowledge-mcp/
├── knowledge/           # the knowledge base itself (Markdown, organized by topic area)
│   ├── api/
│   ├── cloud/
│   ├── data/
│   ├── frontend/
│   └── general/
├── inbox/
│   └── knowledge-inbox.md   # low-friction capture target; triage manually into knowledge/
├── src/
│   ├── index.ts         # MCP server entrypoint (stdio transport)
│   ├── paths.ts         # path sanitization / traversal protection
│   ├── knowledge.ts     # search, get, create, update, capture logic
│   └── tools/index.ts   # MCP tool registration + input schemas
├── test/                # node:test unit tests
├── CLAUDE.md            # agent instructions auto-loaded by Claude Code when working in this repo
├── package.json
└── tsconfig.json

의도적인 설계 선택 사항:

• stdio 전용 MCP. HTTP 서버도, Express도 없습니다 — 클라이언트(Claude Code, Copilot, MCP Inspector)가 이 프로세스를 실행하고 stdin/stdout으로 JSON-RPC를 주고받습니다.

• 데이터베이스 없음, 임베딩 없음, 벡터 저장소 없음. 검색은 Markdown 섹션에 대한 대소문자 구분 없는 토큰 매칭이며, 요청 시 계산됩니다. 수십~수백 개의 소규모 문서 규모에서는 충분히 괜찮으며, 디스크의 파일과 동기화할 인덱스가 없다는 뜻입니다 — 파일이 항상 진실의 원천입니다.

• 인메모리 인덱스 없음, 파일시스템 감시 없음. 모든 도구 호출은 호출 시점에 디스크에서 필요한 것만 읽습니다. 더 단순하고, 이 규모에서는 저렴합니다.

• 자동 git 커밋 없음. 도구 호출은 작업 트리만 건드립니다. 검토와 커밋/푸시는 사용자의 몫입니다. (설계상 도구 계약을 바꾸지 않고도 나중에 자동 커밋이나 PR 생성을 추가할 여지가 있습니다.)

공식 SDK 참고

브리핑에서 @modelcontextprotocol/server를 언급했지만, 실제 게시된 패키지는 @modelcontextprotocol/sdk(v1.30+)이며, 이 프로젝트가 사용하는 것도 이것입니다(McpServer + StdioServerTransport).

3. 지식 저장 방식

각 문서는 knowledge/<area>/<topic>.md 아래의 Markdown 파일이며, 선택적으로 최소한의 frontmatter를 가질 수 있습니다:

---
title: APIM
tags:
  - api
  - apim
---

# APIM

## Base paths

Internal modelling APIs use ...

## Authentication

...

## Local development

...

그 이상의 필수 스키마는 없습니다 — frontmatter는 선택 사항이고, 제목은 일반 Markdown ## 섹션일 뿐입니다. search_knowledge와 update_knowledge는 ## 수준(및 그보다 깊은) 제목을 "섹션"의 단위로 사용하므로, 문서를 명확한 제목으로 구조화하면 검색 결과와 업데이트가 모두 더 정확해집니다.

캡처되었지만 아직 분류되지 않은 지식은 타임스탬프가 있는 항목으로 inbox/knowledge-inbox.md에 들어갑니다. 주기적으로(수동으로, 또는 에이전트의 도움을 받아) 인박스의 항목을 적절한 knowledge/ 문서로 이동/정리합니다.

4. 실행 방법

Node.js 20+ 필요.

npm install
npm run build
npm start

로컬 반복 개발용(tsx로 TypeScript에서 직접 실행, 빌드 단계 없음):

npm run dev

둘 다 stdio에서 서버를 시작하고 클라이언트가 연결되기를 기다립니다 — 터미널에서 프로토콜 트래픽은 보이지 않습니다. 시작/진단 로그만 보입니다(stderr로 기록되며, stdout은 MCP 프로토콜 메시지 전용이므로 절대 stdout으로 출력하지 않습니다).

5. MCP Inspector로 테스트

대화형 UI:

npx @modelcontextprotocol/inspector npm run dev

브라우저 UI가 열리며, 여기서 search_knowledge, list_knowledge_topics, get_knowledge, capture_knowledge, create_knowledge, update_knowledge를 직접 호출하고 JSON 스키마와 응답을 검사할 수 있습니다.

비대화형 / 스크립트 가능:

npx @modelcontextprotocol/inspector --cli node dist/index.js --method tools/list

npx @modelcontextprotocol/inspector --cli node dist/index.js \
  --method tools/call --tool-name search_knowledge --tool-arg query="apim authentication"

6. MCP 클라이언트 구성 예시

Claude Code / 대부분의 MCP 클라이언트는 다음과 같은 구성 블록을 사용합니다:

{
  "mcpServers": {
    "engineering-knowledge": {
      "command": "node",
      "args": ["/absolute/path/to/engineering-knowledge-mcp/dist/index.js"]
    }
  }
}

GitHub Copilot의 MCP 지원의 경우, MCP 구성 파일에 동일한 command/args stdio 서버 항목을 사용합니다. 먼저 npm run build를 실행하여 dist/index.js가 존재하게 하거나, command/args를 npx tsx /absolute/path/to/src/index.ts로 지정하여 소스에서 직접 실행할 수 있습니다.

7. 에이전트가 도구를 사용하는 방법

이 저장소에는 아래 지침이 담긴 CLAUDE.md가 포함되어 있으며, Claude Code는 이 저장소 안에서 작업할 때마다 자동으로 로드합니다. 다른 클라이언트(Copilot 등)의 경우 해당 시스템 프롬프트/지침 파일에 동일한 지침을 추가하세요:

내부 엔지니어링 컨벤션, 인프라, API, 인증, 플랫폼 구성 또는 확립된 개발 패턴에 대해 사용자에게 묻기 전에 엔지니어링 지식 MCP를 검색하세요. 내부 구성 값을 임의로 만들지 마세요. 사용자가 지속적인 엔지니어링 지식을 기억하거나, 캡처하거나, 추가하라고 명시적으로 요청하면 지식 MCP 쓰기 도구를 사용하세요.

도구별 가이드:

• search_knowledge(query) — "우리는 보통 어떻게...", "우리 컨벤션은...", "기본 URL / 인증 흐름이 뭐지..." 같은 질문의 첫 번째 도구입니다. 전체 문서가 아닌 파일 경로가 포함된 순위가 매겨진 섹션을 반환합니다. 아직 분류되지 않은 inbox/knowledge-inbox.md의 항목도 검색하므로, 최근 캡처한 내용은 적절한 주제로 정리되기 전에도 찾을 수 있습니다. 본문/제목 텍스트에서 이미 매칭된 문서 중에서 frontmatter tags도 쿼리 단어와 일치하는 문서가 더 높은 순위를 받습니다 — 태그는 순위를 높일 뿐, 자체적으로 매칭을 만들지는 않습니다.

• list_knowledge_topics() — 인자 없음; 전체 내용 없이 각 문서의 경로, 제목, 태그를 나열합니다. 아직 좋은 검색어가 없을 때 무엇이 있는지 둘러보거나, create_knowledge를 호출하기 전에 주제가 이미 존재하는지 확인할 때 사용합니다.

• get_knowledge(topicOrPath) — 원하는 문서를 알게 되면(또는 search_knowledge가 알려줬다면) 전체를 가져옵니다. 느슨한 참조를 허용합니다: "apim", "api/apim", 또는 "knowledge/api/apim.md".

• capture_knowledge(content, suggestedTopic?) — 사용자가 "이거 기억해" / "그거 기록해" / 보관할 가치가 있는 사실을 말할 때 사용하며, 사용자가 어디에 속하는지 파악하게 하지 않습니다. 인박스에 추가만 합니다.

• create_knowledge(topic, title, content) — 아직 존재하지 않는 진정한 새 주제를 추가할 때 사용합니다. 주제가 이미 존재하면 명시적으로 실패합니다(대신 update_knowledge 사용).

• update_knowledge(topicOrPath, heading, content, mode) — 의도적으로 자연어가 아닌 쓰기 도구입니다. 아래 설계 노트를 참조하세요.

update_knowledge가 자유 텍스트 change 대신 heading + mode를 받는 이유

브리핑에서 이 부분이 신중한 설계가 필요한 부분으로 지적되었습니다: 목표는 자연어 변경이 무엇을 의미하는지 결정하는 것은 에이전트(LLM을 가진)가 하도록 하는 것이지, 이 서버가 지침에 대한 자체 AI 해석을 실행하는 것이 아닙니다. 따라서 update_knowledge는 구조적이고 결정적인 대상을 받습니다:

• topicOrPath — 어떤 문서인지.

• heading — 섹션을 식별하는 정확한 ##/### 등의 제목 텍스트. 존재하지 않으면 해당 제목의 새 ## 섹션이 문서 끝에 추가됩니다(약간 오래된 문서에 대해 업데이트가 조용히 실패하지 않도록).

• content — 작성할 그대로의 Markdown.

• mode: "append"(기본값)는 content를 섹션 끝에 추가하고, "replace"는 섹션 본문 전체를 덮어씁니다.

즉, 호출하는 에이전트는 "로컬 개발 섹션을 새 포트를 언급하도록 업데이트"를 이미 구체적인 Markdown 콘텐츠로 변환하고 append/replace를 선택했을 것으로 기대합니다 — LLM 기반 클라이언트가 하기에 적합한 판단 유형이며, 이 경량 서버가 원시 문자열에서 해서는 안 되는 판단 유형이기도 합니다.

8. 기존 지식 베이스 가져오기

이미 어딘가에 노트가 있다면(개인 위키, .md 파일 폴더, Notion 내보내기, 방대한 "암묵적 지식" 문서, 저장해 둔 Slack 스레드 등), 가져오기 도구도 변환할 특별한 형식도 없습니다 — 의도적으로 Markdown 파일 폴더일 뿐입니다. 기존 구조 중 얼마나 보존할 가치가 있는지에 따라 대략 두 가지 방법으로 시작할 수 있습니다:

A. 파일을 직접 넣기(노트가 이미 합리적으로 정리되어 있을 때 가장 좋음)

1. 기존 .md 파일을 knowledge/에 복사하고, api/ cloud/ data/ frontend/ general/ 중 가장 잘 맞는 폴더에 정리합니다(또는 새 주제 폴더를 추가 — 초기 5개를 강제하는 것은 없습니다).

2. 각 파일에 최소한의 frontmatter(title, 선택적으로 tags)를 추가합니다 — 필수는 아니지만 저렴하고, get_knowledge/검색 결과가 제목이 있을 때 더 읽기 좋습니다.

3. 매우 긴 문서를 아직 그렇지 않다면 제목이 있는 ## 섹션으로 나눕니다 — search_knowledge와 update_knowledge 모두 제목 수준에서 작동하므로, 10,000단어짜리 단일 섹션의 텍스트 벽은 몇 개의 명확한 제목 아래에 나눈 동일한 콘텐츠보다 검색/업데이트 성능이 나쁩니다.

4. npm test를 실행하고(아무것도 깨지지 않았는지 확인) Inspector(§5)를 통해 실제 콘텐츠에 대해 search_knowledge / get_knowledge 호출을 몇 번 시도합니다.

5. diff를 검토하고 이 저장소에 대한 다른 변경과 마찬가지로 직접 커밋합니다.

B. 에이전트가 마이그레이션을 대신 하게 하기(지저분한/비구조화된 소스 자료에 가장 좋음)

Claude Code(또는 이 MCP가 구성된 다른 코딩 에이전트)를 기존 노트에 지정하고 쓰기 도구를 사용해 마이그레이션하도록 요청합니다. 예:

~/notes/engineering/에 엔지니어링 노트가 있어. 그것들을 읽고 create_knowledge를 사용해 knowledge/ 아래에 주제별로 그룹화된 적절한 문서로 만들어줘. 기존 주제에 깔끔하게 맞지 않는 것은 capture_knowledge를 대신 사용해서 내가 검토할 수 있게 인박스에 넣어줘.

이 방법이 잘 작동하는 이유는 지저분한 산문을 "제목, 몇 개의 태그, 몇 개의 명확한 ## 섹션"으로 바꾸는 것이 LLM 기반 에이전트가 잘하는 판단 유형이기 때문입니다 — update_knowledge가 그 판단을 서버가 아닌 호출자에게 미루는 이유와 같은 논리입니다(§7 참조). 에이전트는 여전히 knowledge//inbox/ 밖에 쓸 수 없으며, 결과 파일은 모두 커밋 전에 검토할 수 있는 일반적인 추적되지 않음/수정됨 파일로 표시됩니다 — 자동 커밋은 없습니다.

어느 쪽이든 첫 번째 패스를 초안으로 취급하세요: 처음부터 완벽한 분류 체계를 만들려고 하기보다는 capture_knowledge가 여러 세션에 걸쳐 분류할 긴 인박스를 만드는 것도 괜찮습니다(오히려 예상됩니다).

9. 보안 노트

• 모든 읽기/쓰기는 저장소 루트 아래의 knowledge/와 inbox/로 제한됩니다. 호출자가 제공한 모든 경로는 safeResolve(src/paths.ts)를 거치며, 절대 경로, .. 트래버설, null 바이트, 허용 디렉터리 밖으로 해석되는 모든 것을 거부합니다.

• create_knowledge는 사용 전에 topic을 안전한 파일명 세그먼트로 정화합니다.

• 문서 콘텐츠가 실행, 평가, 또는 셸로 전달되는 일은 없습니다.

• 어떤 도구도 MCP 입력에 기반한 셸 명령을 실행하지 않습니다.

• 오류는 추측에 의존하는 대신 명시적입니다(예: "X와 일치하는 지식 문서를 찾을 수 없음").