paput-mcp 2.4.0 → 2.6.0

package/docs/directory-submission.md

@@ -0,0 +1,102 @@
+# MCP Directory Submission Notes
+
+This document collects public submission information for PaPut MCP.
+
+## Server Summary
+
+- Name: PaPut MCP
+- Website: https://paput.io
+- Remote MCP server URL: https://mcp.paput.io
+- Transport: Streamable HTTP
+- Authentication: OAuth 2.1-style authorization code with PKCE
+- Dynamic client registration: Supported through PaPut OAuth metadata
+- Data model: Data-only MCP server
+- UI widgets: None
+- Primary use: Give AI assistants controlled access to PaPut memos, notes, skill sheets, and reusable knowledge workflows
+
+## OAuth Metadata
+
+- Protected resource metadata: `https://mcp.paput.io/.well-known/oauth-protected-resource`
+- Authorization server: `https://api.paput.io`
+- Authorization server metadata: `https://api.paput.io/.well-known/oauth-authorization-server`
+- Authorization endpoint: `https://api.paput.io/oauth/authorize`
+- Token endpoint: `https://api.paput.io/oauth/token`
+- Registration endpoint: `https://api.paput.io/oauth/register`
+- Supported scopes: `paput.read`, `paput.write`
+- Token endpoint auth method: `none`
+- PKCE method: `S256`
+
+## Claude Connector Preparation
+
+Recommended listing details:
+
+- Connector name: PaPut
+- Description: Connect Claude to PaPut memos, notes, skill sheets, and knowledge capture workflows.
+- Server URL: `https://mcp.paput.io`
+- Authentication: OAuth
+- Transport: Streamable HTTP
+- Scopes: `paput.read paput.write`
+- Category: Productivity, knowledge management, developer tools
+- Data access summary: Reads and writes PaPut content only after the user authorizes access through PaPut OAuth.
+- Safety summary: Read-only tools are annotated. Write and destructive tools require clear user intent and should be confirmed by the client.
+- Callback URL handling: Claude registers its redirect URI through dynamic client registration. PaPut validates the registered redirect URI during authorization instead of relying on a preconfigured static callback URL.
+
+Validation checklist:
+
+Status: verified with Claude custom connector UI.
+
+1. Add `https://mcp.paput.io` as a remote MCP connector in Claude.
+2. Complete the PaPut OAuth consent flow.
+3. Confirm `tools/list` returns PaPut tools.
+4. Call a read-only tool such as `paput_get_categories`.
+5. Call a search tool such as `paput_search_memo` with a low `limit`.
+6. Call one write tool with test-safe content.
+7. Confirm write/destructive tools show user confirmation before execution.
+8. Confirm the created or changed data is visible in PaPut.
+
+## ChatGPT Developer Mode Preparation
+
+Recommended listing details:
+
+- App name: PaPut
+- Remote MCP server URL: `https://mcp.paput.io`
+- Authentication: OAuth with dynamic client registration
+- Transport: Streamable HTTP
+- Tool access: Full MCP tools, data-only, no UI widgets
+- Scopes: `paput.read paput.write`
+- Description: Connect PaPut to ChatGPT so you can search, read, create, and organize your PaPut memos, notes, skill sheet, and reusable knowledge. PaPut MCP uses OAuth and only accesses your PaPut data after you authorize the connection.
+- Callback URL handling: ChatGPT should register its redirect URI through dynamic client registration. PaPut validates registered redirect URIs before issuing authorization codes.
+
+Developer Mode validation checklist:
+
+Status: verified with ChatGPT Developer Mode.
+
+1. Enable Developer Mode in ChatGPT settings.
+2. Create an app for the remote MCP server URL `https://mcp.paput.io`.
+3. Use OAuth without static credentials so dynamic client registration is exercised.
+4. Complete the PaPut OAuth flow in the browser.
+5. Refresh the app tools and confirm PaPut tools are listed.
+6. Start a conversation with Developer Mode enabled and select the PaPut app.
+7. Prompt: `Use the PaPut app to get my categories. Do not use other tools.`
+8. Confirm `paput_get_categories` succeeds.
+9. Prompt a write action in a test-safe way and confirm the client asks for approval before execution.
+10. Confirm the created or changed data is visible in PaPut.
+
+## Submission Positioning
+
+PaPut MCP should be submitted as a data-only MCP connector. It should not request UI widget support. The connector should emphasize:
+
+- User-owned PaPut data access through OAuth.
+- Knowledge management and session knowledge capture.
+- Explicit confirmation for write and destructive operations.
+- No broad web browsing, scraping, or unrelated third-party data access.
+
+## Public References
+
+- Privacy Policy: https://github.com/mizulba-dev/paput-mcp/blob/main/docs/privacy-policy.md
+- Usage Examples: https://github.com/mizulba-dev/paput-mcp/blob/main/docs/usage-examples.md
+- Tools And Use Cases: https://github.com/mizulba-dev/paput-mcp/blob/main/docs/tools.md
+- Directory Submission Notes: https://github.com/mizulba-dev/paput-mcp/blob/main/docs/directory-submission.md
+- OpenAI ChatGPT Developer Mode documentation: https://platform.openai.com/docs/guides/developer-mode
+- OpenAI MCP documentation: https://platform.openai.com/docs/mcp/
+- Anthropic remote MCP connector documentation: https://support.anthropic.com/en/articles/11175166-getting-started-with-custom-integrations-using-remote-mcp

package/docs/privacy-policy.md

@@ -0,0 +1,61 @@
+# Privacy Policy
+
+Effective date: June 1, 2026
+
+PaPut MCP Server connects AI assistants and MCP clients to PaPut through the Model Context Protocol. This policy explains what data is handled when you use the PaPut MCP Server.
+
+## Data The Server Handles
+
+Depending on the tools you use, the server may process:
+
+- PaPut memos, notes, categories, skill sheet data, and related project metadata.
+- OAuth access tokens used to authenticate requests to PaPut.
+- MCP request and response metadata needed to execute tool calls.
+- Local Claude or Codex session metadata and transcripts when you explicitly use local knowledge capture tools.
+- Local pending knowledge candidates and cache data stored on your device.
+
+## How Data Is Used
+
+Data is used only to provide the MCP tools you invoke, including:
+
+- Searching, reading, creating, and updating PaPut memos and notes.
+- Reading and updating your PaPut skill sheet.
+- Synchronizing PaPut memo metadata into a local cache for duplicate detection.
+- Scanning local AI session logs and preparing reusable knowledge candidates.
+- Completing OAuth authorization and token-based requests to the PaPut API.
+
+## Authentication
+
+Remote MCP connections use OAuth. PaPut issues tokens after you sign in and approve the requested scopes. The MCP server receives bearer tokens on requests and forwards them to the PaPut API. The MCP server does not intentionally persist OAuth access tokens.
+
+Local stdio usage uses OAuth tokens created by `paput-mcp login`. You are responsible for keeping local token and configuration files private.
+
+## Local Data
+
+When local knowledge capture features are used, PaPut MCP may store cache files under `~/.paput` or a configured cache directory. This local data can include synced memo summaries, pending knowledge candidates, processed session markers, session metadata, and local OAuth tokens created by `paput-mcp login`. The default OAuth token directory is created with `0700` permissions and the token file is written with `0600` permissions. It remains on your device unless you choose to save a pending candidate to PaPut or remove the local token cache with `paput-mcp logout`.
+
+## Logging
+
+Hosted infrastructure and MCP clients may record operational logs such as request timestamps, status codes, errors, and connection metadata. Logs are used for reliability, troubleshooting, abuse prevention, and security. The server is designed not to log OAuth tokens or full private content intentionally.
+
+## Sharing
+
+PaPut MCP does not sell personal data. Data may be processed by PaPut infrastructure providers only as needed to operate the service. Data may also be disclosed if required by law or to protect the security and integrity of PaPut, users, or the service.
+
+## User Control
+
+You can:
+
+- Revoke OAuth access from PaPut account settings when available.
+- Remove local MCP configuration from your client.
+- Delete local cache data stored under `~/.paput` or your configured cache directory.
+- Run `paput-mcp logout` to revoke and remove the local OAuth token cache.
+- Delete or update PaPut content using PaPut or authorized MCP tools.
+
+## Security
+
+PaPut MCP uses OAuth for remote access and supports read/write tool annotations so clients can request user confirmation for write or destructive actions. You should review tool calls before approving actions that create, update, delete, publish, or discard data.
+
+## Contact
+
+For privacy questions, use the contact method provided on https://paput.io.

package/docs/tools.md

@@ -0,0 +1,70 @@
+# 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.
+
+Remote HTTP mode exposes API-backed PaPut tools only. Local cache, pending
+candidate, and session transcript tools are available in local CLI mode because
+they read or write files on the user's device.
+
+## 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.              |
+
+`paput_create_memo` and `paput_update_memo` can link projects through explicit
+`projects`, a `project_match` input, or local `PAPUT_PROJECT_MATCH` in local CLI
+mode.
+
+## 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
+
+These tools are local CLI mode only. They are not listed by the remote HTTP MCP
+server.
+
+| 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,106 @@
+# Usage Examples
+
+These examples show typical ways to use PaPut MCP from an AI assistant.
+
+## 1. Create A Memo From A Remote MCP Client
+
+Prompt:
+
+```text
+Create a private PaPut memo summarizing this conversation.
+```
+
+Expected tool flow:
+
+1. `paput_create_memo`
+2. `paput_search_memo` or `paput_get_memo` when the user wants to verify the result
+
+Use case: quickly save useful content from Claude, ChatGPT, Codex, or another remote MCP client.
+
+## 2. 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.
+
+Local mode note: `paput_add_knowledge_candidates` and pending review tools are
+local CLI mode tools.
+
+## 3. 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.
+
+Local mode note: session scanning and transcript reading are local CLI mode
+tools.
+
+## 4. 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.
+
+Local mode note: pending candidate tools are local CLI mode tools.
+
+## 5. 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.
+
+## 6. 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.4.0",
+  "version": "2.6.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"
   ],