@pikku/core 0.7.8 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.7.8",
+  "version": "0.8.0",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
   "module": "dist/index.js",
@@ -20,13 +20,14 @@
     ".": "./dist/index.js",
     "./middleware": "./dist/middleware/index.js",
     "./function": "./dist/function/index.js",
-    "./channel": "./dist/channel/index.js",
-    "./channel/local": "./dist/channel/local/index.js",
-    "./channel/serverless": "./dist/channel/serverless/index.js",
-    "./http": "./dist/http/index.js",
-    "./rpc": "./dist/rpc/index.js",
+    "./channel": "./dist/events/channel/index.js",
+    "./channel/local": "./dist/events/channel/local/index.js",
+    "./channel/serverless": "./dist/events/channel/serverless/index.js",
+    "./http": "./dist/events/http/index.js",
+    "./queue": "./dist/events/queue/index.js",
+    "./scheduler": "./dist/events/scheduler/index.js",
+    "./rpc": "./dist/events/rpc/index.js",
     "./errors": "./dist/errors/index.js",
-    "./scheduler": "./dist/scheduler/index.js",
     "./services": "./dist/services/index.js",
     "./schema": "./dist/schema.js",
     "./types": "./dist/types/index.d.ts"

package/src/errors/error-handler.ts

@@ -21,6 +21,7 @@ export class PikkuError extends Error {
 export interface ErrorDetails {
   status: number
   message: string
+  mcpCode?: number
 }
 
 /**
@@ -51,7 +52,7 @@ export const addErrors = (
  */
 export const getErrorResponse = (
   error: Error
-): { status: number; message: string } | undefined => {
+): { status: number; message: string; mcpCode?: number } | undefined => {
   const errors = Array.from(pikkuState('misc', 'errors').entries())
   const foundError = errors.find(([e]) => e.name === error.constructor.name)
   if (foundError) {

package/src/errors/errors.ts

@@ -10,6 +10,7 @@ import { addError, PikkuError } from './error-handler.js'
 export class BadRequestError extends PikkuError {}
 addError(BadRequestError, {
   status: 400,
+  mcpCode: -32600,
   message:
     'The server cannot or will not process the request due to client error (e.g., malformed request syntax).',
 })
@@ -85,6 +86,7 @@ export class NotFoundError extends PikkuError {}
  */
 addError(NotFoundError, {
   status: 404,
+  mcpCode: -32601,
   message: 'The server cannot find the requested resource.',
 })
 

package/src/{channel → events/channel}/channel-handler.ts

@@ -2,14 +2,14 @@ import {
   CoreServices,
   JSONValue,
   CoreUserSession,
-} from '../types/core.types.js'
+} from '../../types/core.types.js'
 import {
   ChannelMessageMeta,
   CoreAPIChannel,
   PikkuChannelHandler,
 } from './channel.types.js'
-import { pikkuState } from '../pikku-state.js'
-import { runPikkuFunc } from '../function/function-runner.js'
+import { pikkuState } from '../../pikku-state.js'
+import { runPikkuFunc } from '../../function/function-runner.js'
 
 const getRouteMeta = (
   channelName: string,

package/src/{channel → events/channel}/channel-runner.ts

@@ -1,8 +1,8 @@
-import { NotFoundError } from '../errors/errors.js'
-import { addFunction } from '../function/function-runner.js'
-import { pikkuState } from '../pikku-state.js'
-import { coerceTopLevelDataFromSchema, validateSchema } from '../schema.js'
-import { UserSessionService } from '../services/user-session-service.js'
+import { NotFoundError } from '../../errors/errors.js'
+import { addFunction } from '../../function/function-runner.js'
+import { pikkuState } from '../../pikku-state.js'
+import { coerceTopLevelDataFromSchema, validateSchema } from '../../schema.js'
+import { UserSessionService } from '../../services/user-session-service.js'
 import {
   ChannelMeta,
   CoreAPIChannel,

package/src/{channel → events/channel}/channel-store.ts

@@ -1,4 +1,4 @@
-import { CoreUserSession } from '../types/core.types.js'
+import { CoreUserSession } from '../../types/core.types.js'
 
 export type Channel<ChannelType = unknown, OpeningData = unknown> = {
   channelId: string

package/src/{channel → events/channel}/channel.types.ts

@@ -1,4 +1,4 @@
-import { PikkuError } from '../errors/error-handler.js'
+import { PikkuError } from '../../errors/error-handler.js'
 import {
   HTTPFunctionMetaInputTypes,
   PikkuHTTPRequest,
@@ -9,12 +9,12 @@ import {
   CoreSingletonServices,
   CreateSessionServices,
   PikkuMiddleware,
-} from '../types/core.types.js'
+} from '../../types/core.types.js'
 import {
   CoreAPIFunction,
   CoreAPIFunctionSessionless,
   CoreAPIPermission,
-} from '../function/functions.types.js'
+} from '../../function/functions.types.js'
 
 export type RunChannelOptions = Partial<{
   skipUserSession: boolean

package/src/{channel → events/channel}/local/local-channel-runner.test.ts

@@ -1,7 +1,7 @@
 import { test, beforeEach, afterEach } from 'node:test'
 import * as assert from 'node:assert/strict'
 import { runLocalChannel } from './local-channel-runner.js'
-import { pikkuState, resetPikkuState } from '../../pikku-state.js'
+import { pikkuState, resetPikkuState } from '../../../pikku-state.js'
 import { addChannel } from '../channel-runner.js'
 import {
   HTTPMethod,

package/src/{channel → events/channel}/local/local-channel-runner.ts

@@ -1,6 +1,6 @@
 import { openChannel } from '../channel-runner.js'
 import { createHTTPInteraction } from '../../http/http-runner.js'
-import { closeSessionServices } from '../../utils.js'
+import { closeSessionServices } from '../../../utils.js'
 import { processMessageHandlers } from '../channel-handler.js'
 import {
   CoreAPIChannel,
@@ -8,12 +8,12 @@ import {
   RunChannelParams,
 } from '../channel.types.js'
 import { PikkuLocalChannelHandler } from './local-channel-handler.js'
-import { SessionServices } from '../../types/core.types.js'
-import { handleError } from '../../handle-error.js'
-import { runMiddleware } from '../../middleware-runner.js'
-import { PikkuUserSessionService } from '../../services/user-session-service.js'
+import { SessionServices } from '../../../types/core.types.js'
+import { handleHTTPError } from '../../../handle-error.js'
+import { runMiddleware } from '../../../middleware-runner.js'
+import { PikkuUserSessionService } from '../../../services/user-session-service.js'
 import { PikkuHTTP } from '../../http/http.types.js'
-import { runPikkuFuncDirectly } from '../../function/function-runner.js'
+import { runPikkuFuncDirectly } from '../../../function/function-runner.js'
 import { rpcService } from '../../rpc/rpc-runner.js'
 
 export const runLocalChannel = async ({
@@ -110,7 +110,7 @@ export const runLocalChannel = async ({
         )
       )
     } catch (e: any) {
-      handleError(
+      handleHTTPError(
         e,
         http,
         channelId,

package/src/{channel → events/channel}/local/local-eventhub-service.test.ts

@@ -1,7 +1,7 @@
 import * as assert from 'assert'
 import { test } from 'node:test'
 import { PikkuChannelHandler } from '../channel.types.js'
-import { CoreUserSession } from '../../types/core.types.js'
+import { CoreUserSession } from '../../../types/core.types.js'
 import { LocalEventHubService } from './local-eventhub-service.js'
 
 class MockChannelHandler implements PikkuChannelHandler {

package/src/{channel → events/channel}/log-channels.ts

@@ -1,5 +1,5 @@
-import { pikkuState } from '../pikku-state.js'
-import { Logger } from '../services/index.js'
+import { pikkuState } from '../../pikku-state.js'
+import { Logger } from '../../services/index.js'
 
 /**
  * Logs all the loaded channels.

package/src/{channel → events/channel}/serverless/serverless-channel-runner.ts

@@ -1,5 +1,5 @@
-import { SessionServices } from '../../types/core.types.js'
-import { closeSessionServices } from '../../utils.js'
+import { SessionServices } from '../../../types/core.types.js'
+import { closeSessionServices } from '../../../utils.js'
 import { processMessageHandlers } from '../channel-handler.js'
 import { openChannel } from '../channel-runner.js'
 import type {
@@ -10,13 +10,13 @@ import type {
 } from '../channel.types.js'
 import { createHTTPInteraction } from '../../http/http-runner.js'
 import { ChannelStore } from '../channel-store.js'
-import { handleError } from '../../handle-error.js'
-import { PikkuUserSessionService } from '../../services/user-session-service.js'
-import { runMiddleware } from '../../middleware-runner.js'
-import { pikkuState } from '../../pikku-state.js'
+import { handleHTTPError } from '../../../handle-error.js'
+import { PikkuUserSessionService } from '../../../services/user-session-service.js'
+import { runMiddleware } from '../../../middleware-runner.js'
+import { pikkuState } from '../../../pikku-state.js'
 import { PikkuFetchHTTPRequest } from '../../http/pikku-fetch-http-request.js'
 import { PikkuHTTP } from '../../http/http.types.js'
-import { runPikkuFuncDirectly } from '../../function/function-runner.js'
+import { runPikkuFuncDirectly } from '../../../function/function-runner.js'
 
 export interface RunServerlessChannelParams<ChannelData>
   extends RunChannelParams<ChannelData> {
@@ -124,7 +124,7 @@ export const runChannelConnect = async ({
       }
       http?.response?.status(101)
     } catch (e: any) {
-      handleError(
+      handleHTTPError(
         e,
         http,
         channelId,

package/src/{http → events/http}/http-runner.test.ts

@@ -1,14 +1,14 @@
 import { test, describe, beforeEach, afterEach } from 'node:test'
 import * as assert from 'assert'
-import { NotFoundError } from '../errors/errors.js'
-import { JSONValue, PikkuMiddleware } from '../types/core.types.js'
+import { NotFoundError } from '../../errors/errors.js'
+import { JSONValue, PikkuMiddleware } from '../../types/core.types.js'
 import { fetch, addHTTPRoute } from './http-runner.js'
-import { pikkuState, resetPikkuState } from '../pikku-state.js'
+import { pikkuState, resetPikkuState } from '../../pikku-state.js'
 import {
   PikkuMockRequest,
   PikkuMockResponse,
 } from '../channel/local/local-channel-runner.test.js'
-import { addFunction } from '../function/function-runner.js'
+import { addFunction } from '../../function/function-runner.js'
 
 const sessionMiddleware: PikkuMiddleware = async (services, _, next) => {
   services.userSession.set({ userId: 'test' } as any)

package/src/{http → events/http}/http-runner.ts

@@ -12,25 +12,25 @@ import {
   CoreUserSession,
   PikkuMiddleware,
   SessionServices,
-} from '../types/core.types.js'
+} from '../../types/core.types.js'
 import { match } from 'path-to-regexp'
-import { MissingSessionError, NotFoundError } from '../errors/errors.js'
+import { MissingSessionError, NotFoundError } from '../../errors/errors.js'
 import {
   closeSessionServices,
   createWeakUID,
   isSerializable,
-} from '../utils.js'
+} from '../../utils.js'
 import {
   PikkuUserSessionService,
   UserSessionService,
-} from '../services/user-session-service.js'
-import { runMiddleware } from '../middleware-runner.js'
-import { handleError } from '../handle-error.js'
-import { pikkuState } from '../pikku-state.js'
+} from '../../services/user-session-service.js'
+import { runMiddleware } from '../../middleware-runner.js'
+import { handleHTTPError } from '../../handle-error.js'
+import { pikkuState } from '../../pikku-state.js'
 import { PikkuFetchHTTPResponse } from './pikku-fetch-http-response.js'
 import { PikkuFetchHTTPRequest } from './pikku-fetch-http-request.js'
 import { PikkuChannel } from '../channel/channel.types.js'
-import { addFunction, runPikkuFunc } from '../function/function-runner.js'
+import { addFunction, runPikkuFunc } from '../../function/function-runner.js'
 import { rpcService } from '../rpc/rpc-runner.js'
 
 /**
@@ -499,7 +499,7 @@ export const fetchData = async <In, Out>(
     return result
   } catch (e: any) {
     // Handle errors and, depending on configuration, bubble them up or respond with an error
-    handleError(
+    handleHTTPError(
       e,
       http,
       requestId,

package/src/{http → events/http}/http.types.ts

@@ -1,5 +1,5 @@
 import type { SerializeOptions } from 'cookie'
-import type { PikkuError } from '../errors/error-handler.js'
+import type { PikkuError } from '../../errors/error-handler.js'
 import type {
   APIDocs,
   CoreServices,
@@ -7,13 +7,13 @@ import type {
   CoreUserSession,
   CreateSessionServices,
   PikkuMiddleware,
-} from '../types/core.types.js'
+} from '../../types/core.types.js'
 import type {
   CoreAPIFunction,
   CoreAPIFunctionSessionless,
   CoreAPIPermission,
   CorePermissionGroup,
-} from '../function/functions.types.js'
+} from '../../function/functions.types.js'
 
 type ExtractRouteParams<S extends string> =
   S extends `${string}:${infer Param}/${infer Rest}`

package/src/{http → events/http}/index.ts

@@ -1,6 +1,5 @@
 export * from './pikku-fetch-http-request.js'
 export * from './pikku-fetch-http-response.js'
-export * from './incomingmessage-to-request-convertor.js'
 export * from './log-http-routes.js'
 
 export { fetch, fetchData, addHTTPRoute } from './http-runner.js'

package/src/{http → events/http}/log-http-routes.ts

@@ -1,5 +1,5 @@
-import { pikkuState } from '../pikku-state.js'
-import { Logger } from '../services/index.js'
+import { pikkuState } from '../../pikku-state.js'
+import { Logger } from '../../services/index.js'
 
 /**
  * Logs all the loaded routes.

package/src/{http → events/http}/pikku-fetch-http-request.ts

@@ -1,7 +1,7 @@
 import { parse as parseQuery } from 'picoquery'
 import { parse as parseCookie } from 'cookie'
 import { HTTPMethod, PikkuHTTPRequest, PikkuQuery } from './http.types.js'
-import { UnprocessableContentError } from '../errors/errors.js'
+import { UnprocessableContentError } from '../../errors/errors.js'
 
 /**
  * Abstract class representing a pikku request.

package/src/events/mcp/index.ts

@@ -0,0 +1,2 @@
+export * from './mcp.types.js'
+export * from './mcp-runner.js'

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')
+}