@pikku/core 0.7.7 → 0.8.0

package/src/events/mcp/mcp-runner.ts

@@ -0,0 +1,321 @@
+import type {
+  CoreServices,
+  CoreSingletonServices,
+  CoreUserSession,
+  CreateSessionServices,
+} from '../../types/core.types.js'
+import type {
+  CoreMCPResource,
+  CoreMCPTool,
+  CoreMCPPrompt,
+  JsonRpcRequest,
+  JsonRpcResponse,
+  JsonRpcErrorResponse,
+  PikkuMCP,
+} from './mcp.types.js'
+import type { CoreAPIFunctionSessionless } from '../../function/functions.types.js'
+import { getErrorResponse } from '../../errors/error-handler.js'
+import { closeSessionServices } from '../../utils.js'
+import { pikkuState } from '../../pikku-state.js'
+import { addFunction, runPikkuFunc } from '../../function/function-runner.js'
+import { rpcService } from '../rpc/rpc-runner.js'
+import { BadRequestError, NotFoundError } from '../../errors/errors.js'
+
+export class MCPError extends Error {
+  constructor(public readonly error: JsonRpcErrorResponse) {
+    super(error?.message || 'MCP Error')
+    this.name = 'MCPError'
+    this.stack = new Error().stack
+  }
+}
+
+export type RunMCPEndpointParams<Tools extends string = any> = {
+  session?: CoreUserSession
+  singletonServices: CoreSingletonServices
+  mcp?: PikkuMCP<Tools>
+  createSessionServices?: CreateSessionServices<
+    CoreSingletonServices,
+    CoreServices<CoreSingletonServices>,
+    CoreUserSession
+  >
+}
+
+export type JsonRpcError = {
+  code: number
+  message: string
+  data?: any
+}
+
+export const addMCPResource = <
+  APIFunction extends CoreAPIFunctionSessionless<any, any>,
+>(
+  mcpResource: CoreMCPResource<APIFunction>
+) => {
+  const resourcesMeta = pikkuState('mcp', 'resourcesMeta')
+  const mcpResourceMeta = resourcesMeta[mcpResource.uri]
+  if (!mcpResourceMeta) {
+    throw new Error(`MCP resource metadata not found for '${mcpResource.uri}'`)
+  }
+  addFunction(mcpResourceMeta.pikkuFuncName, {
+    func: mcpResource.func,
+  })
+  const resources = pikkuState('mcp', 'resources')
+  if (resources.has(mcpResource.uri)) {
+    throw new Error(`MCP resource already exists: ${mcpResource.uri}`)
+  }
+  resources.set(mcpResource.uri, mcpResource)
+}
+
+export const addMCPTool = <
+  APIFunction extends CoreAPIFunctionSessionless<any, any>,
+>(
+  mcpTool: CoreMCPTool<APIFunction>
+) => {
+  const toolsMeta = pikkuState('mcp', 'toolsMeta')
+  const mcpToolMeta = toolsMeta[mcpTool.name]
+  if (!mcpToolMeta) {
+    throw new Error(`MCP tool metadata not found for '${mcpTool.name}'`)
+  }
+  addFunction(mcpToolMeta.pikkuFuncName, {
+    func: mcpTool.func,
+  })
+  const tools = pikkuState('mcp', 'tools')
+  if (tools.has(mcpTool.name)) {
+    throw new Error(`MCP tool already exists: ${mcpTool.name}`)
+  }
+  tools.set(mcpTool.name, mcpTool)
+}
+
+export const addMCPPrompt = <
+  APIFunction extends CoreAPIFunctionSessionless<any, any>,
+>(
+  mcpPrompt: CoreMCPPrompt<APIFunction>
+) => {
+  const promptsMeta = pikkuState('mcp', 'promptsMeta')
+  const mcpPromptMeta = promptsMeta[mcpPrompt.name]
+  if (!mcpPromptMeta) {
+    throw new Error(`MCP prompt metadata not found for '${mcpPrompt.name}'`)
+  }
+  addFunction(mcpPromptMeta.pikkuFuncName, {
+    func: mcpPrompt.func,
+  })
+  const prompts = pikkuState('mcp', 'prompts')
+  if (prompts.has(mcpPrompt.name)) {
+    throw new Error(`MCP prompt already exists: ${mcpPrompt.name}`)
+  }
+  prompts.set(mcpPrompt.name, mcpPrompt)
+}
+
+export async function runMCPResource(
+  request: JsonRpcRequest,
+  params: RunMCPEndpointParams,
+  uri: string
+) {
+  let endpoint: CoreMCPResource | undefined
+  let pikkuFuncName: string | undefined
+  let extractedParams: Record<string, string> = {}
+
+  const metas = pikkuState('mcp', 'resourcesMeta')
+  const endpoints = pikkuState('mcp', 'resources')
+
+  if (endpoints.has(uri)) {
+    endpoint = endpoints.get(uri)
+    pikkuFuncName = metas[uri]?.pikkuFuncName
+  } else {
+    for (const [uriTemplate, value] of endpoints.entries()) {
+      // Extract parameter names from the template
+      const paramNames = Array.from(
+        uriTemplate.matchAll(/\{([^}]+)\}/g),
+        (m) => m[1]
+      )
+
+      // Create regex pattern to match and capture parameter values
+      const regexPattern = uriTemplate.replace(/\{[^}]+\}/g, '([^/]+)')
+      const regex = new RegExp(`^${regexPattern}$`)
+      const match = uri.match(regex)
+
+      if (match) {
+        endpoint = value
+        pikkuFuncName = metas[uriTemplate]?.pikkuFuncName
+
+        // Extract parameter values and create params object
+        for (let i = 0; i < paramNames.length; i++) {
+          extractedParams[paramNames[i]!] = match[i + 1]! // match[0] is the full match
+        }
+        break
+      }
+    }
+  }
+
+  return await runMCPPikkuFunc(
+    {
+      ...request,
+      params: { ...request.params, ...extractedParams },
+    },
+    'resource',
+    uri,
+    endpoint,
+    pikkuFuncName,
+    { ...params, mcp: { uri } } as RunMCPEndpointParams<keyof CoreMCPResource>
+  )
+}
+
+export async function runMCPTool(
+  request: JsonRpcRequest,
+  params: RunMCPEndpointParams,
+  name: string
+) {
+  const endpoint = pikkuState('mcp', 'tools').get(name)
+  const meta = pikkuState('mcp', 'toolsMeta')[name]
+  return await runMCPPikkuFunc(
+    request,
+    'tool',
+    name,
+    endpoint,
+    meta?.pikkuFuncName,
+    params
+  )
+}
+
+export async function runMCPPrompt(
+  request: JsonRpcRequest,
+  params: RunMCPEndpointParams,
+  name: string
+) {
+  const endpoint = pikkuState('mcp', 'prompts').get(name)
+  const meta = pikkuState('mcp', 'promptsMeta')[name]
+  return await runMCPPikkuFunc(
+    request,
+    'prompt',
+    name,
+    endpoint,
+    meta?.pikkuFuncName,
+    params
+  )
+}
+
+/**
+ * JSON-RPC 2.0 compatible MCP endpoint runner
+ */
+async function runMCPPikkuFunc(
+  request: JsonRpcRequest,
+  type: 'resource' | 'tool' | 'prompt',
+  name: string,
+  mcp: CoreMCPResource | CoreMCPTool | CoreMCPPrompt | undefined,
+  pikkuFuncName: string | undefined,
+  {
+    session,
+    singletonServices,
+    createSessionServices,
+    mcp: interaction,
+  }: RunMCPEndpointParams
+): Promise<JsonRpcResponse> {
+  let sessionServices: any
+
+  try {
+    // Validate JSON-RPC request structure
+    if (request.jsonrpc !== '2.0') {
+      throw new BadRequestError(
+        'Invalid JSON-RPC version, only supoorted version is 2.0'
+      )
+    }
+
+    if (!mcp) {
+      throw new NotFoundError(
+        `MCP '${type}' registration not found for '${name}'`
+      )
+    }
+
+    if (!pikkuFuncName) {
+      throw new NotFoundError(
+        `MCP '${type}' PikkuFunction Mapping not found for '${name}'`
+      )
+    }
+
+    singletonServices.logger.debug(`Running MCP ${type}: ${name}`)
+
+    const getAllServices = async () => {
+      if (createSessionServices) {
+        const services = await createSessionServices(
+          singletonServices,
+          { mcp: interaction },
+          session
+        )
+        sessionServices = services
+        return rpcService.injectRPCService({
+          ...singletonServices,
+          ...services,
+          mcp: interaction,
+        })
+      }
+      return rpcService.injectRPCService({
+        ...singletonServices,
+        mcp: interaction,
+      })
+    }
+
+    const result = await runPikkuFunc(pikkuFuncName, {
+      getAllServices,
+      session,
+      data: request.params,
+    })
+
+    return {
+      id: request.id,
+      result,
+    }
+  } catch (e: any) {
+    singletonServices.logger.error(
+      `Error running MCP ${type} '${name}':`,
+      e.constructor
+    )
+    const errorResponse = getErrorResponse(e)
+    if (errorResponse?.mcpCode) {
+      throw new MCPError({
+        id: request.id,
+        code: errorResponse.mcpCode,
+        message: errorResponse.message,
+      })
+    } else {
+      if (errorResponse) {
+        singletonServices.logger.warn(
+          `Got error without a mapping: ${errorResponse.message}`
+        )
+      }
+      throw new MCPError({
+        id: request.id,
+        code: -32603,
+        message: 'Internal error',
+        data: { message: e.message, stack: e.stack },
+      })
+    }
+  } finally {
+    if (sessionServices) {
+      await closeSessionServices(singletonServices.logger, sessionServices)
+    }
+  }
+}
+
+export const getMCPTools = () => {
+  return pikkuState('mcp', 'tools')
+}
+
+export const getMCPResources = () => {
+  return pikkuState('mcp', 'resources')
+}
+
+export const getMCPResourcesMeta = () => {
+  return pikkuState('mcp', 'resourcesMeta')
+}
+
+export const getMCPToolsMeta = () => {
+  return pikkuState('mcp', 'toolsMeta')
+}
+
+export const getMCPPrompts = () => {
+  return pikkuState('mcp', 'prompts')
+}
+
+export const getMCPPromptsMeta = () => {
+  return pikkuState('mcp', 'promptsMeta')
+}

package/src/events/mcp/mcp.types.ts

@@ -0,0 +1,150 @@
+import { CoreAPIFunctionSessionless } from '../../function/functions.types.js'
+
+export type PikkuMCP<Tools extends string = any> = {
+  // elicitInput: <Input>(message: string) => Promise<{ action: string, content: Input }>
+  uri?: string
+  sendResourceUpdated: (uri: string) => void
+  enableResources: (resources: Record<string, boolean>) => Promise<boolean>
+  enablePrompts: (prompts: Record<string, boolean>) => Promise<boolean>
+  enableTools: (tools: Record<Tools, boolean>) => Promise<boolean>
+}
+
+/**
+ * Represents metadata for MCP resources, including name, description, and documentation.
+ */
+export type MCPResourceMeta = Record<
+  string,
+  Omit<CoreMCPResource, 'func'> & {
+    pikkuFuncName: string
+    inputSchema: string | null
+    outputSchema: string | null
+  }
+>
+
+/**
+ * Represents metadata for MCP tools, including name, description, and documentation.
+ */
+export type MCPToolMeta = Record<
+  string,
+  Omit<CoreMCPTool, 'func'> & {
+    pikkuFuncName: string
+    inputSchema: string | null
+    outputSchema: string | null
+  }
+>
+
+/**
+ * Represents metadata for MCP prompts, including name, description, and arguments.
+ */
+export type MCPPromptMeta = Record<
+  string,
+  Omit<CoreMCPPrompt, 'func'> & {
+    pikkuFuncName: string
+    inputSchema: string | null
+    outputSchema: string | null
+    arguments: Array<{
+      name: string
+      description: string
+      required: boolean
+    }>
+  }
+>
+
+/**
+ * Represents an MCP resource with specific properties.
+ */
+export type CoreMCPResource<
+  APIFunction = CoreAPIFunctionSessionless<any, any>,
+> = {
+  uri: string
+  title: string
+  description?: string
+  mimeType?: string
+  size?: number
+  streaming?: boolean
+  func: APIFunction
+  tags?: string[]
+}
+
+/**
+ * Represents an MCP tool with specific properties.
+ */
+export type CoreMCPTool<APIFunction = CoreAPIFunctionSessionless<any, any>> = {
+  name: string
+  title?: string
+  description: string
+  annotations?: Record<string, any>
+  func: APIFunction
+  tags?: string[]
+  streaming?: boolean
+}
+
+/**
+ * Represents an MCP prompt with specific properties.
+ */
+export type CoreMCPPrompt<
+  APIFunction = CoreAPIFunctionSessionless<any, MCPPromptResponse>,
+> = {
+  name: string
+  description?: string
+  func: APIFunction
+  tags?: string[]
+}
+
+export type JsonRpcRequest = {
+  jsonrpc: string
+  id?: string | number | null
+  params?: any
+}
+
+export type JsonRpcResponse = {
+  id?: string | number | null
+  result?: any
+}
+
+export type JsonRpcErrorResponse = {
+  id?: string | number | null
+  code: number
+  message: string
+  data?: any
+}
+
+/**
+ * Represents a message in an MCP prompt response
+ */
+export type MCPPromptMessage = {
+  role: 'user' | 'assistant' | 'system'
+  content: {
+    type: 'text' | 'image'
+    text: string
+    data?: string // for image content
+  }
+}
+
+/**
+ * Standard response type for MCP prompts - array of messages
+ */
+export type MCPPromptResponse = MCPPromptMessage[]
+
+export type MCPResourceMessage = {
+  uri: string
+  text: string
+}
+
+export type MCPResourceResponse = MCPResourceMessage[]
+
+/**
+ * Standard response type for MCP prompts - array of messages
+ */
+
+export type MCPToolMessage =
+  | {
+      type: 'text'
+      text: string
+    }
+  | {
+      type: 'image'
+      data: string // base64 encoded image data
+    }
+
+export type MCPToolResponse = MCPToolMessage[]

package/src/events/queue/index.ts

@@ -0,0 +1,18 @@
+// Queue types
+export type * from './queue.types.js'
+
+// Queue processor management
+export {
+  addQueueWorker,
+  runQueueJob,
+  getQueueWorkers,
+  removeQueueWorker,
+} from './queue-runner.js'
+
+// Configuration validation
+export { validateWorkerConfig } from './validate-worker-config.js'
+export type { QueueConfigMapping } from './validate-worker-config.js'
+
+// Queue registration helper
+export { registerqueueWorkers } from './register-queue-helper.js'
+export type { QueueRegistrationCallback } from './register-queue-helper.js'

package/src/events/queue/queue-runner.ts

@@ -0,0 +1,125 @@
+import type { CoreServices } from '../../types/core.types.js'
+import type { CoreQueueWorker, QueueJob } from './queue.types.js'
+import type { CoreAPIFunctionSessionless } from '../../function/functions.types.js'
+import { getErrorResponse } from '../../errors/error-handler.js'
+import { pikkuState } from '../../pikku-state.js'
+import { addFunction, runPikkuFunc } from '../../function/function-runner.js'
+import { CreateSessionServices } from '../../types/core.types.js'
+
+/**
+ * Error class for queue processor not found
+ */
+class QueueWorkerNotFoundError extends Error {
+  constructor(name: string) {
+    super(`Queue processor not found: ${name}`)
+  }
+}
+/**
+ * Add a queue processor to the system
+ */
+export const addQueueWorker = <
+  InputData = any,
+  OutputData = any,
+  APIFunction extends CoreAPIFunctionSessionless<
+    InputData,
+    OutputData
+  > = CoreAPIFunctionSessionless<InputData, OutputData>,
+>(
+  queueWorker: CoreQueueWorker<APIFunction>
+) => {
+  // Get processor metadata
+  const meta = pikkuState('queue', 'meta')
+  const processorMeta = meta[queueWorker.queueName]
+  if (!processorMeta) {
+    throw new Error(
+      `Queue processor metadata not found for '${queueWorker.queueName}'. Make sure to run the CLI to generate metadata.`
+    )
+  }
+
+  // Register the function with pikku
+  addFunction(processorMeta.pikkuFuncName, {
+    func: queueWorker.func,
+  })
+
+  // Store processor definition in state - runtime adapters will pick this up
+  const registrations = pikkuState('queue', 'registrations')
+  registrations.set(queueWorker.queueName, queueWorker)
+}
+
+/**
+ * Get all registered queue processors
+ */
+export function getQueueWorkers(): Map<string, CoreQueueWorker> {
+  return pikkuState('queue', 'registrations')
+}
+
+/**
+ * Stop and remove a queue processor
+ */
+export async function removeQueueWorker(name: string): Promise<void> {
+  const registrations = pikkuState('queue', 'registrations')
+  const registration = registrations.get(name)
+
+  if (!registration) {
+    throw new QueueWorkerNotFoundError(name)
+  }
+
+  registrations.delete(name)
+}
+
+/**
+ * Process a single queue job - this function is called by queue consumers
+ */
+export async function runQueueJob({
+  singletonServices,
+  createSessionServices,
+  job,
+}: {
+  singletonServices: CoreServices
+  createSessionServices?: CreateSessionServices
+  job: QueueJob
+}): Promise<void> {
+  const logger = singletonServices.logger
+
+  const meta = pikkuState('queue', 'meta')
+  const processorMeta = meta[job.queueName]
+  if (!processorMeta) {
+    throw new Error(`Processor metadata not found for: ${job.queueName}`)
+  }
+
+  try {
+    logger.info(`Processing job ${job.id} in queue ${job.queueName}`)
+
+    // Use provided singleton services
+    const getAllServices = () => ({
+      ...singletonServices,
+      ...(createSessionServices
+        ? createSessionServices(singletonServices, {}, undefined)
+        : {}),
+    })
+
+    // Execute the pikku function with the job data
+    const result = await runPikkuFunc(processorMeta.pikkuFuncName, {
+      getAllServices,
+      data: job.data,
+    })
+
+    logger.debug(
+      `Successfully processed job ${job.id} in queue ${job.queueName}`
+    )
+    return result
+  } catch (error: any) {
+    logger.error(
+      `Error processing job ${job.id} in queue ${job.queueName}:`,
+      error
+    )
+
+    const errorResponse = getErrorResponse(error)
+    if (errorResponse != null) {
+      logger.error('Processed error response:', errorResponse)
+    }
+
+    // Re-throw the error so the queue service can handle retries/DLQ
+    throw error
+  }
+}