things-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Development Commands

Essential Commands

npm run build          # Compile TypeScript to build/ directory
npm test              # Run Jest tests with ES module support
npm run dev           # Watch mode for development
npm start             # Run the MCP server
npm run inspector     # Launch MCP Inspector for testing tools

Testing Commands

npm test -- --testNamePattern="URL Builder"  # Run specific test suite
npm test -- tests/server.test.ts             # Run specific test file
npm run test:watch                           # Watch mode for tests

Memories

• Do not run npm run inspector on your own
• github repo is https://github.com/BMPixel/things-mcp

Architecture Overview

MCP Server Design

This is a Model Context Protocol (MCP) server that integrates with Things.app on macOS via URL scheme automation. The architecture follows these key patterns:

Core Flow:

1. MCP tools receive structured parameters (validated with Zod schemas)
2. Tools convert parameters to Things URL scheme format via url-builder.ts
3. URLs are executed using macOS open command to trigger Things.app actions
4. All operations return MCP-compliant content responses

Tool Registration Pattern: Each tool follows a consistent pattern in src/tools/:

• Export a registerXxxTool(server: McpServer) function
• Use Zod schemas for input validation with .shape property
• Call server.tool(name, schema.shape, handler) to register
• Return { content: [{ type: "text", text: "..." }] } format

Key Components

URL Construction (src/utils/url-builder.ts):

• buildThingsUrl(): Converts parameters to Things URL scheme
• openThingsUrl(): Executes URLs via macOS open command (async/await)
• Uses encodeURIComponent() for proper percent encoding (spaces become %20)

Authentication (src/utils/auth.ts):

• Update operations require THINGS_AUTH_TOKEN environment variable
• Use requireAuthToken() for operations that modify existing items
• Token obtained from Things.app Preferences → General → Enable Things URLs