# PostgreSQL MCP セットアップガイド

**目的:** Claude Code から VPS の PostgreSQL 16（posimai_brain DB）に直接接続し、スキーマ確認・データ参照を自然言語で行えるようにする。

---

## アーキテクチャ

```
Windows (Claude Code)
  ↓ SSH トンネル（Tailscale 経由）
VPS (posimai-lab.tail72e846.ts.net)
  ↓ Docker 内部ネットワーク
PostgreSQL 16 コンテナ
  → DB: posimai_brain
```

---

## ステップ 1: 読み取り専用ユーザーの作成（VPS で一度だけ実行）

VPS に SSH ログイン後、PostgreSQL コンテナに接続して実行する。

```bash
# VPS SSH ログイン
ssh <user>@posimai-lab.tail72e846.ts.net

# PostgreSQL コンテナに接続
docker exec -it <postgres_container_name> psql -U postgres

# 読み取り専用ユーザー作成
CREATE USER posimai_readonly WITH PASSWORD 'CHOOSE_STRONG_PASSWORD';
GRANT CONNECT ON DATABASE posimai_brain TO posimai_readonly;
\c posimai_brain
GRANT USAGE ON SCHEMA public TO posimai_readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO posimai_readonly;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO posimai_readonly;

# 確認
\du posimai_readonly
\q
```

**注意:** パスワードは安全なランダム文字列を設定すること。このユーザーは SELECT のみ可能（INSERT/UPDATE/DELETE 不可）。

---

## ステップ 2: SSH トンネルの設定（Claude Code 起動前）

Claude Code セッションを開始する前に、以下のコマンドでトンネルを張る。

```bash
# バックグラウンドでトンネルを張る（セッション維持）
ssh -N -L 5432:localhost:5432 <user>@posimai-lab.tail72e846.ts.net &

# または WSL2 / PowerShell で常時実行
# Windows の場合は Windows Terminal で別タブで実行しておく
```

**VPS の PostgreSQL コンテナが localhost:5432 を公開しているか確認:**
```bash
ssh <user>@posimai-lab.tail72e846.ts.net "docker ps | grep postgres"
# ポートが 0.0.0.0:5432 または 127.0.0.1:5432 で LISTEN していることを確認
```

---

## ステップ 3: .claude/settings.json への MCP 設定

`posimai-project/.claude/settings.json` の `mcpServers` セクションを追加済み。
**パスワードのみ実際の値に変更すること（このファイルは git 管理外）。**

```json
{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://posimai_readonly:CHANGE_ME@localhost:5432/posimai_brain"
      ]
    }
  }
}
```

---

## 使用例（設定完了後）

Claude Code のセッション内で以下のような質問が自然言語でできるようになる:

```
# スキーマ確認
「posimai_brain にどんなテーブルがある？」

# カラム確認
「users テーブルの構造を教えて」

# データ確認（読み取りのみ）
「habit テーブルに最近登録された習慣を5件見せて」

# デバッグ支援
「feed テーブルで unread_count が NULL のレコードはいくつある？」
```

---

## セキュリティ注意事項

| 項目 | 対応 |
|------|------|
| 認証情報の保管 | `.claude/settings.json`（git 管理外）のみに記載 |
| アクセス制限 | Tailscale VPN 経由のみ（公開ポートなし）|
| 権限 | SELECT のみ（DDL・DML 不可）|
| パスワード | 強力なランダム文字列を設定 |
| CLAUDE.md | DB スキーマ変更は mai 確認必須ルールを維持 |

---

## コンテナ名の確認方法

VPS 上で以下を実行:
```bash
docker ps --format "table {{.Names}}\t{{.Ports}}" | grep -i postgres
```

`deploy-server.sh` または `docker-compose.yml` でコンテナ名を確認することもできる。

---

## トラブルシューティング

**接続できない場合:**
1. SSH トンネルが起動しているか確認: `ss -tlnp | grep 5432`
2. VPS PostgreSQL コンテナが起動しているか確認
3. ポートフォワード先が正しいか確認（Docker ネットワーク設定による）

**MCP サーバーが起動しない場合:**
1. `npx -y @modelcontextprotocol/server-postgres --help` が動作するか確認
2. Node.js / npm がインストールされているか確認