MCP Tools Py

모델 컨텍스트 프로토콜(Model Context Protocol, MCP) 서버로, 쉬운 클라이언트 설정을 통해 코드 품질 검사 작업을 제공합니다. 이 서버는 MCP 프로토콜 설계를 따라 지정된 프로젝트 디렉토리 내에서 코드 품질 검사를 수행하기 위한 API를 제공합니다.

개요 (Overview)

이 MCP 서버는 Claude(Claude Desktop을 통한 방식), GitHub Copilot이 통합된 VSCode 또는 기타 MCP 호환 클라이언트가 Python 프로젝트에 대해 코드 품질 검사, 포맷팅 및 리팩토링을 실행할 수 있도록 합니다. 전체 목록은 사용 가능한 도구 (Available Tools)를 참조하십시오.

범위: 이 서버는 Python 프로젝트만을 다룹니다. 다른 언어에 대한 지원은 유사한 기능을 가진 별도의 전용 MCP 서버를 통해 제공될 수 있습니다.

bash 접근 대신 전용 MCP 서버를 사용하는 이유?

일반 목적의 bash MCP 도구는 더 많은 유연성을 허용하지만, 그 대가로 제어력이 떨어집니다. 이 서버는 보다 집중적인 접근 방식을 취합니다:

보안 (Security): 정의된 도구 세트만 실행할 수 있습니다 — 사용 가능한 도구 (Available Tools) 참조. 모든 작업은 지정된 project_dir에 한정됩니다.
컨텍스트 관리 (Context management): AI 어시스턴트의 컨텍스트 부하를 줄이기 위해 결과가 포맷되고 크기가 제한됩니다. 출력은 원시 도구 출력이 아닌 실행 가능한 프롬프트 형태로 구조화됩니다.
투명성 (Transparency): 서버는 오픈 소스이며, 상세한 구조적 로깅을 통해 모든 도구 호출(매개변수, 타이밍 및 결과)이 기록됩니다.

기능 (Features)

모든 도구는 사용 가능한 도구 (Available Tools)에 나열되어 있습니다. 아래 섹션들은 가장 많이 사용되는 도구들의 매개변수를 문서화합니다.

Pylint 매개변수 (Pylint Parameters)

pylint 도구는 커스터마이징을 위해 다음 매개변수를 노출합니다:

매개변수	타입	기본값	설명
`extra_args`	list	None	추가적인 pylint CLI 인수의 선택적 목록 (예: `["--disable=W0611"]`)
...

Pylint 구성 (Pylint Configuration)

Pylint는 프로젝트의 pyproject.toml을 자동으로 읽습니다. pyproject.toml 내에서 [tool.pylint.messages_control]을 구성하여 보고할 이슈를 제어할 수 있습니다. 예시 및 마이그레이션 가이드는 docs/pyproject-configuration.md를 참조하십시오.

타겟 디렉토리 자동 감지 (Target Directory Auto-Detection)

target_directories가 지정되지 않은 경우, 해당 기능을 수용하는 도구들(pylint, mypy, ruff check, ruff fix, bandit, vulture 및 run_format_code)은 pyproject.toml에서 디렉토리를 자동으로 감지합니다:

소스 디렉토리 (Source dirs): [tool.setuptools.packages.find] where 에서 가져옵니다 (폴백: ["src"]).
테스트 디렉토리 (Test dirs): [tool.pytest.ini_options] testpaths 에서 가져옵니다 (폴백: ["tests"]).

run_deptry_check는 테스트 경로를 제외하고 소스 디렉토리만 자동으로 감지합니다.

디스크에 실제로 존재하는 디렉토리만 포함됩니다. 명시적인 목록을 전달하여 자동 감지를 재정의할 수 있습니다:

["src"]: 소스 코드 디렉토리만 분석합니다.
["src", "tests"]: 소스 및 테스트 디렉토리를 모두 분석합니다.
["mypackage", "tests"]: 패키지 구조가 다른 프로젝트용입니다.
["."]: 전체 프로젝트 디렉토리를 분석합니다 (대규모 프로젝트의 경우 느릴 수 있습니다).

Pytest 파라미터 (Pytest Parameters)

run_pytest_check는 사용자 정의를 위해 다음 파라미터를 노출합니다:

파라미터	타입	기본값	설명
`markers`	list	None	테스트 필터링을 위한 선택적 pytest 마커 목록
...
참고: 이 도구는 절대 `-n` 옵션을 추가하지 않습니다. 병렬로 실행되는 테스트는 사용자가 `-n`을 전달하거나 프로젝트의 `addopts`가 이를 설정할 때만 발생합니다. `-n 0`은 pytest-xdist를 비활성화합니다.

실행 결과: 검증된 성공(verified pass)인 경우 "Pytest check completed."를 읽습니다. 테스트 실패는 실패 세부 정보를 보여줍니다. 오류가 발생한 실행 (테스트 실패가 없거나 xdist 컬렉션 불일치로 인한 0이 아닌 종료 코드 포함)의 경우, 종료 코드와 문제점과 함께 "Pytest run reported an error."를 읽습니다. 테스트를 수집했지만 결과를 보고하지 않은 실행은 "Collected N tests but none reported an outcome. Not verified."를 읽습니다.

커버리지(Coverage): coverage=True를 사용하려면 프로젝트 환경에 pytest-cov가 설치되어야 합니다. 다이제스트(digest)는 전체 개수를 제공하며, 가장 많은 누락된 구문과 해당 함수별 라인 범위를 가진 모듈, 아무것도 커버되지 않은 모듈, 그리고 테스트 선택의 숫자가 나오는 근거를 보여줍니다. 프로젝트의 fail_under는 보고되지만 적용되지는 않으므로, 합격/불합격 여부는 오직 테스트만을 반영합니다. 코드를 제외하려면 coverage 자체의 [tool.coverage.run] omit을 사용하거나 # pragma: no cover를 사용하십시오.

Mypy 매개변수(Parameters)

Mypy 도구는 다음과 같은 매개변수를 노출하여 사용자 정의를 할 수 있습니다:

매개변수	타입	기본값	설명
`disable_error_codes`	list	None	무시할 mypy 오류 코드 목록
...

Mypy 설정(Configuration)

Mypy는 프로젝트의 pyproject.toml을 자동으로 읽으며, [tool.mypy]가 플래그 세트의 유일한 진실 공급원(single source of truth)입니다 — 사용자가 follow_imports, cache_dir 또는 disable_error_codes를 전달하는 경우가 아니라면 도구는 출력 형식 지정용 플래그만 추가합니다. 자체적인 [tool.mypy] 섹션이 없는 프로젝트는 바닥(floor)이 없습니다: 범위 내에 설정이 없으면 mypy의 기본값으로 실행되어 매우 적은 검사만을 수행했음에도 "passed"를 보고하며; 부모 디렉터리의 설정 (mypy 1.15 이상) 또는 사용자 레벨의 ~/.config/mypy/config나 ~/.mypy.ini가 범위 내에 있으면 해당 설정으로 실행되어 프로젝트가 요청하지 않은 오류까지 보고할 수 있습니다. 마이그레이션 가이드와 mypy 캐시에 미치는 영향은 docs/pyproject-configuration.md를 참조하십시오.

명령줄 인터페이스(CLI)

기본 사용법

mcp-tools-py --project-dir /path/to/project [options]

필수 매개변수(Required Parameters)

매개변수	타입	설명
`--project-dir`	string	필수. 코드 검사 작업의 기본 디렉터리

선택적 매개변수(Optional Parameters)

Python 설정

Parameter	Type	Default	Description
`--python-executable`	string	sys.executable	프로젝트 환경의 파이썬 인터프리터 경로입니다. pytest, pylint, mypy 및 deptry는 이 환경에서 실행되며 라이브러리/심볼 조회는 이를 기준으로 해결되므로, 반드시 프로젝트 종속성을 보유하고 deptry가 설치된 환경이어야 합니다. black, isort, ruff, bandit, vulture, tach 및 lint-imports는 mcp-tools-py 자체 환경에서 가져오므로 여기에 설치할 필요는 없습니다. bare name은 PATH에서 조회되며, 존재하지 않거나 해결되지 않는 경로는 시작 시 오류가 발생합니다.
`--venv-path`	string	None	사용 중단됨(Deprecated), `--help`에 숨겨져 있습니다. 여전히 허용되며 인터프리터를 해결하지만( `--python-executable`보다 우선함), 도구를 찾는 데는 더 이상 사용되지 않습니다. 대신 `--python-executable`을 사용하십시오.

테스트 설정

Parameter	Type	Default	Description
`--test-folder`	string	"tests"	테스트 폴더 경로 (프로젝트-디렉터리 기준)
`--keep-temp-files`	flag	False	테스트 실행 후 임시 파일을 유지할지 여부. 테스트 실패 시 디버깅에 유용합니다.

로깅 설정

Parameter	Type	Default	Description
`--log-level`	string	"INFO"	로깅 레벨을 설정합니다. 선택지: DEBUG, INFO, WARNING, ERROR, CRITICAL
...

도구 설정

Parameter	Type	Default	Description
`--check-timeout`	integer	None (120; pytest 300)	모든 검사기 및 포매터 서브프로세스에 대한 타임아웃 시간(초). 프로젝트의 `pyproject.toml` 내 `[tool.mcp-tools-py]`에서 도구별로 재정의할 수 있습니다 — 프로젝트 설정 참조
...

참고 사항

더 이상 사용되지 않는(deprecated) --venv-path를 지정하면, 이 값이 --python-executable보다 우선권을 갖습니다. 이제 인터프리터를 해석하는 것이 유일한 효과입니다.
--console-only 플래그는 개발 중에 로그 파일 생성을 방지하는 데 유용합니다.
로그 파일은 구조화된 분석을 위해 JSON 형식으로 생성됩니다.
임시 파일은 --keep-temp-files가 지정되지 않는 한 자동으로 정리됩니다.

환경 구성 (Environment Configuration)

두 가지 환경이 작동하며, 이 중 하나만 구성할 수 있습니다:

프로젝트 환경(project env) — --python-executable로 이름 지어집니다. 프로젝트의 의존성을 담고 있으며, pytest, pylint, mypy, deptry와 같이 작업을 수행하기 위해 해당 의존성을 가져오거나 검사해야 하는 도구들이 포함됩니다. 라이브러리 및 심볼 해석(get_library_source, list_symbols, find_references)은 동일한 인터프리터를 따르므로, 이 플래그를 잘못된 venv에 지정하면 이러한 도구들이 잘못된 패키지에 대해 해석하게 됩니다.
도구 환경(tool env) — mcp_tools_py 자체가 설치되는 곳입니다. 여기에는 black, isort, ruff, bandit, vulture, tach, lint-imports가 포함되며, 이는 mcp-tools-py 자체의 의존성입니다. 이 환경은 구성할 수 없습니다.

따라서 이 일곱 가지 도구는 도구 환경(tool env)의 버전을 사용하여 실행되므로, 프로젝트가 고정하는 버전과 다를 수 있습니다. 그러므로 CI와 패리티를 중요하게 생각하는 프로젝트는 두 곳 모두에서 호환 가능한 범위를 유지해야 합니다. lint-imports는 여전히 작업 중인 트리(working tree)를 확인합니다: 도구 환경에서 실행되지만, import-linter 설정 파일에서 읽고 프로젝트 인터프리터를 통해 위치가 파악된 프로젝트의 루트 패키지를 찾습니다. 해당 루트 패키지 내부의 사용자 정의 contract_types 항목은 여전히 동일한 브릿지를 통해 해석됩니다. 오직 프로젝트 환경에만 설치되는 별도의 배포판(distribution) 내부에 있는 것은, 루트 패키지의 디렉터리만 전달되기 때문에 그렇지 않습니다.

아래 첫 번째 예시는 환경 변수를 보간(interpolating)하여 해당 경로를 구성하므로, 설정되지 않았거나 오래된 변수는 --python-executable을 아무것도 가리키지 않게 만듭니다. 이 경우 서버는 프로젝트의 도구가 누락되었다고 보고 시작하는 대신, 플래그 이름을 언급하며 FileNotFoundError로 시작 시 실패합니다. 대신, python3와 같은 단순 인터프리터 이름은 PATH에서 검색됩니다.

올바른 구성(Correct Configuration)

pytest, pylint 및 mypy가 설치된 프로젝트의 venv를 가리키세요. Windows에서는 다음과 같습니다:

{
    "mcpServers": {
        "mcp-tools-py": {
...

macOS와 Linux에서는 인터프리터가 대신 bin에 위치합니다:

                "--python-executable", "${VIRTUAL_ENV}/bin/python"

잘못된 구성(Incorrect Configuration)

프로젝트의 인터프리터가 아닌 곳을 가리키지 마세요:

{
    "mcpServers": {
        "mcp-tools-py": {
...

시스템 인터프리터 또는 프로젝트의 것이 아닌 모든 venv는 pytest, pylint 및 mypy가 누락되었다고 보고하며 라이브러리 및 심볼 검색을 잘못된 패키지에 대해 해결합니다. 만약 해당 세 가지 도구가 프로젝트 자체의 .venv에 설치되어 있지 않다면, 프로젝트도 같은 방식으로 실패합니다. 따라서 플래그를 다른 곳으로 지정하기보다는 그곳에 설치해야 합니다.

문제 해결(Troubleshooting)

문제 해결 (Troubleshooting)

"Python interpreter not found"가 시작 시 발생할 경우: --python-executable이 존재하지 않는 경로를 가리키고 있다는 의미입니다. 이는 일반적으로 해당 인터폴레이션(interpolation)에 사용되는 환경 변수(environment variable)가 설정되지 않았기 때문입니다. 메시지에는 경로를 제공한 플래그 이름이 명시되어 있습니다.
"No module named pytest" (또는 pylint/mypy): --python-executable이 필요한 도구들이 설치되어 있지 않은 환경을 가리키고 있다는 의미입니다. 프로젝트의 환경(environment)을 지정하고 해당 환경에 도구들을 설치해야 합니다.
"ruff is not available" (또는 black/isort/bandit/vulture/tach/lint-imports): 이 콘솔 스크립트들은 --python-executable에서 오는 것이 아니라, 별도의 도구 환경(tool env)에서 옵니다. 따라서 해당 플래그가 문제가 아닙니다. 이는 mcp-tools-py의 종속성(dependency)이며, 메시지에는 검색된 도구 환경 디렉터리가 명시되어 있습니다. mcp-tools-py와 그 종속성들을 재설치하고 서버를 다시 시작하십시오.
누락된 도구를 설치한 후: pytest, pylint 및 mypy는 한 번 실행되는 구성된 인터프리터를 통해 확인되며(probe), 이 결과는 프로세스 수명 주기 동안 캐시됩니다. 따라서 이 세 가지 중 하나를 설치했다면 MCP 서버를 재시작해야 합니다.

설치 (Installation)

자세한 설치 지침은 INSTALL.md를 참조하십시오.

빠른 설치:

# GitHub에서 설치 (권장)
pip install git+https://github.com/MarcusJellinghaus/mcp-tools-py.git

...

개발 환경 설치:

# 클론 후 개발용으로 설치
git clone https://github.com/MarcusJellinghaus/mcp-tools-py.git
cd mcp-tools-py
...

MCP 클라이언트 설정 (MCP Client Configuration)

이 서버는 mcp-config를 통해 구성할 수 있습니다. 이는 사용자가 직접 설치하는 별도의 Python 도구이며, 이 패키지의 종속성은 아닙니다. mcp-config는 다음 기능을 제공합니다:

대화형 설정 (Interactive setup): Claude Desktop 및 VSCode와 연동됩니다.
설정 관리 (Configuration management): 서버 구성을 추가, 제거 및 조회할 수 있습니다.
서버 저장소 (Server repository): 선별된 MCP 서버 컬렉션에 접근할 수 있습니다.

사전 요구 사항: Python을 설치한 후, mcp-config를 별도로 설치하십시오.

참고: Windsurf나 Cursor와 같은 다른 MCP 클라이언트들도 MCP 서버를 지원하지만, 수동 설정이 필요할 수 있습니다.

MCP 도구 Py를 이용한 코드 품질 검사 서버

요약

핵심 포인트

MCP Tools Py

개요 (Overview)

기능 (Features)

Pylint 매개변수 (Pylint Parameters)

Pylint 구성 (Pylint Configuration)

타겟 디렉토리 자동 감지 (Target Directory Auto-Detection)

Pytest 파라미터 (Pytest Parameters)

Mypy 매개변수(Parameters)

Mypy 설정(Configuration)

명령줄 인터페이스(CLI)

기본 사용법

필수 매개변수(Required Parameters)

선택적 매개변수(Optional Parameters)

Python 설정

테스트 설정

로깅 설정

도구 설정

참고 사항

환경 구성 (Environment Configuration)

올바른 구성(Correct Configuration)

잘못된 구성(Incorrect Configuration)

문제 해결(Troubleshooting)

문제 해결 (Troubleshooting)

설치 (Installation)

MCP 클라이언트 설정 (MCP Client Configuration)

의존성으로 사용하기

requirements.txt에 작성하기

댓글

MCP Tools Py

개요 (Overview)

기능 (Features)

Pylint 매개변수 (Pylint Parameters)

Pylint 구성 (Pylint Configuration)

타겟 디렉토리 자동 감지 (Target Directory Auto-Detection)

Pytest 파라미터 (Pytest Parameters)

Mypy 매개변수(Parameters)

Mypy 설정(Configuration)

명령줄 인터페이스(CLI)

기본 사용법

필수 매개변수(Required Parameters)

선택적 매개변수(Optional Parameters)

Python 설정

테스트 설정

로깅 설정

도구 설정

참고 사항

환경 구성 (Environment Configuration)

올바른 구성(Correct Configuration)

잘못된 구성(Incorrect Configuration)

문제 해결(Troubleshooting)

문제 해결 (Troubleshooting)

설치 (Installation)

MCP 클라이언트 설정 (MCP Client Configuration)

의존성으로 사용하기

requirements.txt에 작성하기