@remnic/replit 1.0.0 → 9.3.515

package/README.md

@@ -0,0 +1,101 @@
+# @remnic/replit
+
+MCP connector helper for using [Remnic](https://github.com/joshuaswarren/remnic) memory with [Replit Agent](https://replit.com/).
+
+Replit Agent has no plugin system, so it can't install a Remnic hook like Claude Code or Codex can. Instead, this package takes a bearer token that you mint separately (`remnic token generate replit`) and produces the exact MCP server config + paste-ready setup instructions for Replit's **Integrations** pane, turning any Replit workspace into a Remnic memory client over HTTP + MCP.
+
+## Install
+
+```bash
+pnpm add @remnic/replit
+# or: npm i @remnic/replit
+```
+
+Needs a running Remnic server (see [`@remnic/server`](https://www.npmjs.com/package/@remnic/server)) or a `@remnic/cli`-managed daemon that exposes MCP on port 4318.
+
+## Quick start
+
+First mint a Replit-scoped token with the Remnic CLI:
+
+```bash
+remnic token generate replit
+```
+
+Then use the helper to render the setup instructions and MCP config:
+
+```ts
+import { generateReplitInstructions } from "@remnic/replit";
+
+// Pass the token returned by `remnic token generate replit`:
+const setup = generateReplitInstructions("YOUR_REMNIC_TOKEN");
+
+console.log(setup.instructions);
+// Paste setup.mcpConfig into Replit's Integrations > Add MCP server form.
+```
+
+For a cloud Replit workspace, pass the public HTTPS origin for your Remnic server:
+
+```ts
+const setup = generateReplitInstructions("YOUR_REMNIC_TOKEN", {
+  baseUrl: "https://remnic.example.com",
+});
+```
+
+The legacy `generateReplitInstructions(token, host?, port?)` form is still supported for
+local or LAN hosts. If `host` already includes a scheme, it is treated as a complete
+origin and the MCP URL is generated with the URL API.
+
+`generateReplitInstructions(token, endpoint?, port?)` returns:
+
+```ts
+interface ReplitInstallResult {
+  token: string;
+  instructions: string; // human-readable setup steps
+  mcpConfig: {
+    url: string;                      // http://localhost:4318/mcp or https://{origin}/mcp
+    headers: Record<string, string>;  // Authorization + X-Engram-Client-Id
+  };
+}
+```
+
+Defaults are `host="localhost"`, `port=4318`. Public origins must be an origin only,
+without a path, query string, or hash.
+
+## Replit pane setup
+
+Running `generateReplitInstructions` prints something like:
+
+```
+Replit Agent MCP Setup
+======================
+
+1. In your Replit workspace, open Integrations > Add MCP server
+2. Enter URL: http://localhost:4318/mcp
+3. Add headers:
+   - Authorization: Bearer <your-remnic-token>
+   - X-Engram-Client-Id: replit
+4. Click Test & Save
+```
+
+A ready-to-paste snippet lives at `setup-snippet.json` in the package.
+
+## Caveats
+
+- For a **cloud** Replit workspace, the Remnic server has to be publicly reachable — via a tunnel (Cloudflare Tunnel, ngrok, Tailscale funnel), a public IP, or a reverse proxy. Pass that public origin with `baseUrl`, for example `https://remnic.example.com`. `localhost` only works for self-hosted Replit-likes.
+- Replit has **no hook system**, so the agent must explicitly call Remnic MCP tools (`recall`, `observe`, `store`, `search`). Auto-recall before prompts isn't available the way it is on Claude Code, Codex, or OpenClaw. All 44 MCP tools are exposed.
+- The token is a plain bearer token. Don't paste it into a Replit that you share with others unless each collaborator should have the same memory namespace.
+
+## Agent note
+
+If you're an AI agent scaffolding a Replit integration: call `generateReplitInstructions(token)` once you have a live Remnic token; don't hand-roll the MCP config (future protocol bumps will update this helper first).
+
+## Related
+
+- [`@remnic/cli`](https://www.npmjs.com/package/@remnic/cli) — daemon lifecycle + token minting
+- [`@remnic/server`](https://www.npmjs.com/package/@remnic/server) — standalone HTTP + MCP server
+- Connector guide: [docs/integration/connector-setup.md](https://github.com/joshuaswarren/remnic/blob/main/docs/integration/connector-setup.md) in the repo
+- Source + issues: <https://github.com/joshuaswarren/remnic>
+
+## License
+
+MIT. See the root [LICENSE](https://github.com/joshuaswarren/remnic/blob/main/LICENSE) file.

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 /**
  * Replit connector installer.
  *
- * Since Replit has no plugin system, this generates a token and
- * prints setup instructions for the Integrations pane.
+ * Since Replit has no plugin system, this formats a pre-existing Remnic
+ * bearer token into setup instructions for the Integrations pane.
  */
 interface ReplitInstallResult {
     token: string;
@@ -12,6 +12,11 @@ interface ReplitInstallResult {
         headers: Record<string, string>;
     };
 }
-declare function generateReplitInstructions(token: string, host?: string, port?: number): ReplitInstallResult;
+interface ReplitEndpointOptions {
+    host?: string;
+    port?: number;
+    baseUrl?: string | URL;
+}
+declare function generateReplitInstructions(token: string, hostOrOptions?: string | URL | ReplitEndpointOptions, port?: number): ReplitInstallResult;
 
 export { type ReplitInstallResult, generateReplitInstructions };

package/dist/index.js

@@ -1,6 +1,39 @@
 // src/installer.ts
-function generateReplitInstructions(token, host = "localhost", port = 4318) {
-  const url = `http://${host}:${port}/mcp`;
+function assertValidPort(port) {
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new TypeError("Replit MCP port must be an integer between 1 and 65535");
+  }
+}
+function hasScheme(value) {
+  return /^[a-z][a-z0-9+.-]*:\/\//i.test(value);
+}
+function endpointFromHost(host, port) {
+  const trimmedHost = host.trim();
+  if (trimmedHost.length === 0) {
+    throw new TypeError("Replit MCP host must be a non-empty hostname or URL origin");
+  }
+  if (hasScheme(trimmedHost)) {
+    const url = new URL(trimmedHost);
+    if (url.pathname !== "/" || url.search !== "" || url.hash !== "") {
+      throw new TypeError("Replit MCP base URL must be an origin without a path, query, or hash");
+    }
+    return url;
+  }
+  if (/[/?#]/.test(trimmedHost)) {
+    throw new TypeError("Replit MCP host must not include a path, query, or hash");
+  }
+  assertValidPort(port);
+  return new URL(`http://${trimmedHost}:${port}`);
+}
+function buildMcpUrl(hostOrOptions = "localhost", port = 4318) {
+  const endpoint = hostOrOptions instanceof URL ? endpointFromHost(hostOrOptions.toString(), port) : typeof hostOrOptions === "object" ? hostOrOptions.baseUrl ? endpointFromHost(hostOrOptions.baseUrl.toString(), hostOrOptions.port ?? port) : endpointFromHost(hostOrOptions.host ?? "localhost", hostOrOptions.port ?? port) : endpointFromHost(hostOrOptions, port);
+  endpoint.pathname = "/mcp";
+  endpoint.search = "";
+  endpoint.hash = "";
+  return endpoint.toString();
+}
+function generateReplitInstructions(token, hostOrOptions = "localhost", port = 4318) {
+  const url = buildMcpUrl(hostOrOptions, port);
   const instructions = `
 Replit Agent MCP Setup
 ======================
@@ -12,11 +45,11 @@ Replit Agent MCP Setup
    - X-Engram-Client-Id: replit
 4. Click Test & Save
 
-Note: For cloud Replit, EMO must be publicly reachable (via tunnel, public IP, or reverse proxy).
+Note: For cloud Replit, the Remnic MCP endpoint must be publicly reachable (via tunnel, public IP, or reverse proxy).
 
 Limitations:
 - Replit has no hook system, so memory recall/observe is manual
-- The agent must explicitly call engram tools (recall, observe, store, search)
+- The agent must explicitly call Remnic MCP tools (recall, observe, store, search)
 - All 44 MCP tools are available
 `.trim();
   return {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@remnic/replit",
-  "version": "1.0.0",
-  "description": "Remnic MCP connector for Replit Agent — setup instructions and token generator",
+  "version": "9.3.515",
+  "description": "Remnic MCP connector for Replit Agent — setup instructions for an existing token",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",