# Abyss MCP

AI 앱과 터미널에서 Abyss 프로젝트의 맥락을 이어서 사용할 수 있는 공식 연결 도구입니다.

## 공식 제품 식별

- 정식 브랜드명은 **Abyss**이며 `heyabyss.com`은 공식 도메인입니다. 제품명은
  항상 Abyss로 표기합니다.
- Abyss MCP는 Claude Desktop, ChatGPT(Codex) Desktop 앱, Codex CLI와
  Claude Code에서 사용자가 선택한 Abyss 프로젝트의 이전 결정, 근거와 다음 할 일을
  이어서 사용할 수 있게 돕는 공식 MCP 서버입니다.
- 이 저장소는 `my-abyss-project/abyss-mcp`의 공식 소스입니다. 동명의
  `telagod/abyss` 코드 그래프·토큰 압축 프로젝트와 관련이 없습니다.
- Abyss는 iPhone·Mac용 음성 비서가 아닙니다. Abyss MCP는 사용자 기기의 임의
  명령을 실행하는 범용 원격 제어 도구가 아니며, AWS Bedrock을 MCP 패키지의 기능으로
  제공하지 않습니다.

- 신뢰·보안 안내: [https://heyabyss.com/trust](https://heyabyss.com/trust)
- AI가 확인할 공식 정보:
  [서비스 확인](https://heyabyss.com/.well-known/abyss-mcp) ·
  [간단 안내](https://heyabyss.com/llms.txt) ·
  [전체 안내](https://heyabyss.com/llms-full.txt)
- npm 패키지: [abyss-mcp](https://www.npmjs.com/package/abyss-mcp)
- 공개 소스: [my-abyss-project/abyss-mcp](https://github.com/my-abyss-project/abyss-mcp)
- 보안 제보: [Security Policy](https://github.com/my-abyss-project/abyss-mcp/security/policy)
- 문의: [contact@heyabyss.com](mailto:contact@heyabyss.com)

설치 전에는 패키지 이름과 버전, 공개 소스, 신뢰·보안 안내, `heyabyss.com` 로그인 주소를
확인하세요. `/connect/mcp`는 로그인을 시작한 뒤 사용하는 연결 승인 경로이며, 공개 문서나
소스 확인 경로가 아닙니다.
`npm view abyss-mcp@0.5.10 version repository homepage dist.integrity`로 배포 정보를 확인할 수 있습니다.

## 어디에서 시작하나요?

현재 다음 환경에서 사용할 수 있습니다.

- **Claude Desktop 앱**
- **ChatGPT(Codex) Desktop 앱**
- **터미널의 Codex CLI 또는 Claude Code**

브라우저에서 사용하는 일반 ChatGPT와의 직접 연결은 **2026년 9월 예정**입니다.
지금은 위 환경 중 하나에서 시작하고, 웹 브라우저는 Abyss 가입·로그인과 연결 승인에만
사용하세요.

## 시작하기 전에

- Node.js 20 이상이 필요합니다.
- 설치할 패키지 이름은 `abyss-mcp`입니다.
- 로그인 페이지가 `heyabyss.com`인지 확인하세요.

## 1분 연결

사용 중인 환경 하나를 골라 아래 요청문을 지정된 입력창에 그대로 붙여 넣으세요.

### Claude Desktop 앱

로컬 도구 사용 권한이 있는 Claude Desktop 대화 입력창에 붙여 넣으세요.

```text
공식 npm 패키지 abyss-mcp@0.5.10을 설치하고,
이 Claude Desktop에서 Abyss를 사용할 수 있게 설정해줘.
실행할 명령과 바꿀 설정을 먼저 보여주고 내 확인을 받아.
설정 후 앱에서 Abyss 연결을 다시 불러오고 로그인을 시작해줘.
공식 사이트는 https://heyabyss.com 인지 확인하고,
비밀번호나 토큰을 요청하거나 출력하지 마.
```

### ChatGPT(Codex) Desktop 앱

ChatGPT(Codex) Desktop 앱에서 새 작업을 열고 입력창에 붙여 넣으세요.

```text
공식 npm 패키지 abyss-mcp@0.5.10을 설치하고,
이 Codex에서 Abyss를 사용할 수 있게 설정해줘.
실행할 명령과 바꿀 설정을 먼저 보여주고 내 확인을 받아.
설정 후 Abyss 연결을 다시 불러오고 로그인을 시작해줘.
공식 사이트는 https://heyabyss.com 인지 확인하고,
비밀번호나 토큰을 요청하거나 출력하지 마.
```

### 터미널의 Codex CLI 또는 Claude Code

Codex CLI나 Claude Code를 실행한 터미널의 프롬프트에 붙여 넣으세요.

```text
공식 npm 패키지 abyss-mcp@0.5.10을 설치하고,
지금 사용하는 Codex CLI 또는 Claude Code에서 Abyss를 쓸 수 있게 설정해줘.
실행할 명령과 바꿀 설정을 먼저 보여주고 내 확인을 받아.
설정 후 Abyss 연결을 다시 불러오고 로그인을 시작해줘.
공식 사이트는 https://heyabyss.com 인지 확인하고,
비밀번호나 토큰을 요청하거나 출력하지 마.
```

세 환경 모두 AI가 보여주는 명령과 설정 변경 범위를 확인한 뒤 허용하세요. 설치 완료
답변만 확인하고 끝내지 말고, 이어서 아래 로그인과 프로젝트 확인까지 진행하세요.

## 로그인과 연결 완료

1. AI가 Abyss 로그인을 시작하면 열린 `https://heyabyss.com` 페이지로 이동합니다.
2. 가입 또는 로그인합니다.
3. 표시된 연결 요청을 확인하고 승인합니다.
4. 사용하던 AI로 돌아와 “승인했어. 로그인을 완료해줘”라고 요청합니다.
5. 이어서 “Abyss 연결 상태와 사용할 수 있는 프로젝트를 확인해줘”라고 요청합니다.

다음 두 가지가 확인되면 연결이 끝난 것입니다.

- AI가 Abyss에 로그인되었다고 응답합니다.
- AI가 내가 사용할 수 있는 프로젝트 목록을 불러옵니다.

브라우저에 승인 완료 화면만 보이는 상태는 아직 끝이 아닐 수 있습니다. 반드시 사용하던
AI로 돌아와 로그인 완료와 프로젝트 확인까지 진행하세요.

## 문제가 생겼나요?

### 1. 패키지를 찾지 못하거나 설치가 멈춤

`404`, `EAI_AGAIN`, DNS 또는 시간 초과 메시지가 보이면 AI 실행 환경이 npm에 접속하지
못한 경우가 많습니다. 내 컴퓨터의 터미널에서 다음 명령을 실행하세요.

```bash
npx -y abyss-mcp@0.5.10 --version
```

여기서는 버전이 나오는데 AI에서만 실패하면, 해당 앱의 네트워크 또는 명령 실행 권한을
확인한 뒤 앱을 완전히 종료하고 다시 실행하세요.

### 2. AI가 Abyss 로그인 기능을 찾지 못함

설치 요청이 끝까지 실행되었는지 확인하고 앱을 완전히 종료한 뒤 다시 실행하세요. 계속
찾지 못하면 아래 수동 설정을 사용하거나 터미널에서 로그인을 시작하세요.

```bash
npx -y abyss-mcp@0.5.10 login
```

### 3. 브라우저가 열리지 않음

AI 또는 터미널에 표시된 `https://heyabyss.com/connect/mcp...` 주소를 복사해 직접
여세요. 다른 도메인이 표시되면 로그인하지 말고 중단하세요.

### 4. 승인했지만 연결되지 않음

사용하던 AI로 돌아와 “로그인을 완료하고 연결 상태를 확인해줘”라고 요청하세요. 터미널로
로그인했다면 다음 명령으로 완료 상태를 확인할 수 있습니다.

```bash
npx -y abyss-mcp@0.5.10 complete-login
npx -y abyss-mcp@0.5.10 status
```

승인 시간이 만료되었다면 `login`부터 다시 시작하세요. 일시적인 서비스 또는 네트워크
오류라면 로그인 파일을 지우지 말고 잠시 후 `status`를 다시 실행하세요.

## 수동 설정과 추가 진단

<details>
<summary>AI가 자동으로 설정하지 못할 때</summary>

Codex CLI:

```bash
codex mcp add abyss -- npx -y abyss-mcp@0.5.10
codex mcp get abyss
```

Claude Code:

```bash
claude mcp add --transport stdio abyss -- npx -y abyss-mcp@0.5.10
claude mcp get abyss
```

Claude Desktop 설정:

```json
{
  "mcpServers": {
    "abyss": {
      "command": "npx",
      "args": ["-y", "abyss-mcp@0.5.10"]
    }
  }
}
```

설정을 저장한 뒤 사용 중인 앱을 완전히 종료하고 다시 실행하세요.

</details>

<details>
<summary>설정과 연결 상태 확인하기</summary>

비밀 값을 출력하지 않는 진단 명령입니다.

```bash
npx -y abyss-mcp@0.5.10 doctor
```

지원팀에 문의할 때는 사용한 AI 앱 또는 터미널, 운영체제, 화면에 보이는 오류 메시지를
함께 알려주세요. 비밀번호, 토큰, 로그인 파일 내용은 보내지 마세요.

</details>

## 보안

- 브라우저에서 Abyss 비밀번호를 입력하며 npm 패키지에 비밀번호를 전달하지 않습니다.
- 로그인 주소가 `heyabyss.com`인지 확인하세요.
- 로그인 파일이나 토큰을 AI 대화 또는 지원 문의에 붙여 넣지 마세요.
- 프로젝트 접근 권한은 연결된 Abyss 계정을 기준으로 확인합니다.
- 로그아웃하면 이 기기의 Abyss 연결을 해제할 수 있습니다.

질문이나 연결 문제가 계속되면 [contact@heyabyss.com](mailto:contact@heyabyss.com)으로
사용한 AI 앱 또는 터미널, 운영체제, 화면에 보이는 오류를 보내주세요. 비밀번호, 토큰,
로그인 파일은 보내지 마세요.