@ainote/mcp 1.2.0 → 1.3.0

package/README.md

@@ -58,6 +58,10 @@ All transports expose the same tool catalog. Choose the option that matches your
 - 🔄 **Claude Environment Sync**: Push/pull `~/.claude/` skills, agents, commands, hooks across machines (macOS/WSL/Linux)
 - 🔐 **End-to-End Encryption**: `mcp` category (mcpServers + API keys) auto-encrypted client-side with age; server never sees plaintext
 - 🪪 **OS Keychain Integration**: Per-machine age identity stored in macOS Keychain / libsecret / Credential Manager (file fallback supported)
+- 🤝 **Session Handoffs**: `handoff_save` / `handoff_list` / `handoff_get` with optional `time: HHMM` for same-day disambiguation — saved under the primary vault, auto-purged after 7 days
+- 📦 **Multi-Device File Sync**: `sync_push` / `sync_pull` / `sync_list` push markdown notes into the user's git-backed primary vault — works across macOS, Linux, iOS shortcuts
+- 🏛️ **GitHub-Backed Vaults**: `vault_create` / `vault_clone` / `vault_sync` provision a private GitHub repo per vault; ainote indexes contents but never proxies git traffic
+- 🛡️ **MCP Tool Annotations**: Every tool advertises `readOnlyHint` / `destructiveHint` / `idempotentHint` / `openWorldHint` so autonomous agent runtimes can gate destructive calls
 - 🏷️ **Category Support**: Organize tasks with categories
 - 🔍 **Advanced Filtering**: 18+ filter options including date ranges, location, overdue tasks
 - ⭐ **Priority Management**: Mark tasks as important
@@ -553,6 +557,115 @@ Claude: I'll list all documents under dev/...
 → list_dev_docs()
 ```
 
+### Session Handoffs (cross-session / cross-device continuation)
+
+Save a self-contained handoff note when the context window fills up or when you need to continue on another machine. Stored in the user's primary vault under `handoffs/`, auto-purged after 7 days.
+
+| Tool | Purpose |
+|------|---------|
+| `handoff_save` | Write a handoff (`project`, `topic`, `content`, optional `date`, optional `time` HHMM for same-day disambiguation) |
+| `handoff_list` | Most-recent-first list, optionally filtered by project. ⚠️ Triggers the 7-day stale purge as a side effect |
+| `handoff_get` | Fetch by `project` + `topic` (+ optional `date`/`time`). Returns latest if `date` omitted. Same purge side effect |
+
+```text
+You: "Save a handoff for the logi-phase4 work I'm wrapping up"
+Claude: → handoff_save({project: "logi", topic: "phase4", time: "1555", content: "..."})
+       Stored at handoffs/logi-phase4-1555-2026-05-14.txt
+
+(later, on the laptop):
+You: "Pick up the logi-phase4 handoff"
+Claude: → handoff_get({project: "logi", topic: "phase4"})
+```
+
+### Multi-Device File Sync (`sync_*` / `vault_sync`)
+
+`sync_push` / `sync_pull` / `sync_list` operate on the user's git-backed primary vault. `vault_sync` is the unified entrypoint that accepts an `action: list|pull|push` argument.
+
+| Tool | Purpose |
+|------|---------|
+| `sync_push` | Push a markdown note (path + content) into the vault repo |
+| `sync_pull` | Read a markdown note from the vault by path |
+| `sync_list` | Enumerate vault paths (optionally filtered) |
+| `vault_sync` | Unified wrapper around the above three |
+
+### GitHub-Backed Vaults
+
+| Tool | Purpose |
+|------|---------|
+| `vault_list` | List the user's vaults + sync status + indexed file counts |
+| `vault_create` | Create a new private vault as a GitHub repo (requires the ainote GitHub App install) |
+| `vault_clone` | Return the git clone URL for an existing vault. ainote does **not** proxy git traffic — use your usual GitHub credentials |
+| `vault_connect_status` | Check whether the ainote GitHub App is installed for this user; returns an install URL otherwise |
+
+---
+
+## Annotations Reference
+
+Every tool advertises four MCP-spec annotations on `tools/list` so autonomous agent runtimes can reason about safety:
+
+| Hint | Meaning | Agent action |
+|------|---------|--------------|
+| `readOnlyHint: true` | Tool does not mutate any server state | Safe to call without consent gates |
+| `destructiveHint: true` | Tool deletes / overwrites / purges state | Require explicit user consent or transaction boundary |
+| `idempotentHint: true` | Repeating the call with same args ends in the same state | Safe to retry on timeout / network error |
+| `openWorldHint: true` | Tool reaches an external system (GitHub, SMTP, third-party) | Outcomes may be non-deterministic; cache cautiously |
+
+**Notable annotations:**
+
+- `handoff_list` / `handoff_get` are marked `destructiveHint: true` because they run a 7-day stale-handoff purge on every call.
+- `login_and_get_key` is marked `readOnlyHint: false` because it creates a default MCP key when the user has none.
+- `vault_sync` is conservatively `destructiveHint: true` because `action=push` with empty content can delete an indexed file.
+
+See the source-of-truth mapping at [`docs/todo/MCP_TOOL_ANNOTATIONS_MAPPING.md`](https://github.com/seunghan91/ainote/blob/main/docs/todo/MCP_TOOL_ANNOTATIONS_MAPPING.md) in the ainote repo.
+
+---
+
+## Agent Compatibility
+
+ainote MCP works with any client that speaks Model Context Protocol over stdio or HTTP. Tested setups:
+
+### Claude Desktop / Claude Code (stdio via this npm package)
+
+```json
+{
+  "mcpServers": {
+    "ainote": {
+      "command": "npx",
+      "args": ["-y", "@ainote/mcp"],
+      "env": { "AINOTE_API_KEY": "..." }
+    }
+  }
+}
+```
+
+### Claude Code (direct HTTP — recommended for full feature set)
+
+```json
+{
+  "mcpServers": {
+    "ainote": {
+      "type": "http",
+      "url": "https://ainote-5muq.onrender.com/api/mcp",
+      "headers": { "Authorization": "McpKey <YOUR_MCP_KEY>" }
+    }
+  }
+}
+```
+
+> The `type: "http"` field is required — without it, Claude Code's user-level MCP loader silently rejects the entire `mcpServers` block.
+
+### Cursor / Windsurf (stdio)
+
+Same as Claude Desktop config — both editors accept the `command + args + env` shape.
+
+### ChatGPT / OpenAI Custom GPTs
+
+Use the hosted HTTP endpoint via OpenAI Connectors or Custom GPT Actions. The MCP JSON-RPC body works as a regular HTTPS POST. An OpenAPI 3.1 mirror of the tool surface is planned (see `docs/todo/AGENT_INTEROP_ROADMAP_2026.md` Phase 1.4).
+
+### LangChain / LangGraph
+
+Wrap the HTTP endpoint as a remote tool. Pass `Authorization: McpKey <YOUR_MCP_KEY>` and POST JSON-RPC requests. Tool definitions can be discovered via `tools/list`.
+
 ---
 
 ## API Reference

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ainote/mcp",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "MCP server for AI Note - Tasks, Dev Docs, and multi-device file sync (CLAUDE.md, memory files, Cursor rules, Windsurf rules)",
   "main": "index.js",
   "type": "module",