@pikku/core 0.12.4 → 0.12.6

package/src/wirings/http/web-request.ts

@@ -0,0 +1,104 @@
+import type { PikkuHTTPRequest } from './http.types.js'
+import type { PikkuHTTPResponse } from './http.types.js'
+
+/**
+ * Converts a PikkuHTTPRequest into a Web API Request.
+ * Useful for bridging Pikku routes to libraries that expect standard Web Request objects.
+ */
+export function toWebRequest(req: PikkuHTTPRequest, baseUrl?: string): Request {
+  const url = new URL(
+    req.path(),
+    baseUrl ?? `http://${req.header('host') ?? 'localhost'}`
+  )
+
+  const query = req.query()
+  for (const [key, value] of Object.entries(query)) {
+    if (value != null) {
+      url.searchParams.set(key, String(value))
+    }
+  }
+
+  const headers = new Headers(req.headers())
+
+  const method = req.method().toUpperCase()
+  const hasBody = !['GET', 'HEAD', 'OPTIONS'].includes(method)
+
+  if (!hasBody) {
+    return new Request(url, { method, headers })
+  }
+
+  return new Request(url, {
+    method,
+    headers,
+    body: new ReadableStream({
+      async start(controller) {
+        try {
+          const buffer = await req.arrayBuffer()
+          if (buffer.byteLength > 0) {
+            controller.enqueue(new Uint8Array(buffer))
+          } else {
+            // arrayBuffer may be empty if body was pre-parsed (e.g., Express middleware)
+            const contentType = (
+              headers.get('content-type') || ''
+            ).toLowerCase()
+            const parsed = await req.json()
+            if (
+              parsed &&
+              typeof parsed === 'object' &&
+              Object.keys(parsed as any).length > 0
+            ) {
+              let reconstructed: string
+              if (contentType.includes('application/x-www-form-urlencoded')) {
+                reconstructed = new URLSearchParams(
+                  parsed as Record<string, string>
+                ).toString()
+              } else {
+                reconstructed = JSON.stringify(parsed)
+              }
+              controller.enqueue(new TextEncoder().encode(reconstructed))
+            }
+          }
+        } catch {
+          // Empty body
+        }
+        controller.close()
+      },
+    }),
+    // @ts-ignore - duplex is needed for streaming body in Node.js
+    duplex: 'half',
+  })
+}
+
+const SKIP_RESPONSE_HEADERS = new Set(['content-length', 'transfer-encoding'])
+
+/**
+ * Applies a Web API Response to a PikkuHTTPResponse.
+ * Copies status, headers (including Set-Cookie), redirects, and body.
+ */
+export async function applyWebResponse(
+  res: PikkuHTTPResponse,
+  webResponse: Response
+): Promise<void> {
+  res.status(webResponse.status)
+
+  webResponse.headers.forEach((value, name) => {
+    const lower = name.toLowerCase()
+    if (SKIP_RESPONSE_HEADERS.has(lower)) {
+      return
+    }
+    if (lower === 'location') {
+      res.redirect(value, webResponse.status)
+    } else {
+      res.header(name, value)
+    }
+  })
+
+  const body = await webResponse.text()
+  if (body) {
+    if (res.send) {
+      res.send(body)
+    } else {
+      res.arrayBuffer(body)
+    }
+  }
+}

package/src/wirings/mcp/index.ts

@@ -0,0 +1,27 @@
+export { MCPEndpointRegistry } from './mcp-endpoint-registry.js'
+export {
+  MCPError,
+  wireMCPResource,
+  wireMCPPrompt,
+  runMCPResource,
+  runMCPTool,
+  runMCPPrompt,
+} from './mcp-runner.js'
+export {
+  getMCPResourcesMeta,
+  getMCPToolsMeta,
+  getMCPPromptsMeta,
+} from './mcp-runner.js'
+export type {
+  AssertMCPResourceURIParams,
+  CoreMCPPrompt,
+  CoreMCPResource,
+  CoreMCPTool,
+  MCPPromptResponse,
+  MCPResourceMeta,
+  MCPResourceResponse,
+  MCPToolMeta,
+  MCPToolResponse,
+  MCPPromptMeta,
+  PikkuMCP,
+} from './mcp.types.js'

package/src/wirings/mcp/mcp-endpoint-registry.test.ts

@@ -0,0 +1,389 @@
+import { test, describe, beforeEach } from 'node:test'
+import * as assert from 'assert'
+import { MCPEndpointRegistry } from './mcp-endpoint-registry.js'
+
+describe('MCPEndpointRegistry', () => {
+  let registry: MCPEndpointRegistry
+
+  beforeEach(() => {
+    registry = new MCPEndpointRegistry()
+  })
+
+  describe('constructor', () => {
+    test('should initialize with empty maps', () => {
+      assert.deepStrictEqual(registry.getTools(), [])
+      assert.deepStrictEqual(registry.getResources(), [])
+      assert.deepStrictEqual(registry.getPrompts(), [])
+    })
+  })
+
+  describe('loadFromMCPJson', () => {
+    test('should load tools from MCP JSON', async () => {
+      const mockData = {
+        tools: [
+          {
+            name: 'test-tool',
+            title: 'Test Tool',
+            description: 'A test tool',
+            parameters: { type: 'object' },
+            returns: { type: 'string' },
+            enabled: true,
+          },
+        ],
+      }
+
+      await registry.loadFromMCPJson(mockData)
+
+      const tools = registry.getTools()
+      assert.strictEqual(tools.length, 1)
+      assert.strictEqual(tools[0].name, 'test-tool')
+      assert.strictEqual(tools[0].title, 'Test Tool')
+      assert.strictEqual(tools[0].description, 'A test tool')
+      assert.deepStrictEqual(tools[0].inputSchema, { type: 'object' })
+      assert.deepStrictEqual(tools[0].outputSchema, { type: 'string' })
+      assert.strictEqual(tools[0].enabled, true)
+    })
+
+    test('should load resources from MCP JSON', async () => {
+      const mockData = {
+        resources: [
+          {
+            name: 'test-resource',
+            uri: 'file://test.txt',
+            description: 'A test resource',
+            parameters: { type: 'object' },
+            enabled: false,
+          },
+        ],
+      }
+
+      await registry.loadFromMCPJson(mockData)
+
+      const resources = registry.getResources()
+      assert.strictEqual(resources.length, 1)
+      assert.strictEqual(resources[0].title, 'test-resource')
+      assert.strictEqual(resources[0].uri, 'file://test.txt')
+      assert.strictEqual(resources[0].description, 'A test resource')
+      assert.deepStrictEqual(resources[0].inputSchema, { type: 'object' })
+      assert.strictEqual(resources[0].enabled, false)
+    })
+
+    test('should load prompts from MCP JSON', async () => {
+      const mockData = {
+        prompts: [
+          {
+            name: 'test-prompt',
+            description: 'A test prompt',
+            arguments: { type: 'object' },
+          },
+        ],
+      }
+
+      await registry.loadFromMCPJson(mockData)
+
+      const prompts = registry.getPrompts()
+      assert.strictEqual(prompts.length, 1)
+      assert.strictEqual(prompts[0].name, 'test-prompt')
+      assert.strictEqual(prompts[0].description, 'A test prompt')
+      assert.deepStrictEqual(prompts[0].inputSchema, { type: 'object' })
+      assert.strictEqual(prompts[0].enabled, true)
+    })
+
+    test('should handle tools with default enabled state', async () => {
+      const mockData = {
+        tools: [
+          {
+            name: 'default-tool',
+            title: 'Default Tool',
+            description: 'Tool with default enabled state',
+          },
+        ],
+      }
+
+      await registry.loadFromMCPJson(mockData)
+
+      const tools = registry.getTools()
+      assert.strictEqual(tools.length, 1)
+      assert.strictEqual(tools[0].enabled, true)
+    })
+
+    test('should handle empty arrays', async () => {
+      const mockData = {
+        tools: [],
+        resources: [],
+        prompts: [],
+      }
+
+      await registry.loadFromMCPJson(mockData)
+
+      assert.deepStrictEqual(registry.getTools(), [])
+      assert.deepStrictEqual(registry.getResources(), [])
+      assert.deepStrictEqual(registry.getPrompts(), [])
+    })
+
+    test('should handle missing arrays', async () => {
+      const mockData = {}
+
+      await registry.loadFromMCPJson(mockData)
+
+      assert.deepStrictEqual(registry.getTools(), [])
+      assert.deepStrictEqual(registry.getResources(), [])
+      assert.deepStrictEqual(registry.getPrompts(), [])
+    })
+
+    test('should handle empty object gracefully', async () => {
+      // Test with empty object
+      await registry.loadFromMCPJson({})
+      assert.deepStrictEqual(registry.getTools(), [])
+      assert.deepStrictEqual(registry.getResources(), [])
+      assert.deepStrictEqual(registry.getPrompts(), [])
+    })
+  })
+
+  describe('meta setters and getters', () => {
+    test('should set and check resource meta', () => {
+      const meta = {
+        'test-resource': {
+          uri: 'file://test.txt',
+          title: 'Test Resource',
+          description: 'Test description',
+          pikkuFuncId: 'testResource',
+          inputSchema: null,
+          outputSchema: null,
+          mimeType: 'text/plain',
+        },
+      }
+      registry.setResourcesMeta(meta)
+      assert.strictEqual(registry.hasResource('test-resource'), true)
+      assert.strictEqual(registry.hasResource('nonexistent'), false)
+    })
+
+    test('should set and check tool meta', () => {
+      const meta = {
+        'test-tool': {
+          name: 'test-tool',
+          title: 'Test Tool',
+          description: 'Test description',
+          pikkuFuncId: 'testTool',
+          inputSchema: null,
+          outputSchema: null,
+        },
+      }
+      registry.setToolsMeta(meta)
+      assert.strictEqual(registry.hasTool('test-tool'), true)
+      assert.strictEqual(registry.hasTool('nonexistent'), false)
+    })
+
+    test('should set and check prompt meta', () => {
+      const meta = {
+        'test-prompt': {
+          name: 'test-prompt',
+          description: 'Test Prompt',
+          pikkuFuncId: 'testPrompt',
+          inputSchema: null,
+          outputSchema: null,
+          arguments: [],
+        },
+      }
+      registry.setPromptsMeta(meta)
+      assert.strictEqual(registry.hasPrompt('test-prompt'), true)
+      assert.strictEqual(registry.hasPrompt('nonexistent'), false)
+    })
+  })
+
+  describe('individual item getters', () => {
+    beforeEach(async () => {
+      const mockData = {
+        tools: [
+          {
+            name: 'tool1',
+            title: 'Tool 1',
+            description: 'First tool',
+            enabled: true,
+          },
+        ],
+        resources: [
+          {
+            name: 'resource1',
+            uri: 'file://resource1.txt',
+            description: 'First resource',
+            enabled: true,
+          },
+        ],
+        prompts: [
+          {
+            name: 'prompt1',
+            description: 'First prompt',
+            enabled: true,
+          },
+        ],
+      }
+
+      await registry.loadFromMCPJson(mockData)
+    })
+
+    test('should get tool by name', () => {
+      const tool = registry.getTool('tool1')
+      assert.strictEqual(tool?.name, 'tool1')
+      assert.strictEqual(tool?.title, 'Tool 1')
+      assert.strictEqual(registry.getTool('nonexistent'), undefined)
+    })
+
+    test('should get resource by name', () => {
+      const resource = registry.getResource('resource1')
+      assert.strictEqual(resource?.title, 'resource1')
+      assert.strictEqual(resource?.uri, 'file://resource1.txt')
+      assert.strictEqual(registry.getResource('nonexistent'), undefined)
+    })
+
+    test('should get prompt by name', () => {
+      const prompt = registry.getPrompt('prompt1')
+      assert.strictEqual(prompt?.name, 'prompt1')
+      assert.strictEqual(prompt?.description, 'First prompt')
+      assert.strictEqual(registry.getPrompt('nonexistent'), undefined)
+    })
+  })
+
+  describe('getTools filters enabled tools', () => {
+    test('should only return enabled tools', async () => {
+      const mockData = {
+        tools: [
+          {
+            name: 'enabled-tool',
+            title: 'Enabled Tool',
+            description: 'This tool is enabled',
+            enabled: true,
+          },
+          {
+            name: 'disabled-tool',
+            title: 'Disabled Tool',
+            description: 'This tool is disabled',
+            enabled: false,
+          },
+        ],
+      }
+
+      await registry.loadFromMCPJson(mockData)
+
+      const tools = registry.getTools()
+      assert.strictEqual(tools.length, 1)
+      assert.strictEqual(tools[0].name, 'enabled-tool')
+    })
+  })
+
+  describe('enable/disable methods', () => {
+    beforeEach(async () => {
+      const mockData = {
+        tools: [
+          {
+            name: 'tool1',
+            title: 'Tool 1',
+            description: 'First tool',
+            enabled: true,
+          },
+          {
+            name: 'tool2',
+            title: 'Tool 2',
+            description: 'Second tool',
+            enabled: false,
+          },
+        ],
+        resources: [
+          {
+            name: 'resource1',
+            uri: 'file://resource1.txt',
+            description: 'First resource',
+            enabled: true,
+          },
+        ],
+        prompts: [
+          {
+            name: 'prompt1',
+            description: 'First prompt',
+            enabled: true,
+          },
+        ],
+      }
+
+      await registry.loadFromMCPJson(mockData)
+    })
+
+    test('should enable/disable tools and return change status', () => {
+      let changed = registry.enableTools({ tool1: false, tool2: true })
+      assert.strictEqual(changed, true)
+
+      const tool1 = registry.getTool('tool1')
+      const tool2 = registry.getTool('tool2')
+      assert.strictEqual(tool1?.enabled, false)
+      assert.strictEqual(tool2?.enabled, true)
+
+      changed = registry.enableTools({ tool1: false, tool2: true })
+      assert.strictEqual(changed, false)
+    })
+
+    test('should handle nonexistent tools', () => {
+      const changed = registry.enableTools({ nonexistent: true })
+      assert.strictEqual(changed, false)
+    })
+
+    test('should enable/disable prompts and return change status', () => {
+      let changed = registry.enablePrompts({ prompt1: false })
+      assert.strictEqual(changed, true)
+
+      const prompt1 = registry.getPrompt('prompt1')
+      assert.strictEqual(prompt1?.enabled, false)
+
+      changed = registry.enablePrompts({ prompt1: false })
+      assert.strictEqual(changed, false)
+    })
+
+    test('should handle nonexistent prompts', () => {
+      const changed = registry.enablePrompts({ nonexistent: true })
+      assert.strictEqual(changed, false)
+    })
+
+    test('should enable/disable resources', () => {
+      const changed = registry.enableResources({ resource1: false })
+      assert.strictEqual(changed, true)
+
+      const resource1 = registry.getResource('resource1')
+      assert.strictEqual(resource1?.enabled, false)
+    })
+  })
+
+  describe('edge cases', () => {
+    test('should handle null/undefined values in MCP JSON', async () => {
+      const mockData = {
+        tools: [
+          {
+            name: 'incomplete-tool',
+            title: null,
+            description: undefined,
+          },
+        ],
+      }
+
+      await registry.loadFromMCPJson(mockData)
+
+      const tools = registry.getTools()
+      assert.strictEqual(tools.length, 1)
+      assert.strictEqual(tools[0].name, 'incomplete-tool')
+      assert.strictEqual(tools[0].title, null)
+      assert.strictEqual(tools[0].description, undefined)
+    })
+
+    test('should handle non-array values for tools/resources/prompts', async () => {
+      const mockData = {
+        tools: 'not an array',
+        resources: null,
+        prompts: undefined,
+      }
+
+      await registry.loadFromMCPJson(mockData)
+
+      assert.deepStrictEqual(registry.getTools(), [])
+      assert.deepStrictEqual(registry.getResources(), [])
+      assert.deepStrictEqual(registry.getPrompts(), [])
+    })
+  })
+})

package/src/wirings/mcp/mcp-endpoint-registry.ts

@@ -0,0 +1,159 @@
+import type {
+  MCPResourceMeta,
+  MCPToolMeta,
+  MCPPromptMeta,
+} from '@pikku/core/mcp'
+
+export interface MCPToolEndpoint {
+  name: string
+  title: string
+  description: string
+  inputSchema?: any
+  outputSchema?: any
+  enabled: boolean
+}
+
+export interface MCPResourceEndpoint {
+  uri: string
+  title: string
+  description: string
+  inputSchema?: any
+  mimeType?: string
+  enabled: boolean
+}
+
+export interface MCPPromptEndpoint {
+  name: string
+  description: string
+  inputSchema?: any
+  enabled: boolean
+}
+
+export class MCPEndpointRegistry {
+  private tools: Map<string, MCPToolEndpoint> = new Map()
+  private resources: Map<string, MCPResourceEndpoint> = new Map()
+  private prompts: Map<string, MCPPromptEndpoint> = new Map()
+  private resourcesMeta: MCPResourceMeta = {}
+  private toolsMeta: MCPToolMeta = {}
+  private promptsMeta: MCPPromptMeta = {}
+
+  async loadFromMCPJson(mcpData: any): Promise<void> {
+    if (mcpData.tools && Array.isArray(mcpData.tools)) {
+      for (const tool of mcpData.tools) {
+        this.tools.set(tool.name, {
+          name: tool.name,
+          title: tool.title,
+          description: tool.description,
+          inputSchema: tool.parameters ?? { type: 'object' },
+          outputSchema: tool.returns,
+          enabled: tool.enabled !== undefined ? tool.enabled : true,
+        })
+      }
+    }
+    if (mcpData.resources && Array.isArray(mcpData.resources)) {
+      for (const resource of mcpData.resources) {
+        this.resources.set(resource.name, {
+          title: resource.name,
+          uri: resource.uri,
+          description: resource.description,
+          inputSchema: resource.parameters,
+          enabled: resource.enabled !== undefined ? resource.enabled : true,
+        })
+      }
+    }
+    if (mcpData.prompts && Array.isArray(mcpData.prompts)) {
+      for (const prompt of mcpData.prompts) {
+        this.prompts.set(prompt.name, {
+          name: prompt.name,
+          description: prompt.description,
+          inputSchema: prompt.arguments,
+          enabled: prompt.enabled !== undefined ? prompt.enabled : true,
+        })
+      }
+    }
+  }
+
+  setResourcesMeta(meta: MCPResourceMeta): void {
+    this.resourcesMeta = meta
+  }
+
+  setToolsMeta(meta: MCPToolMeta): void {
+    this.toolsMeta = meta
+  }
+
+  setPromptsMeta(meta: MCPPromptMeta): void {
+    this.promptsMeta = meta
+  }
+
+  getTools(): MCPToolEndpoint[] {
+    return Array.from(this.tools.values()).filter((tool) => tool.enabled)
+  }
+
+  getResources(): MCPResourceEndpoint[] {
+    return Array.from(this.resources.values())
+  }
+
+  getPrompts(): MCPPromptEndpoint[] {
+    return Array.from(this.prompts.values())
+  }
+
+  getTool(name: string): MCPToolEndpoint | undefined {
+    return this.tools.get(name)
+  }
+
+  getResource(name: string): MCPResourceEndpoint | undefined {
+    return this.resources.get(name)
+  }
+
+  getPrompt(name: string): MCPPromptEndpoint | undefined {
+    return this.prompts.get(name)
+  }
+
+  hasResource(name: string): boolean {
+    return name in this.resourcesMeta
+  }
+
+  hasTool(name: string): boolean {
+    return name in this.toolsMeta
+  }
+
+  hasPrompt(name: string): boolean {
+    return name in this.promptsMeta
+  }
+
+  enableTools(tools: Record<any, boolean>): boolean {
+    let changed = false
+    for (const [name, enabled] of Object.entries(tools)) {
+      const tool = this.tools.get(name)
+      if (tool && tool.enabled !== enabled) {
+        tool.enabled = enabled
+        changed = true
+      }
+    }
+    return changed
+  }
+
+  enablePrompts(prompts: Record<any, boolean>): boolean {
+    let changed = false
+    for (const [name, enabled] of Object.entries(prompts)) {
+      const prompt = this.prompts.get(name)
+      if (prompt && prompt.enabled !== enabled) {
+        prompt.enabled = enabled
+        changed = true
+      }
+    }
+    return changed
+  }
+
+  enableResources(resources: Record<any, boolean>): boolean {
+    let changed = false
+    for (const [name, enabled] of Object.entries(resources)) {
+      const resource = this.resources.get(name)
+      if (resource && resource.enabled !== enabled) {
+        resource.enabled = enabled
+        changed = true
+      }
+    }
+    return changed
+  }
+}