wontopos-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wontopos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,65 @@
+# wontopos-mcp — one memory across every AI tool
+
+[Wontopos (WOS)](https://wontopos.com) long-term memory as an [MCP](https://modelcontextprotocol.io) server.
+
+Memory belongs to your **account**, not to a tool. The same store recalls in
+Claude Code, Claude Desktop, Cursor — and in ChatGPT via Actions with the same
+API ([openapi.json](https://api.wontopos.com/openapi.json)) — so a conversation
+started in one tool continues in another. Pure semantic retrieval, identical
+recall in every language, bounded context (~1,200 tokens) per recall.
+
+## Claude Code
+
+```bash
+claude mcp add wontopos --env WONTOPOS_API_KEY=wos-live-... -- npx -y wontopos-mcp
+```
+
+## Claude Desktop / Cursor / any MCP host
+
+```json
+{
+  "mcpServers": {
+    "wontopos": {
+      "command": "npx",
+      "args": ["-y", "wontopos-mcp"],
+      "env": { "WONTOPOS_API_KEY": "wos-live-..." }
+    }
+  }
+}
+```
+
+Create a key in the [console](https://wontopos.com). Optional env:
+`WONTOPOS_USER_ID` (default store, default `"default"`), `WONTOPOS_MODEL`
+(`tablet-1` default, `scroll-1`), `WONTOPOS_BASE_URL` (self-hosted).
+
+## Tools
+
+| Tool | What the agent does with it |
+|---|---|
+| `recall` | One-call context: recent turns + relevant long-term memories + surroundings. First call when past context matters. |
+| `remember` | Store a durable fact/decision/preference. `speaker: "me"` = the agent's own words; a registered name = who said it. |
+| `search` | Semantic search, optional per-person filter (`speaker`). |
+| `forget` | Delete one memory by id. |
+| `speakers` | Register / list / unregister the people a store remembers (50 to start; `"me"` is free). |
+| `create_store` | Stores are explicit — create one per end-user, project, or agent. |
+
+## One memory, many tools
+
+Same `WONTOPOS_API_KEY` + same store id ⇒ the memory follows you:
+
+```
+ChatGPT (Actions)  ─┐
+Claude / Claude Code ─┼──▶  store "you" on api.wontopos.com
+Cursor / your agent ─┘
+```
+
+Tell Claude Code "remember that we ship on Fridays", then ask ChatGPT "when do
+we ship?" — same memory answers.
+
+Uses the [`wontopos`](https://www.npmjs.com/package/wontopos) SDK underneath, so
+automatic retries, redirect refusal, response caps, and key hygiene apply as-is.
+
+- Docs: <https://wontopos.com/en/why>
+- Spec: <https://api.wontopos.com/openapi.json> · <https://wontopos.com/llms.txt>
+
+License: MIT.

package/index.mjs

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+// wontopos-mcp — use Wontopos (WOS) long-term memory from any MCP host:
+// Claude Code, Claude Desktop, Cursor, Windsurf, or your own agent.
+//
+//   claude mcp add wontopos --env WONTOPOS_API_KEY=wos-live-... -- npx -y wontopos-mcp
+//
+// One store id = one memory across every tool. The same user_id written from
+// ChatGPT (via Actions + openapi.json) recalls here, and vice versa — memory
+// belongs to the account, not the tool.
+//
+// Env:
+//   WONTOPOS_API_KEY   required (wos-live-...)
+//   WONTOPOS_USER_ID   default store for every tool call (default: "default")
+//   WONTOPOS_MODEL     engine, e.g. tablet-1 (default) or scroll-1
+//   WONTOPOS_BASE_URL  self-hosted deployments only
+//
+// Thin wrapper over the `wontopos` SDK, so retries, redirect refusal, response
+// caps, and key hygiene all apply as-is.
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { Client, WosError } from "wontopos";
+
+const VERSION = "1.0.0";
+
+const apiKey = process.env.WONTOPOS_API_KEY ?? process.env.WOS_API_KEY;
+if (!apiKey || !apiKey.trim()) {
+  console.error(
+    "wontopos-mcp: set WONTOPOS_API_KEY (create a key in the console at https://wontopos.com)."
+  );
+  process.exit(1);
+}
+
+const mem = new Client({
+  apiKey,
+  userId: process.env.WONTOPOS_USER_ID || "default",
+  ...(process.env.WONTOPOS_MODEL ? { model: process.env.WONTOPOS_MODEL } : {}),
+  ...(process.env.WONTOPOS_BASE_URL ? { baseUrl: process.env.WONTOPOS_BASE_URL } : {}),
+});
+
+const server = new McpServer({ name: "wontopos", version: VERSION });
+
+/** Wrap a handler: JSON out, typed WosError in-band so the agent can react. */
+function run(fn) {
+  return async (args) => {
+    try {
+      const result = await fn(args ?? {});
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 1) }] };
+    } catch (e) {
+      // WosError.message already carries "[status] ... (request_id: ...)".
+      const msg = e instanceof WosError ? e.message : String(e?.message ?? e);
+      return { content: [{ type: "text", text: msg }], isError: true };
+    }
+  };
+}
+
+const userIdArg = z
+  .string()
+  .optional()
+  .describe("Store to use. Omit for the configured default store — only set this when the user explicitly works with multiple stores.");
+
+server.registerTool(
+  "recall",
+  {
+    title: "Recall memory context",
+    description:
+      "One-call memory context: recent turns + relevant long-term memories + surrounding context. " +
+      "Call this FIRST whenever the user references past work, preferences, people, or decisions " +
+      "('like last time', 'the bug we fixed', 'what does she like'). Returns bounded output (~1,200 tokens) " +
+      "regardless of how much is stored. Works in every language.",
+    inputSchema: {
+      query: z.string().describe("What you want to remember about, phrased like the user's need."),
+      user_id: userIdArg,
+    },
+  },
+  run(({ query, user_id }) => mem.recall(query, user_id))
+);
+
+server.registerTool(
+  "remember",
+  {
+    title: "Store a memory",
+    description:
+      "Store one durable fact, decision, preference, or event worth recalling in future sessions. " +
+      "Write it as a standalone sentence with names and concrete details ('Sunwoo prefers dark mode in the console'), " +
+      "not a chat log. Optional speaker: 'me' = the agent's OWN words/commitments (no registration needed); " +
+      "a person's name = who said it (register the person once with the speakers tool first, or this returns 400). " +
+      "Identical content is deduplicated (status 'duplicate').",
+    inputSchema: {
+      content: z.string().describe("The memory, as one self-contained sentence."),
+      speaker: z
+        .string()
+        .optional()
+        .describe("'me' for the agent's own words, or a REGISTERED person's name. Omit for untagged."),
+      event_date: z
+        .string()
+        .optional()
+        .describe("RFC3339 date when the event actually happened, if different from now."),
+      user_id: userIdArg,
+    },
+  },
+  run(({ content, speaker, event_date, user_id }) => {
+    const metadata = {};
+    if (speaker) metadata.speaker = speaker;
+    if (event_date) metadata.event_date = event_date;
+    return mem.add(content, user_id, metadata);
+  })
+);
+
+server.registerTool(
+  "search",
+  {
+    title: "Search memories",
+    description:
+      "Semantic search over stored memories, most relevant first. Pure semantic (no keywords) — " +
+      "query by meaning in any language. Optional speaker filter recalls one person's words only " +
+      "('me' or a registered name; unregistered names return 404).",
+    inputSchema: {
+      query: z.string(),
+      limit: z.number().int().min(1).max(60).optional().describe("Max results (default 10)."),
+      speaker: z.string().optional().describe("Only this person's words: 'me' or a registered name."),
+      user_id: userIdArg,
+    },
+  },
+  run(({ query, limit, speaker, user_id }) =>
+    mem.search(query, user_id, limit ?? 10, speaker ? { speaker } : {})
+  )
+);
+
+server.registerTool(
+  "forget",
+  {
+    title: "Forget one memory",
+    description:
+      "Delete a single memory by its id (from search/remember results). Destructive and permanent — " +
+      "only when the user asks to forget or a stored fact is wrong (prefer remember with corrected " +
+      "content for updates).",
+    inputSchema: {
+      memory_id: z.string().describe("The memory id to delete."),
+      user_id: userIdArg,
+    },
+  },
+  run(({ memory_id, user_id }) => mem.delete(user_id, memory_id))
+);
+
+server.registerTool(
+  "speakers",
+  {
+    title: "Manage speakers (who said it)",
+    description:
+      "WHO can say memories in this store. action 'list' shows registered people with memory counts; " +
+      "'add' registers a person (explicit, like stores — up to 50 per store to start; a typo can never " +
+      "silently become a new person); 'remove' unregisters (their memories stay, the name tag goes). " +
+      "'me' (the agent itself) is reserved and never needs registration.",
+    inputSchema: {
+      action: z.enum(["list", "add", "remove"]),
+      speaker: z.string().optional().describe("The person's name (required for add/remove)."),
+      user_id: userIdArg,
+    },
+  },
+  run(({ action, speaker, user_id }) => {
+    if (action === "list") return mem.listSpeakers(user_id);
+    if (!speaker) throw new Error("speaker is required for add/remove.");
+    return action === "add" ? mem.addSpeaker(speaker, user_id) : mem.removeSpeaker(speaker, user_id);
+  })
+);
+
+server.registerTool(
+  "create_store",
+  {
+    title: "Create a memory store",
+    description:
+      "Create a store (a user_id namespace). Stores are explicit: writing to or reading a store that " +
+      "does not exist returns 404 — create it once first. Idempotent. Every account already has a " +
+      "'default' store, so this is only needed for additional stores (per end-user, per project, ...).",
+    inputSchema: {
+      user_id: z.string().describe("The store id to create."),
+    },
+  },
+  run(({ user_id }) => mem.createStore(user_id))
+);
+
+await server.connect(new StdioServerTransport());
+console.error(`wontopos-mcp ${VERSION} ready (store: ${process.env.WONTOPOS_USER_ID || "default"})`);

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "wontopos-mcp",
+  "version": "1.0.0",
+  "description": "Wontopos (WOS) long-term memory as an MCP server — one memory across Claude Code, Claude Desktop, Cursor, ChatGPT, and your own agents.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "memory",
+    "ai",
+    "agent",
+    "claude",
+    "long-term-memory"
+  ],
+  "homepage": "https://wontopos.com",
+  "license": "MIT",
+  "author": "Wontopos",
+  "type": "module",
+  "bin": {
+    "wontopos-mcp": "./index.mjs"
+  },
+  "files": [
+    "index.mjs",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "wontopos": "^2.2.9",
+    "zod": "^3.23.0"
+  }
+}