logseq-mcp-server: Instructions file for Claude Code

CLAUDE.md - Logseq AI MCP Server

Common Commands

# Development
npm run dev                 # Start development server
npm run build              # Build the project
npm run type-check          # Run TypeScript type checking
npm run lint               # Run ESLint
npm run test               # Run test suite
npm run test:watch         # Run tests in watch mode

# Package management
npm install                # Install dependencies
npm audit                  # Check for security vulnerabilities

Code Quality & Maintainability Principles

• ALWAYS use TypeScript with strict mode enabled
• Prefer explicit types over any or unknown
• Enforce consistent code style with ESLint + Prettier (or Biome)
• Keep functions small and single-purpose (SRP)
• Use clear naming for handlers, schemas, and RPC methods
• Organize code into modules (/handlers, /schemas, /utils, /tests)
• Document public methods and exported types with JSDoc
• Use named functional components only
• Place hooks above JSX
• Split components >250 LOC
• Avoid useEffect unless truly needed
• Use memo/useCallback/useMemo only when necessary

Runtime Safety Requirements

• YOU MUST validate all incoming JSON-RPC requests with Zod (or JSON Schema)
• YOU MUST validate all outgoing responses before sending back
• Always return proper JSON-RPC error codes (-32600, -32601, -32602, -32603)
• Avoid throwing raw errors — wrap them in structured error helpers
• Sanitize and redact sensitive data in logs

Testing & CI Standards

• Write unit tests for each handler (Vitest/Jest)
• Add at least one integration test that spins up the server and executes RPC calls
• Use mocked inputs/outputs for edge cases (empty data, invalid payloads, timeouts)
• Run tsc --noEmit, lint, and test in CI pipeline
• Ensure 100% type-check clean (no ts-ignore)

Build & Tooling

• Bundle with tsup or esbuild for small, fast CLI output
• Expose CLI entry via bin in package.json
• Use #!/usr/bin/env node in CLI entry point
• Ensure build outputs both CJS and ESM (for compatibility)
• Add "type": "module" in package.json if using ESM
• Automate versioning and changelogs with Changesets (optional)