spine-framework 0.3.145 → 0.4.0

package/.framework/mcp/tools/kb/delete.ts

@@ -0,0 +1,139 @@
+/**
+ * @module   delete
+ * @audience both
+ * @layer    shared-core
+ * @stability stable
+ *
+ * This module handles the deletion of knowledge base entries within the MCP framework. It interacts with the admin database and utilizes the McpServer for server-side operations. INVARIANT: Only authorized admin users can invoke this deletion process.
+ *
+ * @seeAlso adminDb (provides access to the admin database).
+ * @seeAlso kbRevoke (handles knowledge base revocation logic).
+ * @seeAlso adminRemove (performs the actual removal of data from admin records).
+ *
+ * @cil-generated
+ */
+
+// CIL[BEGIN stable_id="~/.framework/mcp/tools/kb/delete.ts:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/mcp/tools/kb/delete.ts"]
+// CIL[DOC-MACRO purpose="Knowledge base entry deletion module for the MCP framework"]
+// CIL[DOC-RESPONSIBILITY responsibility="Delete KB articles through admin-data and revoke their embeddings"]
+// CIL[DOC-CONTEXT module="kb-delete" layer="shared-core" related_files=".framework/functions/admin-data.ts,.framework/mcp/shared/db.ts,.framework/mcp/shared/kb.ts"]
+// CIL[DOC-CONTRACT inputs="server, id, account_id, hard" outputs="deletion and revocation result" errors="invalid UUID, admin errors, revoke errors" side_effects="admin data removal and embedding revocation"]
+// CIL[DOC-MICRO logic_summary="Provides tool registration and context building for KB article deletion" notable_decisions="Only authorized admin users can invoke deletion"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="both"]
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { z } from 'zod'
+import { adminDb } from '../../shared/db.js'
+import { remove as adminRemove } from '../../../functions/admin-data.js'
+import { kbRevoke } from '../../shared/kb.js'
+// CIL[DOC-VECTOR type="context" content="purpose='Knowledge base entry deletion module for the MCP framework'; No verified external callers; imports: .framework/mcp/shared/db.ts,.framework/functions/admin-data.ts,.framework/mcp/shared/kb.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/mcp/tools/kb/delete.ts:module_header:module_header"]
+
+
+/**
+ * Builds a context object for the knowledge base operations, including request metadata and account information. This function is essential for tracking requests and associating them with specific accounts.
+ *
+ * @inputSpec
+ *   - accountId: string (required) — The ID of the account associated with the context.
+ *   - query: any (required) — The query parameters for the operation.
+ * @outputSpec  any — An object containing request metadata, account information, and the provided query.
+ * @sideEffects none
+ * @stability   internal
+ * @cil-generated
+ */
+// CIL[BEGIN stable_id="~/.framework/mcp/tools/kb/delete.ts:buildCtx:function" type="function" identity="buildCtx" parent="~/.framework/mcp/tools/kb/delete.ts"]
+// CIL[DOC-MACRO purpose="Builds a context object for knowledge base operations"]
+// CIL[DOC-RESPONSIBILITY responsibility="Constructs a request context with metadata, account, and query"]
+// CIL[DOC-CONTEXT module="kb-delete" layer="shared-core" related_files=".framework/functions/admin-data.ts,.framework/mcp/shared/db.ts,.framework/mcp/shared/kb.ts,.framework/mcp/tools/kb/delete.ts"]
+// CIL[DOC-CONTRACT inputs="accountId: string, query: any" outputs="context object" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Creates a context with machine principal, admin database, and provided query" notable_decisions="Uses 'kb-mcp' principal with system_admin role"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="internal"]
+function buildCtx(accountId: string, query: any) {
+  return {
+    requestId: `kb-mcp-${Date.now()}`,
+    accountId,
+    principal: {
+      id: 'kb-mcp',
+      type: 'machine' as const,
+      roles: [{ slug: 'system_admin', is_system: true }]
+    },
+    db: adminDb,
+    trace: undefined,
+    query,
+  } as any
+}
+// CIL[DOC-VECTOR type="context" content="purpose='Builds a context object for knowledge base operations'; No verified external callers; imports: .framework/mcp/shared/db.ts,.framework/functions/admin-data.ts,.framework/mcp/shared/kb.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/mcp/tools/kb/delete.ts:buildCtx:function"]
+
+
+/**
+ * Registers a tool for deleting a KB article and revoking its embeddings. This function facilitates the removal of articles from the admin data system.
+ *
+ * @macro       Tool registration function for KB article deletion.
+ * @micro       Builds context for deletion and revocation operations, invoking external services for both actions.
+ * @inputSpec
+ *   - server: McpServer (required) — The server instance to register the tool with.
+ *   - id: string (required) — Item UUID.
+ *   - account_id: string (required) — Account UUID for audit scope.
+ *   - hard: boolean (optional) — Permanently delete the record.
+ * @outputSpec  Promise<{ content: Array<{ type: string, text: string }> }> — Returns a structured response containing the results of the delete and revoke operations.
+ * @sideEffects Calls to external services for article deletion and embedding revocation.
+ * @stability   internal
+ * @calls       buildCtx, adminRemove, kbRevoke
+ * @cil-generated
+ */
+// CIL[BEGIN stable_id="~/.framework/mcp/tools/kb/delete.ts:register:function" type="function" identity="register" parent="~/.framework/mcp/tools/kb/delete.ts"]
+// CIL[DOC-MACRO purpose="Registers a tool for deleting a KB article and revoking its embeddings"]
+// CIL[DOC-RESPONSIBILITY responsibility="Register the spine_kb_delete tool on an McpServer"]
+// CIL[DOC-CONTEXT module="kb-delete" layer="shared-core" related_files=".framework/functions/admin-data.ts,.framework/mcp/shared/db.ts,.framework/mcp/shared/kb.ts,.framework/mcp/tools/kb/delete.ts"]
+// CIL[DOC-CONTRACT inputs="server: McpServer" outputs="Promise<{ content: Array<{ type: string, text: string }> }>" errors="invalid UUID, admin errors, revoke errors" side_effects="Calls adminRemove and kbRevoke"]
+// CIL[DOC-MICRO logic_summary="Registers the tool, builds context, calls adminRemove and kbRevoke, and returns combined result" notable_decisions="Soft delete by default; hard delete controlled by 'hard' flag"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="internal"]
+export function register(server: McpServer) {
+  server.registerTool(
+    'spine_kb_delete',
+    {
+      description: 'Delete a KB article through admin-data and revoke its embeddings.',
+      inputSchema: z.object({
+        id: z.string().uuid().describe('Item UUID'),
+        account_id: z.string().uuid().describe('Account UUID for audit scope'),
+        hard: z.boolean().optional().describe('Permanently delete the record'),
+      }),
+    },
+    async ({ id, account_id, hard }) => {
+      const ctx = buildCtx(account_id, {
+        entity: 'items',
+        id,
+        soft: hard ? 'false' : 'true',
+        method: 'DELETE',
+      })
+
+      const remove = await adminRemove(ctx, {})
+
+      const revokeCtx = buildCtx(account_id, {})
+      const revoke = await kbRevoke(revokeCtx, { id })
+
+      return { content: [{ type: 'text', text: JSON.stringify({ remove, revoke }) }] }
+    }
+  )
+}
+// CIL[DOC-VECTOR type="context" content="purpose='Registers a tool for deleting a KB article and revoking its embeddings'; No verified external callers; imports: .framework/mcp/shared/db.ts,.framework/functions/admin-data.ts,.framework/mcp/shared/kb.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/mcp/tools/kb/delete.ts:register:function"]

package/.framework/mcp/tools/kb/index.ts

@@ -0,0 +1,52 @@
+// CIL[BEGIN stable_id="~/.framework/mcp/tools/kb/index.ts:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/mcp/tools/kb/index.ts"]
+// CIL[DOC-MACRO purpose="Re-export and aggregate Knowledge Base MCP tool modules (search, ingest, revoke, reindex, publish, upsert, delete, list-types) for unified server registration."]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide the integration surface that imports all kb tool submodules and exposes a single register() entry point for the MCP server."]
+// CIL[DOC-CONTEXT module="index" layer="shared-core" related_files=".framework/mcp/tools/kb/delete.ts,.framework/mcp/tools/kb/ingest.ts,.framework/mcp/tools/kb/list-types.ts,.framework/mcp/tools/kb/publish.ts,.framework/mcp/tools/kb/reindex.ts,.framework/mcp/tools/kb/revoke.ts,.framework/mcp/tools/kb/search.ts,.framework/mcp/tools/kb/upsert.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Imports the McpServer type and all sibling tool modules; contains no runtime logic itself." notable_decisions="Tool modules are imported as side-effect namespaces for their register() functions."]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stable]
+// CIL[DOC-AUDIENCE audience="both"]
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import * as search from './search.js'
+import * as ingest from './ingest.js'
+import * as revoke from './revoke.js'
+import * as reindex from './reindex.js'
+import * as publish from './publish.js'
+import * as upsert from './upsert.js'
+import * as remove from './delete.js'
+import * as listTypes from './list-types.js'
+// CIL[DOC-VECTOR type="context" content="purpose='Re-export and aggregate Knowledge Base MCP tool modules (search, ingest, revoke, reindex, publish, upsert, delete, list-types) for unified server registration.'; No verified external callers; imports: .framework/mcp/tools/kb/search.ts,.framework/mcp/tools/kb/ingest.ts,.framework/mcp/tools/kb/revoke.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/mcp/tools/kb/index.ts:module_header:module_header"]
+
+
+// CIL[BEGIN stable_id="~/.framework/mcp/tools/kb/index.ts:register:function" type="function" identity="register" parent="~/.framework/mcp/tools/kb/index.ts"]
+// CIL[DOC-MACRO purpose="Register all Knowledge Base MCP tool handlers on a provided McpServer instance."]
+// CIL[DOC-RESPONSIBILITY responsibility="Initialize and attach search, ingest, revoke, reindex, publish, upsert, remove and listTypes tool registrations to the server."]
+// CIL[DOC-CONTEXT module="index" layer="shared-core" related_files=".framework/mcp/tools/kb/delete.ts,.framework/mcp/tools/kb/index.ts,.framework/mcp/tools/kb/ingest.ts,.framework/mcp/tools/kb/list-types.ts,.framework/mcp/tools/kb/publish.ts,.framework/mcp/tools/kb/reindex.ts,.framework/mcp/tools/kb/revoke.ts,.framework/mcp/tools/kb/search.ts,.framework/mcp/tools/kb/upsert.ts"]
+// CIL[DOC-CONTRACT inputs="server: McpServer (required)" outputs="void" errors="Exceptions thrown by submodule register() calls propagate to the caller." side_effects="Tool handlers are registered on the supplied McpServer."]
+// CIL[DOC-MICRO logic_summary="Calls each submodule's register() method with the server argument, delegating initialization to the individual tool modules." notable_decisions="Registration order matches the import list; each tool owns its own handler attachment."]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stable]
+export function register(server: McpServer) {
+  search.register(server)
+  ingest.register(server)
+  revoke.register(server)
+  reindex.register(server)
+  publish.register(server)
+  upsert.register(server)
+  remove.register(server)
+  listTypes.register(server)
+}
+// CIL[DOC-VECTOR type="context" content="purpose='Register all Knowledge Base MCP tool handlers on a provided McpServer instance.'; No verified external callers; imports: .framework/mcp/tools/kb/search.ts,.framework/mcp/tools/kb/ingest.ts,.framework/mcp/tools/kb/revoke.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/mcp/tools/kb/index.ts:register:function"]

package/.framework/mcp/tools/kb/ingest.ts

@@ -0,0 +1,84 @@
+// CIL[BEGIN stable_id="~/.framework/mcp/tools/kb/ingest.ts:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/mcp/tools/kb/ingest.ts"]
+// CIL[DOC-MACRO purpose="Knowledge base data ingestion module for MCP; integrates external KB sources and ensures ingested data passes schema and validation checks before storage."]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide the kb ingest entry point and validation plumbing for the MCP server."]
+// CIL[DOC-MICRO logic_summary="Exports the register function and serves as the integration point for the spine_kb_ingest tool." notable_decisions="Uses JSDoc metadata to document invariants and related files; delegates actual database and embedding work to shared modules."]
+// CIL[DOC-CONTEXT module="ingest" layer="shared-core" related_files=".framework/mcp/shared/db.ts,.framework/mcp/shared/kb.ts"]
+// CIL[DOC-CONTRACT inputs="none (module import)" outputs="register function for MCP tool registration" errors="none (initialization)" side_effects="none (definitions only)"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="both"]
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { z } from 'zod'
+import { adminDb } from '../../shared/db.js'
+import { kbIngest } from '../../shared/kb.js'
+// CIL[DOC-VECTOR type="context" content="purpose='Knowledge base data ingestion module for MCP; integrates external KB sources and ensures ingested data passes schema and validation checks before storage.'; No verified external callers; imports: .framework/mcp/shared/db.ts,.framework/mcp/shared/kb.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/mcp/tools/kb/ingest.ts:module_header:module_header"]
+
+
+// CIL[BEGIN stable_id="~/.framework/mcp/tools/kb/ingest.ts:buildCtx:function" type="function" identity="buildCtx" parent="~/.framework/mcp/tools/kb/ingest.ts"]
+// CIL[DOC-MACRO purpose="Build a request context for a given account."]
+// CIL[DOC-RESPONSIBILITY responsibility="Create and return a processing context containing request ID, principal, db, and trace for kbIngest operations."]
+// CIL[DOC-MICRO logic_summary="Constructs a machine principal with the system_admin role, prefixes a request ID, and returns the context object with adminDb." notable_decisions="Uses type assertion `as any` and `machine` as const for principal; sets trace to undefined."]
+// CIL[DOC-CONTEXT module="ingest" layer="shared-core" related_files=".framework/mcp/shared/db.ts,.framework/mcp/shared/kb.ts,.framework/mcp/tools/kb/ingest.ts"]
+// CIL[DOC-CONTRACT inputs="accountId: string" outputs="object { requestId, accountId, principal, db, trace }" errors="none" side_effects="none"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="internal"]
+function buildCtx(accountId: string) {
+  return {
+    requestId: `kb-mcp-${Date.now()}`,
+    accountId,
+    principal: {
+      id: 'kb-mcp',
+      type: 'machine' as const,
+      roles: [{ slug: 'system_admin', is_system: true }]
+    },
+    db: adminDb,
+    trace: undefined,
+  } as any
+}
+// CIL[DOC-VECTOR type="context" content="purpose='Build a request context for a given account.'; No verified external callers; imports: .framework/mcp/shared/db.ts,.framework/mcp/shared/kb.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/mcp/tools/kb/ingest.ts:buildCtx:function"]
+
+
+// CIL[BEGIN stable_id="~/.framework/mcp/tools/kb/ingest.ts:register:function" type="function" identity="register" parent="~/.framework/mcp/tools/kb/ingest.ts"]
+// CIL[DOC-MACRO purpose="Register the spine_kb_ingest tool on an MCP server to generate and store embeddings for published KB items."]
+// CIL[DOC-RESPONSIBILITY responsibility="Bind a Zod-validated tool to the server that accepts id and account_id and invokes kbIngest with a built context."]
+// CIL[DOC-MICRO logic_summary="Defines tool metadata and an async handler that builds a context and awaits kbIngest, returning the result wrapped as text content." notable_decisions="Uses Zod for input validation; builds the context with buildCtx; returns JSON stringified result in MCP text content."]
+// CIL[DOC-CONTEXT module="ingest" layer="shared-core" related_files=".framework/mcp/shared/db.ts,.framework/mcp/shared/kb.ts,.framework/mcp/tools/kb/ingest.ts"]
+// CIL[DOC-CONTRACT inputs="server: McpServer" outputs="Promise<{ content: Array<{ type: 'text', text: string }> }>" errors="throws if validation or kbIngest fails" side_effects="Registers a tool with the server"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="internal"]
+export function register(server: McpServer) {
+  server.registerTool(
+    'spine_kb_ingest',
+    {
+      description: 'Generate and store embeddings for a published KB item.',
+      inputSchema: z.object({
+        id: z.string().uuid().describe('Item UUID'),
+        account_id: z.string().uuid().describe('Account UUID for audit scope'),
+      }),
+    },
+    async ({ id, account_id }) => {
+      const ctx = buildCtx(account_id)
+      const result = await kbIngest(ctx, { id })
+      return { content: [{ type: 'text', text: JSON.stringify(result) }] }
+    }
+  )
+}
+// CIL[DOC-VECTOR type="context" content="purpose='Register the spine_kb_ingest tool on an MCP server to generate and store embeddings for published KB items.'; No verified external callers; imports: .framework/mcp/shared/db.ts,.framework/mcp/shared/kb.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/mcp/tools/kb/ingest.ts:register:function"]

package/.framework/mcp/tools/kb/list-types.ts

@@ -0,0 +1,102 @@
+// CIL[BEGIN stable_id="~/.framework/mcp/tools/kb/list-types.ts:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/mcp/tools/kb/list-types.ts"]
+// CIL[DOC-MACRO purpose="Provides module-level JSDoc and imports for the list-types KB tool"]
+// CIL[DOC-RESPONSIBILITY responsibility="Documents the module scope, audience, and dependencies for the MCP KB list-types tool"]
+// CIL[DOC-CONTEXT module="list-types" layer="shared-core" related_files=".framework/mcp/shared/db.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Defines module metadata and imports required for the tool" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="both"]
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { z } from 'zod'
+import { adminDb } from '../../shared/db.js'
+// CIL[DOC-VECTOR type="context" content="purpose='Provides module-level JSDoc and imports for the list-types KB tool'; No verified external callers; imports: .framework/mcp/shared/db.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/mcp/tools/kb/list-types.ts:module_header:module_header"]
+
+/**
+ * @module   list-types
+ * @audience both
+ * @layer    shared-core
+ * @stability stable
+ *
+ * This module defines types for handling keyboard input in the MCP framework, facilitating the interaction between the server and client components. It ensures that the data structures used for keyboard events are validated and conform to the expected formats. INVARIANT: All keyboard events must be processed through the defined types to maintain consistency across the application.
+ *
+ * @seeAlso adminDb.js (provides database access for admin operations)
+ * @seeAlso @modelcontextprotocol/sdk/server/mcp.js (core SDK for server interactions)
+ * @seeAlso zod (used for data validation)
+ *
+ * @cil-generated
+ */
+
+
+// CIL[BEGIN stable_id="~/.framework/mcp/tools/kb/list-types.ts:register:function" type="function" identity="register" parent="~/.framework/mcp/tools/kb/list-types.ts"]
+// CIL[DOC-MACRO purpose="Registers the spine_kb_list_types tool on an McpServer"]
+// CIL[DOC-RESPONSIBILITY responsibility="Bind a named MCP tool that queries installed KB type slugs and their scopes"]
+// CIL[DOC-CONTEXT module="list-types" layer="shared-core" related_files=".framework/mcp/shared/db.ts,.framework/mcp/tools/kb/list-types.ts"]
+// CIL[DOC-CONTRACT inputs="server: McpServer, app_id?: string" outputs="Promise<{ content: Array<{ type: 'text', text: string }> }>" errors="Error on database query failure" side_effects="Database read from public.types"]
+// CIL[DOC-MICRO logic_summary="Query active types with slug ilike 'kb-%', optionally filter by app_id, and return a JSON list of slug, app_id, and scope" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="internal"]
+export function register(server: McpServer) {
+  server.registerTool(
+    'spine_kb_list_types',
+    {
+      description: 'List installed KB type slugs and their scopes.',
+      inputSchema: z.object({
+        app_id: z.string().uuid().optional().describe('Filter by app UUID'),
+      }),
+    },
+    async ({ app_id }) => {
+      let query = adminDb
+        .from('types')
+        .select('slug, app_id, design_schema')
+        .eq('kind', 'item')
+        .eq('is_active', true)
+        .ilike('slug', 'kb-%')
+
+      if (app_id) {
+        query = query.eq('app_id', app_id)
+      }
+
+      const { data, error } = await query
+      if (error) throw error
+
+      const types = (data || []).map((t: any) => ({
+        slug: t.slug,
+        app_id: t.app_id,
+        scope: t.design_schema?.scope || 'account',
+      }))
+
+      return { content: [{ type: 'text', text: JSON.stringify({ types }) }] }
+    }
+  )
+}
+// CIL[DOC-VECTOR type="context" content="purpose='Registers the spine_kb_list_types tool on an McpServer'; No verified external callers; imports: .framework/mcp/shared/db.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/mcp/tools/kb/list-types.ts:register:function"]
+
+/**
+ * Registers a tool to list installed KB type slugs and their scopes for a given application. This function facilitates querying and retrieving specific type information from the database.
+ *
+ * @macro       Tool registration function for listing KB types.
+ * @micro       Constructs a database query based on optional application ID filtering.
+ * @inputSpec
+ *   server: McpServer (required) — the server instance to register the tool with.
+ *   app_id: string (optional) — Filter by app UUID.
+ * @outputSpec  Promise<{ content: Array<{ type: 'text', text: string }> }> — Returns a structured response containing the list of types.
+ * @throws      Error — if the database query encounters an error.
+ * @sideEffects Database read operation to fetch type data.
+ * @stability   internal
+ * @calls       adminDb.from('types')
+ * @errorHandling throws error if the database query fails
+ * @cil-generated
+ */

package/.framework/mcp/tools/kb/publish.ts

@@ -0,0 +1,100 @@
+// CIL[BEGIN stable_id="~/.framework/mcp/tools/kb/publish.ts:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/mcp/tools/kb/publish.ts"]
+// CIL[DOC-AUDIENCE audience="both"]
+// CIL[DOC-MACRO purpose="Handle the publishing of knowledge base content within the MCP framework"]
+// CIL[DOC-RESPONSIBILITY responsibility="Integrate with the McpServer and the admin database to update and ingest knowledge base content; ensure the knowledge base is properly formatted before ingestion"]
+// CIL[DOC-CONTEXT module="publish" layer="shared-core" related_files=".framework/functions/admin-data.ts,.framework/mcp/shared/db.ts,.framework/mcp/shared/kb.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Provides the module header and imports dependencies for the publish module" notable_decisions="Knowledge base must be properly formatted before ingestion"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stable]
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { z } from 'zod'
+import { adminDb } from '../../shared/db.js'
+import { update as adminUpdate } from '../../../functions/admin-data.js'
+import { kbIngest } from '../../shared/kb.js'
+// CIL[DOC-VECTOR type="context" content="purpose='Handle the publishing of knowledge base content within the MCP framework'; No verified external callers; imports: .framework/mcp/shared/db.ts,.framework/functions/admin-data.ts,.framework/mcp/shared/kb.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/mcp/tools/kb/publish.ts:module_header:module_header"]
+
+
+// CIL[BEGIN stable_id="~/.framework/mcp/tools/kb/publish.ts:buildctx:function" type="function" identity="buildCtx" parent="~/.framework/mcp/tools/kb/publish.ts"]
+// CIL[DOC-AUDIENCE audience="internal"]
+// CIL[DOC-MACRO purpose="Create a context object for a specific account"]
+// CIL[DOC-RESPONSIBILITY responsibility="Encapsulate relevant request and query information to standardize the context structure for operations within the module"]
+// CIL[DOC-CONTEXT module="publish" layer="shared-core" related_files=".framework/functions/admin-data.ts,.framework/mcp/shared/db.ts,.framework/mcp/shared/kb.ts,.framework/mcp/tools/kb/publish.ts"]
+// CIL[DOC-CONTRACT inputs="accountId (string), query (any)" outputs="object containing requestId, accountId, principal, db, trace, and query" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Build a request context using the provided account and query, assigning a generated requestId, a machine principal with system_admin role, the adminDb client, and the query" notable_decisions=""]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY internal]
+
+function buildCtx(accountId: string, query: any) {
+  return {
+    requestId: `kb-mcp-${Date.now()}`,
+    accountId,
+    principal: {
+      id: 'kb-mcp',
+      type: 'machine' as const,
+      roles: [{ slug: 'system_admin', is_system: true }]
+    },
+    db: adminDb,
+    trace: undefined,
+    query,
+  } as any
+}
+// CIL[DOC-VECTOR type="context" content="purpose='Create a context object for a specific account'; No verified external callers; imports: .framework/mcp/shared/db.ts,.framework/functions/admin-data.ts,.framework/mcp/shared/kb.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/mcp/tools/kb/publish.ts:buildctx:function"]
+
+
+// CIL[BEGIN stable_id="~/.framework/mcp/tools/kb/publish.ts:register:function" type="function" identity="register" parent="~/.framework/mcp/tools/kb/publish.ts"]
+// CIL[DOC-AUDIENCE audience="internal"]
+// CIL[DOC-MACRO purpose="Register the spine_kb_publish tool for managing KB item publishing"]
+// CIL[DOC-RESPONSIBILITY responsibility="Register a tool that sets a KB item status to published and triggers embedding generation through admin-data"]
+// CIL[DOC-CONTEXT module="publish" layer="shared-core" related_files=".framework/functions/admin-data.ts,.framework/mcp/shared/db.ts,.framework/mcp/shared/kb.ts,.framework/mcp/tools/kb/publish.ts"]
+// CIL[DOC-CONTRACT inputs="server (McpServer)" outputs="Promise<{ content: Array<{ type: string, text: string }> }>" errors="from adminUpdate or kbIngest" side_effects="DB writes for updating item status and generating embeddings"]
+// CIL[DOC-MICRO logic_summary="Register a tool that accepts an item UUID and account UUID, builds a PATCH context for admin-data, updates status to published, builds an ingest context, and calls kbIngest to generate embeddings" notable_decisions="Returns a structured MCP content response"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY internal]
+
+export function register(server: McpServer) {
+  server.registerTool(
+    'spine_kb_publish',
+    {
+      description: 'Set a KB item status to published through admin-data and generate embeddings.',
+      inputSchema: z.object({
+        id: z.string().uuid().describe('Item UUID'),
+        account_id: z.string().uuid().describe('Account UUID for audit scope'),
+      }),
+    },
+    async ({ id, account_id }) => {
+      const ctx = buildCtx(account_id, {
+        entity: 'items',
+        id,
+        method: 'PATCH',
+      })
+
+      const record = await adminUpdate(ctx, { status: 'published' })
+
+      const ingestCtx = buildCtx(account_id, {})
+      const ingest = await kbIngest(ingestCtx, { id })
+
+      return { content: [{ type: 'text', text: JSON.stringify({ record, ingest }) }] }
+    }
+  )
+}
+// CIL[DOC-VECTOR type="context" content="purpose='Register the spine_kb_publish tool for managing KB item publishing'; No verified external callers; imports: .framework/mcp/shared/db.ts,.framework/functions/admin-data.ts,.framework/mcp/shared/kb.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/mcp/tools/kb/publish.ts:register:function"]

package/.framework/mcp/tools/kb/reindex.ts

@@ -0,0 +1,86 @@
+// CIL[BEGIN stable_id="~/.framework/mcp/tools/kb/reindex.ts:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/mcp/tools/kb/reindex.ts"]
+// CIL[DOC-MACRO purpose="MCP KB reindex tool registration"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provides the register function and buildCtx helper to wire the kb reindex MCP tool."]
+// CIL[DOC-CONTEXT module="mcp-tools-kb" layer="tool" related_files=".framework/mcp/shared/db.ts,.framework/mcp/shared/kb.ts"]
+// CIL[DOC-CONTRACT inputs="server: McpServer" outputs="registered kb reindex tool" errors="runtime registration failures" side_effects="registers 'spine_kb_reindex' tool"]
+// CIL[DOC-MICRO logic_summary="Imports McpServer, zod, adminDb, and kbReindex; exports register and buildCtx." notable_decisions="Uses a machine principal with system-admin role for internal requests."]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="maintainer"]
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { z } from 'zod'
+import { adminDb } from '../../shared/db.js'
+import { kbReindex } from '../../shared/kb.js'
+// CIL[DOC-VECTOR type="context" content="purpose='MCP KB reindex tool registration'; No verified external callers; imports: .framework/mcp/shared/db.ts,.framework/mcp/shared/kb.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/mcp/tools/kb/reindex.ts:module_header:module_header"]
+
+
+// CIL[BEGIN stable_id="~/.framework/mcp/tools/kb/reindex.ts:buildCtx:function" type="function" identity="buildCtx" parent="~/.framework/mcp/tools/kb/reindex.ts"]
+// CIL[DOC-MACRO purpose="Build a request context for the kb reindex tool"]
+// CIL[DOC-RESPONSIBILITY responsibility="Constructs an internal request context with a machine principal and admin database."]
+// CIL[DOC-CONTEXT module="kb" layer="mcp" related_files=".framework/mcp/shared/db.ts,.framework/mcp/shared/kb.ts,.framework/mcp/tools/kb/reindex.ts"]
+// CIL[DOC-CONTRACT inputs="accountId: string" outputs="RequestContext-like object" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Creates a context with a generated requestId, accountId, machine principal, adminDb, and undefined trace." notable_decisions="Casts the returned object as any."]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+function buildCtx(accountId: string) {
+  return {
+    requestId: `kb-mcp-${Date.now()}`,
+    accountId,
+    principal: {
+      id: 'kb-mcp',
+      type: 'machine' as const,
+      roles: [{ slug: 'system_admin', is_system: true }]
+    },
+    db: adminDb,
+    trace: undefined,
+  } as any
+}
+// CIL[DOC-VECTOR type="context" content="purpose='Build a request context for the kb reindex tool'; No verified external callers; imports: .framework/mcp/shared/db.ts,.framework/mcp/shared/kb.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/mcp/tools/kb/reindex.ts:buildCtx:function"]
+
+
+// CIL[BEGIN stable_id="~/.framework/mcp/tools/kb/reindex.ts:register:function" type="function" identity="register" parent="~/.framework/mcp/tools/kb/reindex.ts"]
+// CIL[DOC-MACRO purpose="Register the kb reindex tool on an MCP server"]
+// CIL[DOC-RESPONSIBILITY responsibility="Binds the spine_kb_reindex tool to the provided McpServer with a zod input schema."]
+// CIL[DOC-CONTEXT module="kb" layer="mcp" related_files=".framework/mcp/shared/db.ts,.framework/mcp/shared/kb.ts,.framework/mcp/tools/kb/reindex.ts"]
+// CIL[DOC-CONTRACT inputs="server: McpServer" outputs="void" errors="none" side_effects="registers the 'spine_kb_reindex' tool with the server"]
+// CIL[DOC-MICRO logic_summary="Defines the input schema and async handler that builds a context and calls kbReindex, returning JSON." notable_decisions="app_id is optional; response is JSON stringified."]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+export function register(server: McpServer) {
+  server.registerTool(
+    'spine_kb_reindex',
+    {
+      description: 'Re-ingest all published records of a KB type.',
+      inputSchema: z.object({
+        type_slug: z.string().describe('KB type slug'),
+        account_id: z.string().uuid().describe('Account UUID for audit scope'),
+        app_id: z.string().uuid().optional().describe('Filter by app_id'),
+      }),
+    },
+    async ({ type_slug, account_id, app_id }) => {
+      const ctx = buildCtx(account_id)
+      const result = await kbReindex(ctx, { type_slug, app_id })
+      return { content: [{ type: 'text', text: JSON.stringify(result) }] }
+    }
+  )
+}
+// CIL[DOC-VECTOR type="context" content="purpose='Register the kb reindex tool on an MCP server'; No verified external callers; imports: .framework/mcp/shared/db.ts,.framework/mcp/shared/kb.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/mcp/tools/kb/reindex.ts:register:function"]