@onllm-dev/4dpocket-mcp 0.2.0

package/README.md

@@ -0,0 +1,98 @@
+# @onllm-dev/4dpocket-mcp
+
+MCP client launcher for [4DPocket](https://github.com/onllm-dev/4DPocket) — connects stdio-based MCP clients (Claude Desktop, Cursor, Claude Code, Zed, etc.) to a remote 4DPocket instance over streamable HTTP with PAT auth.
+
+## Install
+
+No install needed — use via `npx`:
+
+```bash
+npx @onllm-dev/4dpocket-mcp --url https://your.pocket.tld --token fdp_pat_xxx
+```
+
+## Get a PAT
+
+1. Open your 4DPocket instance → **Settings → API Tokens & MCP**
+2. Click **Create Token**, pick a name and scope
+3. Copy the `fdp_pat_...` string (shown once)
+
+## Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "4dpocket": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@onllm-dev/4dpocket-mcp",
+        "--url", "https://your.pocket.tld",
+        "--token", "fdp_pat_xxx"
+      ]
+    }
+  }
+}
+```
+
+Restart Claude Desktop.
+
+## Cursor
+
+`~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "4dpocket": {
+      "command": "npx",
+      "args": ["-y", "@onllm-dev/4dpocket-mcp", "--url", "https://your.pocket.tld", "--token", "fdp_pat_xxx"]
+    }
+  }
+}
+```
+
+## Claude Code
+
+If your 4DPocket server supports HTTP MCP directly, you can skip this package and wire it natively:
+
+```bash
+claude mcp add --transport http 4dpocket https://your.pocket.tld/mcp \
+  --header "Authorization: Bearer fdp_pat_xxx"
+```
+
+Use `@onllm-dev/4dpocket-mcp` when your client only speaks stdio.
+
+## Env vars
+
+Instead of flags you can use env vars:
+
+```bash
+FDP_URL=https://your.pocket.tld FDP_TOKEN=fdp_pat_xxx npx @onllm-dev/4dpocket-mcp
+```
+
+## Available tools
+
+Once connected, your MCP client gets these 4DPocket tools:
+
+- `save_knowledge` — save a URL or note
+- `search_knowledge` — hybrid search across your saved items
+- `get_knowledge` — fetch an item by id
+- `update_knowledge` — edit title/notes/tags
+- `refresh_knowledge` — re-fetch and reprocess content
+- `delete_knowledge` — remove an item (requires `allow_deletion` PAT)
+- `list_collections`
+- `add_to_collection`
+- `get_entity`
+- `get_related_entities`
+
+## Troubleshooting
+
+- **`401 Unauthorized`** — the token is wrong, revoked, or doesn't start with `fdp_pat_`. Create a new one.
+- **`404 Not Found` on `/mcp`** — your server is older than 0.2.0. Upgrade the 4DPocket instance.
+- **`ENOTFOUND` / `ECONNREFUSED`** — the `--url` isn't reachable from your machine. Check VPN / firewall.
+
+## License
+
+MIT

package/bin.mjs

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+// @onllm-dev/4dpocket-mcp — thin launcher that proxies an MCP stdio client
+// (Claude Desktop, Cursor, Claude Code, etc.) to a remote 4DPocket server
+// over streamable HTTP with PAT auth.
+//
+// Usage:
+//   npx @onllm-dev/4dpocket-mcp --url https://yours.tld --token fdp_pat_xxx
+//   FDP_URL=... FDP_TOKEN=... npx @onllm-dev/4dpocket-mcp
+
+import { spawn } from "node:child_process";
+import { createRequire } from "node:module";
+import path from "node:path";
+import process from "node:process";
+
+const require = createRequire(import.meta.url);
+
+const HELP = `@onllm-dev/4dpocket-mcp — MCP client for 4DPocket
+
+Usage:
+  npx @onllm-dev/4dpocket-mcp --url <server-url> --token <pat>
+
+Options:
+  --url <url>      4DPocket server URL (e.g. https://pocket.example.com).
+                   Reads FDP_URL env var if omitted.
+  --token <pat>    Personal Access Token (fdp_pat_...).
+                   Reads FDP_TOKEN env var if omitted.
+  --help, -h       Show this help.
+  --version, -v    Show version.
+
+Claude Desktop / Cursor config example:
+  {
+    "mcpServers": {
+      "4dpocket": {
+        "command": "npx",
+        "args": ["-y", "@onllm-dev/4dpocket-mcp",
+                 "--url", "https://yours.tld",
+                 "--token", "fdp_pat_xxx"]
+      }
+    }
+  }
+`;
+
+function fail(msg) {
+  process.stderr.write(`4dpocket-mcp: ${msg}\n\n${HELP}`);
+  process.exit(2);
+}
+
+function parseArgs(argv) {
+  const out = { url: process.env.FDP_URL ?? null, token: process.env.FDP_TOKEN ?? null };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--help" || a === "-h") { process.stdout.write(HELP); process.exit(0); }
+    if (a === "--version" || a === "-v") {
+      const pkg = require("./package.json");
+      process.stdout.write(`${pkg.version}\n`);
+      process.exit(0);
+    }
+    if (a === "--url") { out.url = argv[++i]; continue; }
+    if (a === "--token") { out.token = argv[++i]; continue; }
+    fail(`unknown argument: ${a}`);
+  }
+  return out;
+}
+
+function normalizeUrl(raw) {
+  // Strip trailing slash, strip a trailing /mcp or /mcp/ if the user already
+  // included it, then append /mcp/ — FastMCP's streamable-HTTP transport
+  // requires the trailing slash.
+  let u;
+  try { u = new URL(raw); } catch { fail(`invalid --url: ${raw}`); }
+  let p = u.pathname.replace(/\/+$/, "");
+  if (p.endsWith("/mcp")) p = p.slice(0, -"/mcp".length);
+  u.pathname = `${p}/mcp/`;
+  return u.toString();
+}
+
+function resolveMcpRemoteBin() {
+  const pkgPath = require.resolve("mcp-remote/package.json");
+  const pkg = require(pkgPath);
+  const rel = typeof pkg.bin === "string" ? pkg.bin : pkg.bin?.["mcp-remote"];
+  if (!rel) fail("mcp-remote is installed but exposes no 'mcp-remote' bin; reinstall.");
+  return path.resolve(path.dirname(pkgPath), rel);
+}
+
+const { url, token } = parseArgs(process.argv.slice(2));
+if (!url) fail("missing --url (or FDP_URL env var).");
+if (!token) fail("missing --token (or FDP_TOKEN env var).");
+if (!token.startsWith("fdp_pat_")) {
+  process.stderr.write(
+    `4dpocket-mcp: warning: token does not start with fdp_pat_ — is this really a 4DPocket PAT?\n`
+  );
+}
+
+const mcpUrl = normalizeUrl(url);
+const binAbs = resolveMcpRemoteBin();
+
+const child = spawn(
+  process.execPath,
+  [binAbs, mcpUrl, "--header", `Authorization: Bearer ${token}`],
+  { stdio: "inherit" }
+);
+child.on("exit", (code, signal) => {
+  if (signal) process.kill(process.pid, signal);
+  else process.exit(code ?? 0);
+});

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@onllm-dev/4dpocket-mcp",
+  "version": "0.2.0",
+  "description": "MCP client for 4DPocket — connect Claude Desktop, Cursor, and other MCP clients to your self-hosted 4DPocket instance.",
+  "type": "module",
+  "bin": {
+    "4dpocket-mcp": "./bin.mjs"
+  },
+  "files": [
+    "bin.mjs",
+    "README.md"
+  ],
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "4dpocket",
+    "knowledge-base",
+    "claude",
+    "cursor"
+  ],
+  "author": "onllm-dev",
+  "license": "MIT",
+  "homepage": "https://github.com/onllm-dev/4DPocket#mcp",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/onllm-dev/4DPocket.git",
+    "directory": "mcp-npm"
+  },
+  "bugs": {
+    "url": "https://github.com/onllm-dev/4DPocket/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "mcp-remote": "^0.1.38"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}