n2n-nexus 0.4.2 → 0.6.0

package/build/daemon/tool-outputs.js

@@ -0,0 +1,155 @@
+import { z } from "zod";
+import { MESSAGE_CATEGORIES } from "../types.js";
+import { TASK_STATUSES } from "../storage/tasks.js";
+/**
+ * Result contracts, one per tool. Every result passes through its contract on
+ * the way out of the daemon (`finalizeResult`): undeclared fields are stripped
+ * and a result that cannot satisfy the contract becomes an error instead of
+ * structuredContent the client would reject. TypeScript only catches drift in
+ * object literals, so this runtime pass is the real guarantee. The JSON Schema
+ * is published as the tool's `outputSchema` (with additionalProperties:false,
+ * which the stripping makes true). Every schema has an object root, as
+ * 2025-era clients require.
+ */
+const ack = { ok: z.literal(true), message: z.string() };
+const messageSchema = z.object({
+    id: z.number().int().optional(),
+    from: z.string(),
+    text: z.string(),
+    category: z.enum(MESSAGE_CATEGORIES).nullish(),
+    timestamp: z.string()
+});
+const taskSchema = z.object({
+    id: z.string(),
+    status: z.enum(TASK_STATUSES),
+    progress: z.number(),
+    source_meeting_id: z.string().nullable(),
+    metadata: z.record(z.string(), z.unknown()),
+    result_uri: z.string().nullable(),
+    error_message: z.string().nullable(),
+    created_at: z.string(),
+    updated_at: z.string(),
+    ttl: z.number().nullable()
+});
+const topologyNode = z.object({ id: z.string(), name: z.string(), summary: z.string(), lastActive: z.string() });
+const meetingStatus = z.enum(["active", "closed", "archived"]);
+/**
+ * Manifest as read back from storage. Deliberately looser than the input
+ * contract: manifests written by older releases were not validated, so
+ * ids and enum-like fields are plain strings here.
+ */
+const storedManifest = z.object({
+    id: z.string(),
+    name: z.string(),
+    description: z.string(),
+    techStack: z.array(z.string()),
+    relations: z.array(z.object({ targetId: z.string(), type: z.string() })),
+    lastUpdated: z.string(),
+    repositoryUrl: z.string(),
+    localPath: z.string(),
+    endpoints: z.array(z.object({ name: z.string(), url: z.string(), description: z.string() })),
+    apiSpec: z.array(z.object({ method: z.string(), path: z.string(), summary: z.string() })),
+    billing: z.object({ plain: z.string(), price: z.string() }).optional(),
+    apiDependencies: z.record(z.string(), z.string()).optional(),
+    gatewayCompatibility: z.string().optional(),
+    api_versions: z.record(z.string(), z.string()).optional(),
+    feature_tier: z.string().optional()
+});
+export const TOOL_OUTPUT_SCHEMAS = {
+    sync_project_assets: z.object({ ...ack, projectId: z.string() }),
+    upload_project_asset: z.object({ ...ack, projectId: z.string(), fileName: z.string() }),
+    update_project: z.object({ ...ack, projectId: z.string() }),
+    rename_project: z.object({ ...ack, oldId: z.string(), newId: z.string() }),
+    search_projects: z.object({
+        query: z.string(),
+        count: z.number().int(),
+        results: z.array(z.object({ id: z.string(), name: z.string(), description: z.string().optional() }))
+    }),
+    get_global_topology: z.object({
+        mode: z.enum(["list", "focused"]),
+        summary: z.object({ totalProjects: z.number().int(), totalEdges: z.number().int() }).optional()
+            .describe("list mode only"),
+        projects: z.record(z.string(), topologyNode).optional().describe("list mode only"),
+        nodes: z.array(topologyNode).optional().describe("focused mode only"),
+        edges: z.array(z.object({
+            from: z.string(), to: z.string(),
+            type: z.string()
+        })).optional().describe("focused mode only")
+    }),
+    get_project: z.object({
+        manifest: storedManifest,
+        internalDocs: z.string().optional()
+    }),
+    send_message: z.object({
+        ...ack,
+        sentTo: z.enum(["meeting", "global"]),
+        meetingId: z.string().optional(),
+        messageId: z.number().int().optional()
+    }),
+    read_messages: z.object({
+        source: z.enum(["meeting", "global"]),
+        meetingId: z.string().optional(),
+        messages: z.array(messageSchema),
+        count: z.number().int()
+    }),
+    list_events: z.object({
+        count: z.number().int(),
+        events: z.array(z.object({
+            id: z.number().int(),
+            timestamp: z.string(),
+            actor: z.string(),
+            action: z.string(),
+            target: z.string().optional(),
+            detail: z.record(z.string(), z.unknown()).optional()
+        }))
+    }),
+    get_global_strategy: z.object({ content: z.string() }),
+    update_global_strategy: z.object(ack),
+    list_global_docs: z.object({
+        count: z.number().int(),
+        docs: z.array(z.object({ docId: z.string(), title: z.string(), lastUpdated: z.string(), updatedBy: z.string() }))
+    }),
+    get_global_doc: z.object({
+        docId: z.string(), title: z.string(), lastUpdated: z.string(), updatedBy: z.string(), content: z.string()
+    }),
+    sync_global_doc: z.object(ack),
+    list_meetings: z.object({
+        count: z.number().int(),
+        activeMeetingId: z.string().nullable(),
+        meetings: z.array(z.object({
+            id: z.string(),
+            topic: z.string(),
+            status: meetingStatus,
+            initiator: z.string(),
+            startTime: z.string(),
+            endTime: z.string().optional(),
+            participants: z.array(z.string()),
+            messageCount: z.number().int(),
+            decisionCount: z.number().int(),
+            summary: z.string().optional()
+        }))
+    }),
+    start_meeting: z.object({ ok: z.literal(true), meetingId: z.string(), topic: z.string(), status: meetingStatus }),
+    end_meeting: z.object({ ok: z.literal(true), meetingId: z.string(), status: z.literal("closed"), summary: z.string().optional() }),
+    archive_meeting: z.object({ ok: z.literal(true), meetingId: z.string(), status: z.literal("archived") }),
+    reopen_meeting: z.object({ ok: z.literal(true), meetingId: z.string(), status: z.literal("active") }),
+    create_task: z.object({ task_id: z.string(), status: z.enum(TASK_STATUSES), message: z.string(), task: taskSchema }),
+    get_task: taskSchema,
+    list_tasks: z.object({ count: z.number().int(), tasks: z.array(taskSchema) }),
+    cancel_task: z.object({ ...ack, taskId: z.string() }),
+    host_maintenance: z.object({ ...ack, removed: z.number().int(), remaining: z.number().int() }),
+    host_delete_project: z.object({ ...ack, projectId: z.string() })
+};
+export class ResultContractError extends Error {
+    constructor(tool, issues) {
+        super(`Result of ${tool} does not match its contract:\n${issues}`);
+        this.name = "ResultContractError";
+    }
+}
+/** Validate a handler result against its contract and strip undeclared fields. */
+export function finalizeResult(name, result) {
+    const parsed = TOOL_OUTPUT_SCHEMAS[name].safeParse(result);
+    if (!parsed.success)
+        throw new ResultContractError(name, z.prettifyError(parsed.error));
+    return parsed.data;
+}

package/build/daemon/tools.js

@@ -0,0 +1,271 @@
+import { z } from "zod";
+import { MESSAGE_CATEGORIES } from "../types.js";
+import { TASK_STATUSES } from "../storage/tasks.js";
+import { TOOL_OUTPUT_SCHEMAS } from "./tool-outputs.js";
+/**
+ * Tool contracts. Each zod schema is the single source of truth: it is
+ * exported to MCP clients as JSON Schema (GET /api/tools) and used to
+ * validate every call before a handler runs, for both the MCP tool path
+ * and the REST endpoints.
+ */
+const SAFE_ID = /^[a-zA-Z0-9._-]+$/;
+const safeId = (label) => z.string().min(1).regex(SAFE_ID, `${label} may contain only letters, numbers, dots, underscores and hyphens`);
+export const projectIdSchema = safeId("Project ID").describe("Project ID with prefix, e.g. 'web_example.com' or 'mcp_nexus'");
+const docIdSchema = safeId("Document ID").describe("Stable document ID");
+const positiveInt = (max) => z.number().int().min(1).max(max);
+export const manifestSchema = z.object({
+    id: projectIdSchema,
+    name: z.string().min(1),
+    description: z.string(),
+    techStack: z.array(z.string()),
+    relations: z.array(z.object({
+        targetId: projectIdSchema,
+        type: z.enum(["dependency", "parent", "child", "related"])
+    })),
+    repositoryUrl: z.string(),
+    localPath: z.string().describe("Physical disk path of the project"),
+    endpoints: z.array(z.object({ name: z.string(), url: z.string(), description: z.string() })),
+    apiSpec: z.array(z.object({ method: z.string(), path: z.string(), summary: z.string() })),
+    billing: z.object({ plain: z.string(), price: z.string() }).optional(),
+    lastUpdated: z.string().optional(),
+    apiDependencies: z.record(z.string(), z.string()).optional().describe("projectId → version constraint"),
+    gatewayCompatibility: z.string().optional(),
+    api_versions: z.record(z.string(), z.string()).optional(),
+    feature_tier: z.enum(["standard", "advanced", "team"]).optional()
+}).describe("Project manifest");
+export const manifestPatchSchema = manifestSchema.omit({ id: true, lastUpdated: true }).partial().strict()
+    .describe("Manifest fields to update. 'id' cannot be changed here; use rename_project.");
+/** Tools without parameters: the spec recommends a schema that accepts only `{}`. */
+const noParams = z.strictObject({});
+export const TOOL_SCHEMAS = {
+    // Projects
+    sync_project_assets: z.object({
+        manifest: manifestSchema,
+        internalDocs: z.string().describe("Markdown implementation guide")
+    }),
+    upload_project_asset: z.object({
+        projectId: projectIdSchema,
+        fileName: z.string().min(1).describe("Filename only; unsafe characters are replaced"),
+        base64Content: z.string().min(1)
+    }),
+    update_project: z.object({ projectId: projectIdSchema, patch: manifestPatchSchema }),
+    rename_project: z.object({ oldId: projectIdSchema, newId: projectIdSchema }),
+    search_projects: z.object({
+        query: z.string().min(1),
+        limit: positiveInt(200).default(10)
+    }),
+    get_global_topology: z.object({
+        projectId: projectIdSchema.optional().describe("Focus on one project (optional)")
+    }),
+    get_project: z.object({
+        projectId: projectIdSchema,
+        includeDocs: z.boolean().default(true).describe("Also return the internal docs (Markdown)")
+    }),
+    // Messaging
+    send_message: z.object({
+        message: z.string().min(1),
+        category: z.enum(MESSAGE_CATEGORIES).optional(),
+        meetingId: z.string().min(1).optional().describe("Target meeting. Defaults to the active meeting, or global chat when none is active.")
+    }),
+    read_messages: z.object({
+        count: positiveInt(500).default(10),
+        meetingId: z.string().min(1).optional()
+    }),
+    list_events: z.object({
+        limit: positiveInt(500).default(20),
+        action: z.string().min(1).optional().describe("Exact action or prefix such as 'project' or 'meeting'")
+    }),
+    get_global_strategy: noParams,
+    update_global_strategy: z.object({ content: z.string().min(1) }),
+    list_global_docs: noParams,
+    get_global_doc: z.object({ docId: docIdSchema }),
+    sync_global_doc: z.object({
+        docId: docIdSchema,
+        title: z.string().min(1),
+        content: z.string().min(1)
+    }),
+    // Meetings
+    list_meetings: z.object({
+        status: z.enum(["active", "closed", "archived"]).optional(),
+        limit: positiveInt(200).default(20)
+    }),
+    start_meeting: z.object({ topic: z.string().min(1) }),
+    end_meeting: z.object({
+        meetingId: z.string().min(1).optional().describe("Defaults to the active meeting"),
+        summary: z.string().optional()
+    }),
+    archive_meeting: z.object({ meetingId: z.string().min(1) }),
+    reopen_meeting: z.object({ meetingId: z.string().min(1) }),
+    // Tasks
+    create_task: z.object({
+        source_meeting_id: z.string().min(1).optional().describe("Link to a meeting for traceability"),
+        metadata: z.record(z.string(), z.unknown()).optional(),
+        ttl: positiveInt(Number.MAX_SAFE_INTEGER).optional().describe("TTL in milliseconds; a pending/running task past its TTL is marked failed")
+    }),
+    get_task: z.object({ taskId: z.string().min(1) }),
+    list_tasks: z.object({
+        status: z.enum(TASK_STATUSES).optional(),
+        limit: positiveInt(500).default(50)
+    }),
+    cancel_task: z.object({ taskId: z.string().min(1) }),
+    // Maintenance
+    host_maintenance: z.object({
+        action: z.enum(["prune", "clear"]),
+        count: z.number().int().min(0).default(0).describe("Oldest N global messages to remove (prune only)")
+    }),
+    host_delete_project: z.object({ projectId: projectIdSchema })
+};
+const TOOL_DESCRIPTIONS = {
+    sync_project_assets: "Sync full project manifest + internal docs.",
+    upload_project_asset: "Upload a binary file (base64) to a project's asset folder.",
+    update_project: "Patch project manifest fields (partial update).",
+    rename_project: "Rename project ID with cascading relation updates.",
+    search_projects: "Search project registry by name or description.",
+    get_global_topology: "Default: project list + stats. With projectId: detailed subgraph.",
+    get_project: "Read a project's full manifest and, by default, its internal docs.",
+    send_message: "Post a message. Goes to meetingId if given, else to the active meeting, else to global chat.",
+    read_messages: "Read messages this instance has not read yet (cursor advances automatically). Global chat by default; pass meetingId for a meeting.",
+    list_events: "Activity log: structured records of state changes (project.sync, project.rename, meeting.end, ...), newest first.",
+    get_global_strategy: "Read the master strategy document (global/blueprint.md).",
+    update_global_strategy: "Overwrite the master strategy document (global/blueprint.md).",
+    list_global_docs: "List global shared documents: id, title, last update and author.",
+    get_global_doc: "Read a global shared document by docId, with its title and metadata.",
+    sync_global_doc: "Create/update a global shared document.",
+    list_meetings: "List meetings, newest first: id, topic, status, initiator, participants, message/decision counts, summary. Read messages with read_messages(meetingId).",
+    start_meeting: "Start new meeting session. Returns meeting ID.",
+    end_meeting: "End active meeting. Locks history.",
+    archive_meeting: "Archive closed meeting. Read-only after.",
+    reopen_meeting: "Reopen closed/archived meeting.",
+    create_task: "Create a task you track yourself. Returns taskId; update it via get_task/cancel_task.",
+    get_task: "Get task status and progress by ID.",
+    list_tasks: "List tasks with optional status filter.",
+    cancel_task: "Cancel pending/running task.",
+    host_maintenance: "Manage the global chat stream: 'prune' the oldest N messages or 'clear' all.",
+    host_delete_project: "Delete project. Irreversible."
+};
+/** Human-readable names clients show in their UI (MCP `title`). */
+const TOOL_TITLES = {
+    sync_project_assets: "Sync Project",
+    upload_project_asset: "Upload Project Asset",
+    update_project: "Update Project",
+    rename_project: "Rename Project",
+    search_projects: "Search Projects",
+    get_global_topology: "Project Topology",
+    get_project: "Read Project",
+    send_message: "Send Message",
+    read_messages: "Read Messages",
+    list_events: "Activity Log",
+    get_global_strategy: "Read Strategy",
+    update_global_strategy: "Update Strategy",
+    list_global_docs: "List Shared Docs",
+    get_global_doc: "Read Shared Doc",
+    sync_global_doc: "Save Shared Doc",
+    list_meetings: "List Meetings",
+    start_meeting: "Start Meeting",
+    end_meeting: "End Meeting",
+    archive_meeting: "Archive Meeting",
+    reopen_meeting: "Reopen Meeting",
+    create_task: "Create Task",
+    get_task: "Read Task",
+    list_tasks: "List Tasks",
+    cancel_task: "Cancel Task",
+    host_maintenance: "Prune Global Chat",
+    host_delete_project: "Delete Project"
+};
+const readOnly = { readOnlyHint: true, openWorldHint: false };
+/**
+ * Changes state. `destructive` follows the MCP definition: false only when the
+ * tool makes purely additive updates; anything that rewrites or removes
+ * existing state (status changes included) is destructive. `idempotent` =
+ * repeating the same call has no further effect.
+ */
+const write = (destructive, idempotent) => ({ readOnlyHint: false, destructiveHint: destructive, idempotentHint: idempotent, openWorldHint: false });
+const TOOL_ANNOTATIONS = {
+    sync_project_assets: write(true, true), // replaces manifest and docs
+    upload_project_asset: write(true, true), // overwrites a same-named asset
+    update_project: write(true, true), // replaces the patched fields
+    rename_project: write(true, false), // removes the old id, rewrites relations
+    search_projects: readOnly,
+    get_global_topology: readOnly,
+    get_project: readOnly,
+    send_message: write(false, false),
+    read_messages: write(false, false), // only advances this instance's own unread cursor (bookkeeping, not shared data)
+    list_events: readOnly,
+    get_global_strategy: readOnly,
+    update_global_strategy: write(true, true), // overwrites the document
+    list_global_docs: readOnly,
+    get_global_doc: readOnly,
+    sync_global_doc: write(true, true), // overwrites the document
+    list_meetings: readOnly,
+    start_meeting: write(false, false),
+    end_meeting: write(true, false), // closes the meeting, sets summary
+    archive_meeting: write(true, false), // changes status
+    reopen_meeting: write(true, false), // changes status
+    create_task: write(false, false),
+    get_task: readOnly,
+    list_tasks: readOnly,
+    cancel_task: write(true, true), // irreversible status change
+    host_maintenance: write(true, false), // deletes chat messages
+    host_delete_project: write(true, true) // irreversible
+};
+function toOutputSchema(schema) {
+    const json = z.toJSONSchema(schema, { io: "output" });
+    delete json.$schema;
+    return json;
+}
+function toInputSchema(schema) {
+    const json = z.toJSONSchema(schema, { io: "input" });
+    delete json.$schema;
+    return json;
+}
+// Compile-time check: every tool has a result contract and no contract lacks a tool.
+const _outputsCover = TOOL_OUTPUT_SCHEMAS;
+const _outputsMatch = TOOL_SCHEMAS;
+void _outputsCover;
+void _outputsMatch;
+export const TOOL_NAMES = Object.keys(TOOL_SCHEMAS);
+/**
+ * Tools whose outputSchema is published in tools/list. Every tool has a result
+ * contract (and every result is sent as structuredContent), but the schemas of
+ * write tools only describe a short acknowledgement and nearly doubled the
+ * tools/list payload that sits in every model context, so only tools that
+ * return data publish theirs.
+ */
+const PUBLISHED_OUTPUT_SCHEMAS = new Set([
+    "search_projects", "get_global_topology", "get_project",
+    "read_messages", "list_events",
+    "get_global_strategy", "list_global_docs", "get_global_doc",
+    "list_meetings", "get_task", "list_tasks"
+]);
+export const TOOL_DEFINITIONS = TOOL_NAMES.map((name) => ({
+    name,
+    title: TOOL_TITLES[name],
+    description: TOOL_DESCRIPTIONS[name],
+    ...(PUBLISHED_OUTPUT_SCHEMAS.has(name) ? { outputSchema: toOutputSchema(TOOL_OUTPUT_SCHEMAS[name]) } : {}),
+    inputSchema: toInputSchema(TOOL_SCHEMAS[name]),
+    annotations: TOOL_ANNOTATIONS[name]
+}));
+export function isToolName(name) {
+    return Object.prototype.hasOwnProperty.call(TOOL_SCHEMAS, name);
+}
+export class ToolValidationError extends Error {
+    constructor(tool, issues) {
+        super(`Invalid arguments for ${tool}:\n${issues}`);
+        this.name = "ToolValidationError";
+    }
+}
+/** Validate raw arguments against a tool's schema; unknown top-level keys are dropped. */
+export function parseToolArgs(name, args) {
+    const result = TOOL_SCHEMAS[name].safeParse(args ?? {});
+    if (!result.success)
+        throw new ToolValidationError(name, z.prettifyError(result.error));
+    return result.data;
+}
+/** Schema for POST /api/tasks/:id/update (not an MCP tool). */
+export const taskUpdateSchema = z.object({
+    status: z.enum(TASK_STATUSES).optional(),
+    progress: z.number().min(0).max(1).optional(),
+    result_uri: z.string().optional(),
+    error_message: z.string().optional(),
+    metadata: z.record(z.string(), z.unknown()).optional()
+}).strict();

package/build/index.js

@@ -17,7 +17,7 @@ OPTIONS:
   --root <path>      Storage directory for daemon (default: ~/.n2n-nexus)
   --port <port>      HTTP port for daemon (default: 5688)
   --host <host>      Host address for daemon (default: 127.0.0.1)
-  --id <id>          Instance ID for MCP proxy
+  --id <id>          Instance ID for MCP proxy (default: mcp-<hostname>-<cwd hash>-<IDE name>)
   --version, -v      Show version
   --help, -h         Show this help
 

package/build/server/instance-id.js

@@ -0,0 +1,19 @@
+import { createHash } from "node:crypto";
+import os from "node:os";
+/**
+ * Identity of this MCP adapter as seen by the daemon. Read cursors and
+ * meeting initiator permissions are keyed on it, so it has to
+ * survive an IDE restart: derive it from the machine, the workspace the IDE
+ * launched the adapter in and the IDE itself (two IDEs open on the same
+ * workspace must not share cursors), unless the user pins one explicitly.
+ */
+export function resolveInstanceId(env = process.env, argv = process.argv, cwd = process.cwd(), clientName) {
+    if (env.NEXUS_INSTANCE_ID)
+        return env.NEXUS_INSTANCE_ID;
+    const idx = argv.indexOf("--id");
+    if (idx !== -1 && argv[idx + 1])
+        return argv[idx + 1];
+    const digest = createHash("sha1").update(cwd).digest("hex").slice(0, 8);
+    const client = clientName ? `-${clientName.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 24)}` : "";
+    return `mcp-${os.hostname()}-${digest}${client}`;
+}