MCP 서버를 위한 결정론적, CI 우선 품질 스코어카드

MCP 서버를 위한 결정론적, CI 우선 품질 스코어카드.

MCP Scorecard

는 MCP 서버가 실제 워크플로에 진입하기 전에 검토할 수 있도록 지원하는 오픈 소스 인프라 도구입니다. 이 도구는 stdio를 통해 서버를 로컬에서 실행하고, 도구(tools)를 탐색하며, 결정론적 규칙 세트(deterministic ruleset)를 적용하여 다음과 같은 항목에 대해 검토 가능한 점수와 결과(findings)를 생성합니다:

conformance (준수성)

security (보안)

ergonomics (인체공학/사용성)

metadata (메타데이터)

출력물은 CI를 위해 구축되었습니다: 안정적인 터미널 요약, 기계 판독이 가능한 JSON 스코어카드 보고서, 그리고 코드 스캐닝 시스템을 위한 SARIF를 제공합니다.

이 프로젝트는 의도적으로 AI 래퍼(wrapper)로 만들지 않았습니다. LLM 점수 매기기, 숨겨진 판단, 또는 호스팅된 분석에 의존하지 않습니다. 목표는 엔지니어링 팀이 풀 리퀘스트(pull requests) 및 릴리스 파이프라인에서 게이트(gate)로 사용할 수 있는 반복 가능하고 감사 가능한 기준(baseline)을 제공하는 것입니다.

빠른 가치:

실제 MCP 서버를 대상으로 로컬에서 실행
결정론적 임계값 미만일 경우 CI 실패 처리
자동화를 위한 JSON 및 SARIF 내보내기
위험한 MCP 접점(surfaces)을 결정론적으로 검토

MCP Scorecard

는 MCP 서버를 위한 결정론적 품질 스코어카드입니다.

이 도구는 팀이 다음과 같은 질문에 답해야 하는 상황을 위해 설계되었습니다:

이 서버 접점(surface)을 채택하기 전에 검토할 수 있는가?
CI에서 추가적인 정밀 조사가 필요한 기능을 노출하고 있는가?
도구 이름, 설명 및 스키마(schemas)가 인간의 검토를 위해 충분히 명확한가?
자동화 및 정책을 위해 안정적인 기계 판독 가능 보고서를 생성할 수 있는가?

현재 이 도구는 로컬 stdio MCP 서버와 설명, 테스트, 버전 관리가 용이한 결정론적 점수 모델에 집중하고 있습니다.

MCP 서버는 인프라입니다. 이들은 에이전트(agents), 런타임(runtimes), 그리고 자동화가 호출할 수 있는 호출 가능한 도구 접점(tool surfaces)을 정의합니다. 이는 다른 통합 경계(integration boundaries)와 마찬가지로 엄격하게 검토되어야 함을 의미합니다.

실제로 팀들은 종종 MCP 서버를 임시방편(ad hoc)으로 평가하곤 합니다:

설명이 모호함
스키마가 취약하거나 제약 조건이 부족함
고위험 기능이 뒤늦게 발견됨
CI에 일관된 기준(baseline)이 없음

MCP Scorecard

는 이러한 1차 검토를 결정론적인 계약(contract)으로 전환합니다:

로컬에서 실행
CI에서 실행
카테고리별 점수 및 결과(findings) 검토
JSON 및 SARIF로 내보내기
시간이 지나도 결과를 검토할 수 있도록 유지

현재 스코어 모델은 네 가지 명시적인 버킷(buckets)을 사용합니다.

여기서 준수성(Conformance)은 완전한 프로토콜 인증이 아니라, 결정론적인 인터페이스 수준의 준수성 및 스키마 검토 가능성(schema reviewability) 체크를 의미합니다.

서버 인터페이스가 구조적으로 잘 형성되어 있으며 MCP 인터페이스로서 검토 가능한지 확인합니다.

예시:

중복된 도구(tool) 이름
누락된 스키마 타입 (schema type)
임의의 최상위 속성 (top-level properties)
필수(required)로 표시되지 않은 중요한 입력 필드

폭발 반경(blast radius)을 실질적으로 증가시키거나 명시적인 검토가 필요한 노출된 기능들을 확인합니다.

예시:

명령 실행 (command execution)
파일 시스템 변형 (filesystem mutation)
네트워크 및 HTTP 요청 프리미티브 (primitives)
다운로드 후 실행 (download-and-execute) 패턴

서버 인터페이스가 인간과 자동화 도구가 추측 없이 검토할 수 있을 만큼 충분히 이해 가능한지 확인합니다.

예시:

지나치게 일반적인 도구 이름
모호한 설명
취약한 입력 스키마
가시적인 범위 힌트가 없는 파일 시스템 변형 도구

기본적인 설명 메타데이터가 존재하는지, 그리고 파괴적인 동작을 쉽게 발견할 수 있는지 확인합니다.

예시:

누락된 도구 설명
광범위하고 파괴적인 권한을 명시적으로 광고하는 설명

MCP Scorecard는 의도적으로 범위를 좁게 설정하였으며, 그 범위에 대해 솔직합니다.

다음 사항은 보장하지 않습니다:

높은 점수가 서버의 안전함을 의미함
낮은 점수가 서버의 악의성을 의미함
런타임 취약점 분석 (runtime exploitability analysis)
배포 또는 격리 검증 (deployment or isolation verification)
비즈니스 의도 분류 (business intent classification)
서버 인터페이스 외부의 인간 승인 정책 평가
LLM 기반 스코어링
호스팅된 스캐닝 또는 레지스트리 기반 인증 주장

점수는 결정론적이고 검토 가능한 속성만을 측정합니다.

그것이 이 도구의 목적입니다.

포함된 보안 취약 데모 서버를 스캔해 보세요:

python -m venv .venv
source .venv/bin/activate
pip install -e .[dev]
...

JSON 및 SARIF를 생성하고 점수 게이트(score gate)를 적용하세요:

mcp-scorecard scan \
--min-score 80 \
--json-out mcp-scorecard-report.json \
...

스캐너는 --cmd를 셸(shell) 없이 직접 실행합니다. 실제로 이는 실제 실행 파일(executable)과 인자(args)를 전달하기만 하면 python, npx, uvx 또는 컴파일된 바이너리(compiled binary) 모두 작동할 수 있음을 의미합니다.

v1.0.0에서 권장되는 CLI 이름은 mcp-scorecard입니다. 기존의 mcp-trust 명령은 호환성을 위한 별칭(alias)으로 계속 사용할 수 있습니다. Python 모듈 이름은 mcp_trust로 유지됩니다.

Windows (PowerShell)

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e .[dev]
...

이 워크플로(workflow)를 리포지토리(repository)에 추가하세요:

name: MCP Scorecard
on:
pull_request:
...

이 액션(action)은 현재의 로컬 사용 사례를 유지하면서 이를 CI 우선 스코어카드 단계로 패키징합니다.

입력값 (Inputs):

cmd

min-score

json-out

sarif-out

markdown-out

출력값 (Outputs):

total-score

category-scores

passed

각 실행은 또한 PR(Pull Request) 친화적인 Markdown 요약본을 GitHub Actions 단계 요약(step summary)에 작성합니다. 만약 markdown-out이 설정되면, 동일한 요약본이 워크스페이스(workspace) 내부의 파일로 작성됩니다.

마이그레이션 참고 사항 (Migration note):

새로운 워크플로에서는 aak204/MCP-Scorecard@v1.0.0 사용을 권장합니다. 이전 문서나 링크에는 aak204/MCP-Trust-Kit에 대한 기존 참조가 여전히 존재할 수 있습니다.

examples/insecure-server에 대한 현재 터미널 출력:

Generator: MCP Scorecard (mcp-scorecard 1.0.0)
Report Schema: mcp-scorecard-report@1.0
Scan Timestamp: 2026-04-09T15:49:48.930250+00:00
...

이 리포지토리의 샘플 아티팩트 (Sample artifacts):

sample-reports/insecure-server.report.json
sample-reports/insecure-server.report.sarif
sample-reports/insecure-server.terminal.md

점수 모델(score model)은 의도적으로 단순합니다.

100에서 시작합니다.
발견된 항목(findings)에 대해 고정된 결정론적 페널티(deterministic penalties)를 적용합니다.
점수를 0..100 사이로 제한(clamp)합니다.
conformance (준수성), security (보안), ergonomics (인체공학/사용성), metadata (메타데이터)에 대해 동일한 방식으로 버킷 점수(bucket scores)를 계산합니다.

현재 릴리스 라인의 심각도(Severity) 매핑:

심각도 (Severity)	페널티 (Penalty)
`info`	`0`
`warning`	`10`
`error`	`20`

모든 체크(check)는 다음과 같은 명시적인 메타데이터(metadata)를 포함합니다:

id

title

bucket

severity

rationale

모든 보고서(report)는 다음 항목을 공개합니다:

총점 (total score)
카테고리별 점수 (category scores)
발견 항목 수 (finding counts)
전체 메타데이터를 포함한 발견 항목 (findings with full metadata)
버킷(bucket)별로 그룹화된 발견 항목 (grouped findings by bucket)
해당 점수가 산출된 이유 (why this score)
점수의 의미 및 한계 (score meaning and limitations)

이를 통해 출력 결과는 CI(지속적 통합) 환경에서 검토 가능하고, 테스트 가능하며, 안정적으로 유지됩니다.

MCP Scorecard는

현재 네 가지 실용적인 출력물을 생성합니다:

로컬 실행 및 CI 로그를 위한 사람이 읽을 수 있는 요약(Human-readable summary).

표준적인 기계 판독 가능 보고서 형식(Canonical machine-readable report format). 안정적인 V1 최상위 구조는 다음과 같습니다:

schema

generator

scan

inventory

scorecard

checks

findings

grouped_findings

metadata

GitHub 코드 스캐닝 및 기타 SARIF 지원 소비자(consumers)를 위한 형식. SARIF는 현재의 발견(findings) 모델과 일치하도록 유지되며, SARIF 실행 시 스코어카드 메타데이터를 포함합니다.

총점, 합격/불합격(pass/fail), 카테고리별 점수를 포함하여 PR(Pull Request)에 친화적인 Markdown 요약.

JUnit은 현재 릴리스 범위에서 의도적으로 제외되었습니다.

점수는 결정론적인 검토 신호(deterministic review signal)입니다.

높은 점수가 반드시 안전함을 의미하지는 않습니다. - 낮은 점수가 반드시 악성임을 의미하지는 않습니다. - 점수는 결정론적이고 검토 가능한 속성만을 측정합니다.

즉, 점수는 다음과 같은 용도로 유용합니다:

CI 게이트 (CI gate)
검토 기준선 (review baseline)
릴리스 아티팩트 (release artifact)
더 넓은 공학적 판단을 위한 입력값 (input to broader engineering judgment)

이는 런타임 제어(runtime controls), 샌드박싱(sandboxing), 환경 격리(environment isolation) 또는 사람의 승인을 대체하는 것이 아닙니다.

현재의 한계점은 명시되어 있습니다:

주요 전송 방식(transport)은 로컬 stdio에 집중되어 있습니다.
체크는 정적이고 결정론적이며, 동적(dynamic)이거나 행동적(behavioral)이지 않습니다.
런타임 격리(runtime isolation)는 범위 외입니다.
취약점 악용 가능성(exploitability) 주장은 범위 외입니다.
비즈니스 의도(business intent)는 범위 외입니다.
LLM 점수 산정(LLM scoring)은 범위 외입니다.
호스팅 스캐닝(hosted scanning)은 범위 외입니다.

이러한 범위 설정은 의도된 것입니다. 더 넓지만 불투명한 시스템보다는, 더 작더라도 결정론적인 계약(contract)이 CI에서는 더 유용합니다.

세 개의 서버를 확정적인 검증 세트로 취급하는 대신, 현재 더 유용한 참조 대상은 30개의 공개 MCP 서버에 대한 전체 배치 스캔(full batch scan)입니다:

해당 배치가 더 나은 결과물(artifact)인 이유는 다음과 같이 구분하기 때문입니다:

깨끗하게 실행되고 점수가 산출되는 서버
실행은 되지만 결정론적(deterministic) 검토 이슈가 나타나는 서버
블라인드 CI 환경에서 깨끗하게 실행되지 않는 서버

전체 배치에서 선택된 흥미로운 사례들:

서버	결과	중요성
`@modelcontextprotocol/server-memory`	`100/100`	현재 규칙 하에서의 깨끗한 공식 기준점 (baseline)
`@modelcontextprotocol/server-filesystem`	`40/100`	스코어카드를 통해 정당한 파일 시스템 변형(mutation) 표면이 명확히 노출됨
`@modelcontextprotocol/server-everything`	`90/100`	사소한 사용성(ergonomics) 발견 사항만 있는 유용한 공식 대조군 (control case)
`ai.meetlark/mcp-server`	`100/100`	깨끗하게 실행되고 점수가 산출되는 컴팩트한 커뮤니티 사례
`ai.social-api/socialapi`	`50/100`	네트워크 노출 관련 발견 사항과 한 가지 준수(conformance) 이슈가 있는 현실적인 제품 서버
`capital.hove/read-only-local-postgres-mcp-server`	`90/100`	작은 스키마 사용성(ergonomics) 이슈가 있는, 거의 깨끗한 데이터베이스 사례

전체 배치는 또한 더 솔직한 결론을 도출했습니다: MCP Scorecard는

유용해 보이지만 재현 가능하며,
대규모 공개 스캔에는 별도의 사전 점검(preflight)/실행 가능성(launchability) 레이어가 필요합니다.

docs/architecture.md
MCP_SCORECARD_30_SERVER_BATCH.md
MCP_SCORECARD_30_SERVER_BATCH.summary.json
docs/assets/filesystem-scan-hero.svg
examples/insecure-server/README.md
.github/workflows/example.yml

현재 릴리스 이후의 단기 작업 사항:

conformance (준수), security (보안), ergonomics (사용성), metadata (메타데이터) 전반에 걸쳐 결정론적 검사 확장
소스 컨텍스트(source context)가 사용 가능한 경우 SARIF 위치 매핑 개선
더 많은 실제 검증 사례 및 샘플 보고서 추가
현재 점수 계약(score contract)이 안정적으로 유지되면 더 많은 전송(transport) 옵션 추가
리포지토리/패키지/액션 참조와 관련된 남은 호환성 명칭 정리

즉각적인 경로에 있지 않은 사항:

코어 엔진 내 LLM 스코어링 (LLM scoring)
호스팅된 스코어카드 서비스 (hosted scorecard service)
릴리스 경로 내 레지스트리 통합 (registry integration)
인증 스타일의 주장 (certification-style claims)

python -m venv .venv
source .venv/bin/activate
pip install -e .[dev]
...

기여하기 좋은 영역:

테스트를 포함한 새로운 결정론적 체크 (new deterministic checks)
stdio 전송 (transport) 강화 - 안정적인 출력을 유지하는 리포터 개선
재현 가능한 검증 케이스 (reproducible validation cases)
문서 및 샘플 아티팩트 (documentation and sample artifacts)

Apache-2.0. LICENSE를 참조하세요.

MCP 서버를 위한 결정론적, CI 우선 품질 스코어카드

요약

핵심 포인트

Windows (PowerShell)

댓글