tm-mcp

@pyunto/tm-mcp

Pyunto Time Management 用の MCP（Model Context Protocol）サーバーです。 Claude Code、Claude Desktop、Codex CLI、Cursor など、あらゆる MCP クライアントを Pyunto TM アカウントに接続し、アシスタントがスケジュールを読み取り、時間の使いみちを要約し、時間を記録できるようにします。

ユーザー向けのセットアップ手順は https://tm.pyunto.com/docs/mcp.en.md にあります（日本語： https://tm.pyunto.com/docs/mcp.ja.md）。このファイルは開発者向けです。

ツール

ツール	スコープ
whoami — アカウント、キー名、スコープ、復号ステータス	—
list_projects	projects:read
list_tasks（プロジェクトまたはタスクが対象とする日付で絞り込み）	projects:read
list_time_blocks（期間 ≤ 92 日）	blocks:read
time_summary（プロジェクト／タスク／日付ごとにグループ化）	record:read
log_time（書き込み）	blocks:write
update_time_block（書き込み）	blocks:write
delete_time_block — 1 つの ID、完全削除、添付ファイルも削除	blocks:delete

すべてのツールは JSON をテキストとして返します。エラーは isError の結果として返されます。トランスポートレベルで例外をスローするのではなく、修正方法（不足しているスコープ、誤ったキー、ロックされた E2EE）をメッセージで示すため、エージェントは対応できますが、スタックトレースでは対応できません。

インストール

npx -y @pyunto/tm-mcp        # what an MCP client config runs

ソースからビルドする

このパッケージは、依存する SDK とともに npm-workspaces リポジトリにあります。ワークスペースのリンクを使うため、リポジトリのルートからビルドしてください。

npm install
npm run build                 # both packages
npm test                      # sdk crypto round-trips + 25 MCP tool checks

ビルド結果：mcp/dist/cli.js は実行可能な stdio サーバーです（dist/index.js はテストからインポートできる、副作用のないモジュールのままです）。

設定

環境変数のみを使用します。MCP クライアントがプロセスを起動し、設定ファイルから環境変数を渡します。

API キーがなくてもサーバーは起動し、tools/list に応答します。クライアントやディレクトリは、誰かがサインアップする前に、サーバーが提供する機能を確認できます。キーなしでツールを呼び出すと、不透明な 401 ではなく、isError として同じ案内が返されます。また、whoami は失敗する代わりにキーがないことを報告します。

変数	必須	デフォルト	用途
PYUNTO_TM_API_KEY	データ利用時	—	ptm_…。Settings → Account → API keys で発行します。キーがなくてもツールの一覧表示はできます
PYUNTO_TM_BASE_URL		https://tm.pyunto.com	セルフホスト可能なインスタンス
PYUNTO_TM_PASSWORD		なし	E2EE の名前／メモを復号するため、秘密鍵をローカルで展開します
PYUNTO_TM_PASSWORD_FILE		なし	同じパスワードを環境変数ではなくファイルから読み込みます

{
  "mcpServers": {
    "pyunto-tm": {
      "command": "npx",
      "args": ["-y", "@pyunto/tm-mcp"],
      "env": { "PYUNTO_TM_API_KEY": "ptm_…" }
    }
  }
}

E2EE の処理方法

コンテンツフィールドはユーザーのブラウザーで暗号化されます。サーバーが平文を保持することはなく、このプロセスもデフォルトでは保持しません。パスワードを指定すると、サーバーはユーザーの パスワードでラップされた 秘密鍵の BLOB（GET /api/v1/keys、スコープ keys:read）をこのプロセス内で展開し、メモリー上で各プロジェクトのシールされた DEK を開きます。パスワードが送信されることはなく、ディスクに書き込まれることもありません。

パスワードがなくても、サーバーはスケジュールに関するすべての情報（ID、日付、時刻、期間、集計）に応答します。名前フィールドは、理由を説明する NOTE: を付けて空で返されます。そのため、モデルは名前を作り出すのではなく、制限があることを報告できます。

構成

src/index.ts     tool definitions + implementations + server wiring
src/cli.ts       the bin: calls start()
test/tools.mjs   stub /api/v1 server, exercises every tool and error path
test/cli.mjs     spawns the built bin (directly and via symlink) over real MCP

テスト用に callTool(name, args) をエクスポートしています。start() はトランスポートを接続しますが、呼び出すのは cli.ts のみです。

delete_time_block が 1 つの ID のみを対象とするのは意図的です。範囲指定やフィルターによる削除は提供していません。自動化された呼び出し元が範囲を誤ると、復元手段のない大量のデータが失われるためです。このツールの説明では、モデルに対し、対象のブロックを正確にユーザーに示したうえで、そのブロックについてユーザーから「はい」という確認を得るよう求めています。