@mpowr/nexus-mcp 0.5.0

package/src/tools/ingest-document.ts

@@ -0,0 +1,64 @@
+/**
+ * doc_ingest -- Layer 2 Coordination
+ *
+ * Allows agents to push text/markdown content into a project's
+ * knowledge base via the ingest_items table.
+ * Delegates to POST /api/mcp/documents (action: doc_ingest).
+ */
+
+import { z } from 'zod'
+import { nexusPost } from '../nexus-api.js'
+
+export const ingestDocumentSchema = {
+  project_id: z.string().uuid().describe('Project UUID'),
+  title: z.string().describe('Document title'),
+  body: z.string().describe('Document content (text or markdown)'),
+  source: z
+    .string()
+    .optional()
+    .describe(
+      'Source identifier (e.g. "mcp-agent", "research", "session-extract")',
+    ),
+  source_url: z.string().url().optional().describe('Source URL if applicable'),
+  agent_id: z.string().optional().describe('Agent identifier if applicable'),
+}
+
+type IngestDocumentArgs = {
+  project_id: string
+  title: string
+  body: string
+  source?: string
+  source_url?: string
+  user_id: string
+  agent_id?: string
+}
+
+export async function ingestDocument(args: IngestDocumentArgs) {
+  const result = await nexusPost('/api/mcp/documents', {
+    action: 'doc_ingest',
+    project_id: args.project_id,
+    title: args.title,
+    body: args.body,
+    source: args.source,
+    source_url: args.source_url,
+    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/letter-inbox.ts

@@ -0,0 +1,157 @@
+/**
+ * vl_inbox + vl_outbox + vl_ack -- Layer 2 Coordination
+ *
+ * Inbox/outbox polling and acknowledgment for vault letters.
+ * Delegates to POST /api/mcp/letters (actions: vl_inbox, vl_outbox, vl_ack).
+ */
+
+import { z } from 'zod'
+import { nexusPost } from '../nexus-api.js'
+
+// ---------------------------------------------------------------------------
+// list_inbox
+// ---------------------------------------------------------------------------
+
+export const listInboxSchema = {
+  project_id: z.string().uuid().describe('Project UUID'),
+  status_filter: z
+    .array(z.string())
+    .optional()
+    .describe(
+      'Filter by letter status (default: new, acknowledged, in_progress, blocked, needs_review)',
+    ),
+  limit: z
+    .number()
+    .min(1)
+    .max(50)
+    .default(20)
+    .describe('Max number of letters to return'),
+}
+
+type ListInboxArgs = {
+  project_id: string
+  status_filter?: string[]
+  limit?: number
+  user_id: string
+  agent_id?: string
+}
+
+export async function listInbox(args: ListInboxArgs) {
+  const result = await nexusPost('/api/mcp/letters', {
+    action: 'vl_inbox',
+    project_id: args.project_id,
+    status_filter: args.status_filter,
+    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) },
+    ],
+  }
+}
+
+// ---------------------------------------------------------------------------
+// list_outbox
+// ---------------------------------------------------------------------------
+
+export const listOutboxSchema = {
+  project_id: z.string().uuid().describe('Project UUID'),
+  status_filter: z
+    .array(z.string())
+    .optional()
+    .describe('Filter by letter status (default: all non-closed)'),
+  limit: z
+    .number()
+    .min(1)
+    .max(50)
+    .default(20)
+    .describe('Max number of letters to return'),
+}
+
+type ListOutboxArgs = {
+  project_id: string
+  status_filter?: string[]
+  limit?: number
+  user_id: string
+  agent_id?: string
+}
+
+export async function listOutbox(args: ListOutboxArgs) {
+  const result = await nexusPost('/api/mcp/letters', {
+    action: 'vl_outbox',
+    project_id: args.project_id,
+    status_filter: args.status_filter,
+    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) },
+    ],
+  }
+}
+
+// ---------------------------------------------------------------------------
+// acknowledge_letter
+// ---------------------------------------------------------------------------
+
+export const acknowledgeLetterSchema = {
+  letter_id: z.string().uuid().describe('Letter UUID to acknowledge'),
+}
+
+type AcknowledgeLetterArgs = {
+  letter_id: string
+  user_id: string
+  agent_id?: string
+}
+
+export async function acknowledgeLetter(args: AcknowledgeLetterArgs) {
+  const result = await nexusPost('/api/mcp/letters', {
+    action: 'vl_ack',
+    letter_id: args.letter_id,
+    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/letters.ts

@@ -0,0 +1,144 @@
+/**
+ * vl_create + vl_reply -- Layer 2 Coordination
+ *
+ * Vault letter management for agent coordination.
+ * Delegates to POST /api/mcp/letters (actions: vl_create, vl_reply).
+ */
+
+import { z } from 'zod'
+import { nexusPost } from '../nexus-api.js'
+
+// ---------------------------------------------------------------------------
+// create_letter
+// ---------------------------------------------------------------------------
+
+export const createLetterSchema = {
+  project_id: z.string().uuid().describe('Project UUID'),
+  from_actor: z.string().describe('Sender identifier (agent name or user)'),
+  to_actor: z.string().describe('Recipient identifier (agent name or user)'),
+  subject: z.string().describe('Letter subject'),
+  body: z.string().describe('Initial message body'),
+  priority: z
+    .enum(['low', 'normal', 'high', 'urgent'])
+    .default('normal')
+    .describe('Letter priority'),
+  blocking: z
+    .boolean()
+    .default(false)
+    .describe('Whether this letter blocks the sender'),
+  thread_id: z
+    .string()
+    .uuid()
+    .optional()
+    .describe('Optional thread UUID to group related letters'),
+  agent_id: z.string().optional().describe('Agent identifier if applicable'),
+}
+
+type CreateLetterArgs = {
+  project_id: string
+  from_actor: string
+  to_actor: string
+  subject: string
+  body: string
+  priority?: string
+  blocking?: boolean
+  thread_id?: string
+  user_id: string
+  agent_id?: string
+}
+
+export async function createLetter(args: CreateLetterArgs) {
+  const result = await nexusPost('/api/mcp/letters', {
+    action: 'vl_create',
+    project_id: args.project_id,
+    from_actor: args.from_actor,
+    to_actor: args.to_actor,
+    subject: args.subject,
+    body: args.body,
+    priority: args.priority ?? 'normal',
+    blocking: args.blocking ?? false,
+    thread_id: args.thread_id,
+    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) },
+    ],
+  }
+}
+
+// ---------------------------------------------------------------------------
+// reply_letter
+// ---------------------------------------------------------------------------
+
+export const replyLetterSchema = {
+  letter_id: z.string().uuid().describe('Letter UUID to reply to'),
+  body: z.string().describe('Reply message body'),
+  message_type: z
+    .enum(['response', 'clarification', 'review_note', 'follow_up', 'context'])
+    .default('response')
+    .describe('Type of reply message'),
+  agent_id: z.string().optional().describe('Agent identifier if applicable'),
+  new_status: z
+    .enum([
+      'acknowledged',
+      'in_progress',
+      'answered',
+      'blocked',
+      'needs_review',
+      'closed',
+    ])
+    .optional()
+    .describe('Optionally update the letter status'),
+}
+
+type ReplyLetterArgs = {
+  letter_id: string
+  body: string
+  message_type?: string
+  user_id: string
+  agent_id?: string
+  new_status?: string
+}
+
+export async function replyLetter(args: ReplyLetterArgs) {
+  const result = await nexusPost('/api/mcp/letters', {
+    action: 'vl_reply',
+    letter_id: args.letter_id,
+    body: args.body,
+    message_type: args.message_type ?? 'response',
+    agent_id: args.agent_id,
+    new_status: args.new_status,
+  })
+
+  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/project-list.ts

@@ -0,0 +1,52 @@
+/**
+ * project_list -- Layer 1 Knowledge Access
+ *
+ * List accessible projects for the authenticated user/agent.
+ * Delegates to GET /api/mcp/projects.
+ */
+
+import { z } from 'zod'
+import { nexusGet } from '../nexus-api.js'
+
+export const projectListSchema = {
+  limit: z
+    .number()
+    .int()
+    .min(1)
+    .max(100)
+    .optional()
+    .describe('Maximum number of projects to return'),
+}
+
+type ProjectListArgs = {
+  limit?: number
+}
+
+export async function projectList(args: ProjectListArgs) {
+  const params = new URLSearchParams()
+  if (args.limit !== undefined) {
+    params.set('limit', String(args.limit))
+  }
+  const qs = params.toString()
+  const path = `/api/mcp/projects${qs ? `?${qs}` : ''}`
+
+  const result = await nexusGet(path)
+
+  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/reviews.ts

@@ -0,0 +1,277 @@
+/**
+ * rv_list + rv_get + rv_create + rv_decide + rv_comment -- Layer 4 Reviews
+ *
+ * Review lifecycle management tools for the Nexus platform.
+ * Reviews cover skills, agents, and other governed entities.
+ * Delegates to POST /api/mcp/reviews.
+ */
+
+import { z } from 'zod'
+import { nexusPost } from '../nexus-api.js'
+
+// ---------------------------------------------------------------------------
+// rv_list
+// ---------------------------------------------------------------------------
+
+export const rvListSchema = {
+  entity_type: z
+    .enum(['skill', 'agent'])
+    .optional()
+    .describe('Filter by entity type (skill or agent)'),
+  status: z
+    .string()
+    .optional()
+    .describe('Filter by review status'),
+  limit: z
+    .number()
+    .int()
+    .min(1)
+    .max(100)
+    .optional()
+    .describe('Maximum number of reviews to return'),
+}
+
+type RvListArgs = {
+  entity_type?: string
+  status?: string
+  limit?: number
+  user_id: string
+}
+
+export async function rvList(args: RvListArgs) {
+  const result = await nexusPost('/api/mcp/reviews', {
+    action: 'rv_list',
+    entity_type: args.entity_type,
+    status: args.status,
+    limit: args.limit,
+  })
+
+  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) },
+    ],
+  }
+}
+
+// ---------------------------------------------------------------------------
+// rv_get
+// ---------------------------------------------------------------------------
+
+export const rvGetSchema = {
+  review_id: z
+    .string()
+    .uuid()
+    .optional()
+    .describe('Review UUID (look up by review ID)'),
+  entity_type: z
+    .string()
+    .optional()
+    .describe('Entity type (used with entity_id for lookup by entity)'),
+  entity_id: z
+    .string()
+    .uuid()
+    .optional()
+    .describe('Entity UUID (used with entity_type for lookup by entity)'),
+}
+
+type RvGetArgs = {
+  review_id?: string
+  entity_type?: string
+  entity_id?: string
+  user_id: string
+}
+
+export async function rvGet(args: RvGetArgs) {
+  const result = await nexusPost('/api/mcp/reviews', {
+    action: 'rv_get',
+    review_id: args.review_id,
+    entity_type: args.entity_type,
+    entity_id: args.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) },
+    ],
+  }
+}
+
+// ---------------------------------------------------------------------------
+// rv_create
+// ---------------------------------------------------------------------------
+
+export const rvCreateSchema = {
+  entity_type: z
+    .enum(['skill', 'agent'])
+    .describe('Type of entity to create a review for'),
+  entity_id: z
+    .string()
+    .uuid()
+    .describe('UUID of the entity to review'),
+}
+
+type RvCreateArgs = {
+  entity_type: string
+  entity_id: string
+  user_id: string
+}
+
+export async function rvCreate(args: RvCreateArgs) {
+  const result = await nexusPost('/api/mcp/reviews', {
+    action: 'rv_create',
+    entity_type: args.entity_type,
+    entity_id: args.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) },
+    ],
+  }
+}
+
+// ---------------------------------------------------------------------------
+// rv_decide
+// ---------------------------------------------------------------------------
+
+export const rvDecideSchema = {
+  review_id: z.string().uuid().describe('Review UUID'),
+  transition: z
+    .enum(['submit', 'accept', 'reject', 'request_revision', 'resubmit', 'archive'])
+    .describe('State transition to apply'),
+  rationale: z
+    .string()
+    .optional()
+    .describe('Optional rationale for the decision'),
+}
+
+type RvDecideArgs = {
+  review_id: string
+  transition: string
+  rationale?: string
+  user_id: string
+}
+
+export async function rvDecide(args: RvDecideArgs) {
+  const result = await nexusPost('/api/mcp/reviews', {
+    action: 'rv_decide',
+    review_id: args.review_id,
+    transition: args.transition,
+    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) },
+    ],
+  }
+}
+
+// ---------------------------------------------------------------------------
+// rv_comment
+// ---------------------------------------------------------------------------
+
+export const rvCommentSchema = {
+  review_id: z.string().uuid().describe('Review UUID'),
+  body: z.string().describe('Comment body (markdown supported)'),
+  agent_id: z
+    .string()
+    .optional()
+    .describe('Agent identifier if comment is posted by an agent'),
+  line_start: z
+    .number()
+    .int()
+    .optional()
+    .describe('Start line number for inline comments'),
+  line_end: z
+    .number()
+    .int()
+    .optional()
+    .describe('End line number for inline comments'),
+}
+
+type RvCommentArgs = {
+  review_id: string
+  body: string
+  agent_id?: string
+  line_start?: number
+  line_end?: number
+  user_id: string
+}
+
+export async function rvComment(args: RvCommentArgs) {
+  const result = await nexusPost('/api/mcp/reviews', {
+    action: 'rv_comment',
+    review_id: args.review_id,
+    body: args.body,
+    agent_id: args.agent_id,
+    line_start: args.line_start,
+    line_end: args.line_end,
+  })
+
+  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) },
+    ],
+  }
+}