paput-mcp 2.4.0 → 2.5.0

package/README.md

@@ -38,7 +38,8 @@ npm install -g paput-mcp
 
 ## MCP Configuration
 
-Create an API key in your PaPut account settings and pass it through the MCP server environment.
+Create an API key in your PaPut account settings and pass it through the MCP
+server environment when you want to run tools that call the PaPut API.
 
 ```json
 "paput": {
@@ -53,7 +54,7 @@ Create an API key in your PaPut account settings and pass it through the MCP ser
 
 ### Environment Variables
 
-- `PAPUT_API_KEY` - Required PaPut API key.
+- `PAPUT_API_KEY` - Optional at startup. Required when executing tools that call the PaPut API.
 - `PAPUT_API_URL` - Optional API URL. Defaults to `https://api.paput.io`.
 - `PAPUT_PROJECT_MATCH` - Optional project name fragment for automatic project linking when creating or updating memos.
 - `PAPUT_HOME` - Optional PaPut local data directory. Defaults to `~/.paput`.
@@ -129,6 +130,8 @@ Claude can call skills such as `/paput-save`. Codex can call `$paput-save` or us
 
 ## Available Tools
 
+Detailed public tool documentation is available in [docs/tools.md](docs/tools.md).
+
 ### Memo Management
 
 - `paput_create_memo` - Create a PaPut memo directly.
@@ -176,6 +179,8 @@ Write and destructive tools should be used only when the user intent is clear. I
 
 ## Usage Examples
 
+Additional public examples are available in [docs/usage-examples.md](docs/usage-examples.md).
+
 ### 1. Avoid duplicate knowledge before saving
 
 ```text
@@ -221,3 +226,10 @@ PaPut MCP stores local data under `~/.paput` by default.
   skills/  # Canonical skills linked into Claude/Codex
   cache/   # Synced memos, pending candidates, and processed sessions
 ```
+
+## Public Documents
+
+- [Privacy Policy](docs/privacy-policy.md)
+- [Usage Examples](docs/usage-examples.md)
+- [Tools And Use Cases](docs/tools.md)
+- [MCP Directory Submission Notes](docs/directory-submission.md)

package/dist/check-http.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+const endpoint = process.env.MCP_HTTP_URL ?? process.argv[2];
+if (!endpoint) {
+    console.error('Usage: MCP_HTTP_URL=https://example.onrender.com npm run check:http');
+    process.exit(1);
+}
+const client = new Client({
+    name: 'paput-mcp-http-check',
+    version: '1.0.0',
+}, {
+    capabilities: {},
+});
+try {
+    const transport = new StreamableHTTPClientTransport(new URL(endpoint));
+    await client.connect(transport);
+    const result = await client.listTools();
+    const toolNames = result.tools.map((tool) => tool.name);
+    console.log(`Connected to ${endpoint}`);
+    console.log(`Tools: ${toolNames.length}`);
+    console.log(toolNames.join('\n'));
+}
+finally {
+    await client.close();
+}
+//# sourceMappingURL=check-http.js.map

package/dist/check-http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-http.js","sourceRoot":"","sources":["../src/check-http.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AACnE,OAAO,EAAE,6BAA6B,EAAE,MAAM,oDAAoD,CAAC;AAEnG,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAE7D,IAAI,CAAC,QAAQ,EAAE,CAAC;IACd,OAAO,CAAC,KAAK,CACX,qEAAqE,CACtE,CAAC;IACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,MAAM,MAAM,GAAG,IAAI,MAAM,CACvB;IACE,IAAI,EAAE,sBAAsB;IAC5B,OAAO,EAAE,OAAO;CACjB,EACD;IACE,YAAY,EAAE,EAAE;CACjB,CACF,CAAC;AAEF,IAAI,CAAC;IACH,MAAM,SAAS,GAAG,IAAI,6BAA6B,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC;IACvE,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAEhC,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,SAAS,EAAE,CAAC;IACxC,MAAM,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAExD,OAAO,CAAC,GAAG,CAAC,gBAAgB,QAAQ,EAAE,CAAC,CAAC;IACxC,OAAO,CAAC,GAAG,CAAC,UAAU,SAAS,CAAC,MAAM,EAAE,CAAC,CAAC;IAC1C,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;AACpC,CAAC;QAAS,CAAC;IACT,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;AACvB,CAAC"}

package/dist/http.js

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+import { createServer, } from 'node:http';
+import { fileURLToPath } from 'node:url';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { createMcpServer } from './server.js';
+const OAUTH_SCOPES = ['paput.read', 'paput.write'];
+export async function startHttpMcpServer(options = {}) {
+    const endpoint = options.endpoint ?? '/';
+    const port = options.port ?? Number(process.env.PORT ?? 3000);
+    const host = options.host ?? process.env.HOST;
+    const apiUrl = options.apiUrl ?? process.env.PAPUT_API_URL ?? 'https://api.paput.io';
+    const apiOrigin = new URL(apiUrl).origin;
+    const oauthRequired = options.oauthRequired ?? (!options.apiKey && !process.env.PAPUT_API_KEY);
+    const httpServer = createServer(async (req, res) => {
+        const requestUrl = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);
+        const publicOrigin = getPublicOrigin(req, requestUrl);
+        const resourceUrl = getResourceUrl(publicOrigin, endpoint);
+        const protectedResourceMetadataUrl = getProtectedResourceMetadataUrl(publicOrigin, endpoint);
+        if (requestUrl.pathname === '/healthz') {
+            res.writeHead(200, { 'content-type': 'application/json' });
+            res.end(JSON.stringify({ ok: true }));
+            return;
+        }
+        if (requestUrl.pathname === '/.well-known/oauth-protected-resource') {
+            sendJson(res, 200, {
+                resource: resourceUrl,
+                authorization_servers: [apiOrigin],
+                scopes_supported: OAUTH_SCOPES,
+                bearer_methods_supported: ['header'],
+            });
+            return;
+        }
+        if (requestUrl.pathname === '/.well-known/oauth-authorization-server') {
+            res.writeHead(307, {
+                location: `${apiOrigin}/.well-known/oauth-authorization-server`,
+            });
+            res.end();
+            return;
+        }
+        if (requestUrl.pathname !== endpoint) {
+            sendJsonRpcError(res, 404, -32000, 'Not found');
+            return;
+        }
+        if (req.method !== 'POST') {
+            res.setHeader('allow', 'POST');
+            sendJsonRpcError(res, 405, -32000, 'Method not allowed.');
+            return;
+        }
+        const accessToken = extractBearerToken(req.headers.authorization);
+        if (oauthRequired && !accessToken) {
+            sendOAuthChallenge(res, protectedResourceMetadataUrl);
+            return;
+        }
+        const mcpServer = createMcpServer({ ...options, accessToken });
+        const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: undefined,
+        });
+        transport.onerror = (error) => {
+            console.error('MCP HTTP transport error:', error);
+        };
+        res.on('close', () => {
+            void transport.close().catch((error) => {
+                console.error('Failed to close MCP HTTP transport:', error);
+            });
+            void mcpServer.close().catch((error) => {
+                console.error('Failed to close MCP server:', error);
+            });
+        });
+        try {
+            await mcpServer.connect(transport);
+            await transport.handleRequest(req, res);
+        }
+        catch (error) {
+            console.error('Error handling MCP HTTP request:', error);
+            if (!res.headersSent) {
+                sendJsonRpcError(res, 500, -32603, 'Internal server error');
+            }
+        }
+    });
+    await new Promise((resolve, reject) => {
+        httpServer.once('error', reject);
+        httpServer.listen(port, host, () => {
+            httpServer.off('error', reject);
+            resolve();
+        });
+    });
+    return httpServer;
+}
+function getPublicOrigin(req, requestUrl) {
+    const protoHeader = req.headers['x-forwarded-proto'];
+    const forwardedProto = Array.isArray(protoHeader)
+        ? protoHeader[0]
+        : protoHeader;
+    const scheme = forwardedProto ?? requestUrl.protocol.replace(':', '');
+    return `${scheme}://${req.headers.host ?? 'localhost'}`;
+}
+function getResourceUrl(publicOrigin, endpoint) {
+    return endpoint === '/' ? publicOrigin : `${publicOrigin}${endpoint}`;
+}
+function getProtectedResourceMetadataUrl(publicOrigin, endpoint) {
+    return endpoint === '/'
+        ? `${publicOrigin}/.well-known/oauth-protected-resource`
+        : `${publicOrigin}/.well-known/oauth-protected-resource${endpoint}`;
+}
+function extractBearerToken(authorizationHeader) {
+    if (!authorizationHeader?.toLowerCase().startsWith('bearer ')) {
+        return undefined;
+    }
+    const token = authorizationHeader.slice('bearer '.length).trim();
+    return token || undefined;
+}
+function sendOAuthChallenge(res, resourceMetadataUrl) {
+    res.writeHead(401, {
+        'content-type': 'application/json',
+        'www-authenticate': `Bearer resource_metadata="${resourceMetadataUrl}", scope="${OAUTH_SCOPES.join(' ')}"`,
+    });
+    res.end(JSON.stringify({
+        error: 'unauthorized',
+        error_description: 'OAuth authentication is required.',
+    }));
+}
+function sendJson(res, statusCode, body) {
+    res.writeHead(statusCode, { 'content-type': 'application/json' });
+    res.end(JSON.stringify(body));
+}
+function sendJsonRpcError(res, statusCode, code, message) {
+    res.writeHead(statusCode, { 'content-type': 'application/json' });
+    res.end(JSON.stringify({
+        jsonrpc: '2.0',
+        error: { code, message },
+        id: null,
+    }));
+}
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+    startHttpMcpServer()
+        .then((server) => {
+        const address = server.address();
+        const listeningOn = typeof address === 'object' && address
+            ? `${address.address}:${address.port}`
+            : String(address);
+        console.error(`PaPut MCP Streamable HTTP server listening on ${listeningOn}`);
+        console.error('MCP endpoint: /');
+    })
+        .catch((error) => {
+        console.error('Unexpected error:', error);
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=http.js.map

package/dist/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"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"}

package/dist/server.js

@@ -5,28 +5,27 @@ import { setupTool } from './tool.js';
 import { setupErrorHandling } from './utils/error-handler.js';
 const require = createRequire(import.meta.url);
 const packageJson = require('../package.json');
+export function createMcpServer(options = {}) {
+    const apiKey = options.apiKey ?? process.env.PAPUT_API_KEY;
+    const accessToken = options.accessToken;
+    const apiUrl = options.apiUrl ?? process.env.PAPUT_API_URL ?? 'https://api.paput.io';
+    const server = new Server({
+        name: 'paput-mcp',
+        version: packageJson.version,
+    }, {
+        capabilities: {
+            tools: {},
+            resources: {},
+        },
+    });
+    setupTool(server, apiUrl, apiKey, accessToken);
+    setupErrorHandling(server);
+    return server;
+}
 export class MCPServer {
     server;
-    constructor() {
-        // Read environment variables
-        const apiKey = process.env.PAPUT_API_KEY;
-        const apiUrl = process.env.PAPUT_API_URL ?? 'https://api.paput.io';
-        if (!apiKey) {
-            throw new Error('PAPUT_API_KEY environment variable is not set');
-        }
-        // Initialize server
-        this.server = new Server({
-            name: 'paput-mcp',
-            version: packageJson.version,
-        }, {
-            capabilities: {
-                tools: {},
-                resources: {},
-            },
-        });
-        // Set up tools and error handling
-        setupTool(this.server, apiUrl, apiKey);
-        setupErrorHandling(this.server);
+    constructor(options = {}) {
+        this.server = createMcpServer(options);
     }
     async run() {
         const transport = new StdioServerTransport();

package/dist/server.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AACnE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAE9D,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC/C,MAAM,WAAW,GAAG,OAAO,CAAC,iBAAiB,CAAwB,CAAC;AAEtE,MAAM,OAAO,SAAS;IACZ,MAAM,CAAS;IAEvB;QACE,6BAA6B;QAC7B,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC;QACzC,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,sBAAsB,CAAC;QAEnE,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAC;QACnE,CAAC;QAED,oBAAoB;QACpB,IAAI,CAAC,MAAM,GAAG,IAAI,MAAM,CACtB;YACE,IAAI,EAAE,WAAW;YACjB,OAAO,EAAE,WAAW,CAAC,OAAO;SAC7B,EACD;YACE,YAAY,EAAE;gBACZ,KAAK,EAAE,EAAE;gBACT,SAAS,EAAE,EAAE;aACd;SACF,CACF,CAAC;QAEF,kCAAkC;QAClC,SAAS,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;QACvC,kBAAkB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAClC,CAAC;IAED,KAAK,CAAC,GAAG;QACP,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;QAE7C,SAAS,CAAC,OAAO,GAAG,CAAC,KAAc,EAAE,EAAE;YACrC,OAAO,CAAC,KAAK,CAAC,cAAc,KAAK,EAAE,CAAC,CAAC;QACvC,CAAC,CAAC;QAEF,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IACvC,CAAC;CACF"}
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AACnE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAE9D,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC/C,MAAM,WAAW,GAAG,OAAO,CAAC,iBAAiB,CAAwB,CAAC;AAQtE,MAAM,UAAU,eAAe,CAAC,UAA4B,EAAE;IAC5D,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC;IAC3D,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;IACxC,MAAM,MAAM,GACV,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,sBAAsB,CAAC;IAExE,MAAM,MAAM,GAAG,IAAI,MAAM,CACvB;QACE,IAAI,EAAE,WAAW;QACjB,OAAO,EAAE,WAAW,CAAC,OAAO;KAC7B,EACD;QACE,YAAY,EAAE;YACZ,KAAK,EAAE,EAAE;YACT,SAAS,EAAE,EAAE;SACd;KACF,CACF,CAAC;IAEF,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC;IAC/C,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAE3B,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,OAAO,SAAS;IACZ,MAAM,CAAS;IAEvB,YAAY,UAA4B,EAAE;QACxC,IAAI,CAAC,MAAM,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;IACzC,CAAC;IAED,KAAK,CAAC,GAAG;QACP,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;QAE7C,SAAS,CAAC,OAAO,GAAG,CAAC,KAAc,EAAE,EAAE;YACrC,OAAO,CAAC,KAAK,CAAC,cAAc,KAAK,EAAE,CAAC,CAAC;QACvC,CAAC,CAAC;QAEF,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IACvC,CAAC;CACF"}

package/dist/services/api/client.js

@@ -1,11 +1,16 @@
 export async function apiRequest(config, endpoint, method, body) {
+    if (!config.accessToken && !config.apiKey) {
+        throw new Error('PaPut authentication is not configured. Set PAPUT_API_KEY or connect with OAuth.');
+    }
     const url = endpoint.startsWith('http')
         ? endpoint
         : `${config.apiUrl}${endpoint}`;
     const options = {
         method,
         headers: {
-            'X-API-Key': config.apiKey,
+            ...(config.accessToken
+                ? { Authorization: `Bearer ${config.accessToken}` }
+                : { 'X-API-Key': config.apiKey ?? '' }),
             ...(method !== 'GET' && method !== 'DELETE'
                 ? { 'Content-Type': 'application/json' }
                 : {}),
@@ -37,8 +42,8 @@ export async function apiRequest(config, endpoint, method, body) {
         return {};
     }
 }
-export function createApiClient(apiUrl, apiKey) {
-    const config = { apiUrl, apiKey };
+export function createApiClient(apiUrl, apiKey, accessToken) {
+    const config = { apiUrl, apiKey, accessToken };
     return {
         get: (endpoint) => apiRequest(config, endpoint, 'GET'),
         post: (endpoint, body) => apiRequest(config, endpoint, 'POST', body),

package/dist/services/api/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../../../src/services/api/client.ts"],"names":[],"mappings":"AAOA,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,MAAiB,EACjB,QAAgB,EAChB,MAAkB,EAClB,IAAc;IAEd,MAAM,GAAG,GAAG,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC;QACrC,CAAC,CAAC,QAAQ;QACV,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,GAAG,QAAQ,EAAE,CAAC;IAElC,MAAM,OAAO,GAAgB;QAC3B,MAAM;QACN,OAAO,EAAE;YACP,WAAW,EAAE,MAAM,CAAC,MAAM;YAC1B,GAAG,CAAC,MAAM,KAAK,KAAK,IAAI,MAAM,KAAK,QAAQ;gBACzC,CAAC,CAAC,EAAE,cAAc,EAAE,kBAAkB,EAAE;gBACxC,CAAC,CAAC,EAAE,CAAC;SACR;KACF,CAAC;IAEF,IAAI,IAAI,IAAI,MAAM,KAAK,KAAK,IAAI,MAAM,KAAK,QAAQ,EAAE,CAAC;QACpD,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IACtC,CAAC;IAED,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IAE3C,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,MAAM,SAAS,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;QACxC,IAAI,CAAC;YACH,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;YACxC,MAAM,IAAI,KAAK,CACb,SAAS,CAAC,KAAK,IAAI,uBAAuB,QAAQ,CAAC,MAAM,EAAE,CAC5D,CAAC;QACJ,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,MAAM,IAAI,KAAK,CAAC,SAAS,IAAI,uBAAuB,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;QACzE,CAAC;IACH,CAAC;IAED,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;QAC5B,OAAO,EAAO,CAAC;IACjB,CAAC;IAED,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;IACnC,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,2EAA2E;QAC3E,OAAO,EAAO,CAAC;IACjB,CAAC;AACH,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,MAAc,EAAE,MAAc;IAC5D,MAAM,MAAM,GAAc,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;IAE7C,OAAO;QACL,GAAG,EAAE,CAAc,QAAgB,EAAE,EAAE,CACrC,UAAU,CAAI,MAAM,EAAE,QAAQ,EAAE,KAAK,CAAC;QAExC,IAAI,EAAE,CAAc,QAAgB,EAAE,IAAc,EAAE,EAAE,CACtD,UAAU,CAAI,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC;QAE/C,GAAG,EAAE,CAAc,QAAgB,EAAE,IAAc,EAAE,EAAE,CACrD,UAAU,CAAI,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,IAAI,CAAC;QAE9C,MAAM,EAAE,CAAc,QAAgB,EAAE,EAAE,CACxC,UAAU,CAAI,MAAM,EAAE,QAAQ,EAAE,QAAQ,CAAC;QAE3C,OAAO,EAAE,CACP,QAAgB,EAChB,MAAkB,EAClB,IAAc,EACd,EAAE,CAAC,UAAU,CAAI,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC;KACnD,CAAC;AACJ,CAAC"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../../src/services/api/client.ts"],"names":[],"mappings":"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"}

package/dist/tool.js

@@ -2,8 +2,8 @@ import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSche
 import { createApiClient } from './services/api/index.js';
 import { getGeneratedInputSchema } from './schemas/tool-input.js';
 import { createMemoTool, searchMemoTool, getMemoTool, updateMemoTool, getCategoriesTool, createNoteTool, searchNotesTool, getNoteTool, updateNoteTool, getSkillSheetTool, updateSkillSheetBasicInfoTool, updateSkillSheetSelfPrTool, setSkillSheetSkillsTool, upsertSkillSheetProjectTool, deleteSkillSheetProjectTool, cacheStatusTool, syncRemoteMemosTool, scanSessionsTool, getSessionTranscriptTool, addKnowledgeCandidatesTool, listPendingCandidatesTool, savePendingCandidateTool, discardPendingCandidateTool, } from './handlers/index.js';
-export function setupTool(server, apiUrl, apiKey) {
-    const apiClient = createApiClient(apiUrl, apiKey);
+export function setupTool(server, apiUrl, apiKey, accessToken) {
+    const apiClient = createApiClient(apiUrl, apiKey, accessToken);
     const tools = getRegisteredTools();
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
         tools: tools.map((tool) => tool.definition),

package/dist/tool.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool.js","sourceRoot":"","sources":["../src/tool.ts"],"names":[],"mappings":"AACA,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,0BAA0B,EAC1B,yBAAyB,GAC1B,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,EACL,cAAc,EACd,cAAc,EACd,WAAW,EACX,cAAc,EACd,iBAAiB,EACjB,cAAc,EACd,eAAe,EACf,WAAW,EACX,cAAc,EACd,iBAAiB,EACjB,6BAA6B,EAC7B,0BAA0B,EAC1B,uBAAuB,EACvB,2BAA2B,EAC3B,2BAA2B,EAC3B,eAAe,EACf,mBAAmB,EACnB,gBAAgB,EAChB,wBAAwB,EACxB,0BAA0B,EAC1B,yBAAyB,EACzB,wBAAwB,EACxB,2BAA2B,GAC5B,MAAM,qBAAqB,CAAC;AAG7B,MAAM,UAAU,SAAS,CACvB,MAAc,EACd,MAAc,EACd,MAAc;IAEd,MAAM,SAAS,GAAG,eAAe,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClD,MAAM,KAAK,GAAG,kBAAkB,EAAE,CAAC;IAEnC,MAAM,CAAC,iBAAiB,CAAC,sBAAsB,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC;QAC5D,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC;KAC5C,CAAC,CAAC,CAAC;IAEJ,MAAM,CAAC,iBAAiB,CAAC,qBAAqB,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;QAChE,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,KAAK,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAE1E,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,OAAO;gBACL,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,MAAM;wBACZ,IAAI,EAAE,iBAAiB,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE;qBAC7C;iBACF;gBACD,OAAO,EAAE,IAAI;aACd,CAAC;QACJ,CAAC;QAED,OAAO,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;IACjE,CAAC,CAAC,CAAC;IAEH,+BAA+B;IAC/B,MAAM,CAAC,iBAAiB,CAAC,0BAA0B,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC;QAChE,SAAS,EAAE;YACT;gBACE,GAAG,EAAE,eAAe;gBACpB,IAAI,EAAE,iBAAiB;gBACvB,WAAW,EAAE,sCAAsC;gBACnD,QAAQ,EAAE,kBAAkB;aAC7B;SACF;KACF,CAAC,CAAC,CAAC;IAEJ,sCAAsC;IACtC,MAAM,CAAC,iBAAiB,CAAC,yBAAyB,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;QACpE,IAAI,OAAO,CAAC,MAAM,CAAC,GAAG,KAAK,eAAe,EAAE,CAAC;YAC3C,OAAO;gBACL,QAAQ,EAAE;oBACR;wBACE,GAAG,EAAE,OAAO,CAAC,MAAM,CAAC,GAAG;wBACvB,QAAQ,EAAE,YAAY;wBACtB,IAAI,EAAE,uBAAuB,OAAO,CAAC,MAAM,CAAC,GAAG,EAAE;qBAClD;iBACF;aACF,CAAC;QACJ,CAAC;QAED,MAAM,SAAS,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;YACrC,IAAI,EAAE,IAAI,CAAC,UAAU,CAAC,IAAI;YAC1B,WAAW,EAAE,IAAI,CAAC,UAAU,CAAC,WAAW;YACxC,WAAW,EAAE,IAAI,CAAC,UAAU,CAAC,WAAW;YACxC,WAAW,EAAE,IAAI,CAAC,UAAU,CAAC,WAAW;SACzC,CAAC,CAAC,CAAC;QAEJ,OAAO;YACL,QAAQ,EAAE;gBACR;oBACE,GAAG,EAAE,eAAe;oBACpB,QAAQ,EAAE,kBAAkB;oBAC5B,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;iBACzC;aACF;SACF,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,kBAAkB;IAChC,OAAO;QACL,cAAc;QACd,cAAc;QACd,WAAW;QACX,cAAc;QACd,iBAAiB;QACjB,cAAc;QACd,eAAe;QACf,WAAW;QACX,cAAc;QACd,iBAAiB;QACjB,6BAA6B;QAC7B,0BAA0B;QAC1B,uBAAuB;QACvB,2BAA2B;QAC3B,2BAA2B;QAC3B,eAAe;QACf,mBAAmB;QACnB,gBAAgB;QAChB,wBAAwB;QACxB,0BAA0B;QAC1B,yBAAyB;QACzB,wBAAwB;QACxB,2BAA2B;KAC5B,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC;AAC7B,CAAC;AAED,SAAS,mBAAmB,CAAC,IAAiB;IAC5C,MAAM,IAAI,GAAG,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;IAClC,MAAM,QAAQ,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;IACtC,MAAM,WAAW,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC;IAC5C,MAAM,WAAW,GAAG,uBAAuB,CAAC,IAAI,CAAC,CAAC;IAElD,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,MAAM,IAAI,KAAK,CAAC,wCAAwC,IAAI,EAAE,CAAC,CAAC;IAClE,CAAC;IAED,OAAO;QACL,GAAG,IAAI;QACP,UAAU,EAAE;YACV,GAAG,IAAI,CAAC,UAAU;YAClB,WAAW;YACX,WAAW,EAAE;gBACX,GAAG,IAAI,CAAC,UAAU,CAAC,WAAW;gBAC9B,YAAY,EAAE,QAAQ;gBACtB,eAAe,EAAE,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,WAAW;gBAC/C,cAAc,EAAE,gBAAgB,CAAC,IAAI,CAAC;gBACtC,aAAa,EAAE,KAAK;aACrB;SACF;KACF,CAAC;AACJ,CAAC;AAED,SAAS,cAAc,CAAC,IAAY;IAClC,OAAO,CACL,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC;QACtB,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC;QACzB,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC;QACvB,IAAI,KAAK,sBAAsB;QAC/B,IAAI,KAAK,oBAAoB;QAC7B,IAAI,KAAK,qBAAqB,CAC/B,CAAC;AACJ,CAAC;AAED,SAAS,iBAAiB,CAAC,IAAY;IACrC,OAAO,CACL,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC;QACzB,IAAI,KAAK,iCAAiC;QAC1C,IAAI,KAAK,8BAA8B;QACvC,IAAI,KAAK,kCAAkC;QAC3C,IAAI,CAAC,UAAU,CAAC,eAAe,CAAC,CACjC,CAAC;AACJ,CAAC;AAED,SAAS,gBAAgB,CAAC,IAAY;IACpC,OAAO,CACL,cAAc,CAAC,IAAI,CAAC;QACpB,IAAI,CAAC,UAAU,CAAC,eAAe,CAAC;QAChC,IAAI,KAAK,8BAA8B,CACxC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"tool.js","sourceRoot":"","sources":["../src/tool.ts"],"names":[],"mappings":"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"}

package/docs/directory-submission.md

@@ -0,0 +1,91 @@
+# 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.
+
+Validation checklist:
+
+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. Confirm write/destructive tools show user confirmation before execution.
+
+## 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`
+
+Developer Mode validation checklist:
+
+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.
+
+## 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: `docs/privacy-policy.md`
+- Usage Examples: `docs/usage-examples.md`
+- Tools And Use Cases: `docs/tools.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,60 @@
+# 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 or API keys 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 may use a PaPut API key provided through environment variables. You are responsible for keeping API keys and local 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, and session metadata. It remains on your device unless you choose to save a pending candidate to PaPut.
+
+## 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 API keys, 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.
+- 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,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.4.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"
   ],