cordenar-mcp 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,58 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.1] - 2026-07-11
+
+### Fixed
+- Compend synapse parity — description, body, and preview now read from
+  Compend's concepts table. Content cell fallback chain shows preview,
+  title, description, then slug. Detail panel renders full body text.
+  Search includes description and body fields.
+
+### Changed
+- Page title simplified to "Cordenar".
+- Layout width matched to Compend/Hemisphere — `#app` wrapper at 960px
+  content area (was 920px due to padding inside body container).
+
+## [0.1.0] - 2026-07-10
+
+### Added
+
+- Initial scaffold: MCP stdio server with 6 tool registrations (`cordenar_auth`, `cordenar_status`, `cordenar_list`, `cordenar_share`, `cordenar_pull`, `cordenar_sync`)
+- Config singleton (`config.js`) — code defaults, `~/.cordenar/config.json`, environment variable overrides
+- Sync database (`db.js`) — `synapse_map` table with CRUD operations for cloud-to-local ID reconciliation
+- Sync logic (`sync.js`) — `cordenar_list` reads both Hemisphere and Compend databases (read-only), unified synapse view with `already_shared` flag
+- Auth module (`auth.js`) — JWT token store at `~/.cordenar/auth.json`, with load, save, clear, and validation helpers
+- Supabase client wrapper (`supabase.js`) — authenticated and anonymous Supabase client creation
+- Embedding module (`embedding.js`) — MurmurHash3 256-dim LSH vector (copy from Hemisphere, deterministic, ~2µs per call)
+- Local dashboard (port 3458) — vanilla JS SPA with dark/light theme, SSE real-time updates, skeleton loading, toast notifications, WCAG 2.1 AA accessibility
+- Dashboard kebab menu per synapse — context-sensitive actions by status (Share, Unlink, Remove Local, Dismiss)
+- Source and status filters with debounced search
+- Confirm dialog for destructive actions
+- Theme toggle with persistence (`localStorage`) and FOUC prevention via synchronous head script
+- CLI commands (`cordenar`, `cordenar stop`, `cordenar restart`)
+- Global bin entry and npm scripts
+- Project-level OpenCode config with ponytail plugin
+- `.gitignore` and `.npmignore` for database and environment files
+- Real-time SSE — `notifyDash()` wired in MCP index.js with event notifications after share/pull/sync tool calls
+- External event remapping in `/api/notify` handler — `memory_*`/`compend_*`/`concept_*`/`project_*` events remapped to `synapse_updated`
+- Named Service Discovery — `~/.cordenar/manifest.json` written on startup, deleted on shutdown. Producers (Hemisphere/Compend) reference `"notifySubscribers": ["cordenar"]` instead of raw URLs
+- Dashboard search filter in `/api/synapses` (matches preview, title, type)
+
+### Changed
+
+- Replaced browser fallback polling with `synapse_updated` SSE listener
+- Dynamic imports replaced with static imports in MCP index.js
+- Combined Hemisphere+Compend synapse results sorted by `created_at` DESC
+- `sync_complete` SSE notification gated on actual sync results
+- Event name remapping: external tool events normalized to `synapse_updated` for dashboard consumption
+
+### Fixed
+
+- Dashboard SSE not reaching browser — events now delivered via active HTTP request cycles (`notifyDash` → `/api/notify` → `broadcast`)
+- Dashboard search box returning unfiltered results
+- Removed unused `client` variable in `supabase.js`

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hector Jarquin
+
+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,330 @@
+<img src="dashboard/public/logo.svg" height="48" alt="" />
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
+
+# Cordenar MCP
+
+Cloud orchestration MCP server — bridges local [Hemisphere](https://github.com/hectorjarquin/hemisphere) and [Compend](https://github.com/hectorjarquin/compend) knowledge bases to distributed team synapses.
+
+Cordenar gives teams the ability to securely share, approve, and synchronize knowledge across MCP nodes. Think of it as the control plane that makes context portable, auditable, and collaborative — whether you're running a single server or a distributed mesh.
+
+Built entirely in Node.js with zero cloud dependencies in the MCP layer. Syncing happens through Supabase on the cloud side.
+
+## Quick Start
+
+```bash
+npm install -g cordenar-mcp
+```
+
+Once installed, run the dashboard:
+
+```bash
+cordenar
+# → http://localhost:3458
+```
+
+### CLI commands
+
+```bash
+cordenar              # Start the dashboard
+cordenar stop         # Stop a running instance
+cordenar restart      # Stop then restart
+```
+
+### MCP server
+
+Add to `opencode.json`:
+
+```json
+{
+  "mcp": {
+    "cordenar": {
+      "type": "local",
+      "command": ["node", "/home/user/.nvm/versions/node/v22.22.0/lib/node_modules/cordenar-mcp/index.js"],
+      "enabled": true
+    }
+  }
+}
+```
+
+Find your exact path with `npm root -g` — append `/cordenar-mcp/index.js`.
+
+### Dashboard
+
+Browse and manage your local synapses at `http://localhost:3458`.
+
+Port configurable via `~/.cordenar/config.json` or `CORDENAR_PORT`.
+
+**Features:** dark/light theme toggle with persistence, WCAG 2.1 AA accessibility (keyboard navigation, ARIA labels, focus-visible outlines), real-time SSE updates (no polling), toast notifications, skeleton loading, search with debounce, source and status filters, expandable detail rows, kebab menu per synapse with context-sensitive actions (Share, Unlink, Remove Local, Dismiss).
+
+## How It Works
+
+```
+Local DBs (Hemisphere/Compend)  →  Cordenar MCP  →  Supabase (cloud)  →  Team nodes
+        (read-only)                  (sync)          (orgs/groups)        (pull + SSE revoke)
+```
+
+### Synapse Lifecycle
+
+1. **Share** — Select local synapses from Hemisphere or Compend. Push to cloud as `pending_approval`.
+2. **Approve** — Org admin reviews and approves in the cloud dashboard.
+3. **Sync** — Team members pull approved synapses into their local knowledge bases.
+4. **Revoke** — Admin can revoke access at any time. Synapse is removed from local DBs via SSE.
+
+### Architecture
+
+Cordenar MCP is **standalone** — it reads Hemisphere and Compend databases directly (read-only) and does not wrap or extend either MCP. Hemisphere and Compend remain sovereign, local-first, open-source MCPs. Cordenar is the cloud bridge for distributed synapse sharing across nodes.
+
+### Real-Time Updates
+
+Cordenar receives real-time notifications from Hemisphere and Compend via **Named Service Discovery**:
+
+1. When Cordenar starts, it writes `~/.cordenar/manifest.json`:
+   ```json
+   { "name": "cordenar", "notifyEndpoint": "http://127.0.0.1:3458/api/notify" }
+   ```
+2. Configure Hemisphere and Compend to subscribe by name:
+   ```json
+   // ~/.hemisphere/config.json
+   { "notifySubscribers": ["cordenar"] }
+   
+   // ~/.compend/config.json
+   { "notifySubscribers": ["cordenar"] }
+   ```
+3. On every tool call (`memory_store`, `compend_index`, etc.), Hemisphere and Compend read the manifest and POST the event to Cordenar's notify endpoint
+4. Cordenar remaps external events (`memory_*`, `compend_*`, `concept_*`, `project_*`) to `synapse_updated` and broadcasts to the browser via SSE
+5. On shutdown, the manifest is deleted. No polling — everything is push-based and real-time.
+
+## Installation
+
+### Prerequisites
+
+- Node.js 18+
+- C++ build tools (`build-essential` on Debian/Ubuntu, Xcode CLI tools on macOS) — required to compile `better-sqlite3`
+
+### From npm (recommended)
+
+```bash
+npm install -g cordenar-mcp
+```
+
+The `cordenar` CLI is now available globally. The MCP server runs via your AI client — see [Configuration](#configuration-1).
+
+### From git
+
+```bash
+git clone https://github.com/hectorjarquin/cordenar-mcp.git ~/cordenar
+cd ~/cordenar
+npm install
+npm link  # creates global `cordenar` command
+```
+
+### Configuration
+
+```json
+{
+  "mcp": {
+    "cordenar": {
+      "type": "local",
+      "command": ["node", "/usr/lib/node_modules/cordenar-mcp/index.js"],
+      "enabled": true
+    }
+  }
+}
+```
+
+Find your exact path with `npm root -g` — append `/cordenar-mcp/index.js`. For nvm users the path is typically `~/.nvm/versions/node/vX/lib/node_modules/cordenar-mcp/index.js`.
+
+## MCP Tools (Human-Facing)
+
+These tools are available through your AI client when Cordenar MCP is configured. They provide manual control over synapse sharing — no automatic uploads or background sync.
+
+### `cordenar_auth`
+
+Authenticate this node with Cordenar cloud via device code OAuth flow. Opens a browser or prints a URL + code for the user to enter in the dashboard.
+
+No parameters. Returns authentication state and node ID.
+
+### `cordenar_status`
+
+Show current auth state, node info, pending push count, un-pulled synapse count, and last sync time.
+
+No parameters.
+
+### `cordenar_list`
+
+List local synapses (Hemisphere memories + Compend concepts) available for sharing. Supports filters.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `source` | string | no | — | Filter by source: `'hemisphere'` or `'compend'` |
+| `type` | string | no | — | Filter by type: memory kind or concept type |
+| `project` | string | no | — | Filter Hemisphere memories by project namespace |
+| `limit` | number | no | `50` | Max results |
+
+Returns a unified view with `source`, `type`, `preview`, `status`, and `already_shared` flags.
+
+### `cordenar_share`
+
+Push selected local synapses to the cloud. Synapses enter `pending_approval` status until an admin approves them.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `synapses` | array | yes | — | Array of `{ source, id }` objects to share |
+
+### `cordenar_pull`
+
+Fetch approved active synapses from your groups and store them locally.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `group_id` | string | no | — | Limit pull to a specific group |
+
+Pulled memories are stored in Hemisphere with `project='cordenar'`, `kind='synapse'`. Pulled concepts are stored in Compend with `source='remote'`.
+
+### `cordenar_sync`
+
+Full bidirectional sync: push locally-edited shared synapses, detect and unlink locally-deleted shared synapses, pull new approved synapses from cloud.
+
+No parameters. Returns summary of pushed, unlinked, and pulled counts.
+
+## HTTP API (Dashboard-Facing)
+
+The dashboard exposes REST endpoints:
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/api/synapses` | List synapses with source, status, and search filters |
+| `GET` | `/api/status` | Auth state, push/pull/dirty counts |
+| `GET` | `/api/events` | SSE stream for real-time dashboard updates |
+| `POST` | `/api/sync` | Trigger full bidirectional sync |
+| `POST` | `/api/notify` | SSE event relay. Accepts external events from Hemisphere/Compend (via `notifySubscribers`) and MCP tools (via `notifyDash`). Remaps `memory_*`/`compend_*`/`concept_*`/`project_*` → `synapse_updated`. |
+| `POST` | `/api/synapses/:id/share?source=` | Share a synapse to cloud |
+| `POST` | `/api/synapses/:id/unshare?source=` | Cancel a pending share |
+| `POST` | `/api/synapses/:id/unlink?source=` | Remove mapping, keep local entity |
+| `POST` | `/api/synapses/:id/pull-delete?source=` | Delete local copy and unlink |
+| `POST` | `/api/synapses/:id/dismiss?source=` | Dismiss a rejected synapse |
+
+## Configuration
+
+### Config File (`~/.cordenar/config.json`)
+
+Create an optional JSON config file to customize settings. All keys are optional — missing keys use code defaults.
+
+**Priority chain** (highest wins): code defaults < config file < environment variables.
+
+```json
+{
+  "port": 3458,
+  "dbPath": "~/.cordenar/sync.db",
+  "hemisphereDb": "~/.hemisphere/memories.db",
+  "compendDb": "~/.compend/concepts.db",
+  "supabaseUrl": "",
+  "supabaseAnonKey": ""
+}
+```
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `port` | number | `3458` | Dashboard HTTP server port |
+| `dbPath` | string | `~/.cordenar/sync.db` | Sync database path (supports `~`) |
+| `hemisphereDb` | string | `~/.hemisphere/memories.db` | Hemisphere database path |
+| `compendDb` | string | `~/.compend/concepts.db` | Compend database path |
+| `supabaseUrl` | string | — | Supabase project URL (required for cloud sync) |
+| `supabaseAnonKey` | string | — | Supabase anonymous key (required for cloud sync) |
+| `manifestPath` | string | `~/.cordenar/manifest.json` | Named Service Discovery manifest path |
+
+### Hemisphere & Compend Integration
+
+Cordenar requires no configuration on its side to receive events. Instead, configure Hemisphere and Compend to push events to Cordenar:
+
+```json
+// ~/.hemisphere/config.json
+{ "notifySubscribers": ["cordenar"] }
+
+// ~/.compend/config.json
+{ "notifySubscribers": ["cordenar"] }
+```
+
+When configured, every tool call in Hemisphere (`memory_store`, `memory_trash`, `memory_update`, etc.) and Compend (`compend_index`) will notify Cordenar in real time. The Cordenar manifest (`~/.cordenar/manifest.json`) is created automatically on startup and deleted on shutdown — no URL to maintain.
+
+Hemisphere config key: `notifySubscribers` (array of service names). Env override: `HEMISPHERE_NOTIFY_SUBSCRIBERS` (comma-separated).
+Compend config key: `notifySubscribers` (array of service names). Env override: `COMPEND_NOTIFY_SUBSCRIBERS` (comma-separated).
+
+### Environment Variables
+
+Environment variables override the config file and code defaults at the highest priority.
+
+| Variable | Equivalent Config Key | Default |
+|----------|----------------------|---------|
+| `CORDENAR_PORT` | `port` | `3458` |
+| `CORDENAR_DB_PATH` | `dbPath` | `~/.cordenar/sync.db` |
+| `CORDENAR_DIR` | `cordenarDir` | `~/.cordenar` |
+| `SUPABASE_URL` | `supabaseUrl` | — |
+| `SUPABASE_ANON_KEY` | `supabaseAnonKey` | — |
+
+## Project Structure
+
+```
+cordenar-mcp/
+├── index.js                MCP stdio server (6 tool handlers)
+├── dashboard.js            HTTP dashboard + SSE broadcast server
+├── dashboard/
+│   ├── api-handler.js      Dashboard REST API routes
+│   └── public/
+│       ├── index.html      Dashboard HTML + ARIA structure
+│       ├── style.css       Full theme (dark/light), toast, dialog, skeleton
+│       ├── app.js          Frontend SSE client, keyboard nav, WCAG 2.1 AA
+│       └── logo.svg        Network icon logo
+├── db.js                   Sync database init + synapse_map CRUD
+├── sync.js                 Push/pull/hash-diff/unlink logic
+├── auth.js                 Device code OAuth + JWT store
+├── supabase.js             Supabase client wrapper
+├── embedding.js            MurmurHash3 → 256-dim float vector
+├── config.js               Config loader (defaults ← config.json ← env vars)
+├── package.json
+├── CHANGELOG.md
+└── README.md
+```
+
+On startup, Cordenar writes `~/.cordenar/manifest.json` for Named Service Discovery. On shutdown, it is deleted automatically.
+
+## Development
+
+### Scripts
+
+For local development (after `git clone`):
+
+```bash
+npm start           # Start dashboard server (same as `cordenar`)
+npm run stop        # Stop running instance (same as `cordenar stop`)
+npm run restart     # Stop then start
+```
+
+For installed users, the global `cordenar` CLI handles these — see [Quick Start](#quick-start).
+
+### Testing the MCP server
+
+Test with the MCP Inspector:
+
+```bash
+npx @modelcontextprotocol/inspector node index.js
+```
+
+## Roadmap
+
+- Supabase integration (device auth, synapse push/pull, SSE revocation)
+- Full bidirectional sync with hash diff and conflict resolution
+- Cloud dashboard (React SPA — org management, approval queue, billing)
+- Lemon Squeezy billing integration (annual subscriptions per node)
+- Multi-node registration and seat management
+- Role-based access control (Owner, Admin, Member)
+- Tier enforcement (Team, Business, Enterprise)
+
+## Contributing
+
+Open an issue or PR at [github.com/hectorjarquin/cordenar-mcp](https://github.com/hectorjarquin/cordenar-mcp).
+
+## License
+
+MIT License — see [LICENSE](LICENSE) for details.

package/auth.js

@@ -0,0 +1,48 @@
+// Cordenar MCP — Device code OAuth + JWT store
+// Pattern: ~/.cordenar/auth.json holds the session
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { getConfig } from './config.js';
+
+export function loadAuth() {
+  const cfg = getConfig();
+  try {
+    if (!existsSync(cfg.authFile)) return null;
+    const raw = readFileSync(cfg.authFile, 'utf-8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+export function saveAuth(data) {
+  const cfg = getConfig();
+  writeFileSync(cfg.authFile, JSON.stringify(data, null, 2));
+}
+
+export function clearAuth() {
+  const cfg = getConfig();
+  try {
+    if (existsSync(cfg.authFile)) {
+      writeFileSync(cfg.authFile, '');
+    }
+  } catch {}
+}
+
+export function isAuthenticated() {
+  const auth = loadAuth();
+  if (!auth || !auth.access_token) return false;
+  if (auth.expires_at && Date.now() / 1000 > auth.expires_at) return false;
+  return true;
+}
+
+export function getAccessToken() {
+  const auth = loadAuth();
+  if (!auth) return null;
+  return auth.access_token;
+}
+
+export function getNodeId() {
+  const auth = loadAuth();
+  if (!auth) return null;
+  return auth.node_id;
+}

package/config.js

@@ -0,0 +1,87 @@
+// Cordenar MCP — Configuration loader
+// Pattern mirrors Hemisphere (config.js) and Compend (config.js)
+// Priority: code defaults → config file → environment variables
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { existsSync, mkdirSync, readFileSync } from 'node:fs';
+
+const DEFAULTS = {
+  port: 3458,
+  cordenarDir: join(homedir(), '.cordenar'),
+  dbPath: join(homedir(), '.cordenar', 'sync.db'),
+  hemisphereDb: join(homedir(), '.hemisphere', 'memories.db'),
+  compendDb: join(homedir(), '.compend', 'concepts.db'),
+  authFile: join(homedir(), '.cordenar', 'auth.json'),
+  manifestPath: join(homedir(), '.cordenar', 'manifest.json'),
+  supabaseUrl: '',
+  supabaseAnonKey: '',
+};
+
+const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+export function deepMerge(target, source) {
+  for (const key of Object.keys(source)) {
+    if (!Object.hasOwn(target, key)) {
+      target[key] = JSON.parse(JSON.stringify(source[key]));
+      continue;
+    }
+    const tv = target[key];
+    const sv = source[key];
+    if (isObject(tv) && isObject(sv)) {
+      deepMerge(tv, sv);
+    } else {
+      target[key] = sv;
+    }
+  }
+  return target;
+}
+
+function readConfigFile() {
+  const path = join(homedir(), '.cordenar', 'config.json');
+  try {
+    const raw = readFileSync(path, 'utf-8');
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+
+function resolveTilde(p) {
+  if (typeof p !== 'string') return p;
+  if (p.startsWith('~/') || p === '~') {
+    return join(homedir(), p.slice(1));
+  }
+  return p;
+}
+
+function applyEnvOverrides(cfg) {
+  if (process.env.SUPABASE_URL) cfg.supabaseUrl = process.env.SUPABASE_URL;
+  if (process.env.SUPABASE_ANON_KEY)
+    cfg.supabaseAnonKey = process.env.SUPABASE_ANON_KEY;
+  if (process.env.CORDENAR_PORT)
+    cfg.port = parseInt(process.env.CORDENAR_PORT, 10) || 3458;
+  if (process.env.CORDENAR_DIR)
+    cfg.cordenarDir = resolveTilde(process.env.CORDENAR_DIR);
+  if (process.env.CORDENAR_DB_PATH)
+    cfg.dbPath = resolveTilde(process.env.CORDENAR_DB_PATH);
+  return cfg;
+}
+
+let _cfg = null;
+
+export function getConfig() {
+  if (_cfg) return _cfg;
+  const defaults = JSON.parse(JSON.stringify(DEFAULTS));
+  _cfg = deepMerge(defaults, readConfigFile());
+  applyEnvOverrides(_cfg);
+  return _cfg;
+}
+
+export function getDbPath() {
+  const cfg = getConfig();
+  const dir = join(cfg.dbPath, '..');
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  return cfg.dbPath;
+}