better-notion-mcp: Instructions file for Codex

AGENTS.md - better-notion-mcp

MCP Server for Notion API. TypeScript, Node.js >= 24, bun, ESM.

Build / Lint / Test Commands

bun install                 # Install dependencies
bun run build               # tsc --build && esbuild CLI bundle
bun run check               # Biome check + tsc --noEmit (CI command)
bun run check:fix           # Auto-fix Biome + type check
bun run test                # vitest --passWithNoTests (NEVER use bare "bun test")
bun run test:watch          # vitest watch
bun run test:coverage       # vitest --coverage
bun run lint                # biome lint src
bun run format              # biome format --write .
bun run type-check          # tsc --noEmit
bun run dev                 # tsx watch dev server

# Run a single test file
bun x vitest run src/tools/helpers/errors.test.ts

# Run a single test by name
bun x vitest run -t "test name pattern"

# Mise shortcuts
mise run setup              # Full dev environment setup
mise run lint               # bun run check
mise run test               # bun run test
mise run fix                # bun run check:fix

Code Style

Formatting (Biome)

• Indent: 2 spaces
• Line width: 120
• Quotes: Single quotes
• Semicolons: As needed (omit when possible)
• Trailing commas: None
• Arrow parens: Always
• Bracket spacing: true
• Line endings: LF

Imports

1. Type imports use import type (separate statement)
2. External packages first, then internal imports (relative paths)
3. Node builtins with node: prefix (node:fs, node:path, node:url)
4. Always use .js extension in import paths (ESM requirement)

import type { Client } from '@notionhq/client'
import { NotionMCPError, withErrorHandling } from '../helpers/errors.js'
import { blocksToMarkdown, markdownToBlocks } from '../helpers/markdown.js'

TypeScript

• strict: true, target: es2021, module: es2022, moduleResolution: Bundler
• composite: true for incremental builds
• isolatedModules: true, forceConsistentCasingInFileNames: true