unanet-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.

Development Commands

Building and Running

npm run build    # Compile TypeScript to dist/
npm run dev      # Run in development mode with tsx (hot reload)
npm start        # Run compiled server from dist/
npm run clean    # Remove dist/ directory

Setup Requirements

1. Create .env file from .env.example with Unanet credentials:
   • UNANET_USERNAME, UNANET_PASSWORD, UNANET_API_KEY, UNANET_FIRM_CODE, UNANET_BASE_URL
2. Run npm install to install dependencies
3. Node.js >= 18.0.0 required (ES modules)

Architecture Overview

This is an MCP (Model Context Protocol) server that bridges Claude Desktop with Unanet GovCon ERP. The architecture follows a tool-based pattern where each Unanet operation is exposed as an MCP tool.

Core Components

MCP Server (src/index.ts)

• Implements stdio transport (communicates via stdin/stdout with Claude Desktop)
• Registers all tools and resources with the MCP SDK
• Validates authentication on startup
• Routes tool calls to appropriate handlers

Authentication (src/auth.ts)

• Creates authenticated Axios clients with Basic Auth + API Key headers
• Implements request/response interceptors for logging and error handling
• Maps HTTP errors to user-friendly messages

Tools Pattern Each tool follows this structure:

export const toolName = {
  name: "unanet_operation_name",
  description: "What it does",
  inputSchema: z.object({ /* Zod validation */ }),
  handler: async (args, auth) => {
    // 1. Create authenticated client
    // 2. Make API call(s)
    // 3. Return success/error object
  }
}

Tool Categories

• tools/projects.ts: Project management operations
• tools/timesheet.ts: Time and expense tracking
• tools/contacts.ts: CRM operations (contacts, leads, opportunities)
• tools/financials.ts: Billing, invoicing, and financial reports