Modelcontextprotocol

Pikku is a TypeScript-powered framework that normalizes all the different ways you can interact with Node.js servers. It provides a unified approach to handling HTTP requests, WebSocket connections, scheduled tasks, and channels across different runtime environments.

Type-safe, runtime-agnostic, batteries included.

Quick Start

npm create pikku@latest my-app
cd my-app
npm run dev

Features

• 🔐 Type Safety - Full TypeScript support with auto-generated type-safe clients
• 🌍 Runtime Agnostic - Works on Express, Fastify, Next.js, AWS Lambda, Cloudflare Workers, and more
• ⚡ Performance Optimized - Smart routing with static route optimization and middleware caching
• 🔋 Batteries Included - HTTP handlers, WebSocket channels, scheduled tasks, and pub/sub out of the box
• 🛠️ Great DX - Code generation, OpenAPI docs, and excellent tooling support
• 🎯 Unified API - Handle data from params, query, or body without knowing the source

Core Concepts

PikkuFunc - The Heart of Pikku

At the core of Pikku is the pikkuFunc - a unified function that handles data from any source:

import { pikkuFunc } from '#pikku/function'

const addGithubStar = pikkuFunc<
  { repo: string },
  { success: boolean; repo: string }
>({
  func: async ({ githubService }, { repo }, { session }) => {
    const currentSession = await session?.get()
    await githubService.addStar(repo, currentSession.userId)
    return { success: true, repo }
  },
  auth: true, // Whether a session is needed for function to be invoked
  permissions: {}, // Permissions to run before function is invoked
  middleware: [logUsage, rateLimit], // Middleware to wrap functions
  docs: {
    name: 'Github star',
    description: 'Used to add stars to repos!',
  },
  expose: true, // Expose this function via RPC
})

Services - Dependency Injection Made Simple

Services are initialized at server startup and available to all functions. Pikku uses two types of services:

import { pikkuServices, pikkuWireServices } from '#pikku/setup'
import { ConsoleLogger, LocalVariablesService } from '@pikku/core/services'

// Singleton services - created once at startup
export const createSingletonServices = pikkuServices(async (config) => {
  const variables = new LocalVariablesService()
  const logger = new ConsoleLogger()
  const db = new DatabaseClient()

  return { variables, logger, db }
})

// Wire services - created per request
export const createWireServices = pikkuWireServices(
  async (singletonServices, wire) => {
    return {}
  }
)

Type Generation

Pikku automatically generates type-safe clients from your API definitions:

npx pikku all

Generates:

• pikku-fetch.gen.ts - HTTP client
• pikku-websocket.gen.ts - WebSocket client
• Full TypeScript definitions

Runtime Support

Pikku works across multiple runtime environments:

Example: One Function, Multiple Ways

Wire it up to HTTP:

wireHTTP({
  route: '/api/github/star',
  method: 'post',
  func: addGithubStar,
  auth: true,
})

Wire it to WebSocket channels:

wireChannel({
  route: '/ws/github',
  name: 'github-api',
  onMessage: {
    addStar: addGithubStar,
  },
  auth: true,
})

Wire it to queue processing:

wireQueueWorker({
  name: 'github-star-queue',
  func: addGithubStar,
})

Offer it as an MCP tool by setting mcp: true on the function:

const addGithubStar = pikkuFunc<{ repo: string }, { success: boolean }>({
  func: async ({ githubService }, { repo }) => {
    /* … */
  },
  mcp: true,
})

Wire a scheduled task (different function since no input/output):

const logStarCount = pikkuVoidFunc(async ({ githubService, logger }) => {
  const count = await githubService.getTotalStars()
  logger.info(`Total GitHub stars: ${count}`)
})

wireScheduler({
  name: 'star-counter',
  schedule: '0 0 * * *', // daily
  func: logStarCount,
})

Documentation

The documentation is available at pikku.dev.

Migration

Upgrading from an earlier 0.12 release? See docs/MIGRATION.md.

Contributing

We welcome contributions! The repository is a bun workspace (bun 1.4, Node.js 24 or later):

bun install
bun run build:packages
bun run test

See our Contributing Guide for details on:

• Setting up the development environment
• Running tests and type checking
• Submitting pull requests
• Creating runtime adapters

Community

• GitHub Discussions
• Discord Server
• X/Twitter

Contributors

Thanks to all contributors!

License

Pikku uses a dual licensing approach:

• Core packages (@pikku/core, @pikku/* runtimes, services, etc.) - MIT License
• Inspector and CLI (@pikku/inspector, @pikku/cli) - Business Source License 1.1 (converts to MIT after 4 years)

See LICENSE for full details. The BSL restriction only prohibits offering commercial visual development tools for Pikku. Free and open source alternatives are welcome!

Contributors: By submitting a pull request, you agree to our CLA.