# llm4s (MCP-Lens)

[![PyPI version](https://img.shields.io/pypi/v/llm4s.svg)](https://pypi.org/project/llm4s/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

> K9s-inspired MCP traffic monitor for Claude Desktop

Claude Desktop이 MCP 서버를 호출할 때의 **tool call 트래픽을 실시간으로 모니터링**하는 터미널 UI 도구입니다.

---

## MCP가 뭔지 모르겠다면

Claude Desktop은 두 가지 방식으로 통신합니다:

```
┌─────────────────────────────────────────────────────┐
│                  Claude Desktop                      │
│                                                      │
│   사용자가 채팅 입력                                  │
│       ↓                                             │
│   Claude (LLM) 가 판단                               │
│   "파일 읽기 도구 써야겠다"                            │
└──────────────┬──────────────────────────────────────┘
               │  JSON-RPC (stdio)
               │  {"method": "tools/call",
               │   "params": {"name": "read_file", ...}}
               ↓
┌─────────────────────────────────────────────────────┐
│              MCP 서버 (별도 프로세스)                  │
│                                                      │
│   예) filesystem 서버, fetch 서버, 직접 만든 서버 등   │
│                                                      │
│   실제로 파일 읽기 / 웹 요청 등 실행 후 결과 반환        │
└─────────────────────────────────────────────────────┘
```

- **Claude ↔ Anthropic API**: LLM 추론 (HTTPS, 볼 수 없음)
- **Claude ↔ MCP 서버**: tool call (stdio, llm4s가 모니터링)

**llm4s는 Claude Desktop이 MCP 서버를 호출하는 순간을 포착합니다.**

---

## llm4s가 끼면

```
┌──────────────────┐
│  Claude Desktop  │
└────────┬─────────┘
         │ stdio (JSON-RPC)
         ↓
┌──────────────────┐
│   llm4s proxy    │  ← 트래픽을 가로채어 SQLite에 기록
└────────┬─────────┘
         │ stdio (JSON-RPC, 그대로 전달)
         ↓
┌──────────────────┐
│    MCP 서버       │  ← 정상 동작, 지연 없음
└──────────────────┘

┌──────────────────┐
│   llm4s TUI      │  ← DB 읽어서 실시간 표시
└──────────────────┘
```

**핵심 설계**: asyncio Queue + SQLite WAL — MCP 통신 속도에 영향 없음

---

## 빠른 시작

```bash
# 1. 설치
pipx install llm4s

# 2. 설정 (Claude Desktop 자동 연결 포함)
llm4s setup

# 3. Claude Desktop 재시작

# 4. 모니터링 시작
llm4s
```

`llm4s setup` 하나로 API key 등록 + Claude Desktop 자동 연결까지 완료됩니다.

---

## MCP 서버 추가

```bash
# 서버 등록 → Claude Desktop 자동 연결까지 한 번에
llm4s add-server <이름> --command <명령어> -- <인자>

# 예시: filesystem 서버
llm4s add-server filesystem --command npx -- -y @modelcontextprotocol/server-filesystem ~/Desktop
```

---

## TUI 화면 구성

3단계 계층 구조 (K9s 스타일):

| 단계 | 화면 | 내용 |
|------|------|------|
| 1 | **Providers** | 등록된 MCP 서버 목록 |
| 2 | **Sessions** | 대화 세션별 로그 |
| 3 | **Logs** | tool call 상세 내용 |

로그 화면에서 볼 수 있는 것:
- `🔧 get_weather(location='Seoul')` — 어떤 도구를 어떤 인자로 호출했는지
- `← 응답 결과` — MCP 서버가 반환한 내용
- `🔌 연결 요청` / `✓ 초기화 완료` 등 MCP 연결 과정

### 키 바인딩

| 키 | 동작 |
|----|------|
| `Enter` | 다음 단계로 진입 |
| `Esc` | 이전 단계로 돌아가기 |
| `/` | 검색 |
| `e` | 페이로드 편집 |
| `r` | 편집한 메시지 재전송 (Replay) |
| `x` | 세션 Markdown으로 내보내기 |
| `R` / `F5` | 새로고침 |
| `q` | 종료 |

### 고급 필터

```
method:tools/call     # 특정 메서드만 보기
dir:C2S               # 방향 필터 (C2S / S2C)
ms>3000               # 응답시간 3초 초과
error:true            # 에러만 보기
```

---

## CLI 명령어

```bash
llm4s                  # TUI 대시보드 실행
llm4s setup            # 초기 설정 (API key + Claude Desktop 연결)
llm4s add-server ...   # MCP 서버 등록
llm4s list-servers     # 등록된 서버 목록
llm4s doctor           # 상태 점검
```

---

## 기술 스택

| 구성요소 | 기술 |
|---------|------|
| TUI | [Textual](https://textual.textualize.io/) |
| DB | SQLite WAL + `aiosqlite` |
| API | [FastAPI](https://fastapi.tiangolo.com/) |
| 코어 | Python `asyncio` |

---

## License

MIT
