GhostPaw Email

@ghostpaw/email

エージェント向けメール：IMAP と SMTP をプロセス内で処理し、SQLite にキャッシュします。読み取りと送信は別々のツールです。

npm install @ghostpaw/email

SQLite を基盤とする、Node.js 用の単独型メールエンジンです。

IMAP 同期、SMTP 送信、ローカルキャッシュ、スレッド管理、検索、トランスポートエラーを、ばらばらなプロトコルアダプターの寄せ集めではなく、一貫したモデルとして扱います。実行時依存関係ゼロの、単一の事前バンドル済みファイルとして提供されます。コードを直接扱う開発者、構造化された soul / tools / skills ランタイムを通じて操作する LLM エージェント、そして接続コードを書かずにすぐ使える email CLI バイナリを求めるエージェント運用者という、3 つの対象者に向けて設計されています。

MCP サーバー

以下の各クライアントは、同じ stdio サーバー npx -y @ghostpaw/email mcp を起動します。キャッシュ済みメッセージは、GHOSTPAW_EMAIL_DB 環境変数（絶対パス）または --db <path> で別の場所を指定しない限り、~/.ghostpaw/email.db に保存されます。

Claude Code

claude mcp add ghostpaw-email -- npx -y @ghostpaw/email mcp

スキルもインストールするプラグインとして使うこともできます。

/plugin marketplace add GhostPawJS/email
/plugin install ghostpaw-email@ghostpaw-email

Email CLI（~/.email/config.toml）

[mcp_servers.ghostpaw-email]
command = "npx"
args = ["-y", "@ghostpaw/email", "mcp"]

Cursor（.cursor/mcp.json）、Claude Desktop（claude_desktop_config.json）、またはプロジェクトの .mcp.json：

{
  "mcpServers": {
    "ghostpaw-email": {
      "command": "npx",
      "args": ["-y", "@ghostpaw/email", "mcp"]
    }
  }
}

Claude Desktop のユーザーは、最新の GitHub リリースから server.mcpb をインストールすることもできます。コンテナホスト向けに Dockerfile も用意されています。 docker build -t ghostpaw-email . && docker run -i --rm -v email:/data ghostpaw-email。

サーバーは MCP 2026-07-28（ステートレス、server/discover）および、initialize ベースの各リビジョン 2025-11-25、2025-06-18、2025-03-26、2024-11-05 に対応しています。

ネットワーク操作には、既存の CLI アカウント設定（email account add）または EMAIL_IMAP_HOST、EMAIL_SMTP_HOST、EMAIL_USER、EMAIL_PASS（または EMAIL_ACCESS_TOKEN）を使用します。ツールの検出とキャッシュ済みデータの読み取りには、アカウントも認証情報も不要です。サーフェスデータベースの既定値は ~/.ghostpaw/email.db です。既存のアカウントキャッシュを読み取るには、--db にそのパスを指定してください。ネットワーク呼び出しごとに IMAP セッションを開いて閉じます。接続コマンドでは、呼び出し間でセッションは保持されません。

ツール CLI

npx -y @ghostpaw/email tools
npx -y @ghostpaw/email call mail_read '{"view":"folders"}' --db :memory:
npx -y @ghostpaw/email call mail_search '{"query":"invoice"}'

email と ghostpaw-email は、どちらも同じ CLI を実行します。既存のアカウント、読み取り、検索、作成、整理、同期コマンドも引き続き利用できます。完全なガイドは skills/email/references/cli.md にあります。

エージェントスキル：SKILL.md と skills/email/ はパッケージに含まれています。npx -y @ghostpaw/email skill でスキルを出力できます。

インストール

npm install @ghostpaw/email        # as a library
npm install -g @ghostpaw/email     # as a global CLI
npx @ghostpaw/email --help         # one-off, no install needed

Node.js 24+ が必要です（組み込みの node:sqlite モジュールを使用します）。

クイックスタート

import { Mailbox } from '@ghostpaw/email';

const mailbox = new Mailbox({
  imap: { host: 'imap.example.com', port: 993, tls: true },
  smtp: { host: 'smtp.example.com', port: 465, tls: true },
  auth: { user: '[email protected]', pass: 'secret' },
  storage: 'mail.db',
});

await mailbox.connect();

const folders = mailbox.read.folders();
await mailbox.network.sync();
const messages = mailbox.read.messages('INBOX', { limit: 20 });

await mailbox.write.send({
  to: [{ address: '[email protected]' }],
  subject: 'Hello',
  text: 'Sent from @ghostpaw/email.',
});

await mailbox.disconnect();

connect() は SQLite データベースを開き、スキーマを初期化し、アカウントを upsert して、IMAP セッションを認証します。この 1 回の呼び出しですべて完了します。

モデル

保存される概念が 7 つ、そこから導出される概念が 3 つあります。

概念	目的
Account	IMAP/SMTP 接続設定を持つ 1 つのメールアイデンティティ
Folder	同期メタデータと役割検出機能を持つ 1 つの IMAP メールボックスパス
Message	フラグ、ラベル、エンベロープを含む、ローカルにキャッシュされたメールヘッダーレコード
Body	1 通のメッセージのデコード済みテキスト／HTML コンテンツと、生の RFC 2822 バイト列
Attachment	オンデマンドでバイナリを取得できる、デコード済み MIME パート
SyncLog	フォルダーごとに、完了した同期処理を記録するレコード
Thread	References/In-Reply-To ヘッダーから導出される JWZ 会話ツリー

このモデルでは、メールの状態の種類ごとに、それぞれの保存先があります。

見た目	実際の内容
メールの受信トレイ	role: 'inbox' と同期済みメッセージを持つ Folder
会話	References と In-Reply-To のチェーンから算出される Thread
未読メール	flags 配列に \Seen がない Message
スター付きメール	flags に \Flagged がある Message
メッセージに添付された PDF	BODYSTRUCTURE のメタデータを持ち、データをオンデマンドで取得する Attachment
「同期で新しいメッセージが 12 件見つかった」	戦略、件数、所要時間を記録した SyncLog の行

状態は切り替えるのではなく、導出されます。スレッド ID は同期時にヘッダーチェーンから算出され、フォルダーの役割は IMAP の special-use 属性から検出され、添付ファイルのメタデータは BODYSTRUCTURE から抽出されます。すべて同期時に実体化され、手動設定のステータスフィールドとして保存されることはありません。

2 つの利用者層

人間の開発者

型付きの read、write、network サーフェスを備えた Mailbox クラスを使用すると、すべてのメール操作にコードから直接アクセスできます。

import { Mailbox } from '@ghostpaw/email';

const mailbox = new Mailbox(config);
await mailbox.connect();

const threads = mailbox.read.threads('INBOX', { limit: 20 });
const detail = await mailbox.read.getMessage('INBOX', uid);
await mailbox.write.reply('INBOX', uid, { text: 'Acknowledged.' });
await mailbox.write.archive('INBOX', [uid]);

実例を含む、人間向けの完全なガイドについては、HUMAN.md を参照してください。

LLM エージェント

LLM の認知負荷を最小限に抑えるよう設計された、構造化ランタイムサーフェスとして tools、skills、soul の名前空間を使用します。

import { skills, soul, tools } from '@ghostpaw/email';

// 5 intent-shaped tools covering the full mailbox lifecycle
const allTools = tools.aligned.emailTools;
const readTool = tools.aligned.getEmailToolByName('mail_read');

// 8 reusable workflow skills for multi-step scenarios
const triageSkill = skills.getEmailSkillByName('triage-inbox');

// Thinking foundation for system prompts
const systemPrompt = soul.renderEmailSoulPromptFoundation();

共有ファサードは name、description、whenToUse、whenNotToUse、inputSchema、readOnly、sideEffects を公開します。ハンドラーは read、write、network サーフェスと、既存のツール入力を含むコンテキストを受け取ります。戻り値は { ok, outcome, summary, next, data } です。data.entities にはメッセージまたはメールボックスへの参照が含まれ、next には後続の操作に関するヒントが含まれます。エラーは ok: false に対応します。読み取り操作でもローカルキャッシュが更新される場合があるため、メタデータではすべてのツールが状態を書き込むものとして保守的に扱います。

const definitions = tools.aligned.listEmailToolDefinitions();
const tool = tools.aligned.getEmailToolByName('mail_read');
if (!tool) throw new Error('mail_read is unavailable');
const result = await tool.handler(
  { read: mailbox.read, write: mailbox.write, network: mailbox.network },
  { view: 'folders' },
);
console.log(result.ok, result.summary);

非推奨の tools.emailTools と tools.getEmailToolByName() は、元の { outcome, summary, entities, nextSteps } 形式の結果と変更されていない入力で引き続き利用できます。共通形式を使用するには tools.aligned に移行してください。

soul、tools、skills を網羅した AI 向けの完全なガイドについては、LLM.md を参照してください。

CLI（bash）

このパッケージにはスタンドアロンの email バイナリが含まれています。アカウントは ~/.config/email/accounts.json に保存され、すべてのコマンドで機械可読な出力を得るための --json を指定できます。

# Add an account once
email account add --name work \
  --imap-host imap.example.com --smtp-host smtp.example.com \
  --user [email protected] --pass secret

# Then use it
email sync                              # pull latest from server
email read                             # check inbox
email search "invoice"                 # FTS5 search
email compose send --to [email protected] --subject "Hi" --body "Hello"

# Machine-readable output for agents and scripts
email read queue --json | jq '.entities[].title'
echo "body text" | email compose send --to [email protected] --subject "Hi"

すべてのコマンドは、ツールレイヤーと同じ { outcome, summary, entities, nextSteps } 形式を返し、一貫した終了コードを使用します（0 は成功、1 はユーザーエラー、2 は設定エラー、3 は認証エラー、4 はネットワークエラー、5 はツールエラー）。

エージェント運用者および Claude Code / OpenClaw ユーザー向けの CLI リファレンス全文については、SKILL.md を参照してください。

ツール

生のプロトコル操作ではなく、運用者の意図に沿って設計された 5 つのツールです。

ツール	機能
mail_read	フォルダー一覧、メッセージキュー、スレッド、本文、添付ファイル、生の EML を読み取ります
mail_search	FTS5 によるローカル検索、またはサーバー上での IMAP SEARCH
mail_compose	メールの送信、返信、転送、下書きの保存／更新／送信
mail_organize	フラグ、ラベル、コピー、移動、アーカイブ、ゴミ箱、迷惑メール、フォルダー管理
mail_sync	接続、切断、再接続、同期、フォルダーの更新、監視

主な特性

• ランタイム依存関係ゼロ。 Node 24+ に組み込まれている node:sqlite、node:tls、node:net、 node:zlib、node:crypto のみを使用します。
• 単一の事前バンドル済みファイル。 dist/ に ESM と CJS のエントリーポイントがそれぞれ 1 つずつあります。サブパス エクスポートもコード分割もありません。
• 純粋な SQLite ストレージ。 FTS5 の全文検索、6 つのテーブル、決定論的な派生読み取りを備えています。Mailbox が独自の DatabaseSync インスタンスを作成して管理します。
• 完全な IMAP エンジン。 ストリーミングトークナイザー、レスポンスパーサー、COMPRESS=DEFLATE、 IDLE（RFC 2177）、CONDSTORE/QRESYNC（RFC 7162）、XOAUTH2/OAUTHBEARER に対応しています。
• 完全な SMTP クライアント。 TLS/STARTTLS/平文、PLAIN/LOGIN/XOAUTH2、ドット スタッフィング、送信後の「送信済み」への APPEND に対応しています。
• 必要に応じた本文の取得。 初回同期ではヘッダーと BODYSTRUCTURE のみを取得します。 メッセージ本文と添付ファイルのバイトデータは、実際に読み取る際に取得します。
• JWZ スレッド化。 References/In-Reply-To ヘッダーから会話ツリーを計算し、深さ順のレンダリングとフォルダー横断に対応しています。
• 意図に沿った書き込み。 send、reply、forward、archive、trash、 saveDraft、sendDraft — 汎用的な CRUD ではなく、何を行ったかを表す操作です。
• AI ランタイムの追加機能。 姿勢を定める soul、アクションを実行する tools、ワークフローをガイドする skills — すべて任意で、構造化されています。
• テストを各モジュールに配置。 型定義のみのモジュールを除くすべてのモジュールに、同じ場所に .test.ts ファイルがあります。 ドキュメントに記載された動作は、実行可能なテストでカバーされています。

パッケージの公開インターフェース

import {
  Mailbox,      // porcelain class — the primary entry point
  initSchema,   // schema setup (called automatically by Mailbox.connect())
  read,         // read surface factory
  write,        // write surface factory
  network,      // network surface factory
  tools,        // LLM tool definitions + registry
  skills,       // LLM workflow skills + registry
  soul,         // thinking foundation for system prompts
} from '@ghostpaw/email';

すべてのドメイン型とランタイム型は、TypeScript の利用者向けにルートからも利用できます。

import type {
  EmailConfig,
  AuthConfig,
  EmailReadSurface,
  EmailWriteSurface,
  EmailNetworkSurface,
  EmailToolDefinition,
  EmailToolResult,
  EmailSkill,
  EmailSoul,
  ComposeInput,
  ReplyInput,
  ForwardInput,
  Message,
  MessageDetail,
  Thread,
  Folder,
  Attachment,
  AttachmentMeta,
  SyncResult,
  WatchEvent,
} from '@ghostpaw/email';

ドキュメント

ドキュメント	対象者
SKILL.md	email を bash ツールとして実行するエージェント運用者と Claude Code ユーザー
HUMAN.md	read／write／network を使って Mailbox API を利用する開発者
LLM.md	soul、tools、skills を LLM システムに組み込むエージェントの開発者
docs/README.md	アーキテクチャの概要：モデル、不変条件、プロトコル境界、ソースの構成
docs/entities/	スキーマ、操作、不変条件を記載したエンティティ別マニュアル

開発

npm install
npm test            # node:test runner
npm run typecheck   # tsc --noEmit
npm run lint        # biome check
npm run build       # ESM + CJS + declarations via tsup

このリポジトリでは、.nvmrc／.node-version／ .tool-versions／mise.toml／Volta を通じて Node 24.14.0 に固定しています。お好みのバージョンマネージャーをご利用ください。

サポート

このパッケージがお役に立った場合は、メンテナンスへの協賛をご検討ください。

---

Anonyfox • MIT License