gristmill-mcp

AI가 생성한 코드를 검사하고 구조적 및 안전 위반 사항의 결정적 목록을 반환하여, AI 코딩 에이전트가 코드가 배포되기 전에 자체 출력을 수정할 수 있게 하는 MCP 서버입니다.

Grist는 방앗간에 갈기 위해 가져온 곡물입니다. AI 출력물은 그리스트(grist)입니다. 진정으로 가치 있는 원재료이지만 가공되지 않았습니다. 방앗간이 그것에 구조를 부여합니다.

AI가 그리스트를 작성합니다. Gristmill이 배송 가능한 코드로 만듭니다.

왜 스킬이 아닌 MCP 서버인가

스킬은 모델의 컨텍스트에 로드되는 텍스트입니다. 모델이 알고 있는 것을 변경합니다. MCP 서버는 모델이 실행하는 프로그램입니다. 모델이 할 수 있는 것을 변경합니다.

스타일 지침("느슨한 함수보다 클래스를 선호하세요")은 스킬에 속합니다. 검증("이 파일은 12, 40, 66행에 7개의 최상위 함수가 있습니다")은 파일에 대해 코드를 실행해야 합니다. 모델이 자신의 출력을 읽고 "이것은 함수가 너무 많은 것 같다"고 추론하는 것은 관찰로 가장한 추측입니다. 이 파일에서 "너무 많다"는 것이 무엇을 의미하는지에 대한 기본 진실이 없고, 신뢰할 수 있는 계산 방법도 없습니다. Gristmill은 AST를 파싱하고 계산합니다. 이러한 차이(지시 대 실행)가 이 도구가 조언의 단락 대신 서버로 존재하는 이유입니다.

서버는 LLM을 호출하지 않으며, 동일한 입력에 대해 실행 간에 변하지 않으며, 신뢰도 점수를 내보내지 않습니다. 동일한 입력 → 매번 동일한 바이트 출력. 그 결정론이 바로 제품의 전부입니다. AI 계층은 이 서버 위에 위치하여 결과를 소비하고 그에 대해 무엇을 할지 결정합니다. 서버의 작업은 행 번호와 함께 사실을 보고하는 데서 끝납니다.

Related MCP server: code-verify-mcp

Install

git clone <this repo> gristmill-mcp
cd gristmill-mcp
python3 -m venv .venv
.venv/bin/pip install -e .

Claude Code

CLI에 등록하고, venv의 콘솔 스크립트를 가리킵니다:

claude mcp add gristmill -- /absolute/path/to/gristmill-mcp/.venv/bin/gristmill-mcp

또는 MCP 구성에 직접 추가합니다(프로젝트의 .mcp.json 또는 글로벌 Claude Code 구성):

{
  "mcpServers": {
    "gristmill": {
      "command": "/absolute/path/to/gristmill-mcp/.venv/bin/gristmill-mcp"
    }
  }
}

기타 MCP 클라이언트

모든 stdio 기반 MCP 클라이언트는 동일한 바이너리를 실행할 수 있습니다. gristmill-mcp(또는 venv 내에서 python3 -m gristmill.server)는 클라이언트별 구성 없이 표준 MCP stdio 전송을 사용합니다.

명령줄(MCP 클라이언트 없음)

로컬 테스트를 위해, 또는 아래의 작업 예제를 재현하기 위해, 얇은 CLI가 동일한 엔진을 감쌉니다:

.venv/bin/gristmill-verify path/to/file_or_dir [--checks secrets structure comment_slop] [--severity-floor warning] [--json]

작업 예제

demo/billing.py, Stripe 청구 도우미의 편집되지 않은 초안:

import stripe

# I've added this as you requested — sets up the Stripe client
STRIPE_SECRET_KEY = None  # was a literal sk_live_... key — see note below

stripe.api_key = STRIPE_SECRET_KEY


def customer_create(config):
    return stripe.Customer.create(**config)


def customer_delete(config):
    return stripe.Customer.delete(config["id"])


def customer_find(config):
    return stripe.Customer.retrieve(config["id"])


def customer_update(config):
    return stripe.Customer.modify(config["id"], **config)

.venv/bin/gristmill-verify demo/billing.py

위의 None 대신 실제 Stripe 라이브 키 형태의 리터럴을 사용한 출력:

gristmill: 1 files scanned, 0 skipped (2 error, 4 warning, 0 info) in 1ms
  [WARNING] STR002  billing.py:1  4 top-level functions share the prefix `customer_` — consider a `Customer` class or module
  [WARNING] STR003  billing.py:1  4 top-level functions take a first parameter named `config` — consider making it instance state
  [WARNING] CMT001  billing.py:3  Comment addresses the reader conversationally ('as you requested')
  [ERROR  ] SEC006  billing.py:4:22  Stripe live key assigned to `STRIPE_SECRET_KEY`
  [ERROR  ] SEC010  billing.py:4:22  String literal assigned to `STRIPE_SECRET_KEY`, which looks credential-shaped
  [WARNING] SEC011  billing.py:4:22  High-entropy string literal (5.1 bits/char) assigned to `STRIPE_SECRET_KEY`

(파일 경로는 가장 가까운 .gristmill.toml을 기준으로 표시됩니다. demo/ 디렉토리는 자체 .gristmill.toml을 가지고 있어 이 예제의 출력이 최상위 프로젝트 구성과 무관하게 안정적으로 유지됩니다.)

참고: GitHub의 푸시 보호는 실제 형식의 비밀을 포함하는 모든 푸시된 파일을 차단합니다. 주석이나 마크다운 코드 블록, 이 README를 포함합니다. demo/billing.py는 현재 초기 푸시를 차단 해제하기 위해 키가 None으로 대체되었습니다. 이는 데모를 다시 활성화하기 위해 (허용 목록에 추가된 비밀 스캔 예외를 통해) 복원해야 할 TODO입니다.

--json 플래그(또는 두 가지를 모두 반환하는 verify MCP 도구)는 전체 구조화된 형식을 제공합니다. 파일, 행, 열, 정적 제안 문자열, 그리고 수정된 evidence 필드(sk_l… (49자), 키 자체는 절대 포함되지 않음).

Tools

verify

소스 파일에서 비밀, 구조적 문제, 저품질 주석을 검사합니다. 파일 경로와 행 번호가 포함된 결정적 결과를 반환합니다. 코드를 생성하거나 편집한 후, 완료된 것으로 제시하기 전에 이것을 호출하세요.

입력: paths (필수, 파일 또는 디렉토리), checks (선택 사항, secrets/structure/comment_slop의 하위 집합, 기본값 모두), severity_floor (선택 사항, 기본값 info).

출력: 간결한 사람이 읽을 수 있는 요약과 함께 전체 구조화된 JSON(파일, 행, 열, 메시지, 수정된 증거, 규칙별 정적 제안 문자열)이 이어집니다. 결과는 항상 path, line, rule_id 순으로 정렬됩니다. 이러한 안정성이 실행을 바이트 단위로 동일하게 만들고 모델이 문제로 바로 이동할 수 있게 합니다.

explain_rule

rule_id(예: SEC001)를 받아 그 근거, 잡아내는 것, 놓치는 것, 그리고 억제 방법을 반환합니다. docs/RULES.md와 동일한 내용으로, 필요 시 제공되어 verify 출력을 간결하게 유지할 수 있습니다.

Rules

각 규칙에 대한 전체 근거, 위음성 참고 사항, 억제 지침: docs/RULES.md.

Configuration

.gristmill.toml을 프로젝트 루트에, 모든 키는 선택 사항:

[checks]
enabled = ["secrets", "structure", "comment_slop"]

[structure]
max_top_level_functions = 5
max_function_lines = 60

[secrets]
entropy_threshold = 4.5

[ignore]
paths = ["legacy/**", "vendor/**"]
rules = ["CMT003"]

.gristmillignore 파일(gitignore 구문)이 [ignore] paths와 함께 작동합니다. 인라인 억제도 플래그가 지정된 행 또는 그 위 행에서 인정됩니다:

SUPPRESSED = "ghp_" + "..."  # gristmill: ignore SEC003

// gristmill: ignore SEC003
const suppressed = "ghp_" + "...";

Language support

• Python — 완전 지원 (stdlib ast 및 tokenize).

• JavaScript/TypeScript — 완전 지원. Node 기반 파서를 호출하는 대신 tree-sitter와 컴파일된 tree-sitter-javascript 및 tree-sitter-typescript 문법을 통해 지원됩니다. 이는 호스트에 Node가 전혀 설치되어 있지 않아도 독립성을 위해 컴파일된 Python 의존성을 교환합니다. structure 및 comment_slop은 node가 PATH에 있는지 여부에 관계없이 동일하게 작동하며, 텍스트 전용 폴백 대신 실제 AST를 제공합니다.

• 기타 — secrets 검사는 여전히 실행됩니다(정규식 기반이며 언어에 구애받지 않음). 해당 파일의 structure 및 comment_slop은 건너뛰고 skipped_paths에 보고됩니다.

Limitations

도구가 얻은 것보다 더 신뢰하기 전에 이것을 읽으세요:

• secrets는 형태가 있거나 높은 엔트로피의 문자열만 잡아냅니다. hunter2와 같은 낮은 엔트로피의 인간 비밀번호는 절대 플래그되지 않습니다. 일반적인 짧은 문자열과 구별할 신뢰할 수 있는 방법이 없기 때문입니다. 런타임에 조합된 자격 증명(문자열 연결, os.environ.get(...) or "fallback", base64 디코딩된 조각)은 정적 텍스트에 대한 정규식/엔트로피 검사에서 보이지 않습니다.

• 파일에 걸친 구조적 문제는 보이지 않습니다. structure는 한 번에 하나의 파일을 봅니다. 파일에 걸쳐 분할되어야 하는 클래스나 두 개의 다른 모듈에 중복된 로직은 범위 밖입니다.

• comment_slop의 CMT002는 의도적으로 좁습니다. 이는 집합에서 가장 높은 위양성 위험 규칙이므로, 침묵 쪽으로 강하게 편향되도록 구현되었습니다. 실제 설명을 과도하게 플래그하는 것보다 훨씬 더 자주 놓칠 것입니다. 정확한 하위 집합 일치 규칙은 docs/RULES.md를 참조하세요.

• Python 및 JS/TS 외부 언어는 secrets 전용 범위를 얻습니다. v1에서는 Go, Rust, Ruby 등에 대한 구조적 또는 주석 분석이 없습니다.

• 이것은 git 기록 내 비밀 스캐너가 아닙니다. 주어진 대로 작업 트리를 검사합니다. 커밋되었다가 현재 파일에서 제거된 키는 이 도구의 관심사가 아닙니다(git 기록 스캐너는 다른 보완 도구입니다).

• 자동 수정 없음. Gristmill은 보고합니다. 호출 모델이 무엇을 어떻게 변경할지 결정합니다. 이러한 분할은 의도적입니다(위의 "왜 스킬이 아닌 MCP 서버인가" 참조), 하지만 이는 verify 호출만으로는 아무것도 수정하지 않음을 의미합니다.

자신의 범위를 과장 판매하는 도구는 맹점에 대해 솔직한 도구보다 나쁩니다. 여기서 침묵은 시끄러운 결과만큼이나 잘못된 자신감을 이깁니다.

Roadmap

v1의 범위에서 명시적으로 제외된 항목, 대략적인 우선순위 순서:

• 자동 수정/패치 생성 (호출 모델이 오늘날 verify 결과를 사용하여 이를 수행함)

• 의존성 최신 상태 및 CVE 확인 (패키지 레지스트리에 대한 네트워크 호출 필요 — 자연스러운 v2)

• Python 및 JavaScript/TypeScript를 넘어선 언어 지원

• 커밋되었다가 나중에 제거된 비밀에 대한 Git 기록 스캔

• 호스팅 서비스, 웹 UI 또는 대시보드

Development

.venv/bin/pip install -e ".[dev]"
.venv/bin/pytest tests/ -q

src/gristmill/rules.py를 편집한 후 docs/RULES.md를 다시 생성하세요:

.venv/bin/python3 scripts/generate_rules_doc.py

테스트는 (tests/) 다음을 포함합니다: 알려진 더러운 고정 장치 디렉토리에 대한 골든 파일 출력, 병렬 처리 유무에 따른 10배 결정론, 결과를 0개 생성해야 하는 위양성 코퍼스, 수정(원시 비밀이 출력 필드에 도달하지 않음), 복원력(잘못된 구문, 바이너리, 빈 파일, 초대형 파일이 실행을 중단시키지 않음).

License

MIT — LICENSE 참조.