# note-mcp

自分の [note.com](https://note.com) アカウントに下書き記事を作成・更新するための
[MCP](https://modelcontextprotocol.io/) サーバーです。Claude Code や Claude Desktop などの
MCPクライアントから、「noteに下書きを作って」といった依頼で記事を投稿できます。

note.com は記事投稿の公式APIを公開していません。本プロジェクトは、ブラウザの開発者ツールで
観測できる内部API（非公式）をセッションCookie経由で呼び出す実装です。
（参考: [note.comの非公式API調査記事](https://note.com/satokenx/n/n8427a09deec0)）

## 2つの実行方法

| 方法 | 使えるタイミング | セットアップ |
|---|---|---|
| **① ローカル / Docker（stdio）** | 自分のPCが起動している間だけ | [セットアップ](#セットアップ)（簡単） |
| **② Cloudflare Workers（リモート）** | PCの電源に関係なく常時 | [常時稼働させたい場合](#常時稼働させたい場合cloudflare-workers)（要Cloudflareアカウント。`main`へのpushで[GitHub Actions](.github/workflows/deploy.yml)が自動デプロイ） |

`/schedule` のようなクラウド上のスケジュール実行から呼び出したい場合、①のstdio版は
「Claude Codeがその場でローカルにサブプロセスを起動する」方式のため使えません
（PCが起動していても、クラウド側のエージェントからはローカルのDockerに到達できません）。
その場合は②のCloudflare Workers版で常時稼働のURLを用意してください。

## ⚠️ 免責事項

- **非公式のAPIを利用しています。** note.com の仕様変更により、予告なく動作しなくなる
  可能性があります。
- note.com の利用規約に抵触しないか、利用者ご自身の責任で判断してください。
- 本ソフトウェアは無保証で提供されます（[LICENSE](./LICENSE) 参照）。作者は本ソフトウェアの
  利用によって生じたいかなる損害についても責任を負いません。
- **公開・タグ付け機能（`note_publish_draft` / タグ引数）は未確認のAPIに基づく実験的機能です。**
  下書きの作成・更新のみが動作確認済みです。詳しくは [既知の制限](#既知の制限) を参照してください。

## 🔒 セキュリティについて

このリポジトリ・配布Dockerイメージ・Cloudflare Workersのコードには、**個人の認証情報
（note.comのセッションCookie等）は一切含まれていません。** 利用者ご自身のセッションCookieを、
①は実行時の環境変数、②はCloudflare Secretsとして渡す必要があります
（`.env` / `.dev.vars` はテンプレート（`.env.example` / `.dev.vars.example`）のみを
コミット対象とし、実際の値を入れたファイルは `.gitignore` で除外されます）。
②は`/mcp`エンドポイント自体もOAuth（Dynamic Client Registration対応）で保護されており、
ブラウザでのログイン（`MCP_ACCESS_TOKEN`をパスワードとして入力）を経ないと接続できません。

## 必要なもの

- [Docker](https://www.docker.com/)（推奨。環境を問わず動かせます）
- または Node.js 22以上（Dockerを使わずローカル実行する場合。wranglerがNode 22以上を要求するため）
- note.com のアカウント（ログイン済みのブラウザ）

## セットアップ（① ローカル / Docker）

### 1. Cookieの取得方法

1. ブラウザで note.com にログインする。
2. 開発者ツールを開く（Chromeの場合: `F12` または右クリック→「検証」）。
3. 「Application」タブ（Firefoxは「Storage」タブ）→ 左側の「Cookies」→
   `https://note.com` を選択。
4. 一覧から `_note_session_v5` という名前の行を探し、「Value」列の値をコピーする。

この値は note.com へのログインセッションそのものです。**第三者と共有しないでください。**
有効期限が切れたら（下書き作成が失敗し始めたら）、同じ手順で取得し直してください。

### 2. `.env` の作成

```bash
git clone <このリポジトリのURL>
cd note-mcp
cp .env.example .env
```

`.env` を開き、手順1で取得した値を入れる:

```
NOTE_SESSION_COOKIE=（コピーした値）
```

### 3. Dockerイメージのビルド

```bash
docker build -t note-mcp .
```

### 4. Claude Codeへの登録（ユーザースコープ）

```bash
claude mcp add note-mcp --scope user -- \
  docker run -i --rm --env-file /絶対パス/note-mcp/.env note-mcp
```

`--scope user` で登録すると、どのプロジェクトを開いているときでも
`note_create_draft` などのツールが使えるようになります。

登録できているかは `claude mcp list` で確認できます。

## 使えるツール

| ツール名 | 内容 | 状態 |
|---|---|---|
| `note_create_draft` | タイトル・本文（・タグ）を指定して新規下書きを作成 | ✅ 動作確認済み（下書き作成・保存） |
| `note_update_draft` | 既存の下書き（IDで指定）のタイトル・本文（・タグ）を更新 | ✅ 動作確認済み（下書き保存部分） |
| `note_get_draft` | 下書きの現在の内容を取得（デバッグ用） | 🧪 実験的（未確認） |
| `note_publish_draft` | 下書きを公開する。`confirm:true` が無いと実行されない | 🧪 実験的（未確認・不可逆操作） |
| 各ツールの `tags` 引数 | タグ付けを試みる | 🧪 実験的（未確認。失敗しても記事本体は保存される） |

本文はプレーンテキストを渡すと1行1段落として保存されます。簡易的に
`**太字**` と `[表示文字](URL)` にも対応していますが、note.com の本文HTML仕様は
非公開のため、複雑なMarkdown装飾までは保証しません。

## 常時稼働させたい場合（Cloudflare Workers）

PCを起動していなくても（`/schedule` のクラウドスケジュール実行や、スマホ・ブラウザの
claude.aiからも）使えるようにしたい場合は、①のstdio版とは別に、Cloudflare Workers上に
常時稼働のMCPサーバーをデプロイできます。ツールの中身（`src/register-tools.ts`）は
共通で、通信方式だけがstdioからHTTP（Streamable HTTP）に変わり、認証はOAuth 2.1
（Dynamic Client Registration対応。[`@cloudflare/workers-oauth-provider`](https://github.com/cloudflare/workers-oauth-provider)使用）に
なります。claude.aiのカスタムコネクタはOAuthを前提にしているため、この方式にすることで
Claude Code・claude.ai（Web/Desktop/モバイル）のどちらからも同じ手順で接続できます。

**必要なもの:** [Cloudflareアカウント](https://dash.cloudflare.com/sign-up)（無料枠で可）

### 1. Cloudflareにログイン

```bash
npm install
npx wrangler login
```

### 2. KVネームスペースを作成

OAuthの認可コード・トークン・DCRで登録されたクライアント情報を保存するために使う
（`@cloudflare/workers-oauth-provider`が内部で使用）。このリポジトリをforkした場合は
自分のアカウントで作り直す必要がある。

```bash
npx wrangler kv namespace create OAUTH_KV
```

表示された`id`を`wrangler.jsonc`の`kv_namespaces`に反映する（フォーク元のIDのままだと
他人のネームスペースを指してしまい失敗する）。

### 3. シークレットを設定

note.comのセッションCookie（[取得方法](#1-cookieの取得方法)は①と同じ）に加えて、
ログイン用のパスワードも作る。これは、Claude Code・claude.aiがOAuthで接続する際に
ブラウザのログイン画面（`/authorize`）で入力する「このMCPサーバーの持ち主本人であることの
証明」用の合言葉（note.com自体のパスワードやCookieとは別物）。

```bash
# ランダムな値を生成（例）
openssl rand -hex 32

npx wrangler secret put NOTE_SESSION_COOKIE
npx wrangler secret put MCP_ACCESS_TOKEN   # 上で生成した値を貼り付ける。ログインパスワードとして使う
```

どちらもCloudflare側に暗号化して保存され、リポジトリやDockerイメージには一切残らない。

### 4. デプロイ

**方法A（推奨）: GitHub Actions経由で自動デプロイ**

`main`ブランチに`src/`等の変更がpushされるたびに、GitHub Actions
（[`.github/workflows/deploy.yml`](.github/workflows/deploy.yml)）が自動で
`wrangler deploy`を実行する構成になっています。

1. このリポジトリをご自身のGitHubアカウントにpush（fork/新規リポジトリ作成）する。
2. Cloudflareダッシュボード → 右上のアイコン →「My Profile」→「API Tokens」→
   「Create Token」→ テンプレート「Edit Cloudflare Workers」でAPIトークンを発行する。
3. Cloudflareダッシュボードのトップページ右側に表示されている「Account ID」を控える。
4. GitHubリポジトリの Settings → Secrets and variables → Actions →
   「New repository secret」で以下を登録する:
   - `CLOUDFLARE_API_TOKEN`（手順2の値）
   - `CLOUDFLARE_ACCOUNT_ID`（手順3の値）
5. `main`ブランチにpushする（初回は空コミットでもよい）と、Actionsタブでデプロイが
   実行される。

以降は`main`にマージするだけで自動的に最新版がデプロイされます。
[`.github/workflows/ci.yml`](.github/workflows/ci.yml) はPull Requestの時点で
ビルド・テスト・型チェックのみ行い（Cloudflareの認証情報は使わないため、フォークからの
PRでも安全に実行できる）、実際のデプロイは`main`へのマージ後に限定しています。

より厳格に運用したい場合は、GitHubリポジトリの Settings → Environments で
`production` という名前のEnvironmentを作り、Required reviewers（承認者）を
設定すると、デプロイ実行前に人の承認を挟めます。

**方法B: ローカルから手動デプロイ**

```bash
npm run deploy:worker
```

どちらの方法でも、成功すると `https://note-mcp.<あなたのサブドメイン>.workers.dev`
が発行される（同一Workerなので、方法Aと方法Bを併用しても問題ない）。

### 5. 接続する

OAuth対応にしたことで、Claude Code・claude.ai（Web/Desktop/モバイル）のどちらからも
同じMCPサーバーに接続できる。初回はブラウザでログイン画面が開き、手順3で設定した
`MCP_ACCESS_TOKEN`をパスワードとして入力する（以後はトークンが自動更新されるため、
毎回入力する必要はない）。

**Claude Codeの場合:**

```bash
claude mcp add note-mcp-remote --scope user --transport http \
  https://note-mcp.<あなたのサブドメイン>.workers.dev/mcp
```

`-H`でのヘッダー指定は不要（OAuthに統一したため）。ローカル/Docker版（①）と名前が
被らないよう `note-mcp-remote` 等の別名にすると、両方を併用する場合にも混乱しない。
接続時にブラウザが開かない場合は `claude mcp login note-mcp-remote` を実行する。

**claude.aiの場合:**

1. Customize → Connectors → 「Add custom connector」
2. MCPサーバーのURL（`https://note-mcp.<あなたのサブドメイン>.workers.dev/mcp`）を入力
3. 保存すると自動的にOAuthのログイン画面へリダイレクトされるので、`MCP_ACCESS_TOKEN`を
   パスワードとして入力して「許可する」

Advanced settings（OAuth Client ID/Secret）の入力は不要（Dynamic Client Registrationで
claude.ai側が自動的にクライアント登録するため）。

### ローカルでWorkerの動作確認をする場合

```bash
cp .dev.vars.example .dev.vars   # NOTE_SESSION_COOKIE / MCP_ACCESS_TOKEN を設定（コミット対象外）
npm run dev:worker               # wrangler dev。Cloudflareへのデプロイはせずローカルで起動
```

## 既知の制限

- **非公式API**: note.com が公式に提供しているAPIではなく、ブラウザの通信を観察して
  発見したエンドポイントを利用しています。仕様変更でいつ動作しなくなってもおかしくありません。
- **公開機能は未確認**: 記事を実際に公開するAPIエンドポイントは特定できていません。
  `note_publish_draft` は候補となるエンドポイントを複数試しますが、失敗する可能性が高いです。
  失敗した場合は、実際にブラウザで「公開に進む」ボタンを押した際の通信をDevToolsの
  Networkタブで確認し、`src/note-client.ts` の `publishDraft` 内の候補エンドポイントを
  実際のリクエストに合わせて書き換えてください。
- **タグ付けも未確認**: 同様に、実際の通信を確認しながら `updateHashtags` を調整してください。
- **セッションCookieの有効期限**: 切れた場合は取得し直して、①は `.env`、②は
  `npx wrangler secret put NOTE_SESSION_COOKIE` で再設定してください。
- **OAuthは単一ユーザー専用の簡易実装**: `/authorize`のログイン画面はユーザーごとの
  アカウント管理をせず、`MCP_ACCESS_TOKEN`と一致するパスワードなら誰でもログインできる
  設計です（このMCPサーバーの持ち主1人だけが使う前提のため）。複数人での利用や、
  より厳密なアクセス制御が必要な場合はCloudflare Access等の追加を検討してください。

## ローカル開発（Dockerを使わない場合）

```bash
npm install
cp .env.example .env   # NOTE_SESSION_COOKIE を設定
npm run build
npm start
```

本文変換ロジック（`src/text-to-html.ts`）の単体テスト（外部通信なし）:

```bash
npm run test:text-to-html
```

## ライセンス

[MIT](./LICENSE)