paput-mcp 2.3.0 → 2.5.0

package/docs/tools.md

@@ -0,0 +1,59 @@
+# Tools And Use Cases
+
+PaPut MCP is a data-only MCP server. It exposes tools and resources for PaPut data. It does not provide UI widgets.
+
+## Confirmation Policy
+
+Clients and assistants should follow these rules:
+
+- Read-only tools may be used when they are relevant to the user's request.
+- Create, update, save, publish, discard, and delete tools should be used only when the user's intent is clear.
+- Destructive tools require explicit confirmation before execution.
+- `paput_save_pending_candidate` requires explicit user approval because it creates a PaPut memo from a local pending candidate.
+- `paput_delete_skill_sheet_project` should be used only when the user clearly intends to remove a project.
+- `paput_set_skill_sheet_skills` replaces the full skill list and should be used only when the complete desired final list is known.
+- `paput_discard_pending_candidate` removes a pending item from the save flow and should be confirmed when the candidate may still be useful.
+- Update and upsert tools should preserve existing data unless the user requested the change.
+
+## Memo Tools
+
+| Tool                   | Safety            | Use case                                                                         |
+| ---------------------- | ----------------- | -------------------------------------------------------------------------------- |
+| `paput_create_memo`    | Write             | Create a PaPut memo when the user explicitly asks to save content directly.      |
+| `paput_search_memo`    | Read-only         | Search memos by keyword, category, IDs, date, visibility, or pagination.         |
+| `paput_get_memo`       | Read-only         | Read the full details of a memo by ID.                                           |
+| `paput_update_memo`    | Destructive/write | Update an existing memo title, body, visibility, categories, or linked projects. |
+| `paput_get_categories` | Read-only         | List categories before assigning categories or checking duplicates.              |
+
+## Note Tools
+
+| Tool                 | Safety            | Use case                                               |
+| -------------------- | ----------------- | ------------------------------------------------------ |
+| `paput_create_note`  | Write             | Create a note that groups existing memo IDs.           |
+| `paput_search_notes` | Read-only         | Search notes by keyword, visibility, and pagination.   |
+| `paput_get_note`     | Read-only         | Read a note and its attached memos.                    |
+| `paput_update_note`  | Destructive/write | Update a note title, visibility, or attached memo IDs. |
+
+## Skill Sheet Tools
+
+| Tool                                  | Safety            | Use case                                                                                   |
+| ------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------ |
+| `paput_get_skill_sheet`               | Read-only         | Read the user's PaPut skill sheet.                                                         |
+| `paput_update_skill_sheet_basic_info` | Destructive/write | Update profile fields such as nearest station, gender, birth date, or years of experience. |
+| `paput_update_skill_sheet_self_pr`    | Destructive/write | Update the self PR section.                                                                |
+| `paput_set_skill_sheet_skills`        | Destructive/write | Replace the full skill list with a known final state.                                      |
+| `paput_upsert_skill_sheet_project`    | Destructive/write | Add or update a skill sheet project by ID or exact title match.                            |
+| `paput_delete_skill_sheet_project`    | Destructive       | Delete a skill sheet project by ID.                                                        |
+
+## Knowledge Capture And Local Cache Tools
+
+| Tool                              | Safety                       | Use case                                                                      |
+| --------------------------------- | ---------------------------- | ----------------------------------------------------------------------------- |
+| `paput_cache_status`              | Read-only                    | Inspect local cache, pending candidates, processed sessions, and sync status. |
+| `paput_sync_remote_memos`         | Write to local cache         | Sync existing PaPut memos into the local cache for duplicate detection.       |
+| `paput_scan_sessions`             | Read-only                    | Scan local Claude and Codex session logs for reusable knowledge sources.      |
+| `paput_get_session_transcript`    | Read-only                    | Read a selected local Claude or Codex session transcript.                     |
+| `paput_add_knowledge_candidates`  | Write to local pending queue | Add extracted reusable knowledge candidates before they are saved to PaPut.   |
+| `paput_list_pending_candidates`   | Read-only                    | List pending candidates for review.                                           |
+| `paput_save_pending_candidate`    | Write                        | Save an approved pending candidate as a PaPut memo.                           |
+| `paput_discard_pending_candidate` | Destructive local action     | Remove a pending candidate from the save flow.                                |

package/docs/usage-examples.md

@@ -0,0 +1,83 @@
+# Usage Examples
+
+These examples show typical ways to use PaPut MCP from an AI assistant.
+
+## 1. Search Existing Memos Before Creating Knowledge
+
+Prompt:
+
+```text
+Search my PaPut memos for existing notes about OAuth dynamic client registration before creating a new knowledge candidate.
+```
+
+Expected tool flow:
+
+1. `paput_search_memo`
+2. `paput_add_knowledge_candidates` only when no duplicate or near-duplicate exists
+3. `paput_list_pending_candidates` when the user wants to review pending items
+
+Use case: avoid duplicate long-term knowledge while preserving useful decisions from engineering work.
+
+## 2. Capture Reusable Knowledge From A Codex Session
+
+Prompt:
+
+```text
+Scan recent Codex sessions, find the OAuth implementation session, and extract reusable knowledge candidates.
+```
+
+Expected tool flow:
+
+1. `paput_scan_sessions`
+2. `paput_get_session_transcript`
+3. `paput_add_knowledge_candidates`
+
+Use case: turn completed development work into reviewable knowledge without immediately publishing it to PaPut.
+
+## 3. Save An Approved Pending Candidate
+
+Prompt:
+
+```text
+Review my pending PaPut knowledge candidates and save the OAuth metadata candidate if it is not a duplicate.
+```
+
+Expected tool flow:
+
+1. `paput_list_pending_candidates`
+2. `paput_search_memo`
+3. `paput_save_pending_candidate` only after explicit user approval
+
+Use case: keep the user in control before creating a permanent PaPut memo.
+
+## 4. Update A Skill Sheet Project
+
+Prompt:
+
+```text
+Update my PaPut skill sheet project for the MCP server work with the latest technologies and responsibilities.
+```
+
+Expected tool flow:
+
+1. `paput_get_skill_sheet`
+2. `paput_upsert_skill_sheet_project`
+3. `paput_get_skill_sheet` to verify the final result
+
+Use case: maintain an accurate skill sheet after project milestones.
+
+## 5. Organize Memos Into A Note
+
+Prompt:
+
+```text
+Find my MCP-related memos and create a PaPut note that groups the most relevant ones.
+```
+
+Expected tool flow:
+
+1. `paput_search_memo`
+2. `paput_create_note`
+3. `paput_get_note` to verify attached memo IDs
+
+Use case: create curated collections from existing PaPut memos.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paput-mcp",
-  "version": "2.3.0",
+  "version": "2.5.0",
   "description": "PaPut MCP Server",
   "main": "dist/index.js",
   "type": "module",
@@ -11,7 +11,11 @@
     "build": "tsc",
     "test": "vitest run",
     "start": "node dist/index.js",
+    "start:http": "node dist/http.js",
     "dev": "ts-node --esm src/index.ts",
+    "dev:http": "ts-node --esm src/http.ts",
+    "check:http": "ts-node --esm src/check-http.ts",
+    "test:mcp:transports": "vitest run src/transport.test.ts",
     "prepare": "npm run build",
     "format": "prettier --write .",
     "type-check": "tsc --noEmit"
@@ -28,6 +32,7 @@
   "homepage": "https://paput.io",
   "files": [
     "dist",
+    "docs",
     "README.md",
     "LICENSE.txt"
   ],