✨ TPC Server ✨

TPC サーバー

AI と人間の協業を目的とした Node.js/Express API です。まずは、思考や計画を JSON ファイルに保存します。

セットアップと使い方

1. 依存関係をインストールします：npm install
2. サーバーを起動します：node server.js
3. サーバーは http://localhost:3001 で実行されます。

変更履歴

詳しいリリースノートは CHANGELOG.md を参照してください。

テスト

npm test（または npm run test:unit）を実行して、Jest による API／統合テストを実施します。 Playwright による UI テストを実施するには、npm run test:e2e を実行します。 決定論的な MCP の計画／思考ライフサイクルのスモーク検証を実施するには、npm run smoke:mcp を実行します。

本番環境のセキュリティ

本番環境では、デフォルトで /tpc.db のダウンロードは無効になっています。 明示的に許可するには、EXPOSE_TPC_DB=true を設定します。

運用エンドポイント

• GET /health は基本的な稼働状況を返します。
• GET /ready は準備状況と DB パスを返します。

データ契約（REST + MCP）

• ID：計画／思考には SQLite による整数の自動採番 ID を使用します。
• タイムスタンプ：
  • thoughts.timestamp、plans.timestamp = ISO8601 形式の文字列。
  • plans.created_at、plans.last_modified_at = エポックミリ秒。
• タグ：DB カラムには JSON エンコードされた文字列配列を保存します。

プロジェクト構成

• server.js：モジュール化された構成（db/、routes/、middleware/）を持つメインの Express サーバー。
• mcp-server.js：AI クライアント向け MCP サーバー（stdio トランスポート）。npm run mcp で起動します。
• data/tpc.db：思考や計画を永続的に保存する SQLite データベース。
• tests/：テストファイル（Jest のユニットテスト、MCP テスト）。
• public/：静的なシングルページ UI。

使用例

REST API

• すべての思考を取得：curl http://localhost:3001/thoughts
• すべての計画を取得：curl http://localhost:3001/plans
• 思考を作成：curl -X POST http://localhost:3001/thoughts -H "Content-Type: application/json" -d '{"content": "My thought"}'
• 計画を作成：curl -X POST http://localhost:3001/plans -H "Content-Type: application/json" -d '{"title": "My Plan", "description": "Plan details"}'
• 計画のステータスを更新：curl -X PATCH http://localhost:3001/plans/1 -H "Content-Type: application/json" -d '{"status": "in_progress"}'
• 計画／思考を横断検索：curl "http://localhost:3001/search?q=AI&type=plans&tags=urgent&limit=5"
• 計画にタグを追加：curl -X PATCH http://localhost:3001/plans/1/tags -H "Content-Type: application/json" -d '{"tag": "ai"}'（追加）または {"tags": ["ai", "urgent"]}（置換）
• タグで計画を絞り込み：curl "http://localhost:3001/plans?tags=ai,urgent"
• UI を表示：サーバーの起動後に http://localhost:3001/index.html にアクセスします。

MCP サーバー

• MCP サーバーを起動：npm run mcp
• stdio 経由で接続します。MCP クライアントにこれを設定してください。
• 利用可能なツール：list_plans、get_plan、create_plan、update_plan、list_thoughts、create_thought、search_thoughts、get_context
• 利用可能なリソース：tpc://plans、tpc://thoughts、tpc://context

機能

• MCP サーバー：AI クライアント向けの完全な MCP プロトコル実装です。npm run mcp で起動します（stdio トランスポート）。
• モジュール化されたサーバーアーキテクチャ：保守性の高い API 開発のため、db/、routes/、middleware/ に整理されています。
• SQLite による永続化：思考と計画を保存する単一の data/tpc.db を使用し、べき等なスキーマ移行に対応します。
• 包括的なテスト：ユニットテスト（エンドポイント、バリデーション、統合）には Jest を、E2E UI テスト（レンダリング、操作）には Playwright を使用します。
• AI との協業を重視：/context などのエンドポイントでエージェントのメモリ用データを集約し、レビュー用フラグを使った人間による編集にも対応します。
• リッチテキスト対応：Plan の説明では Markdown 形式（太字、リストなど）を受け付け、marked.js を使って UI に表示します。
• 検索と整理：タイプ／タグ／件数のフィルターに対応した全文検索 API（/search?q=）を提供します。UI では検索入力とタグによる絞り込み／編集が可能です。
• タグ付けシステム：API／UI から計画や思考のタグを追加／編集／絞り込みでき、分類に役立ちます（例：['ai', 'urgent']）。

v2.7 - 検索と整理

実装済みの機能

• 全文検索エンドポイント（GET /search?q=<query>）。対象を絞り込むには、任意で?type=plans|thoughts、?tags=tag1,tag2、?limit=Nを指定できます。
• タグ付けシステム：plans/thoughtsテーブルにtags列（JSON配列）を追加。POST/PUT/PATCH /plans/:id/tags（thoughtsの場合も同様）で管理できます。
• タグによる絞り込み：リストエンドポイント（/plans、/thoughts、/search）で?tags=ai,urgentを指定します（AND条件）。
• /contextを拡張し、?search=<query>で集約データを絞り込めるようになりました。
• UI：グローバル検索入力欄、詳細画面でのタグ編集、リスト内のタグ絞り込みドロップダウン。

使用方法

• API検索：curl "http://localhost:3001/search?q=collaboration&type=plans&tags=ai"
• プランにタグを付ける：curl -X PATCH http://localhost:3001/plans/1/tags -H "Content-Type: application/json" -d '{"tags": ["ai", "urgent"]}'（置換）または{"tag": "new"}（追加）。
• タグで絞り込む：curl "http://localhost:3001/plans?tags=ai,urgent"
• UI：検索ボックスにクエリを入力します。プラン／思考の各ビューでタグをクリックすると、編集や絞り込みができます。

主な変更点

• スキーマの追加：plans/thoughtsテーブルにtags TEXT列（デフォルト値は'[]'）を追加。バックフィルを含む後方互換性のあるマイグレーションを実施しました。
• 新しいルート：統合クエリ用の/search。
• v2.6のMarkdownサポートとモジュール構造を基盤としています。