Cordenar MCP

Cloud orchestration MCP server — bridges local Hemisphere and 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

npm install -g cordenar-mcp

Once installed, run the dashboard:

cordenar
# → http://localhost:3458

CLI commands

cordenar              # Start the dashboard
cordenar stop         # Stop a running instance
cordenar restart      # Stop then restart

MCP server

Add to opencode.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:

   { "name": "cordenar", "notifyEndpoint": "http://127.0.0.1:3458/api/notify" }

2. Configure Hemisphere and Compend to subscribe by name:

   // ~/.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+

From npm (recommended)

npm install -g cordenar-mcp

The cordenar CLI is now available globally. The MCP server runs via your AI client — see Configuration.

From git

git clone https://github.com/hectorjarquin/cordenar-mcp.git ~/cordenar
cd ~/cordenar
npm install
npm link  # creates global `cordenar` command

Configuration

{
  "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)

Status: cordenar_list is fully functional. cordenar_share, cordenar_pull, and cordenar_sync are wired at the MCP layer but await Supabase integration. cordenar_auth and cordenar_status are stubs — not yet implemented.

These tools are available through your AI client when Cordenar MCP is configured.

cordenar_auth

Authenticate this node with Cordenar cloud via device code OAuth flow. Not yet implemented.

cordenar_status

Show current auth state, node info, pending push count, un-pulled synapse count, and last sync time. Not yet implemented.

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, title, description, body (Compend), slug (Compend), status, and already_shared flags.

cordenar_share

Push selected local synapses to the cloud. Synapses enter pending_approval status until an admin approves them. Awaiting Supabase integration — currently checks already_shared status only.

cordenar_pull

Fetch approved active synapses from your groups and store them locally. Awaiting Supabase integration.

cordenar_sync

Full bidirectional sync: push locally-edited shared synapses, detect and unlink locally-deleted shared synapses, pull new approved synapses from cloud. Awaiting Supabase integration.

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.

{
  "port": 3458,
  "dbPath": "~/.cordenar/sync.db",
  "hemisphereDb": "~/.hemisphere/memories.db",
  "compendDb": "~/.compend/concepts.db",
  "supabaseUrl": "",
  "supabasePublishableKey": "",
  "authFile": "~/.cordenar/auth.json",
  "manifestPath": "~/.cordenar/manifest.json"
}

| 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) | | supabasePublishableKey | string | — | Supabase publishable key (required for cloud sync) | | authFile | string | ~/.cordenar/auth.json | JWT token store path | | 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:

// ~/.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 | | SUPABASE_URL | supabaseUrl | — | | SUPABASE_PUBLISHABLE_KEY | supabasePublishableKey | — |

Project Structure

cordenar-mcp/
├── index.js                MCP stdio server (6 handlers: list, share, pull, sync, auth, status)
├── 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 (awaiting integration)
├── 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):

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.

Testing the MCP server

Test with the MCP Inspector:

npx @modelcontextprotocol/inspector node index.js

Roadmap

In Progress

• Supabase local development (Docker + CLI, schema migrations)
• Device code OAuth (Supabase Edge Functions)

Planned

• Supabase cloud integration (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)

Contributing

Open an issue or PR at github.com/hectorjarquin/cordenar-mcp.

License

MIT License — see LICENSE for details.