attio-mcp-server: Instructions file for Claude Code

CLAUDE.md

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

Project Overview

This repository contains an Attio MCP (Model Context Protocol) server generated from the Attio OpenAPI specification. The server enables AI assistants like Claude Desktop and Cursor to interact with the Attio API through standardized MCP tools.

Common Development Commands

Building and Running

# Install dependencies
bun install

# Build TypeScript code
bun run build

# Run the server (stdio mode)
bun start

# Run tests
bun test
bun test --watch       # Watch mode
bun test --coverage    # With coverage

# Run single test file
bun test src/__tests__/tool-name-transformer.test.ts

# Manual testing
bun run test:manual    # Interactive test client
bun run test:demo      # Demo script with sample commands  
bun run test:names     # Test tool name transformations
bun run test:server    # Raw server for JSON-RPC input

Testing the MCP Server

With Claude Desktop or Cursor

1. Run ./install.sh to install the server
2. Restart Claude Desktop/Cursor
3. The server will appear in the tools list with human-readable names
4. Example prompts:
   • "Use Attio to list all objects in my workspace"
   • "Get my Attio workspace information"
   • "List all contacts in Attio"

Manual Testing (JSON-RPC)

# Run the interactive test client
npm run test:manual

# Quick demo of all functionality
npm run test:demo

# Test tool name transformations
npm run test:names

# Example commands using human-readable names:
# 1. List available tools
{"jsonrpc": "2.0", "method": "tools/list", "id": 1}

# 2. Call a tool with human-readable name
{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "list_objects", "arguments": {}}, "id": 2}

# 3. Get workspace info
{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "get_current_user", "arguments": {}}, "id": 3}

Code Quality

# Run all checks (format, lint, typecheck)
bun run check

# Run individual tools
bun run lint          # Lint with Biome
bun run format        # Format with Biome  
bun run typecheck     # TypeScript type checking
bun run ci           # CI checks (for pre-commit)