@mpowr/nexus-mcp 0.5.0

package/src/tools/add-task-note.ts

@@ -0,0 +1,50 @@
+/**
+ * task_note -- Layer 2 Coordination
+ *
+ * Appends a note to an existing task. Notes are append-only and
+ * maintain a chronological history/timeline.
+ * Delegates to POST /api/mcp/tasks (action: task_note).
+ */
+
+import { z } from 'zod'
+import { nexusPost } from '../nexus-api.js'
+
+export const addTaskNoteSchema = {
+  task_id: z.string().uuid().describe('Task UUID to add a note to'),
+  note: z.string().describe('Note content to append'),
+  agent_id: z.string().optional().describe('Agent identifier if applicable'),
+}
+
+type AddTaskNoteArgs = {
+  task_id: string
+  note: string
+  user_id: string
+  agent_id?: string
+}
+
+export async function addTaskNote(args: AddTaskNoteArgs) {
+  const result = await nexusPost('/api/mcp/tasks', {
+    action: 'task_note',
+    task_id: args.task_id,
+    note: args.note,
+    agent_id: args.agent_id,
+  })
+
+  if (!result.ok) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ error: result.error }, null, 2),
+        },
+      ],
+      isError: true,
+    }
+  }
+
+  return {
+    content: [
+      { type: 'text' as const, text: JSON.stringify(result.data, null, 2) },
+    ],
+  }
+}

package/src/tools/append-session-entry.ts

@@ -0,0 +1,83 @@
+/**
+ * session_append -- Layer 2 Coordination
+ *
+ * Appends an entry to an existing session.
+ * Enforces append-only semantics and session write isolation.
+ * Delegates to POST /api/mcp/sessions (action: session_append).
+ */
+
+import { z } from 'zod'
+import { nexusPost } from '../nexus-api.js'
+
+export const appendSessionEntrySchema = {
+  session_id: z.string().uuid().describe('Session UUID to append to'),
+  entry_type: z
+    .enum([
+      'decision_referenced',
+      'task_created',
+      'task_updated',
+      'letter_sent',
+      'letter_replied',
+      'research_added',
+      'conflict_detected',
+      'adr_drafted',
+      'adr_accepted',
+      'handoff_recorded',
+      'note',
+      'correction',
+    ])
+    .describe('Type of session entry'),
+  summary: z.string().describe('Entry content / summary text'),
+  linked_entity_type: z
+    .string()
+    .optional()
+    .describe(
+      'Type of linked entity (e.g., "task", "decision", "letter", "research_link")',
+    ),
+  linked_entity_id: z
+    .string()
+    .uuid()
+    .optional()
+    .describe('UUID of the linked entity'),
+  agent_id: z.string().optional().describe('Agent identifier if applicable'),
+}
+
+type AppendSessionEntryArgs = {
+  session_id: string
+  entry_type: string
+  summary: string
+  linked_entity_type?: string
+  linked_entity_id?: string
+  user_id: string
+  agent_id?: string
+}
+
+export async function appendSessionEntry(args: AppendSessionEntryArgs) {
+  const result = await nexusPost('/api/mcp/sessions', {
+    action: 'session_append',
+    session_id: args.session_id,
+    entry_type: args.entry_type,
+    summary: args.summary,
+    agent_id: args.agent_id,
+    linked_entity_type: args.linked_entity_type,
+    linked_entity_id: args.linked_entity_id,
+  })
+
+  if (!result.ok) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ error: result.error }, null, 2),
+        },
+      ],
+      isError: true,
+    }
+  }
+
+  return {
+    content: [
+      { type: 'text' as const, text: JSON.stringify(result.data, null, 2) },
+    ],
+  }
+}

package/src/tools/create-task.ts

@@ -0,0 +1,66 @@
+/**
+ * task_create -- Layer 2 Coordination
+ *
+ * Creates a new task within a project scope.
+ * Delegates to POST /api/mcp/tasks (action: task_create).
+ */
+
+import { z } from 'zod'
+import { nexusPost } from '../nexus-api.js'
+
+export const createTaskSchema = {
+  project_id: z.string().uuid().describe('Project UUID'),
+  title: z.string().describe('Task title'),
+  description: z.string().optional().describe('Task description'),
+  priority: z
+    .enum(['low', 'normal', 'high', 'urgent'])
+    .default('normal')
+    .describe('Task priority'),
+  assignee: z.string().uuid().optional().describe('UUID of the assigned user'),
+  status: z
+    .enum(['open', 'in_progress', 'blocked', 'done', 'cancelled'])
+    .default('open')
+    .describe('Initial task status'),
+  agent_id: z.string().optional().describe('Agent identifier if applicable'),
+}
+
+type CreateTaskArgs = {
+  project_id: string
+  title: string
+  description?: string
+  priority?: string
+  assignee?: string
+  status?: string
+  user_id: string
+  agent_id?: string
+}
+
+export async function createTask(args: CreateTaskArgs) {
+  const result = await nexusPost('/api/mcp/tasks', {
+    action: 'task_create',
+    project_id: args.project_id,
+    title: args.title,
+    description: args.description,
+    priority: args.priority ?? 'normal',
+    assignee: args.assignee,
+    status: args.status ?? 'open',
+  })
+
+  if (!result.ok) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ error: result.error }, null, 2),
+        },
+      ],
+      isError: true,
+    }
+  }
+
+  return {
+    content: [
+      { type: 'text' as const, text: JSON.stringify(result.data, null, 2) },
+    ],
+  }
+}

package/src/tools/decision-comments.ts

@@ -0,0 +1,102 @@
+/**
+ * Decision comment tools -- Layer 2 Coordination
+ *
+ * Provides append-only comment threads for ADR decisions.
+ * Delegates to POST /api/mcp/governance (actions: dc_add, dc_list).
+ */
+
+import { z } from 'zod'
+import { nexusPost } from '../nexus-api.js'
+
+// ---------------------------------------------------------------------------
+// add_decision_comment -> dc_add
+// ---------------------------------------------------------------------------
+
+export const addDecisionCommentSchema = {
+  decision_id: z.string().uuid().describe('Decision UUID to comment on'),
+  body: z.string().describe('Comment body (markdown supported)'),
+  agent_id: z
+    .string()
+    .optional()
+    .describe('Agent identifier if comment is posted by an agent'),
+}
+
+type AddDecisionCommentArgs = {
+  decision_id: string
+  body: string
+  agent_id?: string
+  user_id: string
+}
+
+export async function addDecisionComment(args: AddDecisionCommentArgs) {
+  const result = await nexusPost('/api/mcp/governance', {
+    action: 'dc_add',
+    decision_id: args.decision_id,
+    body: args.body,
+    agent_id: args.agent_id,
+  })
+
+  if (!result.ok) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ error: result.error }, null, 2),
+        },
+      ],
+      isError: true,
+    }
+  }
+
+  return {
+    content: [
+      { type: 'text' as const, text: JSON.stringify(result.data, null, 2) },
+    ],
+  }
+}
+
+// ---------------------------------------------------------------------------
+// list_decision_comments -> dc_list
+// ---------------------------------------------------------------------------
+
+export const listDecisionCommentsSchema = {
+  decision_id: z.string().uuid().describe('Decision UUID'),
+  limit: z
+    .number()
+    .int()
+    .min(1)
+    .max(100)
+    .default(50)
+    .describe('Maximum comments to return'),
+}
+
+type ListDecisionCommentsArgs = {
+  decision_id: string
+  limit?: number
+}
+
+export async function listDecisionComments(args: ListDecisionCommentsArgs) {
+  const result = await nexusPost('/api/mcp/governance', {
+    action: 'dc_list',
+    decision_id: args.decision_id,
+    limit: args.limit ?? 50,
+  })
+
+  if (!result.ok) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ error: result.error }, null, 2),
+        },
+      ],
+      isError: true,
+    }
+  }
+
+  return {
+    content: [
+      { type: 'text' as const, text: JSON.stringify(result.data, null, 2) },
+    ],
+  }
+}

package/src/tools/get-document.ts

@@ -0,0 +1,80 @@
+/**
+ * kb_get -- Layer 1 Knowledge Access
+ *
+ * Fetches a single knowledge object in canonical form.
+ * Returns metadata, current version, body, and linked references.
+ * Delegates to POST /api/mcp/documents (action: kb_get).
+ *
+ * ADR-0001 spec: kb_get(entity_type, entity_id, render_mode)
+ */
+
+import { z } from 'zod'
+import { nexusPost } from '../nexus-api.js'
+
+export const getDocumentSchema = {
+  entity_type: z
+    .enum([
+      'session',
+      'decision',
+      'letter',
+      'task',
+      'research_note',
+      'planning_item',
+      'ingest_item',
+    ])
+    .describe('Type of the knowledge object'),
+  entity_id: z.string().uuid().describe('UUID of the entity'),
+  render_mode: z
+    .enum(['structured', 'markdown', 'summary'])
+    .default('structured')
+    .describe('Output format: structured JSON, markdown, or summary'),
+}
+
+type GetDocumentArgs = {
+  entity_type: string
+  entity_id: string
+  render_mode?: string
+}
+
+export async function getDocument(args: GetDocumentArgs) {
+  const result = await nexusPost('/api/mcp/documents', {
+    action: 'kb_get',
+    entity_type: args.entity_type,
+    entity_id: args.entity_id,
+    render_mode: args.render_mode ?? 'structured',
+  })
+
+  if (!result.ok) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ error: result.error }, null, 2),
+        },
+      ],
+      isError: true,
+    }
+  }
+
+  // For markdown and summary modes, the API returns { content: "..." }
+  // For structured mode, the API returns the full object
+  const data = result.data as Record<string, unknown>
+  const renderMode = args.render_mode ?? 'structured'
+
+  if (renderMode === 'markdown' || renderMode === 'summary') {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: (data.content as string) ?? JSON.stringify(data, null, 2),
+        },
+      ],
+    }
+  }
+
+  return {
+    content: [
+      { type: 'text' as const, text: JSON.stringify(data, null, 2) },
+    ],
+  }
+}

package/src/tools/get-project-memory.ts

@@ -0,0 +1,65 @@
+/**
+ * kb_memory -- Layer 1 Knowledge Access
+ *
+ * Returns curated project context for agent bootstrapping.
+ * Includes ADRs, active tasks, recent sessions, open letters, etc.
+ * Delegates to POST /api/mcp/memory.
+ *
+ * ADR-0001 spec: kb_memory(project_id, include[], depth)
+ */
+
+import { z } from 'zod'
+import { nexusPost } from '../nexus-api.js'
+
+export const getProjectMemorySchema = {
+  project_id: z.string().uuid().describe('Project UUID'),
+  include: z
+    .array(
+      z.enum([
+        'adrs',
+        'rules',
+        'active_tasks',
+        'recent_sessions',
+        'open_letters',
+        'planning',
+        'research',
+      ]),
+    )
+    .describe('Categories of knowledge to include'),
+  depth: z
+    .enum(['light', 'standard', 'deep'])
+    .default('standard')
+    .describe('Detail level: light (summaries), standard, deep (full bodies)'),
+}
+
+type GetProjectMemoryArgs = {
+  project_id: string
+  include: string[]
+  depth?: string
+}
+
+export async function getProjectMemory(args: GetProjectMemoryArgs) {
+  const result = await nexusPost('/api/mcp/memory', {
+    project_id: args.project_id,
+    include: args.include,
+    depth: args.depth ?? 'standard',
+  })
+
+  if (!result.ok) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ error: result.error }, null, 2),
+        },
+      ],
+      isError: true,
+    }
+  }
+
+  return {
+    content: [
+      { type: 'text' as const, text: JSON.stringify(result.data, null, 2) },
+    ],
+  }
+}

package/src/tools/get-related-entities.ts

@@ -0,0 +1,73 @@
+/**
+ * kb_related -- Layer 1 Knowledge Access
+ *
+ * Returns graph-neighbor entities related to a given entity.
+ * Delegates to POST /api/mcp/related.
+ *
+ * ADR-0001 spec: kb_related(entity_type, entity_id, relation_types[], limit)
+ */
+
+import { z } from 'zod'
+import { nexusPost } from '../nexus-api.js'
+
+export const getRelatedEntitiesSchema = {
+  entity_type: z
+    .enum([
+      'session',
+      'decision',
+      'letter',
+      'task',
+      'research_note',
+      'planning_item',
+      'ingest_item',
+    ])
+    .describe('Type of the source entity'),
+  entity_id: z.string().uuid().describe('UUID of the source entity'),
+  relation_types: z
+    .array(z.string())
+    .optional()
+    .describe(
+      'Filter by specific relation types (e.g., "references", "created_in", "supersedes")',
+    ),
+  limit: z
+    .number()
+    .int()
+    .min(1)
+    .max(50)
+    .default(20)
+    .describe('Maximum related entities to return'),
+}
+
+type GetRelatedEntitiesArgs = {
+  entity_type: string
+  entity_id: string
+  relation_types?: string[]
+  limit?: number
+}
+
+export async function getRelatedEntities(args: GetRelatedEntitiesArgs) {
+  const result = await nexusPost('/api/mcp/related', {
+    entity_type: args.entity_type,
+    entity_id: args.entity_id,
+    relation_types: args.relation_types,
+    limit: args.limit ?? 20,
+  })
+
+  if (!result.ok) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ error: result.error }, null, 2),
+        },
+      ],
+      isError: true,
+    }
+  }
+
+  return {
+    content: [
+      { type: 'text' as const, text: JSON.stringify(result.data, null, 2) },
+    ],
+  }
+}

package/src/tools/governance.ts

@@ -0,0 +1,162 @@
+/**
+ * ADR Governance tools -- Layer 3
+ *
+ * Manages the ADR lifecycle:
+ *   draft -> under_review -> accepted | rejected -> superseded -> archived
+ *
+ * Delegates to POST /api/mcp/governance.
+ */
+
+import { z } from 'zod'
+import { nexusPost } from '../nexus-api.js'
+
+// ---------------------------------------------------------------------------
+// create_adr_draft -> adr_create
+// ---------------------------------------------------------------------------
+
+export const createAdrDraftSchema = {
+  project_id: z.string().uuid().describe('Project UUID'),
+  title: z.string().describe('ADR title'),
+  context: z
+    .string()
+    .describe('Context / motivation for the decision (markdown)'),
+  decision: z.string().describe('The decision content (markdown)'),
+  consequences: z
+    .string()
+    .optional()
+    .describe('Expected consequences of the decision (markdown)'),
+  supersedes: z
+    .string()
+    .uuid()
+    .optional()
+    .describe('UUID of the ADR this one supersedes'),
+  agent_id: z.string().optional().describe('Agent identifier if applicable'),
+}
+
+type CreateAdrDraftArgs = {
+  project_id: string
+  title: string
+  context: string
+  decision: string
+  consequences?: string
+  supersedes?: string
+  user_id: string
+  agent_id?: string
+}
+
+export async function createAdrDraft(args: CreateAdrDraftArgs) {
+  const result = await nexusPost('/api/mcp/governance', {
+    action: 'adr_create',
+    project_id: args.project_id,
+    title: args.title,
+    context: args.context,
+    decision: args.decision,
+    consequences: args.consequences,
+    supersedes: args.supersedes,
+  })
+
+  if (!result.ok) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ error: result.error }, null, 2),
+        },
+      ],
+      isError: true,
+    }
+  }
+
+  return {
+    content: [
+      { type: 'text' as const, text: JSON.stringify(result.data, null, 2) },
+    ],
+  }
+}
+
+// ---------------------------------------------------------------------------
+// submit_adr_review -> adr_submit
+// ---------------------------------------------------------------------------
+
+export const submitAdrReviewSchema = {
+  adr_id: z.string().uuid().describe('ADR UUID to submit for review'),
+}
+
+type SubmitAdrReviewArgs = {
+  adr_id: string
+  user_id: string
+}
+
+export async function submitAdrReview(args: SubmitAdrReviewArgs) {
+  const result = await nexusPost('/api/mcp/governance', {
+    action: 'adr_submit',
+    adr_id: args.adr_id,
+  })
+
+  if (!result.ok) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ error: result.error }, null, 2),
+        },
+      ],
+      isError: true,
+    }
+  }
+
+  return {
+    content: [
+      { type: 'text' as const, text: JSON.stringify(result.data, null, 2) },
+    ],
+  }
+}
+
+// ---------------------------------------------------------------------------
+// record_adr_decision -> adr_decide
+// ---------------------------------------------------------------------------
+
+export const recordAdrDecisionSchema = {
+  adr_id: z.string().uuid().describe('ADR UUID'),
+  decision: z
+    .enum(['accepted', 'rejected'])
+    .describe('Decision outcome: accept or reject'),
+  rationale: z
+    .string()
+    .optional()
+    .describe('Optional rationale for the decision'),
+}
+
+type RecordAdrDecisionArgs = {
+  adr_id: string
+  decision: string
+  rationale?: string
+  user_id: string
+}
+
+export async function recordAdrDecision(args: RecordAdrDecisionArgs) {
+  const result = await nexusPost('/api/mcp/governance', {
+    action: 'adr_decide',
+    adr_id: args.adr_id,
+    decision: args.decision,
+    rationale: args.rationale,
+  })
+
+  if (!result.ok) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ error: result.error }, null, 2),
+        },
+      ],
+      isError: true,
+    }
+  }
+
+  return {
+    content: [
+      { type: 'text' as const, text: JSON.stringify(result.data, null, 2) },
+    ],
+  }
+}