# Logo.dev MCP Server
## Overview
This is a Model Context Protocol (MCP) server that provides integration with the Logo.dev API. The server enables AI agents and applications to search for company logos and retrieve customizable logo URLs. Built with TypeScript and the MCP SDK, it exposes two primary tools: `search_logos` for finding companies by name and `get_logo_url` for retrieving direct logo image URLs with customization options like format, size, theme, and greyscale conversion.
**Status**: Ready for deployment to Smithery
## User Preferences
Preferred communication style: Simple, everyday language.
## Recent Changes
**December 8, 2025**:
- Created complete MCP server implementation for Logo.dev API
- Implemented two tools: `search_logos` and `get_logo_url`
- Configured for Smithery TypeScript runtime deployment
- Exports `configSchema` and `createServer` for Smithery integration
- Supports local STDIO mode for Claude Desktop
- Server tested and running successfully
## System Architecture
### Smithery Integration Pattern
The server follows Smithery's TypeScript runtime pattern:
- **`configSchema` export**: Zod schema defining required configuration (API key)
- **`createServer` default export**: Function that receives config and returns MCP server
- **Local STDIO mode**: Runs standalone when executed directly with environment variable
### Server Architecture
**MCP Server Pattern**: The application implements the Model Context Protocol server pattern using the `@modelcontextprotocol/sdk`. This architectural decision enables the server to act as a bridge between AI agents (like Claude) and the Logo.dev API, exposing tools through a standardized protocol.
- **Rationale**: MCP provides a standardized way for AI models to interact with external services and APIs
- **Implementation**: Uses `McpServer` class with tool registration and Zod schema validation
- **Smithery Runtime**: Smithery handles transport layer automatically when deployed
### API Integration Layer
**Logo.dev API Client**: Custom implementation for interacting with Logo.dev's REST API
- **Search Endpoint**: `https://api.logo.dev/search?q={query}` - Queries companies by name
- **Image Endpoint**: `https://img.logo.dev/{domain}` - Serves logo images with customization parameters
- **Authentication**: Bearer token authentication using API key from configuration
### Schema Validation
**Zod Integration**: Uses Zod for runtime type validation and schema definition
- **Config Schema**: Exported for Smithery to generate configuration UI
- **Tool Parameters**: All tool inputs are validated using Zod schemas
- **Type Safety**: Provides TypeScript compile-time types and runtime validation
### Tool Design
**Tool 1 - search_logos**: Query-based company logo search
- **Input**: Single string query parameter
- **Output**: Structured JSON with array of companies including name, domain, and logo URL
- **Error Handling**: Returns user-friendly messages for no results or API errors
**Tool 2 - get_logo_url**: Direct logo URL generation with customization
- **Input**: Domain (required) plus optional format, size, theme, and greyscale parameters
- **Output**: Customized logo URL with query parameters
### Build and Distribution
**TypeScript Compilation**: Source code in `src/` compiled to `build/` directory
- **Module System**: ES Modules (Node16 module resolution)
- **Target**: ES2022 for modern JavaScript features
- **Smithery Build**: Smithery CLI builds from source TypeScript automatically
**Smithery Deployment**: Configured with smithery.yaml
- Runtime: TypeScript
- Entry Point: `src/index.ts` (via package.json module field)
- Config Schema: Requires apiKey parameter (defined via Zod export)
## External Dependencies
### Core Dependencies
**@modelcontextprotocol/sdk** (^1.0.4)
- Purpose: MCP server implementation and protocol handling
- Provides: McpServer, transport layers, tool registration system
**zod** (^3.23.8)
- Purpose: Schema validation and type safety
- Used for: Config schema export and tool parameter validation
**@smithery/sdk** (^2.1.0)
- Purpose: Smithery platform integration
- Used for: Deployment compatibility with Smithery runtime
### External API Services
**Logo.dev API**
- Base URL: `https://api.logo.dev`
- Image URL: `https://img.logo.dev`
- Authentication: Bearer token (API key required)
- Endpoints Used:
- `/search?q={query}` - Company logo search
- Image serving with query parameters (format, size, theme, greyscale)
### Runtime Environment
**Node.js**: Version 20 or higher
**Environment Variables** (for local STDIO mode):
- `LOGO_DEV_API_KEY` - Required for local execution
## Deployment
### Smithery Deployment
1. Push the code to a Git repository
2. Connect the repository to Smithery
3. Smithery automatically detects TypeScript runtime
4. Enter your Logo.dev API key when prompted
5. Deploy and use!
### Local Development
```bash
# Install dependencies
npm install
# Build the project
npm run build
# Run in STDIO mode
export LOGO_DEV_API_KEY="your-api-key"
npm start
```
## Architecture Decisions Log
1. **Smithery TypeScript Runtime** (December 8, 2025)
- Decision: Use Smithery's TypeScript runtime with exported configSchema and createServer
- Rationale: Simplest deployment path, Smithery handles transport layer
- Trade-offs: Requires following Smithery's specific patterns
2. **Direct API Calls vs SDK** (December 8, 2025)
- Decision: Use direct fetch() calls to Logo.dev API
- Rationale: Keep dependencies minimal, full control over requests
- Trade-offs: Manual error handling, but simpler and more transparent
