unsplash-mcp-server: Instructions file for Codex

Agent Instructions for Unsplash MCP Server

Project Context

You are working on an Unsplash MCP Server - a Model Context Protocol server that integrates with the Unsplash API. This server allows LLMs to search for photos, collections, and users on Unsplash through a standardized MCP interface.

Tech Stack:

• TypeScript with ES modules
• Node.js LTS (currently 20.x)
• MCP SDK (@modelcontextprotocol/sdk)
• Zod for validation
• Node's built-in test runner

Architecture Overview

File Structure

src/
├── index.ts                          # MCP server entry point (stdio/HTTP)
├── services/
│   ├── unsplash-client.ts           # Unsplash API client
│   ├── unsplash-client.test.ts      # API client tests
│   ├── formatters.ts                # Response formatters
│   └── formatters.test.ts           # Formatter tests
├── tools/
│   ├── photos.ts                    # Photo-related MCP tools
│   └── collections-users.ts         # Collection/user MCP tools
├── schemas/
│   └── index.ts                     # Zod validation schemas
├── types.ts                         # TypeScript type definitions
└── constants.ts                     # Constants (API URL, limits)

Key Components

UnsplashClient (src/services/unsplash-client.ts)

• Handles all HTTP communication with Unsplash API
• Implements error handling with UnsplashAPIError class
• Provides makeRequest<T>() and trackDownload() methods

Formatters (src/services/formatters.ts)

• Convert API responses to markdown or JSON
• Include: formatPhotoMarkdown(), formatCollectionMarkdown(), formatUserMarkdown(), etc.
• Use truncateIfNeeded() for content length management

MCP Tools (src/tools/)

• Register tools with the MCP server
• Use Zod schemas for input validation
• Return formatted responses (markdown or JSON based on format parameter)

Development Guidelines

When Adding New Features

Step-by-step process:

1. Add types to src/types.ts
2. Create Zod schema in src/schemas/index.ts
3. Add API method to UnsplashClient if needed
4. Create formatter function in src/services/formatters.ts
5. Register MCP tool in appropriate file under src/tools/
6. Write comprehensive tests
7. Update AGENTS.md if new patterns are introduced