@thinkingroot/mcp 0.2.0

package/README.md

@@ -0,0 +1,80 @@
+# @thinkingroot/mcp
+
+**Give any AI agent a living, per-user memory — by pasting one URL.**
+
+ThinkingRoot is the managed cloud for the cognition database. This connects any
+MCP client (Claude, Cursor, Codex, VS Code, …) to your project's brain over the
+hosted gateway, exposing the full tool catalog — including the **Compiled
+Workspace** tools: `ask` (citation-gated, refuses rather than hallucinates),
+`search`, `compile`, `repo_map`, `code_traverse`, `code_search_entity`,
+`summaries`, plus memory `remember`/`recall`.
+
+Every answer is grounded in **verbatim, byte-anchored** sources. Memory is
+deletable and provable — not an opaque blob.
+
+---
+
+## Two ways to connect
+
+### 1. Hosted URL (no install)
+
+For clients that support **remote MCP servers**, paste the hosted endpoint and
+your key — nothing to install:
+
+```
+URL:    https://api.thinkingroot.com/mcp/sse
+Header: Authorization: Bearer tr_sk_…
+```
+
+Get a `tr_sk_…` project key from the Console → **Keys** tab. That's the whole
+setup — the gateway authenticates the key, resolves your project's engine, and
+streams the tools.
+
+### 2. One-line bridge (any stdio client)
+
+For clients that speak stdio only, this package bridges stdio ↔ the hosted SSE
+endpoint. Drop it into your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "thinkingroot": {
+      "command": "npx",
+      "args": ["-y", "@thinkingroot/mcp"],
+      "env": { "TR_PROJECT_KEY": "tr_sk_…" }
+    }
+  }
+}
+```
+
+- **`TR_PROJECT_KEY`** (required) — a `tr_sk_…` project API key.
+- **`TR_GATEWAY_URL`** (optional) — defaults to `https://api.thinkingroot.com`.
+
+Works in Claude Desktop, Claude Code, Cursor, Codex, Windsurf, and any client
+that runs a `command`-based MCP server.
+
+---
+
+## Per-user minds
+
+ThinkingRoot isn't one shared database — each of your end-users can have their
+own **private, fail-closed** brain (`u_{userId}`). To scope a hosted session to
+one user, mint a user-bound embed token (`tr_em_…`) from your backend via
+`POST /tokens/session` and present it in place of the `tr_sk_` key. The gateway
+derives the identity from the token, so a session can never read another user's
+mind.
+
+## Security
+
+- Fail-closed: without a valid `tr_sk_…` key the bridge exits rather than
+  connect unauthenticated.
+- The key is sent only to the hosted gateway over TLS; the underlying engine
+  key is never exposed to the client.
+- `tr_pk_…` publishable keys are ask/recall-scoped and domain-locked — safe for
+  browser embeds; `tr_sk_…` full-scope keys belong on a server.
+
+## Links
+
+- Docs & keys: [thinkingroot.com](https://thinkingroot.com)
+- SDK: [`@thinkingroot/sdk`](https://www.npmjs.com/package/@thinkingroot/sdk) · CLI: [`thinkingroot`](https://www.npmjs.com/package/thinkingroot)
+- Built on [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) for the stdio bridge.

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@thinkingroot/mcp",
+  "version": "0.2.0",
+  "description": "Give any AI agent a living, per-user memory over MCP — hosted URL or one-line stdio bridge to ThinkingRoot (ask/search/compile/remember/recall + full tool catalog).",
+  "type": "module",
+  "bin": {
+    "thinkingroot-mcp": "src/bin/thinkingroot-mcp.mjs"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.mjs",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test src/args.test.mjs"
+  },
+  "keywords": [
+    "mcp",
+    "thinkingroot",
+    "model-context-protocol",
+    "claude",
+    "cursor"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "UNLICENSED"
+}

package/src/args.mjs

@@ -0,0 +1,39 @@
+// Pure arg-building for the @thinkingroot/mcp wrapper. Kept dependency-free
+// and side-effect-free so it is unit-testable without spawning anything.
+
+/** The public HTTPS front door (Cloudflare → Caddy → gateway :3109). */
+export const DEFAULT_GATEWAY_URL = "https://api.thinkingroot.com";
+
+/** Normalize a gateway base URL (strip trailing slash). */
+export function normalizeGateway(url) {
+  return String(url || DEFAULT_GATEWAY_URL).replace(/\/+$/, "");
+}
+
+/** The SSE MCP endpoint clients connect to (the gateway proxies to the engine). */
+export function mcpSseUrl(gatewayUrl) {
+  return `${normalizeGateway(gatewayUrl)}/mcp/sse`;
+}
+
+/**
+ * Build the `mcp-remote` argv that bridges stdio ↔ the gateway's SSE MCP
+ * endpoint, injecting the project key as a bearer header. We pass the header
+ * value with no space after the colon and quote-free because mcp-remote
+ * mis-splits header values containing a space (matches the Console's
+ * claude-code config). Throws if the project key is missing — fail closed,
+ * never connect unauthenticated.
+ */
+export function buildArgs({ gatewayUrl, projectKey } = {}) {
+  if (!projectKey || !String(projectKey).startsWith("tr_sk_")) {
+    throw new Error(
+      "TR_PROJECT_KEY (a tr_sk_… project API key) is required. " +
+        "Get one from the Console → Keys tab.",
+    );
+  }
+  return [
+    "-y",
+    "mcp-remote",
+    mcpSseUrl(gatewayUrl),
+    "--header",
+    `Authorization:Bearer ${projectKey}`,
+  ];
+}

package/src/bin/thinkingroot-mcp.mjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+// @thinkingroot/mcp — one-line MCP server for ThinkingRoot.
+//
+// Adds the project's Compiled Workspace tools (compile/search/ask/repo_map/
+// code_traverse/code_search_entity/summaries + the full engine catalog) to any
+// stdio MCP client (Claude Code, Cursor, Codex) by bridging stdio ↔ the
+// gateway's SSE MCP endpoint via `mcp-remote`.
+//
+// Usage (in an MCP client config):
+//   command: "npx", args: ["-y", "@thinkingroot/mcp"]
+//   env: { TR_PROJECT_KEY: "tr_sk_…", TR_GATEWAY_URL?: "https://…" }
+import { spawn } from "node:child_process";
+import { buildArgs, mcpSseUrl } from "../args.mjs";
+
+let argv;
+try {
+  argv = buildArgs({
+    gatewayUrl: process.env.TR_GATEWAY_URL,
+    projectKey: process.env.TR_PROJECT_KEY,
+  });
+} catch (e) {
+  process.stderr.write(`thinkingroot-mcp: ${e.message}\n`);
+  process.exit(2);
+}
+
+process.stderr.write(
+  `thinkingroot-mcp → ${mcpSseUrl(process.env.TR_GATEWAY_URL)} (key tr_sk_…)\n`,
+);
+
+// Bridge runs as a child speaking the MCP stdio protocol on our stdio.
+const child = spawn("npx", argv, { stdio: "inherit" });
+child.on("exit", (code) => process.exit(code ?? 0));
+child.on("error", (err) => {
+  process.stderr.write(`thinkingroot-mcp: failed to start mcp-remote: ${err.message}\n`);
+  process.exit(1);
+});