Harvest MCP Server

# Harvest MCP Server Setup Log ## Project Overview Creating a TypeScript CLI project that implements an MCP (Model Context Protocol) server for the Harvest API v2. ## Progress Log ### Step 1: Research and Package Selection - **MCP Package**: `@modelcontextprotocol/sdk` (v1.16.0) - The official TypeScript SDK - **Harvest API Package**: `harvest` - Offers good TypeScript support and is actively maintained - **Alternative Harvest Package**: `harvest-v2` - Full client API for Harvest API V2 ### Step 2: Project Structure Created project directory: `/home/beagle/work/harvest-mcp` ### Next Steps: 1. Initialize npm project ✓ 2. Install dependencies 3. Set up TypeScript configuration ✓ 4. Create basic MCP server structure ✓ 5. Integrate Harvest API client ✓ 6. Implement MCP tools for Harvest operations ✓ ## Commands to Run ```bash # Initialize project npm init -y # Install dependencies npm install @modelcontextprotocol/sdk harvest dotenv npm install --save-dev typescript @types/node tsx nodemon # Initialize TypeScript npx tsc --init ``` ### Step 3: Project Initialization - Created package.json with npm init ✓ - Note: npm install failing in Claude Code environment, creating files manually ### Step 4: Creating Project Structure Created the following files: - `tsconfig.json` - TypeScript configuration ✓ - `src/index.ts` - Main MCP server file ✓ - `src/harvest-client.ts` - Harvest API client wrapper ✓ - `src/tools.ts` - MCP tool definitions ✓ - `.env.example` - Environment variables example ✓ ### Step 5: Implementation Details #### Files Created: 1. **package.json** - Updated with proper dependencies and scripts - Added MCP SDK and Harvest client - Configured as ES module - Added dev/build/start scripts - Added bin entry for CLI usage 2. **tsconfig.json** - TypeScript configuration - Target ES2022 - Module ESNext - Strict mode enabled - Source maps and declarations 3. **src/index.ts** - Main MCP server - Loads environment variables - Initializes Harvest client - Sets up MCP server with stdio transport - Implements tool handlers for all Harvest operations 4. **src/harvest-client.ts** - Harvest API wrapper - Wraps the Harvest npm package - Provides methods for all major Harvest resources - Handles authentication configuration 5. **src/tools.ts** - MCP tool definitions - Defines 14 tools for Harvest operations - Covers time entries, projects, tasks, users, clients, and reports - Each tool has proper input schema with types and descriptions 6. **.env.example** - Environment template - HARVEST_ACCOUNT_ID - HARVEST_ACCESS_TOKEN - Optional MCP server configuration ### Step 6: Available Tools The MCP server implements the following tools: **Time Entry Management:** - `harvest_list_time_entries` - List time entries with filters - `harvest_create_time_entry` - Create new time entry - `harvest_update_time_entry` - Update existing time entry - `harvest_delete_time_entry` - Delete time entry **Project Management:** - `harvest_list_projects` - List all projects - `harvest_get_project` - Get project details **Task Management:** - `harvest_list_tasks` - List all tasks **User Management:** - `harvest_get_current_user` - Get authenticated user info - `harvest_list_users` - List all users **Client Management:** - `harvest_list_clients` - List all clients **Reporting:** - `harvest_time_report` - Get time reports for date range **Assignments:** - `harvest_list_project_assignments` - List project assignments - `harvest_list_task_assignments` - List task assignments for a project ### Next Steps for Usage: 1. **Install dependencies:** ```bash cd /home/beagle/work/harvest-mcp npm install ``` 2. **Set up environment:** - Copy `.env.example` to `.env` - Add your Harvest account ID and access token 3. **Build the project:** ```bash npm run build ``` 4. **Test the server:** ```bash npm run dev ``` 5. **Configure with Claude Desktop or other MCP clients:** - Add to Claude Desktop's config file - Point to the built executable