tinderbox-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.

Overview

Tinderbox MCP Server is a Model Context Protocol (MCP) server that enables AI assistants to interact with Tinderbox, a macOS knowledge management application. The server uses AppleScript to control Tinderbox documents, allowing AI assistants to create notes, link them, update attributes, and navigate document hierarchies via natural language.

Build and Development Commands

# Install dependencies
npm install

# Build the TypeScript project
npm run build

# Run the server (requires built files)
npm run start

# Run with custom AppleScript directory
node build/index.js /path/to/applescripts

The build output goes to the build/ directory. The server accepts one optional argument: the path to the AppleScript files (defaults to ./applescripts).

Architecture

Core Components

src/index.ts - Single-file architecture containing:

• MCP Server Setup: Creates an MCP server using @modelcontextprotocol/sdk
• Script Registry (scriptConfigs): Maps tool names to their configurations, including descriptions and Zod parameter schemas
• Script Execution Pipeline: Uses Node's child_process.execFile to call osascript with compiled AppleScript files
• Security Validation (validateScriptPath): Ensures scripts are within the allowed directory and have .scpt extension

AppleScript Integration

The server bridges MCP tools to AppleScript via a registration system:

1. Each entry in scriptConfigs defines a tool with its parameters and defaults
2. The registerScriptTools() function dynamically registers each configured script as an MCP tool
3. When a tool is called, parameters are validated with Zod schemas (applying defaults), then converted to key=value format
4. The corresponding .scpt file in applescripts/ is executed via osascript

Available AppleScript Tools:

• create_note - Creates notes with title, text, parent path
• read_note - Retrieves note title and text
• get_children - Lists child notes with paths and ChildCount
• get_siblings - Lists sibling notes at the same hierarchy level
• get_links - Returns outgoing links from a note
• link_notes - Creates typed links between notes
• update_attribute - Modifies note attributes (WARNING: can overwrite existing content including Name and Text)