@datafrog-io/n2n-nexus 0.2.0 → 0.2.1

package/README.md

@@ -10,6 +10,8 @@
 
 > **Works with:** Claude Code · Claude Desktop · VS Code · Cursor · Windsurf · Zed · JetBrains · Theia · Google Antigravity
 
+📖 **Documentation:** [CHANGELOG](CHANGELOG.md) | [TODO](TODO.md) | [中文文档](docs/README_zh.md) | [AI Assistant Guide](docs/ASSISTANT_GUIDE.md)
+
 ## 🏛️ Architecture
 
 1.  **Nexus Room (Discussion)**: Unified public channel for all IDE assistants to coordinate across projects.
@@ -31,19 +33,21 @@ Nexus stores all data in the local file system (customizable path), ensuring com
 Nexus_Storage/
 ├── global/
 │   ├── blueprint.md       # Master Strategy
-│   ├── discussion.json    # Chat History
-│   ├── docs_index.json    # Global Docs Metadata
+│   ├── discussion.json    # Global Chat History (fallback)
+│   ├── docs_index.json    # Global Docs Index
 │   └── docs/              # Global Markdown Docs
 │       ├── coding-standards.md
 │       └── deployment-flow.md
 ├── projects/
-│   ├── my-app/
-│   │   ├── manifest.json  # Project Metadata
-│   │   ├── internal_blueprint.md
-│   │   └── assets/        # Binary Assets
-│   └── ...
+│   └── {project-id}/
+│       ├── manifest.json          # Project Metadata
+│       ├── internal_blueprint.md  # Technical Implementation Docs
+│       └── assets/                # Binary Assets (images, PDFs)
+├── meetings/              # Meeting files (JSON fallback mode)
+│   └── {meeting-id}.json
 ├── registry.json          # Global Project Index
-└── archives/              # (Reserved for backups)
+├── archives/              # Reserved for backups
+└── nexus.db               # SQLite Database (meetings, tasks, state)
 ```
 
 **Self-healing**: Core data files (e.g., `registry.json`, `discussion.json`) include automatic detection and repair mechanisms. If files are corrupted or missing, the system automatically rebuilds the initial state to ensure uninterrupted service.
@@ -89,9 +93,9 @@ To ensure clarity and prevent collisions in the flat local namespace, all Projec
 
 ### C. Global Collaboration
 - `send_message`: Post a message to the team (Auto-routes to active meeting).
-- `read_messages`: Retrieve latest logs from active meeting or global registry.
+- `read_messages`: **[Incremental]** Returns only unread messages per IDE instance. Server tracks read cursor automatically.
 - `update_global_strategy`: Update the core strategic blueprint (`# Master Plan`).
-- `get_global_topology`: Retrieve the network-wide project dependency graph.
+- `get_global_topology`: **[Progressive]** Default: summary list. With `projectId`: detailed subgraph.
 - `sync_global_doc`: Create or update a shared cross-project document.
 
 ### D. Meeting Management
@@ -113,14 +117,21 @@ To ensure clarity and prevent collisions in the flat local namespace, all Projec
 
 ## 📄 Resources (URI)
 
+**Core Resources (Static):**
 - `mcp://nexus/chat/global`: Real-time conversation history.
-- `mcp://nexus/hub/registry`: Global project registry overview.
+- `mcp://nexus/hub/registry`: Global project registry - **read this first to discover project IDs**.
 - `mcp://nexus/docs/global-strategy`: Strategic blueprint.
+- `mcp://nexus/docs/list`: Index of shared documents.
+- `mcp://nexus/meetings/list`: List of active and closed meetings.
 - `mcp://nexus/session`: Current session status and identity.
 - `mcp://nexus/status`: System operational status and storage mode.
 - `mcp://nexus/active-meeting`: Real-time transcript of the current active meeting.
-- `mcp://nexus/projects/{id}/manifest`: Full metadata for a specific project.
-- `mcp://nexus/projects/{id}/internal-docs`: Internal technical docs for a specific project.
+
+**Resource Templates (Use registry to discover IDs):**
+- `mcp://nexus/projects/{projectId}/manifest`: Full metadata for a specific project.
+- `mcp://nexus/projects/{projectId}/internal-docs`: Internal technical docs for a project.
+- `mcp://nexus/docs/{docId}`: Read a specific shared document.
+- `mcp://nexus/meetings/{meetingId}`: Full transcript for a specific meeting.
 
 ## 🚀 Quick Start
 

package/build/resources/index.js

@@ -33,7 +33,7 @@ export async function getResourceContent(uri, currentProject) {
         const storageInfo = await UnifiedMeetingStore.getStorageInfo();
         const status = {
             status: "online",
-            version: "0.2.0",
+            version: "0.2.1",
             ...storageInfo,
             active_meetings_count: state.activeMeetings.length,
             default_meeting: state.defaultMeetingId
@@ -89,39 +89,31 @@ export async function getResourceContent(uri, currentProject) {
 }
 /**
  * Returns the list of available resources for MCP ListResourcesRequestSchema
+ *
+ * OPTIMIZATION: No longer lists individual projects dynamically.
+ * Uses resourceTemplates instead - AI should query registry first.
  */
 export async function listResources() {
     const registry = await StorageManager.listRegistry();
-    const projectIds = Object.keys(registry.projects);
+    const projectCount = Object.keys(registry.projects).length;
     return {
         resources: [
-            { uri: "mcp://nexus/chat/global", name: "Global Collaboration History", description: "Real-time discussion stream." },
-            { uri: "mcp://nexus/hub/registry", name: "Global Project Registry", description: "Consolidated index of all local projects." },
-            { uri: "mcp://nexus/docs/list", name: "Global Documentation Index", description: "List of all shared cross-project documents." },
-            { uri: "mcp://nexus/docs/global-strategy", name: "Master Strategy Blueprint", description: "Top-level cross-project coordination document." },
-            { uri: "mcp://nexus/meetings/list", name: "Meeting Registry", description: "Consolidated list of active and closed meetings." },
-            { uri: "mcp://nexus/session", name: "Current Session Info", description: "Your identity and role in this Nexus instance." },
-            { uri: "mcp://nexus/status", name: "System Status & Storage Mode", description: "Backend storage mode (sqlite/json) and active meeting counts." },
-            { uri: "mcp://nexus/active-meeting", name: "Current Active Meeting", description: "Full transcript and participants of the current default meeting." },
-            ...projectIds.map(id => {
-                const prefix = id.split("_")[0];
-                const typeLabel = {
-                    web: "🌐 Website", api: "⚙️ API", chrome: "🧩 Chrome Ext",
-                    vscode: "💻 VSCode Ext", mcp: "🔌 MCP Server", android: "📱 Android",
-                    ios: "🍎 iOS", flutter: "📲 Flutter", desktop: "🖥️ Desktop",
-                    lib: "📦 Library", bot: "🤖 Bot", infra: "☁️ Infra", doc: "📄 Docs"
-                }[prefix] || "📁 Project";
-                return {
-                    uri: `mcp://nexus/projects/${id}/manifest`,
-                    name: `${typeLabel}: ${id}`,
-                    description: `Structured metadata (Tech stack, relations) for ${id}`
-                };
-            })
+            // Core resources (static, always available)
+            { uri: "mcp://nexus/chat/global", name: "Global Chat", description: "Real-time discussion stream." },
+            { uri: "mcp://nexus/hub/registry", name: "Project Registry", description: `Index of ${projectCount} registered projects. Read this first to discover project IDs.` },
+            { uri: "mcp://nexus/docs/list", name: "Docs Index", description: "List of shared cross-project documents." },
+            { uri: "mcp://nexus/docs/global-strategy", name: "Strategy Blueprint", description: "Top-level coordination document." },
+            { uri: "mcp://nexus/meetings/list", name: "Meetings List", description: "Active and closed meetings." },
+            { uri: "mcp://nexus/session", name: "Session Info", description: "Your identity and role." },
+            { uri: "mcp://nexus/status", name: "System Status", description: "Storage mode and active meeting count." },
+            { uri: "mcp://nexus/active-meeting", name: "Active Meeting", description: "Current default meeting transcript." }
         ],
         resourceTemplates: [
-            { uriTemplate: "mcp://nexus/projects/{projectId}/internal-docs", name: "Internal Project Docs", description: "Markdown-based detailed implementation plans." },
-            { uriTemplate: "mcp://nexus/docs/{docId}", name: "Specific Global Doc", description: "Read a specific document from the global index." },
-            { uriTemplate: "mcp://nexus/meetings/{meetingId}", name: "Meeting Insights", description: "Full transcript and decisions for a specific meeting." }
+            // Project resources - use registry to discover IDs first
+            { uriTemplate: "mcp://nexus/projects/{projectId}/manifest", name: "Project Manifest", description: "Metadata for a specific project. Get projectId from registry." },
+            { uriTemplate: "mcp://nexus/projects/{projectId}/internal-docs", name: "Project Docs", description: "Internal implementation guide for a project." },
+            { uriTemplate: "mcp://nexus/docs/{docId}", name: "Global Doc", description: "Read a specific shared document." },
+            { uriTemplate: "mcp://nexus/meetings/{meetingId}", name: "Meeting Details", description: "Full transcript for a specific meeting." }
         ]
     };
 }

package/build/storage/index.js

@@ -104,21 +104,76 @@ export class StorageManager {
         await fs.writeFile(path.join(assetDir, fileName), content);
         return path.join("projects", id, "assets", fileName);
     }
-    static async calculateTopology() {
+    /**
+     * Calculate project dependency topology.
+     *
+     * Context7-style progressive loading:
+     * - Default: Returns summary (project list + stats) - lightweight
+     * - With projectId: Returns detailed subgraph for that project
+     */
+    static async calculateTopology(projectId) {
         const registry = await this.listRegistry();
         const projectIds = Object.keys(registry.projects);
-        const nodes = [];
-        const edges = [];
+        // Collect manifests
+        const manifests = new Map();
+        let totalEdges = 0;
         for (const id of projectIds) {
             const manifest = await this.getProjectManifest(id);
-            if (!manifest)
-                continue;
-            nodes.push({ id, name: manifest.name, type: "project" });
-            (manifest.relations || []).forEach(rel => {
-                edges.push({ from: id, to: rel.targetId, type: rel.type });
+            if (manifest) {
+                manifests.set(id, manifest);
+                totalEdges += (manifest.relations || []).length;
+            }
+        }
+        // === FOCUSED MODE: Return detailed subgraph ===
+        if (projectId) {
+            const targetManifest = manifests.get(projectId);
+            if (!targetManifest) {
+                return { mode: "focused", projectId, error: "Project not found", nodes: [], edges: [] };
+            }
+            const nodes = [];
+            const edges = [];
+            // Add target node
+            nodes.push({ id: projectId, name: targetManifest.name });
+            // Outgoing relations
+            const connectedIds = new Set();
+            (targetManifest.relations || []).forEach(rel => {
+                edges.push({ from: projectId, to: rel.targetId, type: rel.type });
+                connectedIds.add(rel.targetId);
             });
+            // Incoming relations
+            for (const [id, manifest] of manifests) {
+                if (id === projectId)
+                    continue;
+                (manifest.relations || []).forEach(rel => {
+                    if (rel.targetId === projectId) {
+                        edges.push({ from: id, to: projectId, type: rel.type });
+                        connectedIds.add(id);
+                    }
+                });
+            }
+            // Add connected nodes
+            for (const id of connectedIds) {
+                const m = manifests.get(id);
+                if (m)
+                    nodes.push({ id, name: m.name });
+            }
+            return { mode: "focused", projectId, nodes, edges };
         }
-        return { nodes, edges };
+        // === LIST MODE: Return lightweight summary ===
+        const projects = Array.from(manifests.entries()).map(([id, m]) => ({
+            id,
+            name: m.name,
+            relationsCount: (m.relations || []).length
+        }));
+        return {
+            mode: "list",
+            summary: {
+                totalProjects: projects.length,
+                totalEdges,
+                hint: "Call with projectId to get detailed subgraph"
+            },
+            projects
+        };
     }
     // --- Discussion & Log Management ---
     /**

package/build/storage/sqlite-meeting.js

@@ -233,21 +233,51 @@ export class SqliteMeetingStore {
         return this.getMeeting(defaultId);
     }
     /**
-     * Get recent messages from a meeting
+     * Get recent messages from a meeting (incremental read based on instance cursor)
+     * Automatically returns only unread messages for the current instance.
      */
-    static getRecentMessages(count = 10, meetingId) {
+    static getRecentMessages(count = 10, meetingId, instanceId) {
         const db = getDatabase();
         const targetId = meetingId || this.getState("default_meeting");
         if (!targetId)
             return [];
+        // If no instanceId provided, fall back to returning all recent messages
+        if (!instanceId) {
+            const stmt = db.prepare(`
+                SELECT id, sender as "from", text, category, timestamp
+                FROM messages WHERE meeting_id = ?
+                ORDER BY id DESC LIMIT ?
+            `);
+            const messages = stmt.all(targetId, count);
+            return messages.reverse();
+        }
+        // Get cursor for this instance + meeting
+        const cursorStmt = db.prepare(`
+            SELECT last_read_id FROM read_cursors 
+            WHERE instance_id = ? AND context_type = 'meeting' AND context_id = ?
+        `);
+        const cursorRow = cursorStmt.get(instanceId, targetId);
+        const lastReadId = cursorRow?.last_read_id || 0;
+        // Fetch unread messages (id > lastReadId)
         const stmt = db.prepare(`
-            SELECT sender as "from", text, category, timestamp
-            FROM messages WHERE meeting_id = ?
-            ORDER BY timestamp DESC LIMIT ?
+            SELECT id, sender as "from", text, category, timestamp
+            FROM messages 
+            WHERE meeting_id = ? AND id > ?
+            ORDER BY id ASC
+            LIMIT ?
         `);
-        const messages = stmt.all(targetId, count);
-        // Reverse to get chronological order
-        return messages.reverse();
+        const messages = stmt.all(targetId, lastReadId, count);
+        // Update cursor if we got messages
+        if (messages.length > 0) {
+            const maxId = messages[messages.length - 1].id;
+            const now = new Date().toISOString();
+            const updateStmt = db.prepare(`
+                INSERT OR REPLACE INTO read_cursors (instance_id, context_type, context_id, last_read_id, updated_at)
+                VALUES (?, 'meeting', ?, ?, ?)
+            `);
+            updateStmt.run(instanceId, targetId, maxId, now);
+        }
+        return messages;
     }
     /**
      * Get meeting state value

package/build/storage/sqlite.js

@@ -50,6 +50,16 @@ CREATE INDEX IF NOT EXISTS idx_messages_meeting ON messages(meeting_id);
 CREATE INDEX IF NOT EXISTS idx_messages_timestamp ON messages(timestamp);
 CREATE INDEX IF NOT EXISTS idx_decisions_meeting ON decisions(meeting_id);
 CREATE INDEX IF NOT EXISTS idx_meetings_status ON meetings(status);
+
+-- Read cursors table (tracks each IDE's last read message per context)
+CREATE TABLE IF NOT EXISTS read_cursors (
+    instance_id TEXT NOT NULL,
+    context_type TEXT NOT NULL CHECK(context_type IN ('meeting', 'global')),
+    context_id TEXT,
+    last_read_id INTEGER DEFAULT 0,
+    updated_at TEXT,
+    PRIMARY KEY (instance_id, context_type, context_id)
+);
 `;
 /**
  * Get the database file path

package/build/storage/store.js

@@ -101,11 +101,18 @@ export const UnifiedMeetingStore = {
         return store.getActiveMeeting();
     },
     /**
-     * Get recent messages
+     * Get recent messages (incremental for SQLite with instanceId)
      */
-    async getRecentMessages(count, meetingId) {
-        const { store } = await getStore();
-        return store.getRecentMessages(count || 10, meetingId);
+    async getRecentMessages(count, meetingId, instanceId) {
+        const { type, store } = await getStore();
+        if (type === "sqlite") {
+            // SQLite supports incremental reads with cursor tracking
+            return store.getRecentMessages(count || 10, meetingId, instanceId);
+        }
+        else {
+            // JSON fallback - no incremental support
+            return store.getRecentMessages(count || 10, meetingId);
+        }
     },
     /**
      * Get the current backend type

package/build/tools/definitions.js

@@ -0,0 +1,295 @@
+/**
+ * Optimized Tool Definitions for Token Economy
+ *
+ * This file provides minimal, human-readable tool definitions that are
+ * directly used by MCP ListTools. We avoid Zod's toJSONSchema() which
+ * generates verbose output with redundant $schema declarations.
+ *
+ * KEY OPTIMIZATIONS:
+ * 1. No $schema on every inputSchema (saves ~50 chars/tool)
+ * 2. Concise descriptions (half the length of originals)
+ * 3. Internal tools (update_task) hidden from public listing
+ * 4. No additionalProperties spam
+ */
+// Hidden tools that should not be exposed to clients
+const HIDDEN_TOOLS = new Set(["update_task"]);
+/**
+ * Minimal tool definitions optimized for token economy.
+ * Each tool has a concise description and a compact inputSchema.
+ */
+const ALL_TOOLS = [
+    // --- Session & Identity ---
+    {
+        name: "register_session_context",
+        description: "Declare active project. Format: [prefix]_[name] (e.g., 'web_example.com', 'mcp_nexus').",
+        inputSchema: {
+            type: "object",
+            properties: {
+                projectId: { type: "string", description: "Project ID with prefix (web_, api_, mcp_, etc.)" }
+            },
+            required: ["projectId"]
+        }
+    },
+    // --- Project Assets ---
+    {
+        name: "sync_project_assets",
+        description: "[ASYNC] Sync full project manifest + internal docs. Returns taskId.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                manifest: {
+                    type: "object",
+                    description: "Project metadata (id, name, description, techStack, relations, endpoints, apiSpec)",
+                    properties: {
+                        id: { type: "string" },
+                        name: { type: "string" },
+                        description: { type: "string" },
+                        techStack: { type: "array", items: { type: "string" } },
+                        relations: { type: "array", items: { type: "object" } },
+                        repositoryUrl: { type: "string" },
+                        localPath: { type: "string" },
+                        endpoints: { type: "array", items: { type: "object" } },
+                        apiSpec: { type: "array", items: { type: "object" } }
+                    },
+                    required: ["id", "name", "description", "techStack", "relations", "repositoryUrl", "localPath", "endpoints", "apiSpec"]
+                },
+                internalDocs: { type: "string", description: "Markdown implementation guide" }
+            },
+            required: ["manifest", "internalDocs"]
+        }
+    },
+    {
+        name: "upload_project_asset",
+        description: "Upload binary file (base64) to active project's asset folder.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                fileName: { type: "string", description: "Safe filename (no path traversal)" },
+                base64Content: { type: "string" }
+            },
+            required: ["fileName", "base64Content"]
+        }
+    },
+    {
+        name: "update_project",
+        description: "Patch project manifest fields (partial update).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                projectId: { type: "string" },
+                patch: { type: "object", description: "Fields to update" }
+            },
+            required: ["projectId", "patch"]
+        }
+    },
+    {
+        name: "rename_project",
+        description: "[ASYNC] Rename project ID with cascading relation updates. Returns taskId.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                oldId: { type: "string" },
+                newId: { type: "string" }
+            },
+            required: ["oldId", "newId"]
+        }
+    },
+    // --- Global Collaboration ---
+    {
+        name: "get_global_topology",
+        description: "Default: project list + stats. With projectId: detailed subgraph.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                projectId: { type: "string", description: "Focus on specific project (optional)" }
+            }
+        }
+    },
+    {
+        name: "send_message",
+        description: "Post message to active meeting or global chat.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                message: { type: "string" },
+                category: { type: "string", enum: ["MEETING_START", "PROPOSAL", "DECISION", "UPDATE", "CHAT"] }
+            },
+            required: ["message"]
+        }
+    },
+    {
+        name: "read_messages",
+        description: "Read unread messages (auto-incremental per IDE instance).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                count: { type: "integer", default: 10 },
+                meetingId: { type: "string" }
+            }
+        }
+    },
+    {
+        name: "update_global_strategy",
+        description: "Overwrite master strategy document.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                content: { type: "string" }
+            },
+            required: ["content"]
+        }
+    },
+    {
+        name: "sync_global_doc",
+        description: "Create/update a global shared document.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                docId: { type: "string" },
+                title: { type: "string" },
+                content: { type: "string" }
+            },
+            required: ["docId", "title", "content"]
+        }
+    },
+    // --- Meeting Management ---
+    {
+        name: "start_meeting",
+        description: "Start new meeting session. Returns meeting ID.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                topic: { type: "string" }
+            },
+            required: ["topic"]
+        }
+    },
+    {
+        name: "end_meeting",
+        description: "[Moderator] End active meeting. Locks history.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                meetingId: { type: "string" },
+                summary: { type: "string" }
+            }
+        }
+    },
+    {
+        name: "archive_meeting",
+        description: "[Moderator] Archive closed meeting. Read-only after.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                meetingId: { type: "string" }
+            },
+            required: ["meetingId"]
+        }
+    },
+    {
+        name: "reopen_meeting",
+        description: "Reopen closed/archived meeting.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                meetingId: { type: "string" }
+            },
+            required: ["meetingId"]
+        }
+    },
+    // --- Task Management (Phase 2) ---
+    {
+        name: "create_task",
+        description: "[ASYNC] Create background task. Returns taskId for polling.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                source_meeting_id: { type: "string", description: "Link to meeting for traceability" },
+                metadata: { type: "object" },
+                ttl: { type: "integer", description: "TTL in milliseconds" }
+            }
+        }
+    },
+    {
+        name: "get_task",
+        description: "Get task status and progress by ID.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                taskId: { type: "string" }
+            },
+            required: ["taskId"]
+        }
+    },
+    {
+        name: "list_tasks",
+        description: "List tasks with optional status filter.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                status: { type: "string", enum: ["pending", "running", "completed", "failed", "cancelled"] },
+                limit: { type: "integer", default: 50 }
+            }
+        }
+    },
+    {
+        name: "update_task",
+        description: "[INTERNAL] Update task state. For workers only.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                taskId: { type: "string" },
+                status: { type: "string", enum: ["pending", "running", "completed", "failed", "cancelled"] },
+                progress: { type: "number", minimum: 0, maximum: 1 },
+                result_uri: { type: "string" },
+                error_message: { type: "string" }
+            },
+            required: ["taskId"]
+        }
+    },
+    {
+        name: "cancel_task",
+        description: "Cancel pending/running task.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                taskId: { type: "string" }
+            },
+            required: ["taskId"]
+        }
+    },
+    // --- Admin (Moderator Only) ---
+    {
+        name: "moderator_maintenance",
+        description: "[Moderator] Manage logs: 'prune' oldest N or 'clear' all.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                action: { type: "string", enum: ["prune", "clear"] },
+                count: { type: "integer", minimum: 0 }
+            },
+            required: ["action", "count"]
+        }
+    },
+    {
+        name: "moderator_delete_project",
+        description: "[ASYNC][Moderator] Delete project. Irreversible. Returns taskId.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                projectId: { type: "string" }
+            },
+            required: ["projectId"]
+        }
+    }
+];
+/**
+ * Public tool definitions (excludes internal tools).
+ * This is what gets returned to MCP ListTools.
+ */
+export const TOOL_DEFINITIONS = ALL_TOOLS.filter(tool => !HIDDEN_TOOLS.has(tool.name));
+/**
+ * Full tool definitions (includes internal tools).
+ * Used internally for handler registration.
+ */
+export const ALL_TOOL_DEFINITIONS = ALL_TOOLS;