Knowerage — AI 분석 커버리지 관리

레거시 코드 분석 커버리지와 최신 상태를 추적하는 로컬 우선 MCP 서버입니다.

소스: github.com/MTimma/knowerage

빠른 시작

요구 사항: Node.js 18 이상 — npx가 PATH에 있어야 합니다 (Node.js에 포함된 npm과 함께 제공됨).

Related MCP server: Atlas

MCP 서버 구성

MCP 호스트가 서버 정의를 기대하는 곳에 Knowerage를 등록하십시오 (예: 일부 클라이언트는 .cursor/mcp.json 또는 .vscode/mcp.json을 사용하며, 다른 클라이언트는 환경 변수나 UI를 사용합니다. 호스트의 문서를 따르십시오). 동일한 서버 항목 형식을 사용하십시오:

{
  "mcpServers": {
    "knowerage": {
      "command": "npx",
      "args": ["@mtimma/knowerage"],
      "env": {
        "KNOWERAGE_WORKSPACE_ROOT": "${workspaceFolder}",
        "KNOWERAGE_AUTO_FULL_RECONCILE": "true"
      }
    }
  }
}

호스트가 ${workspaceFolder} 변수를 확장하지 않는 경우 프로젝트 루트로 바꾸십시오.

KNOWERAGE_AUTO_FULL_RECONCILE은 선택 사항입니다: 설정되지 않았거나, 비어 있거나, 참(truthy) 값이 아닌 경우 파일 감시자는 기본적으로 꺼짐 상태입니다. 활성화하려면 1, true, yes 또는 on (공백 제거, 대소문자 구분 없음)으로 설정하십시오. 켜짐 상태일 때 서버는 knowerage/를 감시하며, 짧은 디바운스(debounce) 후 파일 시스템 변경 시 knowerage_reconcile_all을 실행합니다. 이는 모든 MCP 도구 호출 후 전체 조정(reconcile)을 실행하는 것과는 다릅니다. knowerage/ 하위의 파일 변경 사항에만 반응합니다. registry.json에 대한 레지스트리 쓰기는 감시자에 의해 무시되므로 저장 시 루프가 발생하지 않습니다.

Knowerage 사용 방법

MCP 서버가 구성된 후에는 일반 문장으로 어시스턴트와 대화하면 됩니다. 도구 이름을 외울 필요는 없습니다.

코드 분석 또는 문서화

관심 있는 파일, 클래스 또는 동작을 지정하십시오. 예:

• Knowerage를 사용하여 main.java의 논리적 알고리즘 워크플로우를 분석해 줘.

• ETL 서비스의 데이터 엔티티 조정 및 버전 관리 로직을 분석해 줘.

어시스턴트는 knowerage/analysis/ 하위에 마크다운을 생성하거나 업데이트하고 knowerage/registry.json에 커버리지를 기록합니다 (아래 작동 원리 참조).

커버리지 및 격차 (동일 프로젝트, 이후 대화 또는 다른 에이전트)

트리에 이미 분석 결과가 있는 경우 다음과 같이 물어볼 수 있습니다:

• 우리 코드의 몇 퍼센트가 분석으로 커버되고 있어?

• 이 코드베이스에서 아직 분석되지 않은 부분은 어디야?

Knowerage는 저장소에 대해 막연하게 추측하는 것이 아니라 레지스트리 및 커버리지 도우미(예: 개요, 파일별 상태, 오래된 목록)를 통해 답변합니다.

대체 접근 방식

npm을 통한 설치

npx @mtimma/knowerage

또는 소스에서 빌드

cargo build --release
./target/release/knowerage-mcp

작동 원리

1. AI 에이전트가 소스 파일과 커버된 라인 범위를 선언하는 YAML 프런트매터가 포함된 분석 .md 파일을 생성합니다.

2. 레지스트리(knowerage/registry.json)는 신선도 유지를 위해 SHA-256 해시와 함께 분석 기록을 추적합니다.

3. MCP 도구는 생성, 조정, 쿼리 및 내보내기 작업을 노출합니다.

4. 에이전트가 "X를 분석해"라고 하면 전체 워크플로우가 자동으로 실행됩니다 (생성 → 조정 → 기록).

레지스트리 파일 형태 (knowerage/registry.json)

디스크상의 형식은 키가 분석 경로(문자열)인 JSON 객체입니다. 각 값은 하나의 레코드입니다 (참조: contracts/contracts.md). 두 개의 레코드가 포함된 전체 샘플은 examples/registry.sample.json에 있습니다.

flowchart TB
  subgraph file["knowerage/registry.json"]
    O["Top-level JSON object"]
    O --> K["Each key: analysis markdown path, e.g. knowerage/analysis/.../topic.md"]
    K --> V["Value: one RegistryRecord"]
  end

  subgraph rec["RegistryRecord fields"]
    ap["analysis_path · source_path"]
    cr["covered_ranges: [[start,end], ...]"]
    h["analysis_hash · source_hash (sha256:… )"]
    t["record_created_at · record_updated_at (ISO 8601)"]
    st["status: fresh | stale_doc | stale_src | missing_src | dangling_doc"]
  end

  V --> rec

분석 .md 파일에 대한 프런트매터는 registry.json 내부가 아닌 계약 문서(메타데이터 스키마)에 별도로 지정됩니다.

MCP 도구

프로젝트 구조

knowerage/                  # Created per-project
├── analysis/              # Analysis markdown files
│   └── **/*.md
└── registry.json          # Coverage registry

src/                       # Rust MCP server
├── main.rs
├── lib.rs
├── types.rs
├── parser.rs
├── registry.rs
├── mcp.rs
├── security.rs
└── export.rs

문서

• 사용자 온보딩 — 설정, 구성, 일반적인 사용법

• INSTRUCTIONS.md — MCP 에이전트 지침

• Rust 관례

• JS 관례

• 계약 — 스키마 및 API 계약 (레지스트리 + 프런트매터)

• 레지스트리 JSON 예시 — 샘플 registry.json 내용

보안

• 모든 경로는 작업 공간 루트를 기준으로 검증됨

• 경로 탐색(..) 거부

• 레지스트리에 대한 원자적 쓰기 (충돌 방지)

• 분석 파일이나 보고서에 비밀 정보 포함 안 됨

• SHA-256 해시 기반의 신선도 유지 (git pull 후에도 유지)

라이선스

MIT — 저작권 Martins Timma.

이 프로젝트의 일부는 생성형 AI 코딩 어시스턴트를 사용하여 작성되거나 개선되었습니다. 설계, 보안에 민감한 동작 및 릴리스에는 인간의 검토가 적용됩니다.