# AI 개발 도구 연동

Claude Code, Cursor, VS Code, Codex, Claude Desktop이 Pouchi 개발자 MCP로 문서를 읽고, 문서의 예시를 가져오고, 연동 코드를 점검하게 합니다.

Pouchi 개발자 MCP(`pouchi-dev`)를 코딩 에이전트에 추가하면, 에이전트가 이 문서를 직접 찾아 읽고 문서의 예시 코드로 연동합니다. 지어낸 API 대신 실제 export된 이름만 쓰게 하고, 다 쓴 코드는 흔한 실수가 없는지 점검합니다.

문서, 예시, 정적 점검은 읽기 전용입니다. 앱 설정 도구는 사람이 MCP 환경 변수로 넣은 **앱 관리 콘솔 세션**으로만 설정을 바꿉니다. 지갑 키, 서명, 자금, 관리자 권한에는 접근하지 않습니다.

## 설치

[Pouchi 개발자 MCP 번들 받기](/downloads/pouchi-dev.mcpb)

**패키지 배포 준비 중**

`@shard-lab/pouchi-dev-mcp` 패키지 배포는 준비 중입니다. 배포 전에는 아래 [번들 실행](#번들-실행)의 `node` 명령을 쓰세요. Claude Desktop 번들은 지금 바로 설치됩니다.
배포 뒤에는 SDK와 같은 GitHub Packages에 올라가므로, 사용자 `~/.npmrc`에 `@shard-lab` 레지스트리 설정이 있어야 `npx`가 받을 수 있습니다 ([빠른 시작](/docs/quickstart/)의 `.npmrc`).

## 번들 실행

`.mcpb` 번들은 zip 파일입니다. 풀어서 `node`로 실행하면 패키지 배포 전에도 모든 클라이언트에서 쓸 수 있습니다. Node 20 이상이 필요합니다.

1. 위의 **Claude Desktop 번들 받기**로 받은 파일을 풉니다.

```sh
mkdir -p ~/.pouchi/dev-mcp
unzip -o ~/Downloads/pouchi-dev.mcpb -d ~/.pouchi/dev-mcp
```

2. 아래 패키지 설정에서 `npx -y @shard-lab/pouchi-dev-mcp` 대신 `node ~/.pouchi/dev-mcp/server.mjs`를 씁니다. JSON과 TOML에는 절대 경로를 넣습니다.

```sh
claude mcp add --scope user pouchi-dev -- node ~/.pouchi/dev-mcp/server.mjs
```

```json
{ "command": "node", "args": ["/Users/<사용자>/.pouchi/dev-mcp/server.mjs"] }
```

URL로 붙이는 클라이언트는 `node ~/.pouchi/dev-mcp/server.mjs --http`로 띄우고 `http://127.0.0.1:9470/mcp`(Streamable HTTP)를 넣습니다. 포트는 `DEV_MCP_PORT`로 바꿉니다.

## 패키지 배포 후 설정

아래 `npx` 설정은 패키지 배포 후에 사용합니다. 현재는 위 번들 설정을 사용하세요.

  **Claude Code**

```sh
claude mcp add --scope user pouchi-dev -- npx -y @shard-lab/pouchi-dev-mcp
```

`--scope project`로 넣으면 저장소의 `.mcp.json`에 기록되어 팀이 함께 씁니다. `claude mcp list`로 연결을 확인합니다.

  **Cursor**

패키지 배포 후 프로젝트의 `.cursor/mcp.json`(모든 프로젝트는 `~/.cursor/mcp.json`)에 넣습니다.

```json title=".cursor/mcp.json"
{
  "mcpServers": {
    "pouchi-dev": { "command": "npx", "args": ["-y", "@shard-lab/pouchi-dev-mcp"] }
  }
}
```

  **VS Code**

패키지 배포 후 작업 공간의 `.vscode/mcp.json`에 넣습니다. Copilot Chat의 에이전트 모드에서 도구로 보입니다.

```json title=".vscode/mcp.json"
{
  "servers": {
    "pouchi-dev": { "type": "stdio", "command": "npx", "args": ["-y", "@shard-lab/pouchi-dev-mcp"] }
  }
}
```

  **Codex**

`~/.codex/config.toml`에 넣습니다. Codex CLI와 IDE 확장이 같은 설정을 씁니다.

```toml title="~/.codex/config.toml"
[mcp_servers.pouchi-dev]
command = "npx"
args = ["-y", "@shard-lab/pouchi-dev-mcp"]
```

명령으로 넣어도 됩니다: `codex mcp add pouchi-dev -- npx -y @shard-lab/pouchi-dev-mcp`

  **Claude Desktop**

위의 **Claude Desktop 번들 받기**로 `pouchi-dev.mcpb`를 받아 두 번 클릭합니다. 설정의 확장 프로그램 화면에서 설치를 확인합니다.
번들 안에 서버와 문서가 모두 들어 있어서 Node나 npm 설정이 따로 필요 없습니다 (Claude Desktop에 들어 있는 Node로 실행).

## 도구

| 도구 | 인자 | 하는 일 |
|---|---|---|
| `search_docs` | `query`, `limit?` | 이 문서를 키워드로 찾아 slug, 절, URL, 본문 일부를 줍니다 |
| `get_doc` | `slug` | 문서 한 쪽을 Markdown으로 줍니다. 예: `quickstart`, `privy-migration`, `delegation`, `security`, `reference/react` |
| `get_example` | `name` | 문서의 예시 파일. `react-quickstart`, `privy-migration`, `session-approval`, `tenant-delegated-payment`, `tenant-server` |
| `check_integration` | `package_json?`, `provider_snippet?` | 정적 점검: `appId`나 `apiUrl` 누락, 450815가 아닌 chain id, `useSessionSigners` 사용, 서버 설정 없는 소셜 로그인, 세션 승인 `clientId` 누락, 없는 export, 코드 속 비밀값 |
| `list_chains`, `get_network_info` | `chain_id?` | Maroo Testnet(450815)과 배포 매니페스트의 컨트랙트 주소 |
| `get_tenant`, `get_app_config` | `origin?` | 앱 등록 상태와 다음 할 일, 앱에 넣을 공개 값(apiUrl, appId, clientId)과 `.env` 내용 |
| `set_app_origins`, `set_login_methods`, `set_sponsorship`, `set_policy_caps`, `upsert_web_client` | 각 칸, `dry_run?` | 앱 설정의 그 칸만 바꿉니다. 바꾸기 전 값과 바꾼 뒤 값을 보여 주고, 같은 값이면 부르지 않습니다 |
| `scaffold_app` | `target_dir`, `framework?`, `origin?` | 빈 폴더에 Vite나 Next.js 앱(로그인, 지갑, 송금, 서명, README)을 씁니다. 있는 파일은 덮어쓰지 않습니다 |
| `verify_setup` | `origin?`, `client_id?` | API, 체인, 출처, CORS, 클라이언트, 로그인 수단, 대납을 통과, 실패 표로 점검합니다 |

## 앱 설정

앱 등록과 체인 등록 서명, 등록 승인은 Pouchi 운영팀과 앱 운영자가 합니다. 그 다음 앱 설정은 에이전트가 이 MCP로 합니다.
자격증명은 MCP 설정의 환경 변수로만 넣고 채팅에 쓰지 않습니다. 아래 설정에는 배정받은 호스팅 API를 씁니다. [business@pouchi.app](mailto:business@pouchi.app)으로 API URL, 앱 ID, 콘솔과 패키지 접근 권한을 요청하세요. 호스팅 API에는 `POUCHI_ALLOW_REMOTE_API=1`을 명시해야 합니다. 기본 설정은 루프백 API만 허용합니다. 콘솔 비밀번호는 본인만 읽을 수 있는 로컬 파일에 저장하고 `POUCHI_TENANT_CONSOLE_PASSWORD_FILE`에는 그 경로만 넣습니다.

```sh
claude mcp add --scope local pouchi-dev \
  -e POUCHI_ALLOW_REMOTE_API=1 -e POUCHI_API_URL=YOUR_POUCHI_API_URL -e POUCHI_TENANT_ID=YOUR_POUCHI_APP_ID \
  -e POUCHI_TENANT_CONSOLE_EMAIL=YOUR_CONSOLE_EMAIL -e POUCHI_TENANT_CONSOLE_PASSWORD_FILE=$HOME/.pouchi/console.pw \
  -- node ~/.pouchi/dev-mcp/server.mjs
```

```text
pouchi-dev MCP로 이 빈 폴더에 Vite React 앱을 만들고 앱을 설정해 줘. 앱 출처는 http://localhost:5173 이야.
get_tenant로 상태를 보고, 설정 도구는 dry_run으로 먼저 보여 준 뒤 적용해. 끝나면 verify_setup 표를 보여 줘.
```

React 빠른 시작과 서버 예제는 문서에 보이는 파일과 같으며 SDK 선언에 대한 타입 검사를 통과했습니다. 타입 검사와 정적 점검은 패키지 설치, 로그인, 실제 결제의 성공을 보장하지 않습니다.

## 붙여 넣을 프롬프트

새 앱에 붙일 때:

```text
pouchi-dev MCP를 써서 이 React 앱에 Pouchi 이메일 로그인과 지갑을 붙여 줘.
먼저 get_doc("quickstart")와 get_example("react-quickstart")를 읽고, 문서에 있는 API만 써.
앱 ID는 VITE_POUCHI_TENANT_ID, API 주소는 VITE_POUCHI_API_URL 환경 변수로 받아.
체인은 Maroo Testnet(450815)이야. 다 하면 check_integration에
package.json과 providers.tsx를 넣어 점검하고, 남은 경고와
내가 할 일(앱 설정의 applicationOrigins 등록 등)을 알려 줘.
```

Privy 앱을 옮길 때:

```text
pouchi-dev MCP로 이 앱을 Privy에서 Pouchi로 옮겨 줘.
get_doc("privy-migration")과 get_example("privy-migration")을 먼저 읽어.
@privy-io/react-auth import를 @shard-lab/nc-waas-react로 바꾸고,
Provider에 apiUrl과 defaultChain(Maroo Testnet)을 더해.
useSessionSigners처럼 거절되는 API를 쓰는 곳은 고치지 말고 목록으로 보여 주고,
대안(useSessionApproval 또는 서버 위임)을 제안해. 끝나면 check_integration을 돌려.
```

**비밀값은 넣지 않습니다**

프롬프트나 `check_integration` 입력에 `clientSecret`, 패키지 토큰, 개인키를 넣지 마세요. 점검은 그런 값이 코드에 있으면 알려 주지만 값을 되돌려 보여 주지 않습니다.