content-knowledge-mcp

콘텐츠 에이전트가 기업의 편집 지식(브랜드 규칙, 시각 템플릿 카탈로그, 과거 게시물과 그 결과)에 접근할 수 있게 해주는 MCP 서버입니다. 지식은 기업이 소유한 일반 마크다운 파일에 있으며, 서버는 이를 노출할 뿐입니다.

AI 에이전트와 워크플로 자동화에 관한 제 학사 논문의 기술적 핵심으로 구축되었습니다. 여기 있는 버전은 범용 엔진이며, 예시 지식으로 가상의 기업을 담고 있습니다.

벡터 데이터베이스가 없는 이유

가장 흔한 방법은 지식을 임베딩하고 유사도로 검색하는 것입니다. 이 서버는 두 가지 이유로 의도적으로 그렇게 하지 않습니다.

이 규모에서는 잘 정돈된 파일을 대상으로 한 구조적 검색이 낫습니다. 기업의 편집 규칙은 수천 수만 개가 아니라 수십 개 블록입니다. 이를 여러 조각으로 나누고 코사인 유사도로 검색하면, 인덱싱 단계, 동기화해야 할 저장소, 그리고 잘 드러나지 않는 장애 유형을 추가하는 대가로 이미 갖고 있던 호출률만 되찾을 뿐입니다.

모든 규칙에는 ID가 있고, 바로 그것이 핵심입니다. 규칙은 R1, R17, R905이고 템플릿은 T901, T905, 출시 기록은 L2입니다. 에이전트는 자신이 사용한 ID를 인용하도록 지시됩니다. 그것은 도출이 각 제안을 인간이 몇 초 안에 감사할 수 있는 형태로 바꿔 줍니다. 검토자는 rules_used: ["R920", "R903"]를 읽고 그 게시물이 어떤 규칙들로 나왔는지 정확히 파악할 수 있습니다. 임베딩은 문단을 돌려 주지 논증을 돌려 주지 않습니다. 목표가 작동하는 인간 승인 게이트라면, 감사 가능성이 상황을 낙관시키는 것보다 낫습니다.

그 대가는 실제이며 솔직히 인정할 만합니다. 검색은 어휘 기반이므로 규칙과 공유하는 단어가 하나도 없는 질의는 그 규칙을 찾아내지 못합니다. 서버는 일치하는 척하지 않고 NO_MATCH를 반환합니다. 그것이 평가 사례가 테스트하고 싶어 하는 동작입니다.

Related MCP server: mcp-guide

아키텍처

  Claude Desktop / Claude Code ──stdio──┐
                                        ├──▶ content-knowledge-mcp ──▶ KNOWLEDGE_PATH/
  n8n MCP Client Tool ──────────HTTP────┘         (3 tools)              guidelines/*.md   R# rules, L# launch records
       (host.docker.internal:8765)                                       templates/catalog.md   T# catalog
                                                                         past-posts/*.md        past posts and outcomes

도구 세 개, 전송 스위치 하나, 상태 없음:

서버는 콘텐츠를 소유하지 않습니다. KNOWLEDGE_PATH를 다른 폴더로 가리키면 다른 기업을 서빙합니다. 이것이 코드를 건드리지 않고도 공개할 수 있었던 이유입니다.

빠른 시작

git clone https://github.com/alessandro-martelli/content-knowledge-mcp
cd content-knowledge-mcp
python3 -m venv .venv && .venv/bin/pip install fastmcp

# run the twelve checks against the example knowledge
KNOWLEDGE_PATH=examples/knowledge .venv/bin/python smoke_test.py

# stdio, for Claude Desktop or Claude Code
KNOWLEDGE_PATH=examples/knowledge .venv/bin/python server.py

# HTTP on :8765, for the n8n MCP Client Tool
KNOWLEDGE_PATH=examples/knowledge .venv/bin/python server.py --http

examples/knowledge/ 아래의 예시 지식은 전부 가상의 것입니다. 가상의 디자인 스쿨을 배경으로 하는 규칙, 출시 기록, 템플릿 카탈로그, 그리고 과거 게시물 세 개입니다. 누구나 저장소를 바로 실행하고 프로젝트에 쓸 콘텐츠를 확인할 수 있도록 존재합니다.

평가

스모크 테스트: 12/12. 각 테스트는 프로토콜을 통해 실제 fastmcp.Client를 거칩니다. 헬퍼 함수를 쓰지 않으므로 도구 초죽이나 전송 계층에서 문제가 끊기면 이 테스트에서 드러납니다.

에이전트 수준의 운영 규약: 8가지 케이스, 그중 5가지는 대립적 주의 (상충된 규칙, 범위를 벗어난 요청, 이용 불가한 도구, 일치하는 템플릿 없음, 불분명한 입력). 2026년 8월, 두 에이전트의 프롬프트를 기준으로 실행했습니다. 8개 중 6개가 통과했고, 처음부터 모든 출력이 유효한 JSON이었습니다. 실패 2건은 에이전트의 문제가 아니라 테스트 스위트의 결함이었습니다. 그 2건 모두 eval/test-log.md와 필요 대안들과 함께 적어 두었습니다. 로그는 원문 그대로 유지합니다. 성공만 보고하는 스위트는 아무것도 측정하는 게 아니기 때문입니다.

솔직한 한계

• 검색은 어휘 기반으로 빈도에 따라 점수를 계산합니다. 동의어를 이해하지 못하며, 질문에 쓰지 않은 단어로 표현된 규칙은 찾아내지 못합니다.

• 지식 폴더 구조는 고정되어 있습니다 (guidelines/, templates/catalog.md, past-posts/), 카탈로그 파일의 파일명도 하드코딩되어 있습니다.

• 쓰기 경로도 캐시도 없습니다. 호출이 있을 때마다 파일을 읽습니다. 이 규모에서는 무리가 없지만 블록이 만 개 정도가 되면 다른 문제가 됩니다.

• 평가에서 밝혀진 두 가지 공개 결함은 아직 이 코드에 반영되지 않았습니다. rules_used는 L# 기록을 인용할 수 없고, 진행 계획 스키마는 채널이 비어 있는 행을 표현할 수 없습니다.

라이선스

MIT 라이선스입니다. LICENSE 파일을 참고하세요.