Mcp Server

MCP(Model Context Protocol) 기반 코딩 컨벤션 / 아키텍처 규칙 점검 서버입니다.
다른 Git 프로젝트(로컬 경로 또는 Git URL)를 입력하면, 의존성·보안 점검과 Python/Java 규칙 분석 등을 MCP 도구(tools) 로 호출할 수 있습니다.

구조

• server.py — FastMCP 인스턴스와 @mcp.tool() 로 노출되는 MCP 도구 정의.

순번	한글 레이블	도구 이름 (호출 시)	인자·역할 요약
1	생존 확인	ping()	MCP 서버 응답 확인
2	금지 라이브러리 점검	check_dependencies(local_path?, git_url?, forbidden_libs?)	예: lombok 등 사용 여부 (git clone 지원)
3	비밀정보 후보 탐지	scan_secrets(local_path?, git_url?)	.env, API 키·토큰 패턴 등
4	Python 규칙 상세 검사	analyze_python(path)	PEP8·레이어·FastAPI 룰 전체
5	Java 규칙 상세 검사	analyze_java(path)	네이밍·레이어·Spring·DTO 등 룰 전체
6	README/docs ↔ 코드 요약	audit_project_vs_docs(project_path, language?, spec_glob?)	language: python, java. 상세는 아래 해당 절·4·5번 도구
7	check.md ↔ 코드 요약	audit_project_vs_check_spec(project_path, language?, spec_path?)	기본 spec_path = check.md. 단일 스펙 문서 기준 정합성

· 구현 모듈 (위 도구와 매핑)

파일	담당 도구 번호	역할
convention_checker/core.py	2, 3	로컬 또는 Git URL → clone·파일 순회·의존성·시크릿 검사
convention_checker/spec_audit.py	6, 7	마크다운·코드 마커·룰 결과를 묶어 문서↔코드 요약 반환
tools/python/analyze_project.py, tools/java/analyze_project.py, engine/*, rules/*	4, 5	언어별 파일 스캔·룰 실행 (RuleResult 목록)

실행

pip install -r requirements.txt

# MCP stdio (Cursor / Claude Desktop 등에서 subprocess 로 붙을 때 — 기본)
python server.py

# MCP over HTTP (클라이언트가 HTTP MCP 를 지원할 때)
python app/main.py

.env 는 기본 동작에 필요하지 않습니다. 필요 시 .env.example 을 참고해 추가하면 됩니다.

Cursor에서 사용

1. Cursor Settings → MCP 에서 서버 추가
2. 설정 예시 (stdio — python server.py 가 표준 입출력으로 MCP 를 처리):

{
  "mcpServers": {
    "convention-checker": {
      "command": "C:/Users/parkj/anaconda3/python.exe",
      "args": ["C:/Users/parkj/Documents/GitHub/Mcp-Server/server.py"],
      "cwd": "C:/Users/parkj/Documents/GitHub/Mcp-Server"
    }
  }
}

3. 채팅/에이전트에서 예시
   • 금지 라이브러리 점검: check_dependencies 에 local_path 또는 git_url, 필요 시 forbidden_libs(예: ["lombok"]) 전달
   • 비밀키 스캔: scan_secrets 에 local_path 또는 git_url 전달
   • Python/Java 규칙: analyze_python / analyze_java 에 프로젝트 루트 경로 전달
   • 문서 대조 요약: audit_project_vs_docs 호출
   • check.md 기준 요약: audit_project_vs_check_spec(project_path, language, spec_path?) 호출

Claude에서 사용

Claude Desktop도 Cursor 와 같이 mcpServers 에 command / args / cwd 로 서버 프로세스를 띄웁니다. 위 Cursor 절의 JSON 과 동일하게 넣으면 됩니다(python/paths 만 본인 환경에 맞게 수정).

1. 설정 파일 열기
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
2. mcpServers 에 convention-checker 항목 추가(기존 서버가 있으면 병합).
3. 저장 후 Claude Desktop 재시작 → 대화에서 MCP 도구 연결 확인.

참고: 웹 브라우저의 Claude(chat)만으로는 로컬 MCP 를 붙이지 못합니다. HTTP MCP 는 app/main.py + 클라이언트의 SSE/HTTP 지원 여부에 따릅니다.

---

공통 분석 흐름 (Python / Java) — 도구 4·5

analyze_python / analyze_java 안에서 아래 순서로 동작합니다.

단계	한글	함수·산출
1	프로젝트 로딩	load_project(path) → 루트 경로·메타 정보
2	파일 스캔	Python: scan_python_files(project) → .py 전부 / Java: scan_java_files(project) → .java 전부
3	룰 실행	run_rules(files, rules) → 내용·AST·임포트 등 준비 후 *_rule 순서 호출 → RuleResult 목록

감사 도구 6·7은 내부에서 같은 분석(analyze_*_project)을 불러 요약만 짧게 돌려줍니다.

문서 ↔ 코드 감사 — 도구 6·7

공통: MCP 응답을 짧게 두기 위해 위반 목록·파일 경로·긴 제안 문장은 넣지 않습니다. 상세는 같은 project_path로 도구 4 또는 5를 호출하세요.

6. README/docs ↔ 코드 (audit_project_vs_docs)

항목	내용
한글 레이블	README·docs 기준 요약 감사
읽는 문서	README.md(대소문자 변형 중 하나) + docs/**/*.md + (선택) spec_glob
인자	project_path(필수), language(python, java, 기본 python), spec_glob(선택)
지원 언어	python, java만. 그 외는 unsupported_language

반환 필드

필드	한글
situation	판정 코드(아래 표)
summary	한 줄 요약
violations	룰 위반 건수
doc_files	읽은 Markdown 개수
drift	문서에 없는 스택으로 추정될 때 코드 쪽 힌트(쉼표 문자열) 또는 null
language	적용 언어

situation (6번)

값	한글
aligned	일치
spec_insufficient	문서 부족(md 없음 또는 본문 합계 약 250자 미만)
mismatch	불일치(룰 위반 또는 문서 신호 vs 코드 마커 휴리스틱 불일치)
unsupported_language	지원하지 않는 language

drift 예시 코드(값 일부): Python — undocumented_fastapi, undocumented_pydantic, undocumented_pytest / Java — undocumented_spring, undocumented_jpa, undocumented_junit, undocumented_lombok 등.

7. check.md ↔ 코드 (audit_project_vs_check_spec)

항목	내용
한글 레이블	단일 스펙 파일 기준 요약 감사
읽는 문서	프로젝트 루트의 한 파일(기본 check.md, spec_path로 변경 가능)
인자	project_path, language, spec_path(선택, 기본 check.md)
추가 반환	spec_file — 실제로 읽은 스펙 파일 경로

situation (7번) — 6번 값에 더해 spec_not_found(해당 경로에 파일 없음). 나머지 spec_insufficient / mismatch / aligned / unsupported_language 의미는 6번과 같습니다.

check.md 템플릿

이 저장소 루트의 check.md가 예시입니다. 점검 대상 프로젝트에도 두고 도구 7로 호출하면 됩니다.

Python 룰 목록 — 도구 analyze_python (4)

대상: Python 프로젝트 루트.

구분	한글	룰 이름
스타일	변수 snake_case	pep8_variable_naming_rule
스타일	한 줄 120자 초과	pep8_line_length_rule
레이어	router → repository 직접 금지	python_layered_router_repository_rule
레이어	router는 service에 의존	python_layered_router_service_rule
레이어	service ↔ router/controller 역의존 금지	python_layered_service_repository_rule
레이어	패키지 구조(router/controller가 repo·service 하위에 있지 않은지)	python_layered_package_structure_rule
FastAPI	라우터가 FastAPI 라우터 import	fastapi_router_rule
FastAPI	fastapi 모듈 사용·의존	fastapi_dependency_rule
FastAPI	Request/Response/Schema 네이밍 분리	fastapi_request_response_schema_rule

Java 룰 목록 — 도구 analyze_java (5)

대상: Java/Spring 프로젝트 루트.

구분	한글	룰 이름
스타일	클래스 PascalCase	java_class_naming_rule
스타일	메서드 camelCase	java_method_naming_rule
레이어	controller → repository 직접 금지	java_layered_controller_repository_rule
레이어	controller는 service에 의존	java_layered_controller_service_rule
레이어	service ↔ controller 역의존 금지	java_layered_service_repository_rule
Service	데이터 변경 시 @Transactional	java_service_transaction_rule
Service	생성자 주입(필드 @Autowired 지양)	java_service_constructor_injection_rule
Service	엔티티 직접 반환 지양·DTO 등	java_service_return_dto_rule
DTO	Request/Response 구분	java_dto_request_response_separation_rule
Spring	@RestController / @Controller	spring_controller_annotation_rule
Spring	ResponseEntity / 공통 ApiResponse 등	spring_controller_response_wrapper_rule
Spring	@Service	spring_service_annotation_rule
Spring	@Repository	spring_repository_annotation_rule

한 줄 요약

4·5: 로드 → 스캔 → *_rule 실행 → RuleResult 리스트.6·7: 문서 + 같은 분석을 묶어 짧은 요약만 반환.