@gwdn/nexus-mcp 0.7.0

package/src/tools/reviews.ts

@@ -0,0 +1,281 @@
+/**
+ * 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()
+    .max(50)
+    .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()
+    .max(50)
+    .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()
+    .max(10_000)
+    .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().max(100_000).describe('Comment body (markdown supported)'),
+  agent_id: z
+    .string()
+    .max(200)
+    .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) },
+    ],
+  }
+}

package/src/tools/search-knowledge.ts

@@ -0,0 +1,68 @@
+/**
+ * kb_search -- Layer 1 Knowledge Access
+ *
+ * Searches project knowledge using keyword, semantic, or hybrid mode.
+ * Delegates to POST /api/mcp/search.
+ */
+
+import { z } from 'zod'
+import { nexusPost } from '../nexus-api.js'
+
+export const searchKnowledgeSchema = {
+  query: z.string().max(1000).describe('Free-text search query'),
+  project_id: z.string().uuid().describe('Project UUID to scope the search'),
+  entity_types: z
+    .array(
+      z.enum([
+        'session',
+        'decision',
+        'letter',
+        'task',
+        'research_note',
+        'planning_item',
+        'ingest_item',
+      ]),
+    )
+    .optional()
+    .describe('Filter to specific entity types'),
+  search_mode: z
+    .enum(['keyword', 'semantic', 'hybrid'])
+    .default('keyword')
+    .describe('Search mode: keyword, semantic, or hybrid'),
+  limit: z
+    .number()
+    .int()
+    .min(1)
+    .max(50)
+    .default(10)
+    .describe('Maximum results to return'),
+}
+
+type SearchArgs = {
+  query: string
+  project_id: string
+  entity_types?: string[]
+  search_mode?: string
+  limit?: number
+}
+
+export async function searchKnowledge(args: SearchArgs) {
+  const result = await nexusPost('/api/mcp/search', {
+    project_id: args.project_id,
+    query: args.query,
+    entity_types: args.entity_types,
+    search_mode: args.search_mode ?? 'keyword',
+    limit: args.limit ?? 10,
+  })
+
+  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/sessions.ts

@@ -0,0 +1,157 @@
+/**
+ * Session lifecycle tools -- Layer 2 Coordination
+ *
+ * session_create:      Start a new work session for a project
+ * session_close:       End a session with summary and next entry point
+ * session_list:        List open sessions for a project
+ *
+ * Delegates to POST /api/mcp/sessions.
+ */
+
+import { z } from 'zod'
+import { nexusPost } from '../nexus-api.js'
+
+// ---------------------------------------------------------------------------
+// create_session -> session_create
+// ---------------------------------------------------------------------------
+
+export const createSessionSchema = {
+  project_id: z.string().uuid().describe('Project UUID'),
+  title: z.string().max(500).describe('Session title (e.g., "Architecture review")'),
+  agent_id: z
+    .string()
+    .max(200)
+    .optional()
+    .describe('Agent identifier starting this session'),
+}
+
+type CreateSessionArgs = {
+  project_id: string
+  title: string
+  agent_id?: string
+  user_id: string
+}
+
+export async function createSession(args: CreateSessionArgs) {
+  const result = await nexusPost('/api/mcp/sessions', {
+    action: 'session_create',
+    project_id: args.project_id,
+    title: args.title,
+  })
+
+  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) },
+    ],
+  }
+}
+
+// ---------------------------------------------------------------------------
+// close_session -> session_close
+// ---------------------------------------------------------------------------
+
+export const closeSessionSchema = {
+  session_id: z.string().uuid().describe('Session UUID to close'),
+  summary: z
+    .string()
+    .max(100_000)
+    .optional()
+    .describe('Summary of what was accomplished in the session'),
+  next_entry_point: z
+    .string()
+    .max(10_000)
+    .optional()
+    .describe('Suggested starting point for the next session'),
+}
+
+type CloseSessionArgs = {
+  session_id: string
+  summary?: string
+  next_entry_point?: string
+  user_id: string
+}
+
+export async function closeSession(args: CloseSessionArgs) {
+  const result = await nexusPost('/api/mcp/sessions', {
+    action: 'session_close',
+    session_id: args.session_id,
+    summary: args.summary,
+    next_entry_point: args.next_entry_point,
+  })
+
+  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_open_sessions -> session_list
+// ---------------------------------------------------------------------------
+
+export const listOpenSessionsSchema = {
+  project_id: z.string().uuid().describe('Project UUID'),
+  limit: z
+    .number()
+    .int()
+    .min(1)
+    .max(100)
+    .default(25)
+    .describe('Maximum number of sessions to return (default 25)'),
+}
+
+type ListOpenSessionsArgs = {
+  project_id: string
+  limit?: number
+}
+
+export async function listOpenSessions(args: ListOpenSessionsArgs) {
+  const result = await nexusPost('/api/mcp/sessions', {
+    action: 'session_list',
+    project_id: args.project_id,
+    limit: args.limit ?? 25,
+  })
+
+  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/skill-assign.ts

@@ -0,0 +1,142 @@
+/**
+ * sk_assign + sk_unassign + sk_export -- Layer 2 Coordination
+ *
+ * Skill-project assignment management tools for the Nexus platform.
+ * Delegates to POST /api/mcp/skills.
+ */
+
+import { z } from 'zod'
+import { nexusPost } from '../nexus-api.js'
+
+// ---------------------------------------------------------------------------
+// sk_assign
+// ---------------------------------------------------------------------------
+
+export const skAssignSchema = {
+  project_id: z.string().uuid().describe('Project UUID'),
+  skill_id: z.string().max(200).describe('Skill identifier or UUID'),
+  pinned_version: z
+    .number()
+    .int()
+    .optional()
+    .describe('Pin to a specific skill version'),
+  enabled: z
+    .boolean()
+    .optional()
+    .describe('Whether the assignment is enabled (default: true)'),
+}
+
+type SkAssignArgs = {
+  project_id: string
+  skill_id: string
+  pinned_version?: number
+  enabled?: boolean
+  user_id: string
+}
+
+export async function skAssign(args: SkAssignArgs) {
+  const result = await nexusPost('/api/mcp/skills', {
+    action: 'sk_assign',
+    project_id: args.project_id,
+    skill_id: args.skill_id,
+    pinned_version: args.pinned_version,
+    enabled: args.enabled,
+  })
+
+  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) },
+    ],
+  }
+}
+
+// ---------------------------------------------------------------------------
+// sk_unassign
+// ---------------------------------------------------------------------------
+
+export const skUnassignSchema = {
+  project_id: z.string().uuid().describe('Project UUID'),
+  skill_id: z.string().max(200).describe('Skill identifier or UUID'),
+}
+
+type SkUnassignArgs = {
+  project_id: string
+  skill_id: string
+  user_id: string
+}
+
+export async function skUnassign(args: SkUnassignArgs) {
+  const result = await nexusPost('/api/mcp/skills', {
+    action: 'sk_unassign',
+    project_id: args.project_id,
+    skill_id: args.skill_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) },
+    ],
+  }
+}
+
+// ---------------------------------------------------------------------------
+// sk_export
+// ---------------------------------------------------------------------------
+
+export const skExportSchema = {
+  project_id: z.string().uuid().describe('Project UUID'),
+}
+
+type SkExportArgs = {
+  project_id: string
+  user_id: string
+}
+
+export async function skExport(args: SkExportArgs) {
+  const result = await nexusPost('/api/mcp/skills', {
+    action: 'sk_export',
+    project_id: args.project_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) },
+    ],
+  }
+}