npm package: @notepost/mcp
Description: CLI tool for setting up NotePost MCP integration with AI agents
Latest version: 1.1.3

# @notepost/mcp

[![npm version](https://img.shields.io/npm/v/@notepost/mcp)](https://www.npmjs.com/package/@notepost/mcp)
[![license](https://img.shields.io/npm/l/@notepost/mcp)](https://github.com/algonaut/notepost-mcp/blob/main/LICENSE)
[![node](https://img.shields.io/node/v/@notepost/mcp)](https://nodejs.org)

**AI エージェントから Note.com に記事を投稿できる MCP サーバー。**
下書き保存・即時公開・予約投稿・画像アップロードを、Claude Code / Cursor / Copilot などから自然言語で実行できます。

> MCP (Model Context Protocol) は、AI エージェントが外部サービスと連携するための標準プロトコルです。

---

## Install

```bash
npx @notepost/mcp
```

対話型ウィザードが起動し、すべてを自動セットアップします。

**セットアップの流れ:**

```
npx @notepost/mcp
  │
  ├─ 1. ブラウザが開く → NotePost にログイン → API キーを取得
  ├─ 2. API キーをターミナルに貼り付け
  ├─ 3. Claude Code に notepost を自動登録 (user config)
  ├─ 4. MCP サーバー設定を保存 (.mcp.json)
  ├─ 5. エージェント用スキルファイルをインストール
  └─ 6. stateful MCP 接続テスト → 完了!
```

Claude Code がインストールされていれば、セットアップ完了時点でこのマシンの Claude Code user config に `notepost` が登録されます。

### 非対話モード (CI / スクリプト用)

```bash
npx @notepost/mcp setup --key sk_live_xxxxxxxx
```

---

## 使い方

セットアップ後は、AI エージェントに自然言語で指示するだけです。

```
💬 "AIツールの比較記事を3000字で書いて、Note.comに下書き保存して"
💬 "先週書いた下書きを明日の朝8時に公開予約して"
💬 "予約投稿の一覧を見せて"
💬 "下書きの記事をいま公開して"
💬 "この画像をアップロードしてサムネイルに設定して"
```

---

## 対応エージェント

| エージェント | サポート状況 |
|:------------|:----------:|
| Claude Code | ✅ |
| Cursor | ✅ |
| GitHub Copilot | ✅ |
| Cline | ✅ |
| その他 MCP 対応エージェント | ✅ |

---

## MCP ツール一覧

セットアップ後にエージェントから使えるツール:

| ツール | 説明 |
|:------|:----|
| `note_list_accounts` | リンク済みの Note.com アカウント一覧 |
| `note_save_draft` | 記事を下書き保存 |
| `note_publish_now` | 記事を即時公開 |
| `note_schedule_post` | 公開日時を予約 |
| `note_list_scheduled` | 予約投稿の一覧 |
| `note_cancel_scheduled` | 予約投稿をキャンセル |
| `note_update_scheduled` | 予約日時・公開モードを変更 |
| `note_upload_image` | 画像をアップロード |

> `note_save_draft`, `note_publish_now`, `note_schedule_post`, `note_upload_image` は Note.com アカウントのリンクが必要です。NotePost アプリの Settings からリンクできます。

---

## CLI コマンド

| コマンド | 説明 |
|:--------|:----|
| `npx @notepost/mcp` | 対話型セットアップウィザード |
| `npx @notepost/mcp setup --key <key>` | 非対話セットアップ |
| `npx @notepost/mcp status` | 接続状態・アカウント確認 |
| `npx @notepost/mcp doctor` | Claude Code 登録状態と `.mcp.json` 競合を診断 |
| `npx @notepost/mcp show-key` | 設定済み API キーを表示 |
| `npx @notepost/mcp update-skill` | スキルファイルを最新版に更新 |
| `npx @notepost/mcp --help` | ヘルプ表示 |

---

## 前提条件

- **Node.js 18 以上**
- **NotePost アカウント** — [algonotes-production.up.railway.app](https://algonotes-production.up.railway.app) から登録

---

## セットアップの詳細

`npx @notepost/mcp` は以下を自動設定します。

### 1. Claude Code への登録

Claude Code がインストールされている場合、CLI は次を実行して user config に直接登録します。

```bash
claude mcp add --scope user --transport http notepost https://algonotes-production.up.railway.app/api/mcp \
  -H "Authorization: Bearer sk_live_xxxxxxxx"
```

これにより trust dialog や `enabledMcpjsonServers` に依存せず、このマシンの Claude Code 設定に `notepost` が入ります。

### 2. MCP サーバー設定

他エージェント互換のため `.mcp.json` にも保存:

```json
{
  "mcpServers": {
    "notepost": {
      "type": "http",
      "url": "https://algonotes-production.up.railway.app/api/mcp",
      "headers": {
        "Authorization": "Bearer sk_live_xxx..."
      }
    }
  }
}
```

API キーのバックアップは `.env.local` にも保存されます。

### 3. エージェントスキルファイル

AI エージェントに Note.com の仕様を教えるナレッジレイヤー:

- **記事フォーマットルール** — Note.com が対応する Markdown 構文 (イタリック不可、テーブル不可 等)
- **ワークフロールール** — ツール実行順序 (画像アップロード → 下書き → 公開)
- **発行ルール** — 予約制約、タグ上限、価格設定オプション

保存先:
- `~/.agents/skills/notepost-mcp/` (全エージェント共通)
- `~/.claude/skills/notepost-mcp/` (Claude Code 用シンボリックリンク)

---

## 手動セットアップ

CLI を使わずに手動で設定する場合:

```bash
# Claude Code の場合: user config に MCP サーバーを直接追加
claude mcp add notepost --scope user --transport http https://algonotes-production.up.railway.app/api/mcp \
  -H "Authorization: Bearer sk_live_xxxxxxxx"

# スキルファイルだけ別途インストール
npx @notepost/mcp update-skill
```

---

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

<details>
<summary><b>"No .mcp.json found"</b></summary>

`npx @notepost/mcp` を実行してセットアップウィザードを開始してください。
</details>

<details>
<summary><b>"notepost is not registered in Claude Code"</b></summary>

Claude Code CLI が未インストールか、setup が user config への登録に失敗しています。

- `npx @notepost/mcp` を再実行
- もしくは `claude mcp add --scope user --transport http ...` を実行
</details>

<details>
<summary><b>"複数の .mcp.json に notepost が入っていて挙動が不安定"</b></summary>

旧セットアップや手動設定で home/project の両方に `notepost` が残っている可能性があります。

```bash
npx @notepost/mcp doctor
```

このコマンドが、どの `.mcp.json` に `notepost` が残っているかを一覧表示します。
</details>

<details>
<summary><b>"MCP server returned error: 401"</b></summary>

API キーが無効または期限切れです。NotePost アプリの Settings > API Keys から新しいキーを発行し、再セットアップしてください。
</details>

<details>
<summary><b>"Could not reach MCP server"</b></summary>

- インターネット接続を確認
- カスタム URL を使用している場合、サーバーが起動しているか確認
- デフォルト URL: `https://algonotes-production.up.railway.app/api/mcp`
</details>

<details>
<summary><b>"Note.com account is NOT linked"</b></summary>

NotePost アプリの Settings から Note.com アカウントをリンクしてください。
</details>

---

## セキュリティ

- API キーはローカル (`.mcp.json`, `.env.local`) にのみ保存
- 通信は HTTPS のみ (localhost 開発時を除く)
- キーの無効化は NotePost アプリの Settings > API Keys から
- `.env.local` は `.gitignore` に追加してください

---

## License

MIT