sombra-mcp 1.0.0

package/README.md

@@ -0,0 +1,80 @@
+# sombra-mcp
+
+Stdio-to-HTTP bridge for [Sombra](https://sombra.so). Persistent reader mode for AI.
+
+MCP clients that only support stdio-based servers (OpenClaw, Cursor, Windsurf, and others) can't connect directly to remote HTTP MCP servers. This package bridges that gap: it speaks stdio locally and proxies requests to `https://sombra.so/mcp` over Streamable HTTP.
+
+## Quick start
+
+```bash
+npx sombra-mcp --token sombra_pat_YOUR_TOKEN
+```
+
+Or set the token as an environment variable:
+
+```bash
+SOMBRA_TOKEN=sombra_pat_YOUR_TOKEN npx sombra-mcp
+```
+
+## Getting a token
+
+1. Sign up or log in at [sombra.so](https://sombra.so/login)
+2. Go to **Settings > Access Tokens**
+3. Click **Create Token**
+4. Copy the token (starts with `sombra_pat_`)
+
+Tokens authenticate your agent against your personal Sombra library. Each token has full read/write access to your account.
+
+## Configuring MCP clients
+
+### OpenClaw, Claude Desktop, Cursor, Windsurf
+
+Add to your MCP config file (`openclaw.json`, `claude_desktop_config.json`, etc.):
+
+```json
+{
+  "mcpServers": {
+    "sombra": {
+      "command": "npx",
+      "args": ["-y", "sombra-mcp", "--token", "sombra_pat_YOUR_TOKEN"]
+    }
+  }
+}
+```
+
+### Claude.ai
+
+Add Sombra as a connector in **Settings > Connectors**. No bridge needed - and it will automatically pop up in Claude Code.
+
+
+### Claude Code
+
+Claude Code supports remote HTTP MCP servers directly, so you don't need this bridge, or if you don't want to set it up in Claude.ai or Claude Desktop.
+
+```bash
+claude mcp add --transport http sombra https://sombra.so/mcp
+```
+
+## What is Sombra?
+
+Sombra is a research library that your AI agent can read from and write to through MCP. Save web pages as clean markdown, organise them into collections, distil the important parts into dense context, and search across everything.
+
+19 tools for saving, searching, organising, and distilling web content and notes. Two prompts for context distillation. Collections exposed as MCP resources.
+
+Your research persists between sessions. Tomorrow's conversation picks up where today's left off.
+
+[sombra.so](https://sombra.so) | [MCP setup docs](https://sombra.so/mcp) | [What is Sombra?](https://sombra.so/blog/what-is-sombra)
+
+## How it works
+
+The bridge reads JSON-RPC messages from stdin, forwards them to `https://sombra.so/mcp` as HTTP POST requests with your Bearer token, and writes the responses back to stdout. It handles session management, protocol version negotiation, and streaming (SSE) responses.
+
+No config beyond the token. No local state.
+
+## Requirements
+
+Node.js 18 or later.
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+const VERSION = "1.0.0";
+const SOMBRA_URL = "https://sombra.so/mcp";
+function log(msg) {
+    process.stderr.write(`[sombra-mcp] ${msg}\n`);
+}
+function printHelp() {
+    process.stdout.write(`sombra-mcp v${VERSION} — Sombra MCP stdio-to-HTTP bridge
+
+Reader mode for AI. Give your agent a persistent research library.
+
+USAGE
+
+  npx sombra-mcp --token <token>
+  SOMBRA_TOKEN=<token> npx sombra-mcp
+
+OPTIONS
+
+  --token <token>  Personal Access Token (or set SOMBRA_TOKEN env var)
+  --help, -h       Show this help message
+  --version, -v    Show version number
+
+GETTING A TOKEN
+
+  1. Sign up or log in at https://sombra.so
+  2. Go to Settings → Access Tokens
+  3. Click "Create Token" — tokens start with sombra_pat_
+  4. Copy the token immediately (it won't be shown again)
+
+CONFIGURING MCP CLIENTS
+
+  Claude Code:
+
+    claude mcp add --transport http sombra https://sombra.so/mcp
+
+  OpenClaw, Claude Desktop, Cursor, Windsurf (stdio clients):
+
+    Add to your MCP config file:
+
+    {
+      "mcpServers": {
+        "sombra": {
+          "command": "npx",
+          "args": ["-y", "sombra-mcp", "--token", "sombra_pat_YOUR_TOKEN"]
+        }
+      }
+    }
+
+ABOUT SOMBRA
+
+  Sombra gives your AI agent a persistent research library accessible
+  via the Model Context Protocol (MCP). Save web pages as clean markdown,
+  organise them into collections, distil the key insights, and search
+  across everything — all through 19 MCP tools.
+
+  https://sombra.so          Sign up & manage your library
+  https://sombra.so/mcp      MCP setup for all clients
+`);
+}
+function getToken() {
+    const args = process.argv.slice(2);
+    if (args.includes("--help") || args.includes("-h")) {
+        printHelp();
+        process.exit(0);
+    }
+    if (args.includes("--version") || args.includes("-v")) {
+        process.stdout.write(`${VERSION}\n`);
+        process.exit(0);
+    }
+    const tokenIdx = args.indexOf("--token");
+    const token = (tokenIdx !== -1 ? args[tokenIdx + 1] : undefined) ??
+        process.env.SOMBRA_TOKEN;
+    if (!token) {
+        process.stderr.write([
+            "Error: token required.",
+            "",
+            "  Use --token <token> or set SOMBRA_TOKEN env var.",
+            "  Get a token at https://sombra.so → Settings → Access Tokens.",
+            "",
+            '  Run "npx sombra-mcp --help" for full setup instructions.',
+            "",
+        ].join("\n"));
+        process.exit(1);
+    }
+    return token;
+}
+async function readSSE(response, stdio) {
+    const body = response.body;
+    if (!body)
+        return;
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        buffer += decoder.decode(value, { stream: true });
+        const parts = buffer.split("\n\n");
+        buffer = parts.pop() || "";
+        for (const part of parts) {
+            let data = "";
+            for (const line of part.split("\n")) {
+                if (line.startsWith("data: "))
+                    data += line.slice(6);
+                else if (line.startsWith("data:"))
+                    data += line.slice(5);
+            }
+            if (data) {
+                try {
+                    await stdio.send(JSON.parse(data));
+                }
+                catch {
+                    /* skip malformed events */
+                }
+            }
+        }
+    }
+}
+async function main() {
+    const token = getToken();
+    const stdio = new StdioServerTransport();
+    let sessionId;
+    let protocolVersion;
+    stdio.onmessage = async (message) => {
+        try {
+            const headers = {
+                "Content-Type": "application/json",
+                Accept: "application/json, text/event-stream",
+                Authorization: `Bearer ${token}`,
+            };
+            if (sessionId)
+                headers["mcp-session-id"] = sessionId;
+            if (protocolVersion)
+                headers["mcp-protocol-version"] = protocolVersion;
+            const response = await fetch(SOMBRA_URL, {
+                method: "POST",
+                headers,
+                body: JSON.stringify(message),
+            });
+            const sid = response.headers.get("mcp-session-id");
+            if (sid)
+                sessionId = sid;
+            // Capture negotiated protocol version from initialize response
+            if ("method" in message && message.method === "initialize") {
+                const clone = response.clone();
+                try {
+                    const body = await clone.json();
+                    if (body?.result?.protocolVersion) {
+                        protocolVersion = body.result.protocolVersion;
+                    }
+                }
+                catch { /* handled below */ }
+            }
+            if (response.status === 202)
+                return; // notification accepted
+            if (!response.ok) {
+                const text = await response.text();
+                log(`server ${response.status}: ${text}`);
+                return;
+            }
+            const ct = response.headers.get("content-type") || "";
+            if (ct.includes("text/event-stream")) {
+                await readSSE(response, stdio);
+            }
+            else {
+                await stdio.send((await response.json()));
+            }
+        }
+        catch (err) {
+            log(`send error: ${err.message}`);
+        }
+    };
+    stdio.onclose = () => process.exit(0);
+    const shutdown = () => {
+        stdio.close().catch(() => { });
+        process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+    await stdio.start();
+    log("ready");
+}
+main().catch((err) => {
+    log(`fatal: ${err.message}`);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "sombra-mcp",
+  "version": "1.0.0",
+  "description": "Sombra MCP stdio-to-HTTP bridge. Persistent reader mode for AI.",
+  "type": "module",
+  "bin": {
+    "sombra-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.27.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "mcp",
+    "sombra",
+    "ai",
+    "model-context-protocol",
+    "research",
+    "context-engineering"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dazld/sombra-mcp"
+  },
+  "homepage": "https://sombra.so"
+}