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에서 사용
- Cursor Settings → MCP 에서 서버 추가
- 설정 예시 (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"
}
}
}- 채팅/에이전트에서 예시
- 금지 라이브러리 점검:
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 만 본인 환경에 맞게 수정).
- 설정 파일 열기
- Windows:
%APPDATA%\Claude\claude_desktop_config.json - macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
mcpServers에convention-checker항목 추가(기존 서버가 있으면 병합).- 저장 후 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: 문서 + 같은 분석을 묶어 짧은 요약만 반환.
