e-conomic-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.

Project Overview

This is an MCP (Model Context Protocol) server that provides AI assistants with tools to interact with the e-conomic REST API for bookkeeping operations. The server uses the @modelcontextprotocol/sdk to register tools that can create and manage customers, products, draft invoices, and booked invoices.

Required Environment Variables

The server requires e-conomic API credentials:

• ECONOMIC_APP_SECRET_TOKEN (required)
• ECONOMIC_AGREEMENT_GRANT_TOKEN (required)
• ECONOMIC_BASE_URL (optional, defaults to https://restapi.e-conomic.com)
• ECONOMIC_DEBUG (optional, set to true to emit JSON debug logs to stderr)

For local development, credentials can be stored in a .env file at the repository root.

Development Commands

Start the server

npm start

Run tests

npm test
# or
npm run test:harness

The test harness (scripts/test-harness.js) invokes all registered tools with sample data to verify functionality. It supports placeholder replacement ($lastDraft, $lastBooked) to chain dependent operations.

Architecture

Entry Point

• src/server.js - Creates the MCP server instance, registers all tools, and connects to stdio transport

Tool Registration Pattern

All tools follow a consistent registration pattern:

1. Tools are defined in individual files under src/tools/
2. Each tool file exports a register*Tool(server) function
3. src/tools/index.js imports and calls all registration functions
4. Tools use Zod schemas for input validation
5. Tools return standardized MCP responses with { content: [{ type: "text", text: "..." }] }

API Client Layer

• src/economic/api-client.js - Centralizes all HTTP communication with e-conomic API
  • validateCredentials() - Checks for required env vars
  • request(method, path, body) - Makes authenticated requests
  • EconomicApiError - Custom error class with status, errorCode, details, hint fields