MCP-CLI: 모델 컨텍스트 프로토콜 명령줄 인터페이스 도구

프로젝트 개요

MCP-CLI는 모델 컨텍스트 프로토콜(Model Context Protocol, MCP) 서버와 상호 작용하도록 특별히 설계된 강력하고 기능이 풍부한 명령줄 인터페이스 도구입니다. 이 도구는 CHUK-MCP 프로토콜 라이브러리를 통합하여 사용자에게 대규모 언어 모델(LLM)과의 원활한 통신 기능을 제공합니다.

이 클라이언트 도구는 도구 사용, 대화 관리 및 다양한 작동 모드를 지원하며, 핵심 프로토콜 구현은 독립적인 패키지로 마이그레이션되어 CLI는 풍부한 사용자 경험을 제공하는 데 집중하고 프로토콜 라이브러리는 통신 계층을 처리합니다.

핵심 기능

🔄 다양한 작동 모드

• 채팅 모드(Chat Mode): 직접 LLM 상호 작용 및 자동화된 도구 사용을 지원하는 대화형 인터페이스
• 인터랙티브 모드(Interactive Mode): 직접 서버 작업을 위한 명령 기반 인터페이스
• 명령 모드(Command Mode): 스크립트 자동화 및 파이프 작업을 지원하는 Unix 친화적 모드
• 직접 명령: 인터랙티브 모드에 진입할 필요 없이 단일 명령 실행

🌐 다중 제공자 지원

• OpenAI 통합: gpt-4o-mini, gpt-4o, gpt-4-turbo 등 모델 지원
• Ollama 통합: llama3.2, qwen2.5-coder 등 로컬 모델 지원
• 확장 가능한 아키텍처: 다른 제공자 추가 지원

🛠️ 강력한 도구 시스템

• 서버가 제공하는 도구 자동 검색
• 서버 인식 도구 실행
• 도구 호출 기록 추적 및 분석
• 복잡한 다단계 도구 체인 지원

💬 고급 대화 관리

• 완전한 대화 기록 추적
• 특정 메시지 범위 필터링 및 보기 지원
• 디버깅 또는 분석을 위한 JSON 내보내기 기능
• 토큰 사용량 감소를 위한 대화 압축 기능

🎨 풍부한 사용자 경험

• 컨텍스트 인식 명령 자동 완성
• 컬러 형식의 콘솔 출력
• 장시간 실행 작업에 대한 진행률 표시기
• 자세한 도움말 및 문서

🔧 안정적인 리소스 관리

• 적절한 비동기 IO 리소스 정리
• 우아한 오류 처리
• 깔끔한 터미널 복구
• 여러 동시 서버 연결 지원

시스템 요구 사항

• Python 3.11 이상
• OpenAI의 경우: OPENAI_API_KEY 환경 변수에 유효한 API 키 설정 필요
• Ollama의 경우: 로컬 Ollama 설치 필요
• 서버 구성 파일 (기본값: server_config.json)
• CHUK-MCP 프로토콜 라이브러리

설치 방법

표준 설치

# 저장소 복제
git clone https://github.com/chrishayuk/mcp-cli
cd mcp-cli

# 패키지 및 개발 종속성 설치
pip install -e ".[cli,dev]"

# CLI 실행
mcp-cli --help

UV를 사용한 종속성 관리

# UV 설치 (설치되지 않은 경우)
pip install uv

# 종속성 설치
uv sync --reinstall

# UV를 사용하여 실행
uv run mcp-cli --help

사용 가이드

전역 옵션

모든 명령은 다음 전역 옵션을 지원합니다:

• --server: 연결할 서버 지정 (여러 서버는 쉼표로 구분)
• --config-file: 서버 구성 파일 경로 (기본값: server_config.json)
• --provider: 사용할 LLM 제공자 (openai 또는 ollama, 기본값: openai)
• --model: 사용할 특정 모델 (제공자의 기본값에 따라 다름)
• --disable-filesystem: 파일 시스템 접근 비활성화 (기본값: true)

채팅 모드

채팅 모드는 LLM과의 대화형 인터페이스를 제공하며, 필요할 때 사용 가능한 도구를 자동으로 사용합니다:

# 기본 채팅 모드
mcp-cli chat --server sqlite

# 제공자 및 모델 지정
mcp-cli chat --server sqlite --provider openai --model gpt-4o
mcp-cli chat --server sqlite --provider ollama --model llama3.2

채팅 모드 슬래시 명령

채팅 모드에서는 다음 슬래시 명령을 사용할 수 있습니다:

도움말 명령:

• /help: 사용 가능한 명령 표시
• /help <command>: 특정 명령에 대한 자세한 도움말 표시
• /quickhelp 또는 /qh: 자주 사용하는 명령에 대한 빠른 참조 표시

도구 관련:

• /tools: 모든 사용 가능한 도구 및 해당 서버 정보 표시
• /tools --all: 매개변수를 포함한 자세한 도구 정보 표시
• /tools --raw: 원시 도구 정의 표시
• /toolhistory 또는 /th: 현재 세션의 도구 호출 기록 표시

대화 관리:

• /conversation 또는 /ch: 대화 기록 표시
• /save <filename>: 대화 기록을 JSON 파일로 저장
• /compact: 대화 기록을 요약으로 압축

인터페이스 제어:

• /cls: 화면을 지우지만 대화 기록은 유지
• /clear: 화면과 대화 기록 모두 지우기
• /verbose 또는 /v: 자세한 도구 표시 모드와 간결한 도구 표시 모드 전환

인터랙티브 모드

인터랙티브 모드는 슬래시 명령을 사용하여 직접 서버 상호 작용을 위한 명령줄 인터페이스를 제공합니다:

mcp-cli interactive --server sqlite

인터랙티브 모드 명령

• /ping: 서버 응답 확인
• /prompts: 사용 가능한 프롬프트 나열
• /tools: 사용 가능한 도구 나열
• /resources: 사용 가능한 리소스 나열
• /chat: 채팅 모드 진입
• /exit 또는 /quit: 프로그램 종료

명령 모드

명령 모드는 자동화 및 파이프라인 통합을 위한 Unix 친화적인 인터페이스를 제공합니다:

mcp-cli cmd --server sqlite [options]

명령 모드 옵션

• --input: 입력 파일 경로 (-는 stdin을 의미)
• --output: 출력 파일 경로 (-는 stdout을 의미, 기본값)
• --prompt: 프롬프트 템플릿 ({{input}}을 입력 플레이스홀더로 사용)
• --raw: 형식 지정 없이 원시 텍스트 출력
• --tool: 특정 도구 직접 호출
• --tool-args: 도구 호출의 JSON 매개변수
• --system-prompt: 사용자 정의 시스템 프롬프트

명령 모드 예시

# 문서 요약
mcp-cli cmd --server sqlite --input document.md --prompt "Summarize this: {{input}}" --output summary.md

# stdin 처리 및 stdout으로 출력
cat document.md | mcp-cli cmd --server sqlite --input - --prompt "Extract key points: {{input}}"

# 도구 직접 호출
mcp-cli cmd --server sqlite --tool list_tables --raw
mcp-cli cmd --server sqlite --tool read_query --tool-args '{"query": "SELECT COUNT(*) FROM users"}'

# 배치 처리
ls *.md | parallel mcp-cli cmd --server sqlite --input {} --output {}.summary.md --prompt "Summarize: {{input}}"

직접 명령

인터랙티브 모드에 진입할 필요 없이 단일 명령을 실행합니다:

# 사용 가능한 도구 나열
mcp-cli tools list --server sqlite

# 특정 도구 호출
mcp-cli tools call --server sqlite

# 사용 가능한 프롬프트 나열
mcp-cli prompts list --server sqlite

# 서버 연결 확인
mcp-cli ping --server sqlite

# 사용 가능한 리소스 나열
mcp-cli resources list --server sqlite

구성 파일

서버를 구성하기 위해 server_config.json 파일을 생성합니다:

{
  "mcpServers": {
    "sqlite": {
      "command": "python",
      "args": ["-m", "mcp_server.sqlite_server"],
      "env": {
        "DATABASE_PATH": "your_database.db"
      }
    },
    "another-server": {
      "command": "python",
      "args": ["-m", "another_server_module"],
      "env": {}
    }
  }
}

프로젝트 구조

src/
├── mcp_cli/
│   ├── chat/                    # 채팅 모드 구현
│   │   ├── commands/            # 채팅 슬래시 명령
│   │   │   ├── __init__.py      # 명령 등록 시스템
│   │   │   ├── conversation.py  # 대화 관리
│   │   │   ├── help.py          # 도움말 명령
│   │   │   └── ...
│   │   ├── chat_context.py      # 채팅 세션 상태 관리
│   │   ├── chat_handler.py      # 주 채팅 루프 핸들러
│   │   ├── command_completer.py # 명령 자동 완성
│   │   └── ui_manager.py        # 사용자 인터페이스
│   ├── commands/                # CLI 명령
│   │   ├── chat.py              # 채팅 명령
│   │   ├── cmd.py               # 명령 모드
│   │   ├── interactive.py       # 인터랙티브 모드
│   │   └── ...
│   ├── llm/                     # LLM 클라이언트 구현
│   │   ├── providers/           # 제공자별 클라이언트
│   │   │   ├── base.py          # 기본 LLM 클라이언트
│   │   │   └── openai_client.py # OpenAI 구현
│   │   └── llm_client.py        # 클라이언트 팩토리
│   ├── ui/                      # 사용자 인터페이스 구성 요소
│   │   ├── colors.py            # 색상 정의
│   │   └── ui_helpers.py        # UI 도구
│   ├── main.py                  # 주 진입점
│   └── config.py                # 구성 로더

사용 예시

자동 도구 실행

채팅 모드에서 MCP CLI는 서버가 제공하는 도구를 자동으로 실행할 수 있습니다:

You: 데이터베이스에 어떤 테이블이 있나요?
Assistant: 확인해 드릴게요.
[도구 호출: list_tables]
데이터베이스에서 다음 테이블을 찾았습니다:
- users
- products  
- orders
- categories

You: 사용자 수는 몇 명인가요?
Assistant: 해당 정보를 데이터베이스에서 조회하겠습니다.
[도구 호출: read_query]
데이터베이스에는 873명의 사용자가 있습니다.

자동화 스크립트

명령 모드는 강력한 자동화 스크립트를 지원합니다:

#!/bin/bash
# 여러 문서 분석 예시 스크립트

# 현재 디렉토리의 모든 마크다운 파일 처리
for file in *.md; do
    echo "Processing $file..."
    
    # 요약 생성
    mcp-cli cmd --server sqlite --input "$file" \
        --prompt "이 문서를 요약해 주세요: {{input}}" \
        --output "${file%.md}.summary.md"
    
    # 엔티티 추출
    mcp-cli cmd --server sqlite --input "$file" \
        --prompt "이 텍스트에서 모든 회사 이름, 사람, 위치를 추출해 주세요: {{input}}" \
        --output "${file%.md}.entities.txt" --raw
done

# 종합 보고서 생성
echo "Creating final report..."
cat *.entities.txt | mcp-cli cmd --server sqlite --input - \
    --prompt "이 엔티티들을 분석하고 가장 자주 언급된 것을 식별해 주세요:" \
    --output report.md

대화 기록 관리

대화 기록 추적 및 관리:

> /conversation
대화 기록 (12 메시지)
# | 역할 | 내용
1 | system | 당신은 도구를 사용할 수 있는 지능형 비서입니다...
2 | user | 데이터베이스에 어떤 테이블이 있나요?
3 | assistant | 확인해 드릴게요.
4 | assistant | [도구 호출: list_tables]
...

> /conversation 4
메시지 #4 (역할: assistant)
[도구 호출: list_tables]
도구 호출:
1. ID: call_list_tables_12345678, 유형: function, 이름: list_tables
인수: {}

> /save conversation.json
대화가 conversation.json에 저장되었습니다.

> /compact
대화 기록이 요약과 함께 압축되었습니다.
요약:
사용자가 데이터베이스 테이블에 대해 물었고, 저는 사용 가능한 테이블(users, products, orders, categories)을 나열했습니다. 그런 다음 사용자가 사용자 수를 물었고, 저는 데이터베이스를 쿼리하여 873명의 사용자가 있음을 확인했습니다.

종속성 관리

CLI는 선택적 종속성 그룹으로 구성됩니다:

• cli: 풍부한 터미널 UI, 명령 자동 완성 및 제공자 통합
• dev: 개발 도구 및 테스트 도구
• wasm: (향후 WebAssembly 지원을 위해 예약됨)
• chuk-mcp: 프로토콜 구현 라이브러리 (핵심 종속성)

특정 추가 기능 설치:

pip install "mcp-cli[cli]"        # 기본 CLI 기능
pip install "mcp-cli[cli,dev]"    # CLI + 개발 도구

기여 가이드

기여를 환영합니다! 다음 단계를 따르세요:

1. 저장소 포크
2. 기능 브랜치 생성 (git checkout -b feature/amazing-feature)
3. 변경 사항 커밋 (git commit -m 'Add some amazing feature')
4. 브랜치에 푸시 (git push origin feature/amazing-feature)
5. 풀 리퀘스트 열기

모델 컨텍스트 프로토콜(MCP)에 대하여

MCP는 애플리케이션이 LLM에 컨텍스트를 제공하는 방식을 표준화하는 개방형 프로토콜입니다. MCP는 AI 애플리케이션의 USB-C 포트와 같다고 비유할 수 있습니다. USB-C가 장치를 다양한 주변 장치 및 액세서리에 연결하는 표준화된 방법을 제공하는 것처럼, MCP는 AI 모델을 다양한 데이터 소스 및 도구에 연결하는 표준화된 방법을 제공합니다.