npm package: @lamy-work/mcp-server
Description: MCP server for Lamy-work API integration with OAuth authentication
Latest version: 1.0.1

# @lamy-work/mcp-server

[Lamy Work](https://work.lamysolution.com) 업무 관리 플랫폼을 AI 코딩 에이전트에서 직접 사용할 수 있게 해주는 MCP(Model Context Protocol) 서버입니다.

Claude Code, OpenCode, Gemini CLI, Codex 등 MCP를 지원하는 모든 CLI 에이전트에서 라미워크의 업무, 태스크, 채팅, 공지사항 등을 관리할 수 있습니다.

## Quick Start

### 1. MCP 서버 실행

```bash
npx @lamy-work/mcp-server
```

서버가 `http://localhost:3100/mcp`에서 시작됩니다.

### 2. CLI 에이전트 설정

```bash
# 모든 에이전트 한번에 설정
npx @lamy-work/mcp-server setup all

# 또는 개별 설정
npx @lamy-work/mcp-server setup opencode
npx @lamy-work/mcp-server setup gemini
npx @lamy-work/mcp-server setup codex
```

Claude Code는 `.mcp.json`에 직접 추가합니다:

```json
{
  "mcpServers": {
    "lamy-work": {
      "type": "http",
      "url": "http://localhost:3100/mcp"
    }
  }
}
```

### 3. 인증

첫 사용 시 브라우저가 자동으로 열리며 라미워크 로그인 페이지가 표시됩니다.

1. 라미워크 이메일/비밀번호로 로그인
2. 워크스페이스 선택
3. 인증 완료 — 이후 자동 연결

> OAuth 2.1 + PKCE 표준을 사용합니다. 토큰은 7일간 유효하며, 만료 시 재인증합니다.

## 에이전트별 설정 가이드

> 모든 에이전트에서 MCP 서버가 실행 중이어야 합니다 (`npx @lamy-work/mcp-server`).

### Claude Code

프로젝트 루트에 `.mcp.json` 파일을 생성하거나 편집합니다:

```json
{
  "mcpServers": {
    "lamy-work": {
      "type": "http",
      "url": "http://localhost:3100/mcp"
    }
  }
}
```

### OpenCode

자동 설정:
```bash
npx @lamy-work/mcp-server setup opencode
```

또는 프로젝트 루트에 `opencode.jsonc`를 직접 생성합니다:
```jsonc
{
  "mcp": {
    "lamy-work": {
      "type": "remote",
      "url": "http://localhost:3100/mcp",
      "enabled": true
    }
  }
}
```

### Gemini CLI

자동 설정:
```bash
npx @lamy-work/mcp-server setup gemini
```

또는 `~/.gemini/settings.json`에 직접 추가합니다:
```json
{
  "mcpServers": {
    "lamy-work": {
      "httpUrl": "http://localhost:3100/mcp"
    }
  }
}
```

### Codex (OpenAI)

자동 설정:
```bash
npx @lamy-work/mcp-server setup codex
```

또는 `~/.codex/config.toml`에 직접 추가합니다:
```toml
[mcp_servers.lamy-work]
url = "http://localhost:3100/mcp"
```

### 한번에 모두 설정

```bash
npx @lamy-work/mcp-server setup all
```

## 제공하는 Tools

### 업무 관리

| Tool | 설명 |
|------|------|
| `query_workspace` | 워크스페이스 정보 조회 (멤버, 프로젝트) |
| `manage_work` | 업무 CRUD 및 상태 전환 (생성 → 계획 → 완료 → 보관) |
| `manage_task` | 태스크 관리 (할당, 상태, 체크리스트, 의존성) |
| `manage_task_comment` | 태스크 댓글 CRUD |

### 커뮤니케이션

| Tool | 설명 |
|------|------|
| `read_chat` | 채팅방 목록 및 메시지 조회 |
| `send_chat_message` | 채팅방에 메시지 전송 |
| `manage_work_message` | 업무 소통 채널 (진행 상황 공유, @멘션, 이슈 플래그) |

### 보고 & 알림

| Tool | 설명 |
|------|------|
| `manage_work_report` | 업무 보고서 작성/제출/승인 (진행 보고, 최종 보고) |
| `manage_notification` | 알림 조회, 읽음 처리, 전체 읽음 |
| `manage_announcement` | 공지사항 작성/발행/보관/고정/읽음 추적 |

### 개인 할일

| Tool | 설명 |
|------|------|
| `manage_personal_task` | Google Keep 스타일 할일 관리 (체크리스트, 반복, 스케줄) |

## 사용 예시

### Claude Code에서 업무 확인

```
> 내 업무 목록 보여줘
> "로그인 페이지 리뉴얼" 업무의 태스크들 확인해줘
> 태스크 #3 완료 처리하고 댓글로 "API 연동 완료" 남겨줘
```

### 공지사항 작성

```
> 공지사항 카테고리 목록 조회해줘
> "2월 정기 점검 안내" 공지를 작성하고 발행해줘
```

### 보고서 제출

```
> 이번 주 진행 보고서 작성해줘
> 보고서 제출하고 업무 소통 채널에 공유해줘
```

## 환경 변수

| 변수 | 기본값 | 설명 |
|------|-------|------|
| `MCP_PORT` | `3100` | MCP 서버 포트 |
| `LAMY_API_BASE_URL` | `https://work.lamysolution.com` | 라미워크 API 서버 URL |

### 사내 서버에 연결하기

자체 라미워크 서버를 운영하는 경우:

```bash
LAMY_API_BASE_URL=https://your-server.com npx @lamy-work/mcp-server
```

## 아키텍처

```
┌─────────────┐     OAuth 2.1      ┌──────────────┐     JWT      ┌──────────────┐
│  CLI Agent   │ ◄──── HTTP ────►  │  MCP Server   │ ◄── API ──► │  Lamy Work   │
│ (Claude Code │     localhost      │  (이 패키지)   │    HTTPS    │   Backend    │
│  OpenCode    │     :3100          │               │             │              │
│  Gemini CLI) │                    └──────────────┘             └──────────────┘
└─────────────┘
```

1. CLI 에이전트가 MCP 프로토콜로 로컬 서버에 연결
2. MCP 서버가 OAuth로 사용자 인증 (브라우저 로그인)
3. 인증된 JWT로 라미워크 API를 호출
4. 결과를 MCP 프로토콜로 에이전트에 반환

> MCP 서버는 인증된 프록시 역할만 하며, 자체적으로 데이터를 저장하지 않습니다.

## Docker

Docker로 실행할 수도 있습니다:

```bash
docker build -t lamy-mcp -f packages/mcp-server/Dockerfile .
docker run -p 3100:3100 -e LAMY_API_BASE_URL=https://work.lamysolution.com lamy-mcp
```

또는 docker-compose:

```yaml
services:
  mcp:
    image: lamy-mcp
    ports:
      - "3100:3100"
    environment:
      - LAMY_API_BASE_URL=https://work.lamysolution.com
```

## 요구 사항

- Node.js >= 20.0.0
- 라미워크 계정 (https://work.lamysolution.com)

## License

MIT