watashi-db 0.0.13 → 0.0.15

package/misc/20260331_remote-transport-recipe.md

@@ -0,0 +1,316 @@
+# Streamable HTTP トランスポート追加 — claude.ai / リモートクライアント対応
+
+## Context
+
+watashi-db は現在 stdio トランスポートのみ対応（ローカル CLI 専用）。
+claude.ai やモバイルアプリからの接続には Streamable HTTP トランスポートが必要。
+
+MCP SDK `^1.12.1` を使用中。Streamable HTTP は MCP 仕様 2025-03-26 で標準化済み。
+SDK の `StreamableHTTPServerTransport` は v2 系で提供予定だが、
+仕様準拠の HTTP エンドポイントを自前実装することも可能。
+
+**ゴール**: 同一のツールロジックを stdio（ローカル）と HTTP（リモート）の両方で提供する。
+
+**前提**:
+- 既存の stdio モードはそのまま維持（破壊的変更なし）
+- サーバー起動時のフラグ（`--http`）でモード選択
+- OAuth 認証は後続ステップで追加（まず動くHTTPサーバーを作る）
+
+---
+
+## Step 1: HTTP サーバーエントリポイントの追加
+
+新ファイル `src/http-server.ts` を作成。Express で MCP プロトコルの HTTP エンドポイントを提供する。
+
+### `package.json`
+
+依存追加:
+```json
+{
+  "dependencies": {
+    "express": "^5.0.0"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.0"
+  }
+}
+```
+
+### `src/http-server.ts`
+
+```typescript
+/**
+ * Streamable HTTP トランスポート — MCP over HTTP
+ * MCP 仕様 2025-03-26 準拠の Streamable HTTP エンドポイント
+ */
+import express from "express";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { createMcpServer } from "./server-core.js";
+
+const PORT = parseInt(process.env.WATASHI_HTTP_PORT ?? "3100", 10);
+
+export async function startHttpServer(): Promise<void> {
+  const app = express();
+  app.use(express.json());
+
+  // MCP サーバーインスタンス（ツール登録済み）
+  const { server, cleanup } = await createMcpServer();
+
+  // セッション管理: Mcp-Session-Id ヘッダでセッションを識別
+  const sessions = new Map<string, McpServer>();
+
+  // POST /mcp — MCP リクエスト受信
+  app.post("/mcp", async (req, res) => {
+    // TODO: OAuth 認証チェック (Step 4)
+    // TODO: セッション管理
+    // TODO: MCP JSON-RPC リクエストをサーバーに渡して応答を返す
+  });
+
+  // GET /mcp — SSE ストリーム（サーバー→クライアント通知用）
+  app.get("/mcp", (req, res) => {
+    // TODO: Server-Sent Events ストリーム
+  });
+
+  // DELETE /mcp — セッション終了
+  app.delete("/mcp", (req, res) => {
+    // TODO: セッションクリーンアップ
+  });
+
+  app.listen(PORT, () => {
+    console.error(`[watashi-db] HTTP server listening on port ${PORT}`);
+  });
+
+  process.on("SIGINT", async () => {
+    await cleanup();
+    process.exit(0);
+  });
+}
+```
+
+**注意**: Step 1 では HTTP エンドポイントの骨格のみ。MCP プロトコルの JSON-RPC 処理は Step 2 で実装。
+
+---
+
+## Step 2: server.ts からツール登録ロジックを分離
+
+現在 `server.ts` は McpServer の作成・ツール登録・トランスポート接続・初期化を全て行っている。
+ツール登録と初期化ロジックを `server-core.ts` に抽出し、stdio / HTTP 両方から呼べるようにする。
+
+### `src/server-core.ts`（新規）
+
+```typescript
+/**
+ * MCP サーバーのコア — ツール登録・初期化
+ * トランスポートに依存しない。stdio / HTTP 両方から利用される。
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { SERVER_INSTRUCTIONS } from "./server-instructions.js";
+// ... 既存の import を server.ts から移動
+
+export interface McpServerInstance {
+  server: McpServer;
+  cleanup: () => Promise<void>;
+}
+
+export async function createMcpServer(options?: {
+  devMode?: boolean;
+}): Promise<McpServerInstance> {
+  // server.ts L37-136 のロジックを移動:
+  // 1. config.json 読み込み
+  // 2. StoreManager 初期化
+  // 3. SyncManager 初期化
+  // 4. セッション状態初期化
+  // 5. Embedding Provider 初期化
+  // 6. 起動時同期実行
+  // 7. McpServer 作成 + ツール登録
+
+  const server = new McpServer({ name: "watashi-db", version }, {
+    instructions: SERVER_INSTRUCTIONS,
+  });
+
+  // ツール登録（既存コードをそのまま移動）
+  registerClaimTools(server, toolPrefix);
+  registerDecisionTools(server, toolPrefix);
+  registerEpisodeTools(server, toolPrefix);
+  registerKnowledgeTools(server, toolPrefix);
+  registerUserMemoTools(server, toolPrefix);
+  registerMaintenanceTools(server, toolPrefix);
+
+  const cleanup = async () => {
+    storeManager.closeAll();
+  };
+
+  return { server, cleanup };
+}
+```
+
+### `src/server.ts`（変更）
+
+server-core.ts を使うように簡素化:
+
+```typescript
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createMcpServer } from "./server-core.js";
+
+export async function startServer(): Promise<void> {
+  const { server, cleanup } = await createMcpServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+
+  process.on("SIGINT", async () => {
+    await cleanup();
+    process.exit(0);
+  });
+}
+```
+
+### `src/index.ts`（変更）
+
+`--http` フラグでモード選択:
+
+```typescript
+const subcommand = process.argv[2];
+
+if (subcommand === "http") {
+  const { startHttpServer } = await import("./http-server.js");
+  await startHttpServer();
+} else if (subcommand === "hook") {
+  // ... 既存
+} else {
+  // デフォルト: stdio モード（後方互換）
+  const { startServer } = await import("./server.js");
+  await startServer();
+}
+```
+
+---
+
+## Step 3: MCP JSON-RPC over HTTP の実装
+
+Streamable HTTP トランスポートの仕様に従い、JSON-RPC メッセージのルーティングを実装する。
+
+### MCP Streamable HTTP 仕様のポイント
+
+- `POST /mcp`: クライアント → サーバーの JSON-RPC リクエスト
+  - リクエストボディ: JSON-RPC メッセージ（単一 or バッチ）
+  - レスポンス: JSON-RPC レスポンス（Content-Type: application/json）
+  - またはSSEストリーム（Content-Type: text/event-stream）— 長時間処理の場合
+- `GET /mcp`: サーバー → クライアントの SSE ストリーム（通知・進捗用）
+- `DELETE /mcp`: セッション終了
+- セッション識別: `Mcp-Session-Id` ヘッダ
+
+### 実装方針
+
+MCP SDK の `Server` クラスは内部的にトランスポートの `onmessage` コールバックで JSON-RPC を受け取る。
+HTTP の場合、リクエストボディをパースして `onmessage` に渡し、レスポンスを HTTP レスポンスとして返す。
+
+SDK v2 の StreamableHTTPServerTransport がリリースされれば置き換え可能だが、
+当面は薄い自前アダプタで対応する:
+
+```typescript
+// src/transport/streamable-http.ts（新規）
+
+import { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import type { JSONRPCMessage } from "@modelcontextprotocol/sdk/types.js";
+
+/**
+ * Express の req/res を MCP Transport として橋渡しする薄いアダプタ。
+ * SDK v2 の StreamableHTTPServerTransport がリリースされたら置き換える。
+ */
+export class HttpTransportAdapter implements Transport {
+  // セッション単位で作成
+  // onmessage / onerror / onclose コールバック
+  // send(): JSON-RPC レスポンスをキューに入れる
+  // handleRequest(body): リクエストボディを onmessage に渡す
+}
+```
+
+---
+
+## Step 4: OAuth 認証の追加
+
+claude.ai からの MCP 接続は OAuth 2.0 が必須。
+
+### 認証フロー
+
+1. クライアント（claude.ai）が Authorization Code Flow でトークン取得
+2. リクエストに `Authorization: Bearer <token>` を付与
+3. watashi-db サーバーがトークンを検証
+
+### 実装方針
+
+初期実装はシンプルな Bearer Token 検証（共有シークレット方式）:
+
+```typescript
+// src/auth/token.ts（新規）
+
+/**
+ * 環境変数 WATASHI_AUTH_TOKEN との照合。
+ * 将来的に OAuth 2.0 Resource Server（JWT 検証）に拡張。
+ */
+export function validateRequest(authHeader: string | undefined): boolean {
+  const expected = process.env.WATASHI_AUTH_TOKEN;
+  if (!expected) return true; // トークン未設定 = 認証なし（ローカル開発用）
+  if (!authHeader?.startsWith("Bearer ")) return false;
+  return authHeader.slice(7) === expected;
+}
+```
+
+将来の拡張（claude.ai 本格対応時）:
+- OAuth 2.0 Authorization Server の実装（または外部 IdP 連携）
+- JWT 検証
+- スコープベースのアクセス制御
+
+---
+
+## Step 5: デプロイ構成
+
+### ローカル HTTP モード（同一マシン内の複数クライアント向け）
+
+```bash
+npx watashi-db http
+# → localhost:3100 で起動
+# Claude Desktop の MCP 設定で http://localhost:3100/mcp を指定
+```
+
+### リモートモード（VPS / クラウドホスティング）
+
+```
+[claude.ai / モバイル] --HTTPS--> [VPS: watashi-db http] --> [SQLite on disk]
+```
+
+- Caddy / nginx で TLS 終端
+- systemd で watashi-db http をデーモン化
+- SQLite ファイルは VPS 上のディスクに配置
+- 既存の Sync 機能で VPS ↔ ローカル PC 間のデータ同期も可能
+
+### Cloudflare Workers + D1 案（将来）
+
+SQLite 互換の D1 を使えば、サーバーレスでの運用も視野に入る。
+ただし better-sqlite3 → D1 API への移行が必要で大きな変更になるため、
+まずは VPS + SQLite で動かし、需要に応じて検討。
+
+---
+
+## 実装順序と見積もり
+
+| Step | 内容 | 依存 |
+|------|------|------|
+| **Step 2** | server-core.ts 分離 | なし（**最初にやる**） |
+| **Step 1** | HTTP サーバー骨格 | Step 2 |
+| **Step 3** | JSON-RPC over HTTP 実装 | Step 1 |
+| **Step 4** | OAuth 認証 | Step 3 |
+| **Step 5** | デプロイ構成 | Step 3 |
+
+Step 2 → 1 → 3 で最小限の HTTP サーバーが動く。
+Step 4 は claude.ai 接続時に必須。Step 5 はインフラ側の作業。
+
+---
+
+## テスト方針
+
+- Step 2: 既存テスト全通過（リファクタリングのみ）
+- Step 1-3: integration.test.ts に HTTP クライアントテストを追加
+  - `fetch("http://localhost:3100/mcp", { method: "POST", body: JSON-RPC })` で MCP ツール呼び出し
+- Step 4: 認証あり/なしのテスト
+- E2E: Claude Desktop から localhost:3100 に接続して watashi_get(profile) が返ることを手動確認

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "watashi-db",
-  "version": "0.0.13",
+  "version": "0.0.15",
   "description": "わたしDB - User-owned personal context database as an MCP server for AI tools",
   "type": "module",
   "keywords": [
@@ -25,7 +25,9 @@
     "pretest": "tsc",
     "test": "vitest run",
     "test:watch": "vitest",
-    "prepublishOnly": "npm run build && npm test"
+    "prepublishOnly": "npm run build && npm test",
+    "preversion": "npm test",
+    "version": "bash scripts/update-license-version.sh"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",

package/scripts/update-license-version.sh

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+# Called by npm "version" script to update LICENSE with the new version.
+# $npm_package_version is set by npm automatically.
+set -euo pipefail
+
+sed -i "s/Licensed Work:        watashi-db .*/Licensed Work:        watashi-db $npm_package_version/" LICENSE
+git add LICENSE