n2n-nexus 0.4.2

package/README.md

@@ -0,0 +1,286 @@
+# n2n-nexus
+
+Local-first MCP coordination hub from N2NS Lab for multi-AI assistant collaboration across IDEs, machines, and projects.
+
+[![npm version](https://img.shields.io/npm/v/n2n-nexus)](https://www.npmjs.com/package/n2n-nexus)
+[![npm total downloads](https://img.shields.io/npm/dt/n2n-nexus)](https://www.npmjs.com/package/n2n-nexus)
+[![license](https://img.shields.io/github/license/n2ns/n2n-nexus)](https://github.com/n2ns/n2n-nexus/blob/main/LICENSE)
+[![MCP Protocol](https://img.shields.io/badge/MCP-Protocol-blue)](https://modelcontextprotocol.io)
+[![node version](https://img.shields.io/node/v/n2n-nexus)](https://nodejs.org)
+[![DataFrog.io](https://datafrog.io/badges/datafrog.svg)](https://datafrog.io)
+
+[中文版](./docs/README_zh.md)
+
+---
+
+> **One daemon. Many assistants. Shared project state.**
+
+n2n-nexus is an open-source Model Context Protocol (MCP) coordination server for teams and developers who use multiple AI coding assistants. A long-running local daemon owns project state, meetings, messages, tasks, shared docs, and project assets. Lightweight MCP adapters connect each IDE or assistant to the same daemon.
+
+Use it when Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, JetBrains, or other MCP-enabled clients need a shared local coordination layer instead of isolated per-chat context.
+
+## Search-friendly positioning
+
+If you are searching for:
+
+- multi-agent MCP coordination
+- multi-AI assistant collaboration
+- local MCP coordination hub
+- shared project context for AI coding agents
+- cross-IDE MCP collaboration server
+- local-first project registry for AI assistants
+- meeting and task coordination for coding agents
+
+n2n-nexus is designed for these goals: shared daemon state, stateless MCP adapters, project-aware collaboration, local storage, and cross-environment IDE workflows.
+
+## What Is n2n-nexus?
+
+n2n-nexus gives AI assistants a shared coordination workspace. Instead of each assistant keeping its own isolated conversation state, all connected MCP clients can read and write to the same local daemon.
+
+**TL;DR**
+
+- **Install**: `npx n2n-nexus daemon --port 5688`
+- **Protocol**: Model Context Protocol (MCP), adapter-to-daemon HTTP bridge
+- **Storage**: local filesystem plus SQLite under `~/.n2n-nexus` by default
+- **Best for**: multi-assistant coding sessions, project handoffs, shared decisions, meeting notes, async tasks, project manifests
+- **Not for**: cloud team chat, public project management SaaS, source code indexing, vector search, or remote database hosting
+
+## Why Use It?
+
+- Coordinate multiple AI assistants working on the same project.
+- Share project manifests, internal notes, assets, and topology across IDEs.
+- Keep decisions, proposals, and updates in a local meeting/message log.
+- Run the daemon once and connect adapters from Windows, WSL, SSH hosts, VMs, or multiple editors.
+- Avoid giving each assistant broad filesystem or backend access just to exchange context.
+
+## Architecture
+
+```text
+┌──────────────────────────────────────┐
+│          n2n-nexus daemon            │
+│  Standalone HTTP server · always on  │
+│  Owns data, tools, tasks, messages   │
+└──────────────┬───────────────────────┘
+               │ HTTP (NEXUS_ENDPOINT)
+       ┌───────┼───────┐
+       ▼       ▼       ▼
+    MCP-A   MCP-B   MCP-C
+   (Win)   (WSL)   (SSH/VM)
+  Stateless adapter per IDE
+```
+
+- **Daemon is the source of truth**: start it once and keep it running.
+- **MCP adapters are stateless**: each IDE starts an adapter through `npx`, then forwards tool calls to the daemon.
+- **Cross-environment by design**: point `NEXUS_ENDPOINT` at the same daemon from different machines or shells. The daemon binds to localhost by default; use `--host 0.0.0.0` only on a trusted network.
+
+## Quick Start
+
+### 1. Start the daemon
+
+```bash
+npx n2n-nexus daemon --port 5688
+```
+
+### 2. Configure an MCP client
+
+```json
+{
+  "mcpServers": {
+    "n2n-nexus": {
+      "command": "npx",
+      "args": ["-y", "n2n-nexus", "mcp"],
+      "env": {
+        "NEXUS_ENDPOINT": "http://127.0.0.1:5688"
+      }
+    }
+  }
+}
+```
+
+The adapter can start before the daemon. It loads the daemon tool list once the daemon becomes reachable.
+
+### Cross-environment endpoint examples
+
+| Scenario | `NEXUS_ENDPOINT` |
+| --- | --- |
+| Same machine | `http://127.0.0.1:5688` |
+| WSL IDE to Windows daemon | `http://host.docker.internal:5688` |
+| Windows IDE to WSL daemon | `http://<WSL-IP>:5688` |
+| Remote machine | `http://<Server-IP>:5688` |
+
+## Toolset
+
+### Session and context
+
+- `register_session_context`: declare the active project ID.
+
+### Project asset management
+
+- `sync_project_assets`: submit a project manifest and internal docs.
+- `update_project`: patch a project manifest.
+- `rename_project`: rename a project ID and update relations.
+- `upload_project_asset`: upload binary or text assets.
+- `search_projects`: search the project registry.
+- `get_global_topology`: inspect project topology and dependencies.
+
+### Messaging and collaboration
+
+- `send_message`: post meeting or global messages.
+- `read_messages`: read unread messages incrementally.
+- `update_global_strategy`: update the master strategy document.
+- `sync_global_doc`: create or update shared docs.
+
+### Meeting management
+
+- `start_meeting`: open a meeting session.
+- `end_meeting`: close and lock a meeting.
+- `archive_meeting`: move a closed meeting to archive.
+- `reopen_meeting`: reactivate a closed or archived meeting.
+
+### Async task management
+
+- `create_task`: create a background task.
+- `get_task`: poll task status and result.
+- `list_tasks`: list tasks by status.
+- `cancel_task`: cancel a pending or running task.
+
+### Maintenance
+
+- `host_maintenance`: prune or clear system logs.
+- `host_delete_project`: delete a project and assets.
+
+## Data Storage
+
+Default storage root:
+
+| Platform | Path |
+| --- | --- |
+| Linux / WSL | `~/.n2n-nexus` |
+| Windows | `%USERPROFILE%\.n2n-nexus` |
+| macOS | `~/.n2n-nexus` |
+
+Override with `--root <path>` or `NEXUS_ROOT`.
+
+```text
+~/.n2n-nexus/
+├── global/
+│   ├── blueprint.md
+│   ├── docs_index.json
+│   └── docs/
+├── projects/
+│   └── {project-id}/
+│       ├── manifest.json
+│       ├── internal_blueprint.md
+│       └── assets/
+├── registry.json
+└── nexus.db
+```
+
+## Project ID Conventions
+
+Project IDs follow `[prefix]_[name]`.
+
+| Prefix | Category | Example |
+| --- | --- | --- |
+| `web_` | Websites | `web_datafrog.io` |
+| `api_` | Backend services | `api_user-auth` |
+| `mcp_` | MCP servers | `mcp_nexus` |
+| `lib_` | Libraries / SDKs | `lib_crypto-core` |
+| `chrome_` | Chrome extensions | `chrome_evisa-helper` |
+| `vscode_` | VS Code extensions | `vscode_super-theme` |
+| `desktop_` | Desktop apps | `desktop_main-hub` |
+| `infra_` | Infrastructure / DevOps | `infra_k8s-config` |
+| `doc_` | Documentation | `doc_coding-guide` |
+
+## CLI Reference
+
+```bash
+# Start daemon
+n2n-nexus daemon [--port 5688] [--root ~/.n2n-nexus] [--host 127.0.0.1]
+
+# Start MCP adapter
+NEXUS_ENDPOINT=http://127.0.0.1:5688 n2n-nexus mcp
+```
+
+### Environment variables
+
+| Variable | Description | Default |
+| --- | --- | --- |
+| `NEXUS_ENDPOINT` | Daemon URL for MCP adapter | `http://127.0.0.1:5688` |
+| `NEXUS_ROOT` | Storage root for daemon | `~/.n2n-nexus` |
+| `NEXUS_HOST` | Daemon bind host | `127.0.0.1` |
+| `NEXUS_INSTANCE_ID` | Override MCP instance ID | auto-generated |
+
+## Security and governance notes
+
+- n2n-nexus stores coordination data locally by default.
+- Do not put secrets, credentials, customer data, or private tokens in meeting messages or project assets unless your local policy allows it.
+- Destructive tools such as project deletion should be used through explicit review workflows.
+- Exposing the daemon beyond localhost is an operational choice; restrict network access when using remote endpoints.
+- Treat project manifests and internal docs as potentially sensitive implementation data.
+
+## Real-world example
+
+The docs include a sample multi-agent session where several AI assistants collaborated on architecture and protocol decisions:
+
+| File | Description |
+| --- | --- |
+| [Meeting Minutes](docs/MEETING_MINUTES_2025-12-29.md) | Structured decisions and test notes |
+| [Discussion Log](docs/discussion_2025-12-29_en.md) | Human-readable discussion transcript |
+
+## Local Development
+
+```bash
+git clone https://github.com/n2ns/n2n-nexus.git
+cd n2n-nexus
+npm install
+npm run build
+
+# Run daemon
+node build/index.js daemon --root /tmp/nexus-test --port 5688
+
+# Run MCP adapter
+NEXUS_ENDPOINT=http://127.0.0.1:5688 node build/index.js mcp
+```
+
+## FAQ
+
+### Is n2n-nexus a project management SaaS?
+
+No. It is a local MCP coordination server for AI assistants. It stores state locally and exposes MCP tools to connected clients.
+
+### Does it replace n2n-memory?
+
+No. `n2n-memory` is repository-local memory for one project. `n2n-nexus` is a shared coordination hub for multiple assistants, project manifests, messages, meetings, and tasks.
+
+### Does it work with Claude Desktop, Cursor, VS Code, and other IDEs?
+
+Yes, when the client supports local MCP command servers. The adapter is started by the IDE and connects to the local daemon through `NEXUS_ENDPOINT`.
+
+### Can it coordinate assistants across Windows and WSL?
+
+Yes. Run the daemon in one environment and point each adapter at it using `NEXUS_ENDPOINT`.
+
+### Does it send data to the cloud?
+
+No cloud service is required. Data is stored under the configured local root. If you expose the daemon to a remote machine, that is your own network configuration.
+
+### Is this a vector database or code indexer?
+
+No. n2n-nexus coordinates project metadata, messages, meetings, docs, tasks, and assets. It is not a semantic code search engine.
+
+## Related docs
+
+- [Architecture](./docs/ARCHITECTURE.md)
+- [AI Assistant Guide](./docs/ASSISTANT_GUIDE.md)
+- [Chinese README](./docs/README_zh.md)
+- [Changelog](./CHANGELOG.md)
+- [llms.txt](./llms.txt)
+
+## License
+
+This project is licensed under the [Apache-2.0 License](./LICENSE).
+
+---
+
+Built by N2NS Lab, short for Next-to-Native Systems Lab, Datafrog's open-source lab for practical AI developer tools.

package/build/client/nexus-client.js

@@ -0,0 +1,71 @@
+import http from "node:http";
+import https from "node:https";
+import { URL } from "node:url";
+function normalizeEndpoint(endpoint) {
+    const raw = endpoint || process.env.NEXUS_ENDPOINT || "http://127.0.0.1:5688";
+    if (/^https?:\/\//i.test(raw))
+        return raw;
+    return `http://${raw}`;
+}
+export class NexusClient {
+    endpoint;
+    timeoutMs;
+    constructor(options = {}) {
+        this.endpoint = normalizeEndpoint(options.endpoint);
+        this.timeoutMs = options.timeoutMs ?? 5000;
+    }
+    request(method, path, body) {
+        const url = new URL(path, this.endpoint);
+        const payload = body !== undefined ? JSON.stringify(body) : undefined;
+        const transport = url.protocol === "https:" ? https : http;
+        return new Promise((resolve, reject) => {
+            const req = transport.request({
+                method,
+                protocol: url.protocol,
+                hostname: url.hostname,
+                port: url.port,
+                path: `${url.pathname}${url.search}`,
+                headers: {
+                    "Content-Type": "application/json",
+                    ...(payload ? { "Content-Length": Buffer.byteLength(payload) } : {})
+                },
+                timeout: this.timeoutMs
+            }, (res) => {
+                let data = "";
+                res.on("data", chunk => { data += chunk; });
+                res.on("end", () => {
+                    try {
+                        const parsed = data ? JSON.parse(data) : {};
+                        if (res.statusCode && res.statusCode >= 400) {
+                            reject(new Error(parsed.error || `HTTP ${res.statusCode}`));
+                        }
+                        else {
+                            resolve(parsed);
+                        }
+                    }
+                    catch {
+                        reject(new Error(`Invalid JSON response: ${data}`));
+                    }
+                });
+            });
+            req.on("error", reject);
+            req.on("timeout", () => req.destroy(new Error("Request timeout")));
+            if (payload)
+                req.write(payload);
+            req.end();
+        });
+    }
+    async health() {
+        return this.request("GET", "/health");
+    }
+    async fetchTools() {
+        const res = await this.request("GET", "/api/tools");
+        return res.tools;
+    }
+    async callTool(name, args, instanceId) {
+        const res = await this.request("POST", "/api/tools/call", { tool: name, args: args || {}, instanceId: instanceId || "unknown" });
+        if (!res.ok)
+            throw new Error(res.error || "Tool call failed");
+        return res.result;
+    }
+}

package/build/config/cli.js

@@ -0,0 +1,11 @@
+/**
+ * CLI Argument Parsing
+ */
+const args = process.argv.slice(2);
+export function getArg(k) {
+    const i = args.indexOf(k);
+    return i !== -1 && args[i + 1] ? args[i + 1] : "";
+}
+export function hasFlag(k) {
+    return args.includes(k) || args.includes(k.charAt(1) === "-" ? k : k.substring(0, 2));
+}

package/build/config/index.js

@@ -0,0 +1,16 @@
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const pkgPath = path.resolve(__dirname, "../../package.json");
+export const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+export function getRootPath() {
+    // Priority: --root CLI arg → NEXUS_ROOT env → ~/.n2n-nexus
+    const argIndex = process.argv.indexOf("--root");
+    if (argIndex !== -1 && process.argv[argIndex + 1]) {
+        return process.argv[argIndex + 1];
+    }
+    if (process.env.NEXUS_ROOT)
+        return process.env.NEXUS_ROOT;
+    return path.join(process.env.HOME || process.env.USERPROFILE || ".", ".n2n-nexus");
+}

package/build/config/paths.js

@@ -0,0 +1,38 @@
+/**
+ * Path Resolution Logic
+ */
+import path from "path";
+import os from "os";
+import { SERVICE_NAME } from "../constants.js";
+import { getArg } from "./cli.js";
+/**
+ * Normalize and resolve the root storage path
+ */
+export function normalizeRootPath(inputPath) {
+    // Priority: CLI --root > ENV NEXUS_ROOT > System Default
+    let root = inputPath || process.env.NEXUS_ROOT || getDefaultDataDir();
+    // Resolve ~ to home directory
+    if (root.startsWith("~")) {
+        root = path.join(os.homedir(), root.slice(1));
+    }
+    // Cross-platform adaptation (WSL <-> Windows)
+    if (process.platform === "linux" && /^[a-zA-Z]:[/\\]/.test(root)) {
+        const drive = root[0].toLowerCase();
+        root = `/mnt/${drive}${root.slice(2).replace(/\\/g, "/")}`;
+    }
+    return path.resolve(root);
+}
+/**
+ * Get the default data directory
+ */
+export function getDefaultDataDir() {
+    const home = os.homedir();
+    // Use ~/.n2n-nexus for all platforms (developer-friendly convention)
+    return path.join(home, `.${SERVICE_NAME}`);
+}
+/**
+ * Get the root storage path from CLI or environment
+ */
+export function getRootPath() {
+    return normalizeRootPath(getArg("--root"));
+}

package/build/constants.js

@@ -0,0 +1,22 @@
+/**
+ * Nexus Network Constants
+ *
+ * Centralized configuration for network-related settings.
+ */
+// Service identification
+export const SERVICE_NAME = "n2n-nexus";
+// Host address for binding and connecting.
+// Default to localhost because the daemon exposes unauthenticated local admin APIs.
+// Use "0.0.0.0" only when you intentionally expose it to another trusted environment.
+export const NEXUS_HOST = "127.0.0.1";
+// Port range for auto-election
+export const PORT_RANGE_START = 5688;
+export const PORT_RANGE_END = 5800;
+// Timeouts (milliseconds)
+export const HANDSHAKE_TIMEOUT = 200;
+export const HEARTBEAT_INTERVAL = 30000;
+// Task cleanup
+export const TASK_CLEANUP_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+// File I/O
+export const FILE_ENCODING = "utf-8";
+export const PACKAGE_JSON = "package.json";

package/build/daemon/index.js

@@ -0,0 +1,41 @@
+import { createDaemonServer } from "./server.js";
+import { pkg, getRootPath } from "../config/index.js";
+import { NEXUS_HOST } from "../constants.js";
+function parsePort() {
+    const argIndex = process.argv.indexOf("--port");
+    if (argIndex !== -1) {
+        const parsed = parseInt(process.argv[argIndex + 1] || "", 10);
+        if (!isNaN(parsed) && parsed > 0)
+            return parsed;
+    }
+    const envPort = parseInt(process.env.NEXUS_DAEMON_PORT || process.env.NEXUS_PORT || "", 10);
+    if (!isNaN(envPort) && envPort > 0)
+        return envPort;
+    return 5688;
+}
+function parseHost() {
+    const argIndex = process.argv.indexOf("--host");
+    if (argIndex !== -1 && process.argv[argIndex + 1]) {
+        return process.argv[argIndex + 1];
+    }
+    return process.env.NEXUS_HOST || NEXUS_HOST;
+}
+export async function runDaemon() {
+    const port = parsePort();
+    const host = parseHost();
+    const root = getRootPath();
+    // Inject root path into CONFIG via env so StorageManager picks it up
+    process.env.NEXUS_ROOT = root;
+    const { server, storageInfo } = await createDaemonServer({ port, host, version: pkg.version });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(port, host, () => {
+            console.error(`[n2n-nexus] Daemon v${pkg.version} listening on http://${host}:${port}`);
+            console.error(`[n2n-nexus] Storage: ${root} (${storageInfo.storageMode}${storageInfo.isDegraded ? ", degraded" : ""})`);
+            resolve();
+        });
+    });
+    process.once("SIGINT", () => { console.error("[n2n-nexus] Shutting down."); server.close(() => process.exit(0)); });
+    process.once("SIGTERM", () => { server.close(() => process.exit(0)); });
+    console.error("[n2n-nexus] Ready. Press Ctrl+C to stop.");
+}