# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Overview
This is a Model Context Protocol (MCP) server that enables Claude Desktop to interact with MIRO boards through the MIRO API. The server is written in TypeScript and uses the MCP SDK to expose MIRO functionality as tools.
## Development Commands
```bash
# Install dependencies
npm install
# Build the TypeScript project
npm run build
# Run in development mode with auto-reload
npm run dev
# Start the built server
npm run start
```
## Architecture
### Core Components
1. **MCP Server Integration** (`src/index.ts`):
- Main server class `MiroMCPServer` handles all MCP protocol communication
- Uses `StdioServerTransport` for communication with Claude Desktop
- Implements tool handlers for MIRO API operations
2. **MIRO API Client**:
- Axios-based HTTP client configured with base URL and authentication
- All API calls go through `miroClient` instance with Bearer token authentication
- API base URL: `https://api.miro.com/v2`
3. **Available Tools**:
- `list_boards`: Lists accessible MIRO boards
- `get_board`: Retrieves specific board details
- `get_board_items`: Fetches board items/widgets (sticky notes, text, shapes, cards, etc.)
- `get_board_frames`: Gets all frames from a board
- `search_board_content`: Searches text content across board items
### Configuration
- **Environment Variables**: Uses `.env` file for `MIRO_ACCESS_TOKEN`
- **TypeScript**: ES2022 target with NodeNext module system
- **Build Output**: Compiled to `dist/` directory
- **Entry Point**: `dist/index.js` (ESM module)
### Error Handling
- All tool handlers wrap API calls in try-catch blocks
- Errors return structured MCP error responses with descriptive messages
- Server validates MIRO_ACCESS_TOKEN presence on startup
## Key Implementation Details
- The server filters and transforms MIRO API responses to return only essential data
- Search functionality (`searchBoardContent`) performs client-side filtering on board items
- Item content extraction handles multiple field types: `content`, `title`, and `text`
- All list operations support pagination limits to prevent overwhelming responses
