+ +
+ Generated content...
", + "representation": "storage" + } + } + }' +``` + +--- + +## Common Pitfalls + +- **Docs written once, never updated** β add doc updates to PR checklist +- **Missing local setup step** β test setup instructions on a fresh machine quarterly +- **No error troubleshooting** β debugging section is the most valuable part for new hires +- **Too much detail for contractors** β they need task-specific, not architecture-deep docs +- **No screenshots** β UI flows need screenshots; they go stale but are still valuable +- **Skipping the "why"** β document why decisions were made, not just what was decided + +--- + +## Best Practices + +1. **Keep setup under 10 minutes** β if it takes longer, fix the setup, not the docs +2. **Test the docs** β have a new hire follow them literally, fix every gap they hit +3. **Link, don't repeat** β link to ADRs, issues, and external docs instead of duplicating +4. **Update in the same PR** β docs changes alongside code changes +5. **Version-specific notes** β call out things that changed in recent versions +6. **Runbooks over theory** β "run this command" beats "the system uses Redis for..." diff --git a/engineering/database-schema-designer/SKILL.md b/engineering/database-schema-designer/SKILL.md new file mode 100644 index 0000000..149756e --- /dev/null +++ b/engineering/database-schema-designer/SKILL.md @@ -0,0 +1,522 @@ +# Database Schema Designer + +**Tier:** POWERFUL +**Category:** Engineering +**Domain:** Data Architecture / Backend + +--- + +## Overview + +Design relational database schemas from requirements and generate migrations, TypeScript/Python types, seed data, RLS policies, and indexes. Handles multi-tenancy, soft deletes, audit trails, versioning, and polymorphic associations. + +## Core Capabilities + +- **Schema design** β normalize requirements into tables, relationships, constraints +- **Migration generation** β Drizzle, Prisma, TypeORM, Alembic +- **Type generation** β TypeScript interfaces, Python dataclasses/Pydantic models +- **RLS policies** β Row-Level Security for multi-tenant apps +- **Index strategy** β composite indexes, partial indexes, covering indexes +- **Seed data** β realistic test data generation +- **ERD generation** β Mermaid diagram from schema + +--- + +## When to Use + +- Designing a new feature that needs database tables +- Reviewing a schema for performance or normalization issues +- Adding multi-tenancy to an existing schema +- Generating TypeScript types from a Prisma schema +- Planning a schema migration for a breaking change + +--- + +## Schema Design Process + +### Step 1: Requirements β Entities + +Given requirements: +> "Users can create projects. Each project has tasks. Tasks can have labels. Tasks can be assigned to users. We need a full audit trail." + +Extract entities: +``` +User, Project, Task, Label, TaskLabel (junction), TaskAssignment, AuditLog +``` + +### Step 2: Identify Relationships + +``` +User 1ββ* Project (owner) +Project 1ββ* Task +Task *ββ* Label (via TaskLabel) +Task *ββ* User (via TaskAssignment) +User 1ββ* AuditLog +``` + +### Step 3: Add Cross-cutting Concerns + +- Multi-tenancy: add `organization_id` to all tenant-scoped tables +- Soft deletes: add `deleted_at TIMESTAMPTZ` instead of hard deletes +- Audit trail: add `created_by`, `updated_by`, `created_at`, `updated_at` +- Versioning: add `version INTEGER` for optimistic locking + +--- + +## Full Schema Example (Task Management SaaS) + +### Prisma Schema + +```prisma +// schema.prisma +generator client { + provider = "prisma-client-js" +} + +datasource db { + provider = "postgresql" + url = env("DATABASE_URL") +} + +// ββ Multi-tenancy βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ + +model Organization { + id String @id @default(cuid()) + name String + slug String @unique + plan Plan @default(FREE) + createdAt DateTime @default(now()) @map("created_at") + updatedAt DateTime @updatedAt @map("updated_at") + deletedAt DateTime? @map("deleted_at") + + users OrganizationMember[] + projects Project[] + auditLogs AuditLog[] + + @@map("organizations") +} + +model OrganizationMember { + id String @id @default(cuid()) + organizationId String @map("organization_id") + userId String @map("user_id") + role OrgRole @default(MEMBER) + joinedAt DateTime @default(now()) @map("joined_at") + + organization Organization @relation(fields: [organizationId], references: [id], onDelete: Cascade) + user User @relation(fields: [userId], references: [id], onDelete: Cascade) + + @@unique([organizationId, userId]) + @@index([userId]) + @@map("organization_members") +} + +model User { + id String @id @default(cuid()) + email String @unique + name String? + avatarUrl String? @map("avatar_url") + passwordHash String? @map("password_hash") + emailVerifiedAt DateTime? @map("email_verified_at") + lastLoginAt DateTime? @map("last_login_at") + createdAt DateTime @default(now()) @map("created_at") + updatedAt DateTime @updatedAt @map("updated_at") + deletedAt DateTime? @map("deleted_at") + + memberships OrganizationMember[] + ownedProjects Project[] @relation("ProjectOwner") + assignedTasks TaskAssignment[] + comments Comment[] + auditLogs AuditLog[] + + @@map("users") +} + +// ββ Core entities βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ + +model Project { + id String @id @default(cuid()) + organizationId String @map("organization_id") + ownerId String @map("owner_id") + name String + description String? + status ProjectStatus @default(ACTIVE) + settings Json @default("{}") + createdAt DateTime @default(now()) @map("created_at") + updatedAt DateTime @updatedAt @map("updated_at") + deletedAt DateTime? @map("deleted_at") + + organization Organization @relation(fields: [organizationId], references: [id]) + owner User @relation("ProjectOwner", fields: [ownerId], references: [id]) + tasks Task[] + labels Label[] + + @@index([organizationId]) + @@index([organizationId, status]) + @@index([deletedAt]) + @@map("projects") +} + +model Task { + id String @id @default(cuid()) + projectId String @map("project_id") + title String + description String? + status TaskStatus @default(TODO) + priority Priority @default(MEDIUM) + dueDate DateTime? @map("due_date") + position Float @default(0) // For drag-and-drop ordering + version Int @default(1) // Optimistic locking + createdById String @map("created_by_id") + updatedById String @map("updated_by_id") + createdAt DateTime @default(now()) @map("created_at") + updatedAt DateTime @updatedAt @map("updated_at") + deletedAt DateTime? @map("deleted_at") + + project Project @relation(fields: [projectId], references: [id]) + assignments TaskAssignment[] + labels TaskLabel[] + comments Comment[] + attachments Attachment[] + + @@index([projectId]) + @@index([projectId, status]) + @@index([projectId, deletedAt]) + @@index([dueDate], where: { deletedAt: null }) // Partial index + @@map("tasks") +} + +// ββ Polymorphic attachments βββββββββββββββββββββββββββββββββββββββββββββββββββ + +model Attachment { + id String @id @default(cuid()) + // Polymorphic association + entityType String @map("entity_type") // "task" | "comment" + entityId String @map("entity_id") + filename String + mimeType String @map("mime_type") + sizeBytes Int @map("size_bytes") + storageKey String @map("storage_key") // S3 key + uploadedById String @map("uploaded_by_id") + createdAt DateTime @default(now()) @map("created_at") + + // Only one concrete relation (task) β polymorphic handled at app level + task Task? @relation(fields: [entityId], references: [id], map: "attachment_task_fk") + + @@index([entityType, entityId]) + @@map("attachments") +} + +// ββ Audit trail βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ + +model AuditLog { + id String @id @default(cuid()) + organizationId String @map("organization_id") + userId String? @map("user_id") + action String // "task.created", "task.status_changed" + entityType String @map("entity_type") + entityId String @map("entity_id") + before Json? // Previous state + after Json? // New state + ipAddress String? @map("ip_address") + userAgent String? @map("user_agent") + createdAt DateTime @default(now()) @map("created_at") + + organization Organization @relation(fields: [organizationId], references: [id]) + user User? @relation(fields: [userId], references: [id]) + + @@index([organizationId, createdAt(sort: Desc)]) + @@index([entityType, entityId]) + @@index([userId]) + @@map("audit_logs") +} + +enum Plan { FREE STARTER GROWTH ENTERPRISE } +enum OrgRole { OWNER ADMIN MEMBER VIEWER } +enum ProjectStatus { ACTIVE ARCHIVED } +enum TaskStatus { TODO IN_PROGRESS IN_REVIEW DONE CANCELLED } +enum Priority { LOW MEDIUM HIGH CRITICAL } +``` + +--- + +### Drizzle Schema (TypeScript) + +```typescript +// db/schema.ts +import { + pgTable, text, timestamp, integer, boolean, + varchar, jsonb, real, pgEnum, uniqueIndex, index, +} from 'drizzle-orm/pg-core' +import { createId } from '@paralleldrive/cuid2' + +export const taskStatusEnum = pgEnum('task_status', [ + 'todo', 'in_progress', 'in_review', 'done', 'cancelled' +]) +export const priorityEnum = pgEnum('priority', ['low', 'medium', 'high', 'critical']) + +export const tasks = pgTable('tasks', { + id: text('id').primaryKey().$defaultFn(() => createId()), + projectId: text('project_id').notNull().references(() => projects.id), + title: varchar('title', { length: 500 }).notNull(), + description: text('description'), + status: taskStatusEnum('status').notNull().default('todo'), + priority: priorityEnum('priority').notNull().default('medium'), + dueDate: timestamp('due_date', { withTimezone: true }), + position: real('position').notNull().default(0), + version: integer('version').notNull().default(1), + createdById: text('created_by_id').notNull().references(() => users.id), + updatedById: text('updated_by_id').notNull().references(() => users.id), + createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(), + updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(), + deletedAt: timestamp('deleted_at', { withTimezone: true }), +}, (table) => ({ + projectIdx: index('tasks_project_id_idx').on(table.projectId), + projectStatusIdx: index('tasks_project_status_idx').on(table.projectId, table.status), +})) + +// Infer TypeScript types +export type Task = typeof tasks.$inferSelect +export type NewTask = typeof tasks.$inferInsert +``` + +--- + +### Alembic Migration (Python / SQLAlchemy) + +```python +# alembic/versions/20260301_create_tasks.py +"""Create tasks table + +Revision ID: a1b2c3d4e5f6 +Revises: previous_revision +Create Date: 2026-03-01 12:00:00 +""" + +from alembic import op +import sqlalchemy as sa +from sqlalchemy.dialects import postgresql + +revision = 'a1b2c3d4e5f6' +down_revision = 'previous_revision' + + +def upgrade() -> None: + # Create enums + task_status = postgresql.ENUM( + 'todo', 'in_progress', 'in_review', 'done', 'cancelled', + name='task_status' + ) + task_status.create(op.get_bind()) + + op.create_table( + 'tasks', + sa.Column('id', sa.Text(), primary_key=True), + sa.Column('project_id', sa.Text(), sa.ForeignKey('projects.id'), nullable=False), + sa.Column('title', sa.VARCHAR(500), nullable=False), + sa.Column('description', sa.Text()), + sa.Column('status', postgresql.ENUM('todo', 'in_progress', 'in_review', 'done', 'cancelled', name='task_status', create_type=False), nullable=False, server_default='todo'), + sa.Column('priority', sa.Text(), nullable=False, server_default='medium'), + sa.Column('due_date', sa.TIMESTAMP(timezone=True)), + sa.Column('position', sa.Float(), nullable=False, server_default='0'), + sa.Column('version', sa.Integer(), nullable=False, server_default='1'), + sa.Column('created_by_id', sa.Text(), sa.ForeignKey('users.id'), nullable=False), + sa.Column('updated_by_id', sa.Text(), sa.ForeignKey('users.id'), nullable=False), + sa.Column('created_at', sa.TIMESTAMP(timezone=True), nullable=False, server_default=sa.text('NOW()')), + sa.Column('updated_at', sa.TIMESTAMP(timezone=True), nullable=False, server_default=sa.text('NOW()')), + sa.Column('deleted_at', sa.TIMESTAMP(timezone=True)), + ) + + # Indexes + op.create_index('tasks_project_id_idx', 'tasks', ['project_id']) + op.create_index('tasks_project_status_idx', 'tasks', ['project_id', 'status']) + # Partial index for active tasks only + op.create_index( + 'tasks_due_date_active_idx', + 'tasks', ['due_date'], + postgresql_where=sa.text('deleted_at IS NULL') + ) + + +def downgrade() -> None: + op.drop_table('tasks') + op.execute("DROP TYPE IF EXISTS task_status") +``` + +--- + +## Row-Level Security (RLS) Policies + +```sql +-- Enable RLS +ALTER TABLE tasks ENABLE ROW LEVEL SECURITY; +ALTER TABLE projects ENABLE ROW LEVEL SECURITY; + +-- Create app role +CREATE ROLE app_user; + +-- Users can only see tasks in their organization's projects +CREATE POLICY tasks_org_isolation ON tasks + FOR ALL TO app_user + USING ( + project_id IN ( + SELECT p.id FROM projects p + JOIN organization_members om ON om.organization_id = p.organization_id + WHERE om.user_id = current_setting('app.current_user_id')::text + ) + ); + +-- Soft delete: never show deleted records +CREATE POLICY tasks_no_deleted ON tasks + FOR SELECT TO app_user + USING (deleted_at IS NULL); + +-- Only task creator or admin can delete +CREATE POLICY tasks_delete_policy ON tasks + FOR DELETE TO app_user + USING ( + created_by_id = current_setting('app.current_user_id')::text + OR EXISTS ( + SELECT 1 FROM organization_members om + JOIN projects p ON p.organization_id = om.organization_id + WHERE p.id = tasks.project_id + AND om.user_id = current_setting('app.current_user_id')::text + AND om.role IN ('owner', 'admin') + ) + ); + +-- Set user context (call at start of each request) +SELECT set_config('app.current_user_id', $1, true); +``` + +--- + +## Seed Data Generation + +```typescript +// db/seed.ts +import { faker } from '@faker-js/faker' +import { db } from './client' +import { organizations, users, projects, tasks } from './schema' +import { createId } from '@paralleldrive/cuid2' +import { hashPassword } from '../src/lib/auth' + +async function seed() { + console.log('Seeding database...') + + // Create org + const [org] = await db.insert(organizations).values({ + id: createId(), + name: 'Acme Corp', + slug: 'acme', + plan: 'growth', + }).returning() + + // Create users + const adminUser = await db.insert(users).values({ + id: createId(), + email: 'admin@acme.com', + name: 'Alice Admin', + passwordHash: await hashPassword('password123'), + }).returning().then(r => r[0]) + + // Create projects + const projectsData = Array.from({ length: 3 }, () => ({ + id: createId(), + organizationId: org.id, + ownerId: adminUser.id, + name: faker.company.catchPhrase(), + description: faker.lorem.paragraph(), + status: 'active' as const, + })) + + const createdProjects = await db.insert(projects).values(projectsData).returning() + + // Create tasks for each project + for (const project of createdProjects) { + const tasksData = Array.from({ length: faker.number.int({ min: 5, max: 20 }) }, (_, i) => ({ + id: createId(), + projectId: project.id, + title: faker.hacker.phrase(), + description: faker.lorem.sentences(2), + status: faker.helpers.arrayElement(['todo', 'in_progress', 'done'] as const), + priority: faker.helpers.arrayElement(['low', 'medium', 'high'] as const), + position: i * 1000, + createdById: adminUser.id, + updatedById: adminUser.id, + })) + + await db.insert(tasks).values(tasksData) + } + + console.log(`β Seeded: 1 org, ${projectsData.length} projects, tasks`) +} + +seed().catch(console.error).finally(() => process.exit(0)) +``` + +--- + +## ERD Generation (Mermaid) + +``` +erDiagram + Organization ||--o{ OrganizationMember : has + Organization ||--o{ Project : owns + User ||--o{ OrganizationMember : joins + User ||--o{ Task : "created by" + Project ||--o{ Task : contains + Task ||--o{ TaskAssignment : has + Task ||--o{ TaskLabel : has + Task ||--o{ Comment : has + Task ||--o{ Attachment : has + Label ||--o{ TaskLabel : "applied to" + User ||--o{ TaskAssignment : assigned + + Organization { + string id PK + string name + string slug + string plan + } + + Task { + string id PK + string project_id FK + string title + string status + string priority + timestamp due_date + timestamp deleted_at + int version + } +``` + +Generate from Prisma: +```bash +npx prisma-erd-generator +# or: npx @dbml/cli prisma2dbml -i schema.prisma | npx dbml-to-mermaid +``` + +--- + +## Common Pitfalls + +- **Soft delete without index** β `WHERE deleted_at IS NULL` without index = full scan +- **Missing composite indexes** β `WHERE org_id = ? AND status = ?` needs a composite index +- **Mutable surrogate keys** β never use email or slug as PK; use UUID/CUID +- **Non-nullable without default** β adding a NOT NULL column to existing table requires default or migration plan +- **No optimistic locking** β concurrent updates overwrite each other; add `version` column +- **RLS not tested** β always test RLS with a non-superuser role + +--- + +## Best Practices + +1. **Timestamps everywhere** β `created_at`, `updated_at` on every table +2. **Soft deletes for auditable data** β `deleted_at` instead of DELETE +3. **Audit log for compliance** β log before/after JSON for regulated domains +4. **UUIDs or CUIDs as PKs** β avoid sequential integer leakage +5. **Index foreign keys** β every FK column should have an index +6. **Partial indexes** β use `WHERE deleted_at IS NULL` for active-only queries +7. **RLS over application-level filtering** β database enforces tenancy, not just app code diff --git a/engineering/env-secrets-manager/SKILL.md b/engineering/env-secrets-manager/SKILL.md new file mode 100644 index 0000000..4123e40 --- /dev/null +++ b/engineering/env-secrets-manager/SKILL.md @@ -0,0 +1,686 @@ +# Env & Secrets Manager + +**Tier:** POWERFUL +**Category:** Engineering +**Domain:** Security / DevOps / Configuration Management + +--- + +## Overview + +Complete environment and secrets management workflow: .env file lifecycle across dev/staging/prod, +.env.example auto-generation, required-var validation, secret leak detection in git history, and +credential rotation playbook. Integrates with HashiCorp Vault, AWS SSM, 1Password CLI, and Doppler. + +--- + +## Core Capabilities + +- **.env lifecycle** β create, validate, sync across environments +- **.env.example generation** β strip values, preserve keys and comments +- **Validation script** β fail-fast on missing required vars at startup +- **Secret leak detection** β regex scan of git history and working tree +- **Rotation workflow** β detect β scope β rotate β deploy β verify +- **Secret manager integrations** β Vault KV v2, AWS SSM, 1Password, Doppler + +--- + +## When to Use + +- Setting up a new project β scaffold .env.example and validation +- Before every commit β scan for accidentally staged secrets +- Post-incident response β leaked credential rotation procedure +- Onboarding new developers β they need all vars, not just some +- Environment drift investigation β prod behaving differently from staging + +--- + +## .env File Structure + +### Canonical Layout +```bash +# .env.example β committed to git (no values) +# .env.local β developer machine (gitignored) +# .env.staging β CI/CD or secret manager reference +# .env.prod β never on disk; pulled from secret manager at runtime + +# Application +APP_NAME= +APP_ENV= # dev | staging | prod +APP_PORT=3000 # default port if not set +APP_SECRET= # REQUIRED: JWT signing secret (min 32 chars) +APP_URL= # REQUIRED: public base URL + +# Database +DATABASE_URL= # REQUIRED: full connection string +DATABASE_POOL_MIN=2 +DATABASE_POOL_MAX=10 + +# Auth +AUTH_JWT_SECRET= # REQUIRED +AUTH_JWT_EXPIRY=3600 # seconds +AUTH_REFRESH_SECRET= # REQUIRED + +# Third-party APIs +STRIPE_SECRET_KEY= # REQUIRED in prod +STRIPE_WEBHOOK_SECRET= # REQUIRED in prod +SENDGRID_API_KEY= + +# Storage +AWS_ACCESS_KEY_ID= +AWS_SECRET_ACCESS_KEY= +AWS_REGION=eu-central-1 +AWS_S3_BUCKET= + +# Monitoring +SENTRY_DSN= +DD_API_KEY= +``` + +--- + +## .gitignore Patterns + +Add to your project's `.gitignore`: + +```gitignore +# Environment files β NEVER commit these +.env +.env.local +.env.development +.env.development.local +.env.test.local +.env.staging +.env.staging.local +.env.production +.env.production.local +.env.prod +.env.*.local + +# Secret files +*.pem +*.key +*.p12 +*.pfx +secrets.json +secrets.yaml +secrets.yml +credentials.json +service-account.json + +# AWS +.aws/credentials + +# Terraform state (may contain secrets) +*.tfstate +*.tfstate.backup +.terraform/ + +# Kubernetes secrets +*-secret.yaml +*-secrets.yaml +``` + +--- + +## .env.example Auto-Generation + +```bash +#!/bin/bash +# scripts/gen-env-example.sh +# Strips values from .env, preserves keys, defaults, and comments + +INPUT="${1:-.env}" +OUTPUT="${2:-.env.example}" + +if [ ! -f "$INPUT" ]; then + echo "ERROR: $INPUT not found" + exit 1 +fi + +python3 - "$INPUT" "$OUTPUT" << 'PYEOF' +import sys, re + +input_file = sys.argv[1] +output_file = sys.argv[2] +lines = [] + +with open(input_file) as f: + for line in f: + stripped = line.rstrip('\n') + # Keep blank lines and comments as-is + if stripped == '' or stripped.startswith('#'): + lines.append(stripped) + continue + # Match KEY=VALUE or KEY="VALUE" + m = re.match(r'^([A-Z_][A-Z0-9_]*)=(.*)$', stripped) + if m: + key = m.group(1) + value = m.group(2).strip('"\'') + # Keep non-sensitive defaults (ports, regions, feature flags) + safe_defaults = re.compile( + r'^(APP_PORT|APP_ENV|APP_NAME|AWS_REGION|DATABASE_POOL_|LOG_LEVEL|' + r'FEATURE_|CACHE_TTL|RATE_LIMIT_|PAGINATION_|TIMEOUT_)', + re.I + ) + sensitive = re.compile( + r'(SECRET|KEY|TOKEN|PASSWORD|PASS|CREDENTIAL|DSN|AUTH|PRIVATE|CERT)', + re.I + ) + if safe_defaults.match(key) and value: + lines.append(f"{key}={value} # default") + else: + lines.append(f"{key}=") + else: + lines.append(stripped) + +with open(output_file, 'w') as f: + f.write('\n'.join(lines) + '\n') + +print(f"Generated {output_file} from {input_file}") +PYEOF +``` + +Usage: +```bash +bash scripts/gen-env-example.sh .env .env.example +# Commit .env.example, never .env +git add .env.example +``` + +--- + +## Required Variable Validation Script + +```bash +#!/bin/bash +# scripts/validate-env.sh +# Run at app startup or in CI before deploy +# Exit 1 if any required var is missing or empty + +set -euo pipefail + +MISSING=() +WARNINGS=() + +# --- Define required vars by environment --- +ALWAYS_REQUIRED=( + APP_SECRET + APP_URL + DATABASE_URL + AUTH_JWT_SECRET + AUTH_REFRESH_SECRET +) + +PROD_REQUIRED=( + STRIPE_SECRET_KEY + STRIPE_WEBHOOK_SECRET + SENTRY_DSN +) + +# --- Check always-required vars --- +for var in "${ALWAYS_REQUIRED[@]}"; do + if [ -z "${!var:-}" ]; then + MISSING+=("$var") + fi +done + +# --- Check prod-only vars --- +if [ "${APP_ENV:-}" = "production" ] || [ "${NODE_ENV:-}" = "production" ]; then + for var in "${PROD_REQUIRED[@]}"; do + if [ -z "${!var:-}" ]; then + MISSING+=("$var (required in production)") + fi + done +fi + +# --- Validate format/length constraints --- +if [ -n "${AUTH_JWT_SECRET:-}" ] && [ ${#AUTH_JWT_SECRET} -lt 32 ]; then + WARNINGS+=("AUTH_JWT_SECRET is shorter than 32 chars β insecure") +fi + +if [ -n "${DATABASE_URL:-}" ]; then + if ! echo "$DATABASE_URL" | grep -qE "^(postgres|postgresql|mysql|mongodb|redis)://"; then + WARNINGS+=("DATABASE_URL doesn't look like a valid connection string") + fi +fi + +if [ -n "${APP_PORT:-}" ]; then + if ! [[ "$APP_PORT" =~ ^[0-9]+$ ]] || [ "$APP_PORT" -lt 1 ] || [ "$APP_PORT" -gt 65535 ]; then + WARNINGS+=("APP_PORT=$APP_PORT is not a valid port number") + fi +fi + +# --- Report --- +if [ ${#WARNINGS[@]} -gt 0 ]; then + echo "WARNINGS:" + for w in "${WARNINGS[@]}"; do + echo " β οΈ $w" + done +fi + +if [ ${#MISSING[@]} -gt 0 ]; then + echo "" + echo "FATAL: Missing required environment variables:" + for var in "${MISSING[@]}"; do + echo " β $var" + done + echo "" + echo "Copy .env.example to .env and fill in missing values." + exit 1 +fi + +echo "β All required environment variables are set" +``` + +Node.js equivalent: +```typescript +// src/config/validateEnv.ts +const required = [ + 'APP_SECRET', 'APP_URL', 'DATABASE_URL', + 'AUTH_JWT_SECRET', 'AUTH_REFRESH_SECRET', +] + +const missing = required.filter(key => !process.env[key]) + +if (missing.length > 0) { + console.error('FATAL: Missing required environment variables:', missing) + process.exit(1) +} + +if (process.env.AUTH_JWT_SECRET && process.env.AUTH_JWT_SECRET.length < 32) { + console.error('FATAL: AUTH_JWT_SECRET must be at least 32 characters') + process.exit(1) +} + +export const config = { + appSecret: process.env.APP_SECRET!, + appUrl: process.env.APP_URL!, + databaseUrl: process.env.DATABASE_URL!, + jwtSecret: process.env.AUTH_JWT_SECRET!, + refreshSecret: process.env.AUTH_REFRESH_SECRET!, + stripeKey: process.env.STRIPE_SECRET_KEY, // optional + port: parseInt(process.env.APP_PORT ?? '3000', 10), +} as const +``` + +--- + +## Secret Leak Detection + +### Scan Working Tree +```bash +#!/bin/bash +# scripts/scan-secrets.sh +# Scan staged files and working tree for common secret patterns + +FAIL=0 + +check() { + local label="$1" + local pattern="$2" + local matches + + matches=$(git diff --cached -U0 2>/dev/null | grep "^+" | grep -vE "^(\+\+\+|#|\/\/)" | \ + grep -E "$pattern" | grep -v ".env.example" | grep -v "test\|mock\|fixture\|fake" || true) + + if [ -n "$matches" ]; then + echo "SECRET DETECTED [$label]:" + echo "$matches" | head -5 + FAIL=1 + fi +} + +# AWS Access Keys +check "AWS Access Key" "AKIA[0-9A-Z]{16}" +check "AWS Secret Key" "aws_secret_access_key\s*=\s*['\"]?[A-Za-z0-9/+]{40}" + +# Stripe +check "Stripe Live Key" "sk_live_[0-9a-zA-Z]{24,}" +check "Stripe Test Key" "sk_test_[0-9a-zA-Z]{24,}" +check "Stripe Webhook" "whsec_[0-9a-zA-Z]{32,}" + +# JWT / Generic secrets +check "Hardcoded JWT" "eyJ[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]{20,}" +check "Generic Secret" "(secret|password|passwd|api_key|apikey|token)\s*[:=]\s*['\"][^'\"]{12,}['\"]" + +# Private keys +check "Private Key Block" "-----BEGIN (RSA |EC |DSA |OPENSSH )?PRIVATE KEY-----" +check "PEM Certificate" "-----BEGIN CERTIFICATE-----" + +# Connection strings with credentials +check "DB Connection" "(postgres|mysql|mongodb)://[^:]+:[^@]+@" +check "Redis Auth" "redis://:[^@]+@\|rediss://:[^@]+@" + +# Google +check "Google API Key" "AIza[0-9A-Za-z_-]{35}" +check "Google OAuth" "[0-9]+-[0-9A-Za-z_]{32}\.apps\.googleusercontent\.com" + +# GitHub +check "GitHub Token" "gh[ps]_[A-Za-z0-9]{36,}" +check "GitHub Fine-grained" "github_pat_[A-Za-z0-9_]{82}" + +# Slack +check "Slack Token" "xox[baprs]-[0-9A-Za-z]{10,}" +check "Slack Webhook" "https://hooks\.slack\.com/services/[A-Z0-9]{9,}/[A-Z0-9]{9,}/[A-Za-z0-9]{24,}" + +# Twilio +check "Twilio SID" "AC[a-z0-9]{32}" +check "Twilio Token" "SK[a-z0-9]{32}" + +if [ $FAIL -eq 1 ]; then + echo "" + echo "BLOCKED: Secrets detected in staged changes." + echo "Remove secrets before committing. Use environment variables instead." + echo "If this is a false positive, add it to .secretsignore or use:" + echo " git commit --no-verify (only if you're 100% certain it's safe)" + exit 1 +fi + +echo "No secrets detected in staged changes." +``` + +### Scan Git History (post-incident) +```bash +#!/bin/bash +# scripts/scan-history.sh β scan entire git history for leaked secrets + +PATTERNS=( + "AKIA[0-9A-Z]{16}" + "sk_live_[0-9a-zA-Z]{24}" + "sk_test_[0-9a-zA-Z]{24}" + "-----BEGIN.*PRIVATE KEY-----" + "AIza[0-9A-Za-z_-]{35}" + "ghp_[A-Za-z0-9]{36}" + "xox[baprs]-[0-9A-Za-z]{10,}" +) + +for pattern in "${PATTERNS[@]}"; do + echo "Scanning for: $pattern" + git log --all -p --no-color 2>/dev/null | \ + grep -n "$pattern" | \ + grep "^+" | \ + grep -v "^+++" | \ + head -10 +done + +# Alternative: use truffleHog or gitleaks for comprehensive scanning +# gitleaks detect --source . --log-opts="--all" +# trufflehog git file://. --only-verified +``` + +--- + +## Pre-commit Hook Installation + +```bash +#!/bin/bash +# Install the pre-commit hook +HOOK_PATH=".git/hooks/pre-commit" + +cat > "$HOOK_PATH" << 'HOOK' +#!/bin/bash +# Pre-commit: scan for secrets before every commit + +SCRIPT="scripts/scan-secrets.sh" + +if [ -f "$SCRIPT" ]; then + bash "$SCRIPT" +else + # Inline fallback if script not present + if git diff --cached -U0 | grep "^+" | grep -qE "AKIA[0-9A-Z]{16}|sk_live_|-----BEGIN.*PRIVATE KEY"; then + echo "BLOCKED: Possible secret detected in staged changes." + exit 1 + fi +fi +HOOK + +chmod +x "$HOOK_PATH" +echo "Pre-commit hook installed at $HOOK_PATH" +``` + +Using `pre-commit` framework (recommended for teams): +```yaml +# .pre-commit-config.yaml +repos: + - repo: https://github.com/gitleaks/gitleaks + rev: v8.18.0 + hooks: + - id: gitleaks + + - repo: local + hooks: + - id: validate-env-example + name: Check .env.example is up to date + language: script + entry: bash scripts/check-env-example.sh + pass_filenames: false +``` + +--- + +## Credential Rotation Workflow + +When a secret is leaked or compromised: + +### Step 1 β Detect & Confirm +```bash +# Confirm which secret was exposed +git log --all -p --no-color | grep -A2 -B2 "AKIA\|sk_live_\|SECRET" + +# Check if secret is in any open PRs +gh pr list --state open | while read pr; do + gh pr diff $(echo $pr | awk '{print $1}') | grep -E "AKIA|sk_live_" && echo "Found in PR: $pr" +done +``` + +### Step 2 β Identify Exposure Window +```bash +# Find first commit that introduced the secret +git log --all -p --no-color -- "*.env" "*.json" "*.yaml" "*.ts" "*.py" | \ + grep -B 10 "THE_LEAKED_VALUE" | grep "^commit" | tail -1 + +# Get commit date +git show --format="%ci" COMMIT_HASH | head -1 + +# Check if secret appears in public repos (GitHub) +gh api search/code -X GET -f q="THE_LEAKED_VALUE" | jq '.total_count, .items[].html_url' +``` + +### Step 3 β Rotate Credential +Per service β rotate immediately: +- **AWS**: IAM console β delete access key β create new β update everywhere +- **Stripe**: Dashboard β Developers β API keys β Roll key +- **GitHub PAT**: Settings β Developer Settings β Personal access tokens β Revoke β Create new +- **DB password**: `ALTER USER app_user PASSWORD 'new-strong-password-here';` +- **JWT secret**: Rotate key (all existing sessions invalidated β users re-login) + +### Step 4 β Update All Environments +```bash +# Update secret manager (source of truth) +# Then redeploy to pull new values + +# Vault KV v2 +vault kv put secret/myapp/prod \ + STRIPE_SECRET_KEY="sk_live_NEW..." \ + APP_SECRET="new-secret-here" + +# AWS SSM +aws ssm put-parameter \ + --name "/myapp/prod/STRIPE_SECRET_KEY" \ + --value "sk_live_NEW..." \ + --type "SecureString" \ + --overwrite + +# 1Password +op item edit "MyApp Prod" \ + --field "STRIPE_SECRET_KEY[password]=sk_live_NEW..." + +# Doppler +doppler secrets set STRIPE_SECRET_KEY="sk_live_NEW..." --project myapp --config prod +``` + +### Step 5 β Remove from Git History +```bash +# WARNING: rewrites history β coordinate with team first +git filter-repo --path-glob "*.env" --invert-paths + +# Or remove specific string from all commits +git filter-repo --replace-text <(echo "LEAKED_VALUE==>REDACTED") + +# Force push all branches (requires team coordination + force push permissions) +git push origin --force --all + +# Notify all developers to re-clone +``` + +### Step 6 β Verify +```bash +# Confirm secret no longer in history +git log --all -p | grep "LEAKED_VALUE" | wc -l # should be 0 + +# Test new credentials work +curl -H "Authorization: Bearer $NEW_TOKEN" https://api.service.com/test + +# Monitor for unauthorized usage of old credential (check service audit logs) +``` + +--- + +## Secret Manager Integrations + +### HashiCorp Vault KV v2 +```bash +# Setup +export VAULT_ADDR="https://vault.internal.company.com" +export VAULT_TOKEN="$(vault login -method=oidc -format=json | jq -r '.auth.client_token')" + +# Write secrets +vault kv put secret/myapp/prod \ + DATABASE_URL="postgres://user:pass@host/db" \ + APP_SECRET="$(openssl rand -base64 32)" + +# Read secrets into env +eval $(vault kv get -format=json secret/myapp/prod | \ + jq -r '.data.data | to_entries[] | "export \(.key)=\(.value)"') + +# In CI/CD (GitHub Actions) +# Use vault-action: hashicorp/vault-action@v2 +``` + +### AWS SSM Parameter Store +```bash +# Write (SecureString = encrypted with KMS) +aws ssm put-parameter \ + --name "/myapp/prod/DATABASE_URL" \ + --value "postgres://..." \ + --type "SecureString" \ + --key-id "alias/myapp-secrets" + +# Read all params for an app/env into shell +eval $(aws ssm get-parameters-by-path \ + --path "/myapp/prod/" \ + --with-decryption \ + --query "Parameters[*].[Name,Value]" \ + --output text | \ + awk '{split($1,a,"/"); print "export " a[length(a)] "=\"" $2 "\""}') + +# In Node.js at startup +# Use @aws-sdk/client-ssm to pull params before server starts +``` + +### 1Password CLI +```bash +# Authenticate +eval $(op signin) + +# Get a specific field +op read "op://MyVault/MyApp Prod/STRIPE_SECRET_KEY" + +# Export all fields from an item as env vars +op item get "MyApp Prod" --format json | \ + jq -r '.fields[] | select(.value != null) | "export \(.label)=\"\(.value)\""' | \ + grep -E "^export [A-Z_]+" | source /dev/stdin + +# .env injection +op inject -i .env.tpl -o .env +# .env.tpl uses {{ op://Vault/Item/field }} syntax +``` + +### Doppler +```bash +# Setup +doppler setup # interactive: select project + config + +# Run any command with secrets injected +doppler run -- node server.js +doppler run -- npm run dev + +# Export to .env (local dev only β never commit output) +doppler secrets download --no-file --format env > .env.local + +# Pull specific secret +doppler secrets get DATABASE_URL --plain + +# Sync to another environment +doppler secrets upload --project myapp --config staging < .env.staging.example +``` + +--- + +## Environment Drift Detection + +Check if staging and prod have the same set of keys (values may differ): + +```bash +#!/bin/bash +# scripts/check-env-drift.sh + +# Pull key names from both environments (not values) +STAGING_KEYS=$(doppler secrets --project myapp --config staging --format json 2>/dev/null | \ + jq -r 'keys[]' | sort) +PROD_KEYS=$(doppler secrets --project myapp --config prod --format json 2>/dev/null | \ + jq -r 'keys[]' | sort) + +ONLY_IN_STAGING=$(comm -23 <(echo "$STAGING_KEYS") <(echo "$PROD_KEYS")) +ONLY_IN_PROD=$(comm -13 <(echo "$STAGING_KEYS") <(echo "$PROD_KEYS")) + +if [ -n "$ONLY_IN_STAGING" ]; then + echo "Keys in STAGING but NOT in PROD:" + echo "$ONLY_IN_STAGING" | sed 's/^/ /' +fi + +if [ -n "$ONLY_IN_PROD" ]; then + echo "Keys in PROD but NOT in STAGING:" + echo "$ONLY_IN_PROD" | sed 's/^/ /' +fi + +if [ -z "$ONLY_IN_STAGING" ] && [ -z "$ONLY_IN_PROD" ]; then + echo "β No env drift detected β staging and prod have identical key sets" +fi +``` + +--- + +## Common Pitfalls + +- **Committing .env instead of .env.example** β add `.env` to .gitignore on day 1; use pre-commit hooks +- **Storing secrets in CI/CD logs** β never `echo $SECRET`; mask vars in CI settings +- **Rotating only one place** β secrets often appear in Heroku, Vercel, Docker, K8s, CI β update ALL +- **Forgetting to invalidate sessions after JWT secret rotation** β all users will be logged out; communicate this +- **Using .env.example with real values** β example files are public; strip everything sensitive +- **Not monitoring after rotation** β watch audit logs for 24h after rotation to catch unauthorized old-credential use +- **Weak secrets** β `APP_SECRET=mysecret` is not a secret. Use `openssl rand -base64 32` + +--- + +## Best Practices + +1. **Secret manager is source of truth** β .env files are for local dev only; never in prod +2. **Rotate on a schedule**, not just after incidents β quarterly minimum for long-lived keys +3. **Principle of least privilege** β each service gets its own API key with minimal permissions +4. **Audit access** β log every secret read in Vault/SSM; alert on anomalous access +5. **Never log secrets** β add log scrubbing middleware that redacts known secret patterns +6. **Use short-lived credentials** β prefer OIDC/instance roles over long-lived access keys +7. **Separate secrets per environment** β never share a key between dev and prod +8. **Document rotation runbooks** β before an incident, not during one diff --git a/engineering/git-worktree-manager/SKILL.md b/engineering/git-worktree-manager/SKILL.md new file mode 100644 index 0000000..c628593 --- /dev/null +++ b/engineering/git-worktree-manager/SKILL.md @@ -0,0 +1,157 @@ +# Git Worktree Manager + +**Tier:** POWERFUL +**Category:** Engineering +**Domain:** Parallel Development & Branch Isolation + +## Overview + +The Git Worktree Manager skill provides systematic management of Git worktrees for parallel development workflows. It handles worktree creation with automatic port allocation, environment file management, secret copying, and cleanup β enabling developers to run multiple Claude Code instances on separate features simultaneously without conflicts. + +## Core Capabilities + +- **Worktree Lifecycle Management** β create, list, switch, and cleanup worktrees with automated setup +- **Port Allocation & Isolation** β automatic port assignment per worktree to avoid dev server conflicts +- **Environment Synchronization** β copy .env files, secrets, and config between main and worktrees +- **Docker Compose Overrides** β generate per-worktree port override files for multi-service stacks +- **Conflict Prevention** β detect and warn about shared resources, database names, and API endpoints +- **Cleanup & Pruning** β safe removal with stale branch detection and uncommitted work warnings + +## When to Use This Skill + +- Running multiple Claude Code sessions on different features simultaneously +- Working on a hotfix while a feature branch has uncommitted work +- Reviewing a PR while continuing development on your branch +- Parallel CI/testing against multiple branches +- Monorepo development with isolated package changes + +## Worktree Creation Workflow + +### Step 1: Create Worktree + +```bash +# Create worktree for a new feature branch +git worktree add ../project-feature-auth -b feature/auth + +# Create worktree from an existing remote branch +git worktree add ../project-fix-123 origin/fix/issue-123 + +# Create worktree with tracking +git worktree add --track -b feature/new-api ../project-new-api origin/main +``` + +### Step 2: Environment Setup + +After creating the worktree, automatically: + +1. **Copy environment files:** + ```bash + cp .env ../project-feature-auth/.env + cp .env.local ../project-feature-auth/.env.local 2>/dev/null + ``` + +2. **Install dependencies:** + ```bash + cd ../project-feature-auth + [ -f "pnpm-lock.yaml" ] && pnpm install + [ -f "yarn.lock" ] && yarn install + [ -f "package-lock.json" ] && npm install + [ -f "bun.lockb" ] && bun install + ``` + +3. **Allocate ports:** + ``` + Main worktree: localhost:3000 (dev), :5432 (db), :6379 (redis) + Worktree 1: localhost:3010 (dev), :5442 (db), :6389 (redis) + Worktree 2: localhost:3020 (dev), :5452 (db), :6399 (redis) + ``` + +### Step 3: Docker Compose Override + +For Docker Compose projects, generate per-worktree override: + +```yaml +# docker-compose.worktree.yml (auto-generated) +services: + app: + ports: + - "3010:3000" + db: + ports: + - "5442:5432" + redis: + ports: + - "6389:6379" +``` + +Usage: `docker compose -f docker-compose.yml -f docker-compose.worktree.yml up` + +### Step 4: Database Isolation + +```bash +# Option A: Separate database per worktree +createdb myapp_feature_auth + +# Option B: DATABASE_URL override +echo 'DATABASE_URL="postgresql://localhost:5442/myapp_wt1"' >> .env.local + +# Option C: SQLite β file-based, automatic isolation +``` + +## Monorepo Optimization + +Combine worktrees with sparse checkout for large repos: + +```bash +git worktree add --no-checkout ../project-packages-only +cd ../project-packages-only +git sparse-checkout init --cone +git sparse-checkout set packages/shared packages/api +git checkout feature/api-refactor +``` + +## Claude Code Integration + +Each worktree gets auto-generated CLAUDE.md: + +```markdown +# Worktree: feature/auth +# Dev server port: 3010 +# Created: 2026-03-01 + +## Scope +Focus on changes related to this branch only. + +## Commands +- Dev: PORT=3010 npm run dev +- Test: npm test -- --related +- Lint: npm run lint +``` + +Run parallel sessions: +```bash +# Terminal 1: Main feature +cd ~/project && claude +# Terminal 2: Hotfix +cd ~/project-hotfix && claude +# Terminal 3: PR review +cd ~/project-pr-review && claude +``` + +## Common Pitfalls + +1. **Shared node_modules** β Worktrees share git dir but NOT node_modules. Always install deps. +2. **Port conflicts** β Two dev servers on :3000 = silent failures. Always allocate unique ports. +3. **Database migrations** β Migrations in one worktree affect all if sharing same DB. Isolate. +4. **Git hooks** β Live in `.git/hooks` (shared). Worktree-specific hooks need symlinks. +5. **IDE confusion** β VSCode may show wrong branch. Open as separate window. +6. **Stale worktrees** β Prune regularly: `git worktree prune`. + +## Best Practices + +1. Name worktrees by purpose: `project-auth`, `project-hotfix-123`, `project-pr-456` +2. Never create worktrees inside the main repo directory +3. Keep worktrees short-lived β merge and cleanup within days +4. Use the setup script β manual creation skips env/port/deps +5. One Claude Code instance per worktree β isolation is the point +6. Commit before switching β even WIP commits prevent lost work diff --git a/engineering/mcp-server-builder/SKILL.md b/engineering/mcp-server-builder/SKILL.md new file mode 100644 index 0000000..c659a38 --- /dev/null +++ b/engineering/mcp-server-builder/SKILL.md @@ -0,0 +1,575 @@ +# MCP Server Builder + +**Tier:** POWERFUL +**Category:** Engineering +**Domain:** AI / API Integration + +--- + +## Overview + +Design and implement Model Context Protocol (MCP) servers that expose any REST API, database, or service as structured tools for Claude and other LLMs. Covers both FastMCP (Python) and the TypeScript MCP SDK, with patterns for reading OpenAPI/Swagger specs, generating tool definitions, handling auth, errors, and testing. + +## Core Capabilities + +- **OpenAPI β MCP tools** β parse Swagger/OpenAPI specs and generate tool definitions +- **FastMCP (Python)** β decorator-based server with automatic schema generation +- **TypeScript MCP SDK** β typed server with zod validation +- **Auth handling** β API keys, Bearer tokens, OAuth2, mTLS +- **Error handling** β structured error responses LLMs can reason about +- **Testing** β unit tests for tool handlers, integration tests with MCP inspector + +--- + +## When to Use + +- Exposing a REST API to Claude without writing a custom integration +- Building reusable tool packs for a team's Claude setup +- Wrapping internal company APIs (Jira, HubSpot, custom microservices) +- Creating database-backed tools (read/write structured data) +- Replacing brittle browser automation with typed API calls + +--- + +## MCP Architecture + +``` +Claude / LLM + β + β MCP Protocol (JSON-RPC over stdio or HTTP/SSE) + βΌ +MCP Server + β calls + βΌ +External API / Database / Service +``` + +Each MCP server exposes: +- **Tools** β callable functions with typed inputs/outputs +- **Resources** β readable data (files, DB rows, API responses) +- **Prompts** β reusable prompt templates + +--- + +## Reading an OpenAPI Spec + +Given a Swagger/OpenAPI file, extract tool definitions: + +```python +import yaml +import json + +def openapi_to_tools(spec_path: str) -> list[dict]: + with open(spec_path) as f: + spec = yaml.safe_load(f) + + tools = [] + for path, methods in spec.get("paths", {}).items(): + for method, op in methods.items(): + if method not in ("get", "post", "put", "patch", "delete"): + continue + + # Build parameter schema + properties = {} + required = [] + + # Path/query parameters + for param in op.get("parameters", []): + name = param["name"] + schema = param.get("schema", {"type": "string"}) + properties[name] = { + "type": schema.get("type", "string"), + "description": param.get("description", ""), + } + if param.get("required"): + required.append(name) + + # Request body + if "requestBody" in op: + content = op["requestBody"].get("content", {}) + json_schema = content.get("application/json", {}).get("schema", {}) + if "$ref" in json_schema: + ref_name = json_schema["$ref"].split("/")[-1] + json_schema = spec["components"]["schemas"][ref_name] + for prop_name, prop_schema in json_schema.get("properties", {}).items(): + properties[prop_name] = prop_schema + required.extend(json_schema.get("required", [])) + + tool_name = op.get("operationId") or f"{method}_{path.replace('/', '_').strip('_')}" + tools.append({ + "name": tool_name, + "description": op.get("summary", op.get("description", "")), + "inputSchema": { + "type": "object", + "properties": properties, + "required": required, + } + }) + + return tools +``` + +--- + +## Full Example: FastMCP Python Server for CRUD API + +This builds a complete MCP server for a hypothetical Task Management REST API. + +```python +# server.py +from fastmcp import FastMCP +from pydantic import BaseModel, Field +import httpx +import os +from typing import Optional + +# Initialize MCP server +mcp = FastMCP( + name="task-manager", + description="MCP server for Task Management API", +) + +# Config +API_BASE = os.environ.get("TASK_API_BASE", "https://api.tasks.example.com") +API_KEY = os.environ["TASK_API_KEY"] # Fail fast if missing + +# Shared HTTP client with auth +def get_client() -> httpx.Client: + return httpx.Client( + base_url=API_BASE, + headers={ + "Authorization": f"Bearer {API_KEY}", + "Content-Type": "application/json", + }, + timeout=30.0, + ) + + +# ββ Pydantic models for input validation ββββββββββββββββββββββββββββββββββββββ + +class CreateTaskInput(BaseModel): + title: str = Field(..., description="Task title", min_length=1, max_length=200) + description: Optional[str] = Field(None, description="Task description") + assignee_id: Optional[str] = Field(None, description="User ID to assign to") + due_date: Optional[str] = Field(None, description="Due date in ISO 8601 format (YYYY-MM-DD)") + priority: str = Field("medium", description="Priority: low, medium, high, critical") + +class UpdateTaskInput(BaseModel): + task_id: str = Field(..., description="Task ID to update") + title: Optional[str] = Field(None, description="New title") + status: Optional[str] = Field(None, description="New status: todo, in_progress, done, cancelled") + assignee_id: Optional[str] = Field(None, description="Reassign to user ID") + due_date: Optional[str] = Field(None, description="New due date (YYYY-MM-DD)") + + +# ββ Tool implementations βββββββββββββββββββββββββββββββββββββββββββββββββββββββ + +@mcp.tool() +def list_tasks( + status: Optional[str] = None, + assignee_id: Optional[str] = None, + limit: int = 20, + offset: int = 0, +) -> dict: + """ + List tasks with optional filtering by status or assignee. + Returns paginated results with total count. + """ + params = {"limit": limit, "offset": offset} + if status: + params["status"] = status + if assignee_id: + params["assignee_id"] = assignee_id + + with get_client() as client: + resp = client.get("/tasks", params=params) + resp.raise_for_status() + return resp.json() + + +@mcp.tool() +def get_task(task_id: str) -> dict: + """ + Get a single task by ID including full details and comments. + """ + with get_client() as client: + resp = client.get(f"/tasks/{task_id}") + if resp.status_code == 404: + return {"error": f"Task {task_id} not found"} + resp.raise_for_status() + return resp.json() + + +@mcp.tool() +def create_task(input: CreateTaskInput) -> dict: + """ + Create a new task. Returns the created task with its ID. + """ + with get_client() as client: + resp = client.post("/tasks", json=input.model_dump(exclude_none=True)) + if resp.status_code == 422: + return {"error": "Validation failed", "details": resp.json()} + resp.raise_for_status() + task = resp.json() + return { + "success": True, + "task_id": task["id"], + "task": task, + } + + +@mcp.tool() +def update_task(input: UpdateTaskInput) -> dict: + """ + Update an existing task's title, status, assignee, or due date. + Only provided fields are updated (PATCH semantics). + """ + payload = input.model_dump(exclude_none=True) + task_id = payload.pop("task_id") + + if not payload: + return {"error": "No fields to update provided"} + + with get_client() as client: + resp = client.patch(f"/tasks/{task_id}", json=payload) + if resp.status_code == 404: + return {"error": f"Task {task_id} not found"} + resp.raise_for_status() + return {"success": True, "task": resp.json()} + + +@mcp.tool() +def delete_task(task_id: str, confirm: bool = False) -> dict: + """ + Delete a task permanently. Set confirm=true to proceed. + This action cannot be undone. + """ + if not confirm: + return { + "error": "Deletion requires explicit confirmation", + "hint": "Call again with confirm=true to permanently delete this task", + } + + with get_client() as client: + resp = client.delete(f"/tasks/{task_id}") + if resp.status_code == 404: + return {"error": f"Task {task_id} not found"} + resp.raise_for_status() + return {"success": True, "deleted_task_id": task_id} + + +@mcp.tool() +def search_tasks(query: str, limit: int = 10) -> dict: + """ + Full-text search across task titles and descriptions. + Returns matching tasks ranked by relevance. + """ + with get_client() as client: + resp = client.get("/tasks/search", params={"q": query, "limit": limit}) + resp.raise_for_status() + results = resp.json() + return { + "query": query, + "total": results.get("total", 0), + "tasks": results.get("items", []), + } + + +# ββ Resource: expose task list as readable resource βββββββββββββββββββββββββββ + +@mcp.resource("tasks://recent") +def recent_tasks_resource() -> str: + """Returns the 10 most recently updated tasks as JSON.""" + with get_client() as client: + resp = client.get("/tasks", params={"sort": "-updated_at", "limit": 10}) + resp.raise_for_status() + return resp.text + + +if __name__ == "__main__": + mcp.run() +``` + +--- + +## TypeScript MCP SDK Version + +```typescript +// server.ts +import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; +import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; +import { z } from "zod"; + +const API_BASE = process.env.TASK_API_BASE ?? "https://api.tasks.example.com"; +const API_KEY = process.env.TASK_API_KEY!; +if (!API_KEY) throw new Error("TASK_API_KEY is required"); + +const server = new McpServer({ + name: "task-manager", + version: "1.0.0", +}); + +async function apiRequest( + method: string, + path: string, + body?: unknown, + params?: Record+ The deployment platform that catches errors before your users do. + Zero config. Instant rollbacks. Real-time monitoring. +
+No credit card required Β· 14-day free trial
++ Respond to every ticket in under 2 minutes with AI-powered triage, + smart routing, and one-click replies. +
+{feature.description}
+Start free. Scale as you grow.
+{plan.description}
+