@pikku/core 0.12.4 → 0.12.5

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

@@ -0,0 +1,323 @@
+import type { PikkuWire } from '../../types/core.types.js'
+import type {
+  CoreMCPResource,
+  CoreMCPPrompt,
+  JsonRpcRequest,
+  JsonRpcResponse,
+  JsonRpcErrorResponse,
+  PikkuMCP,
+} from './mcp.types.js'
+import type {
+  CorePikkuFunctionConfig,
+  CorePikkuFunctionSessionless,
+} from '../../function/functions.types.js'
+import { getErrorResponse } from '../../errors/error-handler.js'
+import { closeWireServices } from '../../utils.js'
+import {
+  pikkuState,
+  getSingletonServices,
+  getCreateWireServices,
+} from '../../pikku-state.js'
+import { addFunction, runPikkuFunc } from '../../function/function-runner.js'
+import { resolveNamespace } from '../rpc/rpc-runner.js'
+import {
+  BadRequestError,
+  NotFoundError,
+  PikkuMissingMetaError,
+} from '../../errors/errors.js'
+import {
+  PikkuSessionService,
+  createMiddlewareSessionWireProps,
+} from '../../services/user-session-service.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> = {
+  mcp?: PikkuMCP<Tools>
+}
+
+export type JsonRpcError = {
+  code: number
+  message: string
+  data?: any
+}
+
+export const wireMCPResource = <
+  PikkuFunctionConfig extends CorePikkuFunctionConfig<
+    CorePikkuFunctionSessionless<any, any>
+  > = CorePikkuFunctionConfig<CorePikkuFunctionSessionless<any, any>>,
+>(
+  mcpResource: CoreMCPResource<PikkuFunctionConfig>
+) => {
+  const resourcesMeta = pikkuState(null, 'mcp', 'resourcesMeta')
+  const mcpResourceMeta = resourcesMeta[mcpResource.uri]
+  if (!mcpResourceMeta) {
+    throw new PikkuMissingMetaError(
+      `Missing generated metadata for MCP resource '${mcpResource.uri}'`
+    )
+  }
+  addFunction(mcpResourceMeta.pikkuFuncId, mcpResource.func as any)
+  const resources = pikkuState(null, 'mcp', 'resources')
+  if (resources.has(mcpResource.uri)) {
+    throw new Error(`MCP resource already exists: ${mcpResource.uri}`)
+  }
+  resources.set(mcpResource.uri, mcpResource)
+}
+
+export const wireMCPPrompt = <
+  PikkuFunctionConfig extends CorePikkuFunctionConfig<
+    CorePikkuFunctionSessionless<any, any>
+  > = CorePikkuFunctionConfig<CorePikkuFunctionSessionless<any, any>>,
+>(
+  mcpPrompt: CoreMCPPrompt<PikkuFunctionConfig>
+) => {
+  const promptsMeta = pikkuState(null, 'mcp', 'promptsMeta')
+  const mcpPromptMeta = promptsMeta[mcpPrompt.name]
+  if (!mcpPromptMeta) {
+    throw new PikkuMissingMetaError(
+      `Missing generated metadata for MCP prompt '${mcpPrompt.name}'`
+    )
+  }
+  addFunction(mcpPromptMeta.pikkuFuncId, mcpPrompt.func as any)
+  const prompts = pikkuState(null, '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 pikkuFuncId: string | undefined
+  let extractedParams: Record<string, string> = {}
+
+  const metas = pikkuState(null, 'mcp', 'resourcesMeta')
+  const endpoints = pikkuState(null, 'mcp', 'resources')
+
+  if (endpoints.has(uri)) {
+    endpoint = endpoints.get(uri)
+    pikkuFuncId = metas[uri]?.pikkuFuncId
+  } 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
+        pikkuFuncId = metas[uriTemplate]?.pikkuFuncId
+
+        // 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,
+    pikkuFuncId,
+    { ...params, mcp: { ...params.mcp, uri } } as RunMCPEndpointParams<
+      keyof CoreMCPResource
+    >
+  )
+}
+
+export async function runMCPTool(
+  request: JsonRpcRequest,
+  params: RunMCPEndpointParams,
+  name: string
+) {
+  const meta = pikkuState(null, 'mcp', 'toolsMeta')[name]
+  return await runMCPPikkuFunc(
+    request,
+    'tool',
+    name,
+    undefined,
+    meta?.pikkuFuncId,
+    params
+  )
+}
+
+export async function runMCPPrompt(
+  request: JsonRpcRequest,
+  params: RunMCPEndpointParams,
+  name: string
+) {
+  const endpoint = pikkuState(null, 'mcp', 'prompts').get(name)
+  const meta = pikkuState(null, 'mcp', 'promptsMeta')[name]
+  return await runMCPPikkuFunc(
+    request,
+    'prompt',
+    name,
+    endpoint,
+    meta?.pikkuFuncId,
+    params
+  )
+}
+
+/**
+ * JSON-RPC 2.0 compatible MCP endpoint runner
+ */
+async function runMCPPikkuFunc(
+  request: JsonRpcRequest,
+  type: 'resource' | 'tool' | 'prompt',
+  name: string,
+  mcp: CoreMCPResource | CoreMCPPrompt | undefined,
+  pikkuFuncId: string | undefined,
+  { mcp: mcpWire }: RunMCPEndpointParams
+): Promise<JsonRpcResponse> {
+  const singletonServices = getSingletonServices()
+  const createWireServices = getCreateWireServices()
+  let wireServices: any
+
+  try {
+    if (request.jsonrpc !== '2.0') {
+      throw new BadRequestError(
+        'Invalid JSON-RPC version, only supoorted version is 2.0'
+      )
+    }
+
+    if (mcp === undefined && type !== 'tool') {
+      throw new NotFoundError(
+        `MCP '${type}' registration not found for '${name}'`
+      )
+    }
+
+    if (!pikkuFuncId) {
+      throw new NotFoundError(
+        `MCP '${type}' PikkuFunction Mapping not found for '${name}'`
+      )
+    }
+
+    singletonServices.logger.debug(`Running MCP ${type}: ${name}`)
+
+    const mcpSessionService = new PikkuSessionService()
+    const wire: PikkuWire = {
+      mcp: mcpWire,
+      ...createMiddlewareSessionWireProps(mcpSessionService),
+    }
+
+    let meta: any
+    if (type === 'resource') {
+      meta = pikkuState(null, 'mcp', 'resourcesMeta')[name]
+    } else if (type === 'tool') {
+      meta = pikkuState(null, 'mcp', 'toolsMeta')[name]
+    } else if (type === 'prompt') {
+      meta = pikkuState(null, 'mcp', 'promptsMeta')[name]
+    }
+
+    // Resolve namespaced function IDs (e.g., 'swaggerPetstore:findPetsByStatus')
+    let resolvedFuncName = pikkuFuncId
+    let resolvedPackageName: string | null = meta?.packageName ?? null
+    if (pikkuFuncId.includes(':')) {
+      const resolved = resolveNamespace(pikkuFuncId)
+      if (resolved) {
+        resolvedFuncName = resolved.function
+        resolvedPackageName = resolved.package
+      }
+    }
+
+    let result = await runPikkuFunc(
+      'mcp',
+      `${type}:${name}`,
+      resolvedFuncName,
+      {
+        singletonServices,
+        createWireServices,
+        data: () => request.params,
+        inheritedMiddleware: meta?.middleware,
+        wireMiddleware: mcp?.middleware,
+        inheritedPermissions: meta?.permissions,
+        wirePermissions: mcp?.permissions,
+        tags: mcp?.tags,
+        wire,
+        sessionService: mcpSessionService,
+        packageName: resolvedPackageName,
+      }
+    )
+
+    if (type === 'tool' && meta?.outputSchema !== 'MCPToolResponse') {
+      result = [{ type: 'text', text: JSON.stringify(result) }]
+    }
+
+    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 (wireServices) {
+      await closeWireServices(singletonServices.logger, wireServices)
+    }
+  }
+}
+
+export const getMCPResources = () => {
+  return pikkuState(null, 'mcp', 'resources')
+}
+
+export const getMCPResourcesMeta = () => {
+  return pikkuState(null, 'mcp', 'resourcesMeta')
+}
+
+export const getMCPToolsMeta = () => {
+  return pikkuState(null, 'mcp', 'toolsMeta')
+}
+
+export const getMCPPrompts = () => {
+  return pikkuState(null, 'mcp', 'prompts')
+}
+
+export const getMCPPromptsMeta = () => {
+  return pikkuState(null, 'mcp', 'promptsMeta')
+}

package/src/wirings/mcp/mcp.types.ts

@@ -0,0 +1,216 @@
+import type {
+  CorePermissionGroup,
+  CorePikkuFunctionConfig,
+  CorePikkuFunctionSessionless,
+  CorePikkuPermission,
+} from '../../function/functions.types.js'
+import type {
+  CorePikkuMiddleware,
+  MiddlewareMetadata,
+  PermissionMetadata,
+} from '../../types/core.types.js'
+
+/**
+ * Extract URI parameters from MCP resource URI template.
+ * E.g., "user/{userId}/post/{postId}" => "userId" | "postId"
+ */
+type ExtractMCPURIParams<S extends string> =
+  S extends `${string}{${infer Param}}/${infer Rest}`
+    ? Param | ExtractMCPURIParams<Rest>
+    : S extends `${string}{${infer Param}}`
+      ? Param
+      : never
+
+/**
+ * Type-level assertion that MCP resource URI parameters are present in the input type.
+ * This ensures compile-time safety for URI parameter validation.
+ */
+export type AssertMCPResourceURIParams<In, URI extends string> =
+  ExtractMCPURIParams<URI> extends keyof In
+    ? unknown
+    : [
+        'Error: MCP Resource URI parameters',
+        ExtractMCPURIParams<URI>,
+        'not in input type',
+        keyof In,
+      ]
+
+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' | 'middleware' | 'permissions'> & {
+    pikkuFuncId: string
+    inputSchema: string | null
+    outputSchema: string | null
+    middleware?: MiddlewareMetadata[] // Pre-resolved middleware chain (tag + explicit)
+    permissions?: PermissionMetadata[] // Pre-resolved permission chain (tag + explicit)
+  }
+>
+
+/**
+ * Represents metadata for MCP tools, including name, description, and documentation.
+ */
+export type MCPToolMeta = Record<
+  string,
+  Omit<CoreMCPTool, 'func' | 'middleware' | 'permissions'> & {
+    pikkuFuncId: string
+    inputSchema: string | null
+    outputSchema: string | null
+    middleware?: MiddlewareMetadata[] // Pre-resolved middleware chain (tag + explicit)
+    permissions?: PermissionMetadata[] // Pre-resolved permission chain (tag + explicit)
+  }
+>
+
+/**
+ * Represents metadata for MCP prompts, including name, description, and arguments.
+ */
+export type MCPPromptMeta = Record<
+  string,
+  Omit<CoreMCPPrompt, 'func' | 'middleware' | 'permissions'> & {
+    pikkuFuncId: string
+    inputSchema: string | null
+    outputSchema: string | null
+    arguments: Array<{
+      name: string
+      description: string
+      required: boolean
+    }>
+    middleware?: MiddlewareMetadata[] // Pre-resolved middleware chain (tag + explicit)
+    permissions?: PermissionMetadata[] // Pre-resolved permission chain (tag + explicit)
+  }
+>
+
+/**
+ * Represents an MCP resource with specific properties.
+ */
+export type CoreMCPResource<
+  PikkuFunctionConfig = CorePikkuFunctionConfig<
+    CorePikkuFunctionSessionless<any, any>
+  >,
+  PikkuPermission = CorePikkuPermission<any, any>,
+  PikkuMiddleware = CorePikkuMiddleware<any>,
+> = {
+  uri: string
+  title: string
+  description: string
+  summary?: string
+  errors?: string[]
+  mimeType?: string
+  size?: number
+  streaming?: boolean
+  func: PikkuFunctionConfig
+  tags?: string[]
+  middleware?: PikkuMiddleware[]
+  permissions?: CorePermissionGroup<PikkuPermission>
+}
+
+/**
+ * Represents an MCP tool with specific properties.
+ */
+export type CoreMCPTool<
+  PikkuFunctionConfig = CorePikkuFunctionConfig<
+    CorePikkuFunctionSessionless<any, any>
+  >,
+  PikkuPermission = CorePikkuPermission<any, any>,
+  PikkuMiddleware = CorePikkuMiddleware<any>,
+> = {
+  name: string
+  title?: string
+  description: string
+  summary?: string
+  errors?: string[]
+  func: PikkuFunctionConfig
+  tags?: string[]
+  streaming?: boolean
+  middleware?: PikkuMiddleware[]
+  permissions?: CorePermissionGroup<PikkuPermission>
+}
+
+/**
+ * Represents an MCP prompt with specific properties.
+ */
+export type CoreMCPPrompt<
+  PikkuFunctionConfig = CorePikkuFunctionConfig<
+    CorePikkuFunctionSessionless<any, MCPPromptResponse>
+  >,
+  PikkuPermission = CorePikkuPermission<any, any>,
+  PikkuMiddleware = CorePikkuMiddleware<any>,
+> = {
+  name: string
+  description: string
+  summary?: string
+  errors?: string[]
+  func: PikkuFunctionConfig
+  tags?: string[]
+  middleware?: PikkuMiddleware[]
+  permissions?: CorePermissionGroup<PikkuPermission>
+}
+
+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/wirings/node/index.ts

@@ -0,0 +1,2 @@
+export type { CoreNodeConfig, NodeType } from './node.types.js'
+export type { NodesMeta } from './node.types.js'

package/src/wirings/node/node.types.ts

@@ -0,0 +1,23 @@
+export type NodeType = 'trigger' | 'action' | 'end'
+
+export type CoreNodeConfig = {
+  displayName: string
+  category: string
+  type: NodeType
+  errorOutput?: boolean
+}
+
+export type NodeMeta = {
+  name: string
+  displayName: string
+  category: string
+  type: NodeType
+  rpc: string
+  description?: string
+  errorOutput: boolean
+  inputSchemaName: string | null
+  outputSchemaName: string | null
+  tags?: string[]
+}
+
+export type NodesMeta = Record<string, NodeMeta>

package/src/wirings/oauth2/index.ts

@@ -0,0 +1,3 @@
+export { OAuth2Client } from './oauth2-client.js'
+export { wireOAuth2Credential } from './wire-oauth2-credential.js'
+export type { OAuth2AppCredential, OAuth2Token } from './oauth2.types.js'