pikkujs/pikku-mongodb
.claude/skills/pikku-mongodb/SKILL.md
Use when setting up MongoDB database services in a Pikku app. Covers PikkuMongoDB connection, channel stores, workflow services, secret services, AI storage, agent runs, and deployment services. TRIGGER when: code uses PikkuMongoDB, MongoDBChannelStore, MongoDBWorkflowService, MongoDBSecretService, or user asks about MongoDB setup with Pikku. DO NOT TRIGGER when: user asks about SQL databases (use pikku-kysely) or Redis (use pikku-redis).
$ install --global
skillsauthnpx skillsauth add pikkujs/pikku pikku-mongodbInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Apr 15, 2026, 9:50 PM7.3s1 file scanned
SKILL.md
- name:
- pikku-mongodb
- description:
- Use when setting up MongoDB database services in a Pikku app. Covers PikkuMongoDB connection, channel stores, workflow services, secret services, AI storage, agent runs, and deployment services.
- TRIGGER when:
- code uses PikkuMongoDB, MongoDBChannelStore, MongoDBWorkflowService, MongoDBSecretService, or user asks about MongoDB setup with Pikku.
- DO NOT TRIGGER when:
- user asks about SQL databases (use pikku-kysely) or Redis (use pikku-redis).
Pikku MongoDB
@pikku/mongodb provides MongoDB-backed implementations of Pikku's core service interfaces.
Installation
yarn add @pikku/mongodb
API Reference
PikkuMongoDB (Connection Wrapper)
import { PikkuMongoDB } from '@pikku/mongodb'
const mongo = new PikkuMongoDB(
logger: Logger,
clientOrUri: MongoClient | string,
dbName: string,
options?: MongoClientOptions
)
await mongo.init()
mongo.db // Db instance for queries
await mongo.close()
Available Services
| Service | Interface | Purpose |
|---------|-----------|---------|
| MongoDBChannelStore | ChannelStore | WebSocket channel state persistence |
| MongoDBEventHubStore | EventHubStore | Event hub state persistence |
| MongoDBWorkflowService | PikkuWorkflowService | Workflow definition storage |
| MongoDBWorkflowRunService | WorkflowRunService | Workflow execution tracking |
| MongoDBDeploymentService | DeploymentService | Deployment state management |
| MongoDBAIStorageService | AIStorageService, AIRunStateService | AI conversation/run storage |
| MongoDBAgentRunService | AgentRunService | Agent execution tracking |
| MongoDBSecretService | SecretService | Encrypted secret storage (envelope encryption) |
All services take a Db instance in their constructor and have an init() method that creates collections/indexes.
Secret Service
import { MongoDBSecretService } from '@pikku/mongodb'
const secrets = new MongoDBSecretService(mongo.db, {
kekSecret: 'your-key-encryption-key',
salt: 'your-salt',
})
await secrets.init()
await secrets.setSecretJSON('api-key', { key: 'sk-...' })
const value = await secrets.getSecretJSON<{ key: string }>('api-key')
await secrets.rotateKEK()
Usage Patterns
Full Setup
import { PikkuMongoDB, MongoDBChannelStore, MongoDBWorkflowService } from '@pikku/mongodb'
const createSingletonServices = pikkuServices(async (config) => {
const logger = new PinoLogger()
const mongo = new PikkuMongoDB(logger, config.mongoUri, 'myapp')
await mongo.init()
const channelStore = new MongoDBChannelStore(mongo.db)
await channelStore.init()
const workflowService = new MongoDBWorkflowService(mongo.db)
await workflowService.init()
return { config, logger, database: mongo, channelStore, workflowService }
})
Related Skills
pikkujs/pikku-tag-middleware
documentation
VerifiedTrustedCommunity
Deprecated — use pikku-middleware instead. Tag middleware (addTagMiddleware) is now documented as a section within the pikku-middleware skill, alongside global HTTP middleware, execution order, and the service-to-service bearer auth pattern.
56SKILL.mdUpdated Jun 10, 2026
pikkujs/pikku-permissions
testing
VerifiedTrustedCommunity
Use when adding authorization checks to Pikku functions or routes — pikkuPermission, pikkuAuth, per-function permissions, pattern-based permissions, or understanding OR/AND permission logic. TRIGGER when: user wants to restrict who can call a function, check resource ownership, add role-based access, or understand where permission checks belong. DO NOT TRIGGER when: user asks about middleware or request interception (use pikku-middleware), authentication strategies (use pikku-security), or session management.
56SKILL.mdUpdated Jun 10, 2026
pikkujs/pikku-middleware
testing
VerifiedTrustedCommunity
Use when adding any middleware to a Pikku app — global HTTP middleware, tag-scoped middleware (including service-to-service bearer auth), per-route middleware, session-setting middleware, or understanding middleware execution order and priority. TRIGGER when: user wants middleware on some or all routes, machine-to-machine auth, tag-scoped cross-cutting concerns, global interceptors, or middleware priority/order questions. DO NOT TRIGGER when: user asks about permissions/authorization checks (use pikku-permissions), auth strategies like authBearer/authCookie (use pikku-security), or deployment.
56SKILL.mdUpdated Jun 10, 2026
pikkujs/pikku-template-clone
documentation
VerifiedTrustedCommunity
Standard cleanup to run right after a Pikku template is cloned or scaffolded into a new project. TRIGGER when: a Pikku template was just cloned/scaffolded (via `pikku create`, `git clone <template>`, or the user says "I cloned the kanban template / starter / template"), or the working tree still looks like an untouched template (template README, placeholder `@project/*` name in package.json). DO NOT TRIGGER when: working in an established project mid-feature, or editing the template repo itself.
56SKILL.mdUpdated Jun 4, 2026