@gwdn/nexus-mcp 0.8.6 → 0.8.8

package/src/tools/get-document.ts

@@ -1,80 +0,0 @@
-/**
- * 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

@@ -1,65 +0,0 @@
-/**
- * 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

@@ -1,73 +0,0 @@
-/**
- * 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().max(50))
-    .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

@@ -1,165 +0,0 @@
-/**
- * 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().max(500).describe('ADR title'),
-  context: z
-    .string()
-    .max(100_000)
-    .describe('Context / motivation for the decision (markdown)'),
-  decision: z.string().max(100_000).describe('The decision content (markdown)'),
-  consequences: z
-    .string()
-    .max(100_000)
-    .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().max(200).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()
-    .max(10_000)
-    .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) },
-    ],
-  }
-}

package/src/tools/ingest-document.ts

@@ -1,65 +0,0 @@
-/**
- * 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().max(500).describe('Document title'),
-  body: z.string().max(100_000).describe('Document content (text or markdown)'),
-  source: z
-    .string()
-    .max(200)
-    .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().max(200).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

@@ -1,157 +0,0 @@
-/**
- * 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().max(50))
-    .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().max(50))
-    .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) },
-    ],
-  }
-}