buchpilot-mcp 0.1.1

package/src/backends/lexoffice.ts

@@ -0,0 +1,392 @@
+import type {
+  IAccountingBackend,
+  Contact, ContactInput, ContactFilter,
+  Invoice, InvoiceInput, InvoiceFilter, LineItem,
+  Voucher, VoucherInput, VoucherFilter,
+  Quotation, QuotationInput,
+} from "./types.js";
+import { ErrorCode, createError } from "../errors.js";
+
+const BASE_URL = "https://api.lexoffice.io/v1";
+
+// Rate limiter: Lexoffice allows max 2 requests/second
+let lastRequestTime = 0;
+
+async function rateLimitSleep(): Promise<void> {
+  const now = Date.now();
+  const elapsed = now - lastRequestTime;
+  if (elapsed < 500) {
+    await new Promise((resolve) => setTimeout(resolve, 500 - elapsed));
+  }
+  lastRequestTime = Date.now();
+}
+
+async function lexofficeRequest(
+  apiKey: string,
+  method: string,
+  endpoint: string,
+  body?: Record<string, unknown>,
+  qs?: Record<string, string>,
+): Promise<any> {
+  await rateLimitSleep();
+
+  const url = new URL(`${BASE_URL}${endpoint}`);
+  if (qs) {
+    for (const [key, value] of Object.entries(qs)) {
+      url.searchParams.set(key, value);
+    }
+  }
+
+  const headers: Record<string, string> = {
+    Authorization: `Bearer ${apiKey}`,
+    Accept: "application/json",
+  };
+
+  const options: RequestInit = { method, headers };
+
+  if (body && method !== "GET") {
+    headers["Content-Type"] = "application/json";
+    options.body = JSON.stringify(body);
+  }
+
+  const response = await fetch(url.toString(), options);
+
+  if (response.status === 401) {
+    throw createError(ErrorCode.AUTH_FAILED, "Lexoffice API key is invalid or expired");
+  }
+  if (response.status === 429) {
+    throw createError(ErrorCode.RATE_LIMITED, "Lexoffice API rate limit exceeded (max 2 req/s)");
+  }
+  if (response.status === 404) {
+    throw createError(ErrorCode.NOT_FOUND, `Resource not found: ${endpoint}`);
+  }
+
+  if (!response.ok) {
+    const errorText = await response.text().catch(() => "Unknown error");
+    throw createError(ErrorCode.BACKEND_ERROR, `Lexoffice API error ${response.status}: ${errorText}`);
+  }
+
+  if (response.status === 204) return {};
+
+  const contentType = response.headers.get("content-type") || "";
+  if (contentType.includes("application/json")) {
+    return response.json();
+  }
+  return response;
+}
+
+// === Mapping Helpers ===
+
+function toLexofficeContact(input: ContactInput): Record<string, unknown> {
+  const roles: Record<string, Record<string, never>> = {};
+  const role = input.role || "customer";
+  if (role === "customer" || role === "both") roles.customer = {};
+  if (role === "vendor" || role === "both") roles.vendor = {};
+
+  const body: Record<string, unknown> = { version: 0, roles };
+
+  if (input.type === "company") {
+    body.company = {
+      name: input.name,
+      ...(input.email ? { contactPersons: [{ emailAddress: input.email }] } : {}),
+    };
+  } else {
+    body.person = {
+      lastName: input.name,
+      ...(input.firstName ? { firstName: input.firstName } : {}),
+    };
+    if (input.email) {
+      body.emailAddresses = { business: [input.email] };
+    }
+  }
+
+  return body;
+}
+
+function fromLexofficeContact(raw: any): Contact {
+  const isCompany = !!raw.company;
+  return {
+    id: raw.id,
+    type: isCompany ? "company" : "person",
+    name: isCompany ? raw.company?.name : raw.person?.lastName,
+    firstName: raw.person?.firstName,
+    email: isCompany
+      ? raw.company?.contactPersons?.[0]?.emailAddress
+      : raw.emailAddresses?.business?.[0] || raw.emailAddresses?.private?.[0],
+    role: raw.roles?.customer && raw.roles?.vendor
+      ? "both"
+      : raw.roles?.vendor ? "vendor" : "customer",
+    backend: "lexoffice",
+    raw,
+  };
+}
+
+function toLexofficeInvoice(input: InvoiceInput): Record<string, unknown> {
+  return {
+    voucherDate: input.date,
+    address: { contactId: input.contactId },
+    lineItems: input.lineItems.map((item) => ({
+      type: "custom",
+      name: item.name,
+      quantity: item.quantity,
+      unitName: "Stueck",
+      unitPrice: {
+        currency: input.currency || "EUR",
+        netAmount: item.unitPrice,
+        taxRatePercentage: item.taxRate,
+      },
+    })),
+    totalPrice: { currency: input.currency || "EUR" },
+    taxConditions: { taxType: "net" },
+    ...(input.title && { title: input.title }),
+    ...(input.introduction && { introduction: input.introduction }),
+    ...(input.remark && { remark: input.remark }),
+  };
+}
+
+function fromLexofficeInvoice(raw: any): Invoice {
+  const lineItems: LineItem[] = (raw.lineItems || [])
+    .filter((li: any) => li.type === "custom")
+    .map((li: any) => ({
+      name: li.name,
+      quantity: li.quantity,
+      unitPrice: li.unitPrice?.netAmount || 0,
+      taxRate: li.unitPrice?.taxRatePercentage || 0,
+    }));
+
+  return {
+    id: raw.id,
+    number: raw.voucherNumber || "",
+    contactId: raw.address?.contactId || "",
+    date: raw.voucherDate || "",
+    dueDate: raw.dueDate || raw.voucherDate || "",
+    status: raw.voucherStatus === "draft" ? "draft"
+      : raw.voucherStatus === "open" ? "open"
+      : raw.voucherStatus === "paid" ? "paid"
+      : raw.voucherStatus === "overdue" ? "overdue"
+      : "open",
+    totalNet: raw.totalPrice?.totalNetAmount || 0,
+    totalGross: raw.totalPrice?.totalGrossAmount || 0,
+    currency: raw.totalPrice?.currency || "EUR",
+    lineItems,
+    backend: "lexoffice",
+    raw,
+  };
+}
+
+function fromLexofficeVoucher(raw: any): Voucher {
+  return {
+    id: raw.id,
+    type: raw.voucherType || "",
+    date: raw.voucherDate || "",
+    totalGross: raw.totalGrossAmount || 0,
+    taxRate: raw.voucherItems?.[0]?.taxRatePercent || 0,
+    backend: "lexoffice",
+    raw,
+  };
+}
+
+function fromLexofficeQuotation(raw: any): Quotation {
+  const lineItems: LineItem[] = (raw.lineItems || [])
+    .filter((li: any) => li.type === "custom")
+    .map((li: any) => ({
+      name: li.name,
+      quantity: li.quantity,
+      unitPrice: li.unitPrice?.netAmount || 0,
+      taxRate: li.unitPrice?.taxRatePercentage || 0,
+    }));
+
+  return {
+    id: raw.id,
+    contactId: raw.address?.contactId || "",
+    date: raw.voucherDate || "",
+    expirationDate: raw.expirationDate,
+    totalNet: raw.totalPrice?.totalNetAmount || 0,
+    totalGross: raw.totalPrice?.totalGrossAmount || 0,
+    lineItems,
+    backend: "lexoffice",
+    raw,
+  };
+}
+
+// === Lexoffice Backend ===
+
+export class LexofficeBackend implements IAccountingBackend {
+  name = "lexoffice";
+  private apiKey: string;
+
+  constructor(apiKey: string) {
+    this.apiKey = apiKey;
+  }
+
+  // --- Contacts ---
+
+  async createContact(input: ContactInput): Promise<Contact> {
+    const body = toLexofficeContact(input);
+    const result = await lexofficeRequest(this.apiKey, "POST", "/contacts", body);
+    return this.getContact(result.id);
+  }
+
+  async getContact(id: string): Promise<Contact> {
+    const raw = await lexofficeRequest(this.apiKey, "GET", `/contacts/${id}`);
+    return fromLexofficeContact(raw);
+  }
+
+  async listContacts(filter?: ContactFilter): Promise<Contact[]> {
+    const qs: Record<string, string> = { size: String(filter?.limit || 25) };
+    if (filter?.email) qs.email = filter.email;
+    if (filter?.name) qs.name = filter.name;
+    if (filter?.role === "customer") qs.customer = "true";
+    if (filter?.role === "vendor") qs.vendor = "true";
+    const response = await lexofficeRequest(this.apiKey, "GET", "/contacts", undefined, qs);
+    return (response.content || []).map(fromLexofficeContact);
+  }
+
+  async updateContact(id: string, input: Partial<ContactInput>): Promise<Contact> {
+    const existing = await lexofficeRequest(this.apiKey, "GET", `/contacts/${id}`);
+    const body = { ...existing, ...input };
+    delete body.id;
+    delete body.resourceUri;
+    if (input.name && body.company) {
+      body.company.name = input.name;
+    }
+    if (input.name && body.person) {
+      body.person.lastName = input.name;
+    }
+    await lexofficeRequest(this.apiKey, "PUT", `/contacts/${id}`, body);
+    return this.getContact(id);
+  }
+
+  // --- Invoices ---
+
+  async createInvoice(input: InvoiceInput): Promise<Invoice> {
+    const body = toLexofficeInvoice(input);
+    const qs: Record<string, string> = {};
+    if (input.finalize) qs.finalize = "true";
+    const result = await lexofficeRequest(this.apiKey, "POST", "/invoices", body, Object.keys(qs).length ? qs : undefined);
+    return this.getInvoice(result.id);
+  }
+
+  async getInvoice(id: string): Promise<Invoice> {
+    const raw = await lexofficeRequest(this.apiKey, "GET", `/invoices/${id}`);
+    return fromLexofficeInvoice(raw);
+  }
+
+  async listInvoices(filter?: InvoiceFilter): Promise<Invoice[]> {
+    const qs: Record<string, string> = { size: String(filter?.limit || 25) };
+    if (filter?.status && filter.status !== "overdue") {
+      qs.voucherStatus = filter.status;
+    }
+    if (filter?.contactId) {
+      qs.contactId = filter.contactId;
+    }
+    const response = await lexofficeRequest(this.apiKey, "GET", "/voucherlist", undefined, {
+      ...qs,
+      voucherType: "invoice",
+    });
+    const items: Invoice[] = (response.content || []).map(fromLexofficeInvoice);
+    if (filter?.status === "overdue") {
+      const now = Date.now();
+      return items.filter((inv: Invoice) => new Date(inv.dueDate).getTime() < now && inv.status !== "paid");
+    }
+    return items;
+  }
+
+  async getInvoicePdf(id: string): Promise<{ data: Buffer; filename: string }> {
+    const docResponse = await lexofficeRequest(this.apiKey, "GET", `/invoices/${id}/document`);
+    const fileId = docResponse.documentFileId;
+    await rateLimitSleep();
+    const fileResponse = await fetch(`${BASE_URL}/files/${fileId}`, {
+      headers: { Authorization: `Bearer ${this.apiKey}` },
+    });
+    if (fileResponse.status === 429) {
+      throw createError(ErrorCode.RATE_LIMITED, "Lexoffice API rate limit exceeded during PDF download");
+    }
+    if (!fileResponse.ok) {
+      throw createError(ErrorCode.BACKEND_ERROR, `Failed to download PDF: ${fileResponse.status}`);
+    }
+    const buffer = Buffer.from(await fileResponse.arrayBuffer());
+    return { data: buffer, filename: `invoice-${id}.pdf` };
+  }
+
+  async updateInvoice(id: string, input: Partial<InvoiceInput>): Promise<Invoice> {
+    const existing = await lexofficeRequest(this.apiKey, "GET", `/invoices/${id}`);
+    const body = { ...existing, ...input };
+    delete body.id;
+    delete body.resourceUri;
+    delete body.organizationId;
+    await lexofficeRequest(this.apiKey, "PUT", `/invoices/${id}`, body);
+    return this.getInvoice(id);
+  }
+
+  // --- Vouchers ---
+
+  async createVoucher(input: VoucherInput): Promise<Voucher> {
+    const taxAmount = input.totalGross - (input.totalGross / (1 + input.taxRate / 100));
+    const body = {
+      type: "voucher",
+      voucherType: input.type,
+      voucherDate: input.date,
+      totalGrossAmount: input.totalGross,
+      totalTaxAmount: taxAmount,
+      taxType: "gross",
+      voucherItems: [{
+        amount: input.totalGross,
+        taxAmount,
+        taxRatePercent: input.taxRate,
+        categoryId: "8f8664a8-fd86-11e1-a21f-0800200c9a66",
+      }],
+      ...(input.contactId && { contactId: input.contactId }),
+      ...(input.remark && { remark: input.remark }),
+    };
+    const result = await lexofficeRequest(this.apiKey, "POST", "/vouchers", body);
+    return this.getVoucher(result.id);
+  }
+
+  async getVoucher(id: string): Promise<Voucher> {
+    const raw = await lexofficeRequest(this.apiKey, "GET", `/vouchers/${id}`);
+    return fromLexofficeVoucher(raw);
+  }
+
+  async listVouchers(filter?: VoucherFilter): Promise<Voucher[]> {
+    const qs: Record<string, string> = { size: String(filter?.limit || 25) };
+    if (filter?.type && filter.type !== "any") qs.voucherType = filter.type;
+    const response = await lexofficeRequest(this.apiKey, "GET", "/voucherlist", undefined, qs);
+    return (response.content || []).map(fromLexofficeVoucher);
+  }
+
+  // --- Quotations ---
+
+  async createQuotation(input: QuotationInput): Promise<Quotation> {
+    const body = {
+      voucherDate: input.date,
+      address: { contactId: input.contactId },
+      lineItems: input.lineItems.map((item) => ({
+        type: "custom",
+        name: item.name,
+        quantity: item.quantity,
+        unitName: "Stueck",
+        unitPrice: {
+          currency: "EUR",
+          netAmount: item.unitPrice,
+          taxRatePercentage: item.taxRate,
+        },
+      })),
+      totalPrice: { currency: "EUR" },
+      taxConditions: { taxType: "net" },
+      ...(input.expirationDate && { expirationDate: input.expirationDate }),
+      ...(input.title && { title: input.title }),
+      ...(input.introduction && { introduction: input.introduction }),
+      ...(input.remark && { remark: input.remark }),
+    };
+    const qs: Record<string, string> = {};
+    if (input.finalize) qs.finalize = "true";
+    const result = await lexofficeRequest(this.apiKey, "POST", "/quotations", body, Object.keys(qs).length ? qs : undefined);
+    return this.getQuotation(result.id);
+  }
+
+  async getQuotation(id: string): Promise<Quotation> {
+    const raw = await lexofficeRequest(this.apiKey, "GET", `/quotations/${id}`);
+    return fromLexofficeQuotation(raw);
+  }
+}

package/src/backends/types.ts

@@ -0,0 +1,137 @@
+// === Gemeinsame Entity-Typen ===
+
+export interface Contact {
+  id: string;
+  type: "person" | "company";
+  name: string;
+  firstName?: string;
+  email?: string;
+  role: "customer" | "vendor" | "both";
+  backend: string;
+  raw: Record<string, unknown>;
+}
+
+export interface ContactInput {
+  type: "person" | "company";
+  name: string;
+  firstName?: string;
+  email?: string;
+  role?: "customer" | "vendor" | "both";
+}
+
+export interface ContactFilter {
+  name?: string;
+  email?: string;
+  role?: "customer" | "vendor";
+  limit?: number;
+}
+
+export interface LineItem {
+  name: string;
+  quantity: number;
+  unitPrice: number;
+  taxRate: number;
+}
+
+export interface Invoice {
+  id: string;
+  number: string;
+  contactId: string;
+  date: string;
+  dueDate: string;
+  status: "draft" | "open" | "paid" | "overdue";
+  totalNet: number;
+  totalGross: number;
+  currency: string;
+  lineItems: LineItem[];
+  backend: string;
+  raw: Record<string, unknown>;
+}
+
+export interface InvoiceInput {
+  contactId: string;
+  date: string;
+  lineItems: LineItem[];
+  title?: string;
+  introduction?: string;
+  remark?: string;
+  currency?: string;
+  finalize?: boolean;
+}
+
+export interface InvoiceFilter {
+  status?: "draft" | "open" | "paid" | "overdue";
+  contactId?: string;
+  limit?: number;
+}
+
+export interface Voucher {
+  id: string;
+  type: string;
+  date: string;
+  totalGross: number;
+  taxRate: number;
+  backend: string;
+  raw: Record<string, unknown>;
+}
+
+export interface VoucherInput {
+  type: "purchaseinvoice" | "purchasecreditnote" | "any";
+  date: string;
+  totalGross: number;
+  taxRate: number;
+  contactId?: string;
+  remark?: string;
+}
+
+export interface VoucherFilter {
+  type?: "purchaseinvoice" | "purchasecreditnote" | "any";
+  limit?: number;
+}
+
+export interface Quotation {
+  id: string;
+  contactId: string;
+  date: string;
+  expirationDate?: string;
+  totalNet: number;
+  totalGross: number;
+  lineItems: LineItem[];
+  backend: string;
+  raw: Record<string, unknown>;
+}
+
+export interface QuotationInput {
+  contactId: string;
+  date: string;
+  lineItems: LineItem[];
+  expirationDate?: string;
+  title?: string;
+  introduction?: string;
+  remark?: string;
+  finalize?: boolean;
+}
+
+// === Backend Interface ===
+
+export interface IAccountingBackend {
+  name: string;
+
+  createContact(input: ContactInput): Promise<Contact>;
+  getContact(id: string): Promise<Contact>;
+  listContacts(filter?: ContactFilter): Promise<Contact[]>;
+  updateContact(id: string, input: Partial<ContactInput>): Promise<Contact>;
+
+  createInvoice(input: InvoiceInput): Promise<Invoice>;
+  getInvoice(id: string): Promise<Invoice>;
+  listInvoices(filter?: InvoiceFilter): Promise<Invoice[]>;
+  getInvoicePdf(id: string): Promise<{ data: Buffer; filename: string }>;
+  updateInvoice(id: string, input: Partial<InvoiceInput>): Promise<Invoice>;
+
+  createVoucher(input: VoucherInput): Promise<Voucher>;
+  getVoucher(id: string): Promise<Voucher>;
+  listVouchers(filter?: VoucherFilter): Promise<Voucher[]>;
+
+  createQuotation(input: QuotationInput): Promise<Quotation>;
+  getQuotation(id: string): Promise<Quotation>;
+}

package/src/config.ts

@@ -0,0 +1,62 @@
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { z } from "zod";
+import { ErrorCode, createError } from "./errors.js";
+
+const BackendConfigSchema = z.object({
+  api_key: z.string().min(1, "API key must not be empty"),
+});
+
+const ConfigSchema = z.object({
+  backends: z.record(z.string(), BackendConfigSchema),
+  default_backend: z.string(),
+});
+
+export type BuchPilotConfig = z.infer<typeof ConfigSchema>;
+
+export function loadConfig(): BuchPilotConfig {
+  const configPaths = [
+    process.env.BUCHPILOT_CONFIG,
+    join(homedir(), ".buchpilot.json"),
+    join(process.cwd(), ".buchpilot.json"),
+  ].filter(Boolean) as string[];
+
+  for (const configPath of configPaths) {
+    if (existsSync(configPath)) {
+      try {
+        const raw = readFileSync(configPath, "utf-8");
+        const parsed = JSON.parse(raw);
+        const validated = ConfigSchema.parse(parsed);
+
+        if (!validated.backends[validated.default_backend]) {
+          throw createError(
+            ErrorCode.BACKEND_NOT_CONFIGURED,
+            `Default backend "${validated.default_backend}" is not configured in backends`,
+          );
+        }
+
+        return validated;
+      } catch (err) {
+        if (err && typeof err === "object" && "code" in err) {
+          throw err;
+        }
+        throw createError(
+          ErrorCode.CONFIG_MISSING,
+          `Invalid config at ${configPath}: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+    }
+  }
+
+  throw createError(
+    ErrorCode.CONFIG_MISSING,
+    "No .buchpilot.json found. Create one at ~/.buchpilot.json or ./.buchpilot.json with your API keys.",
+    {
+      example: {
+        backends: { lexoffice: { api_key: "YOUR_KEY" } },
+        default_backend: "lexoffice",
+      },
+    },
+  );
+}

package/src/errors.ts

@@ -0,0 +1,34 @@
+export enum ErrorCode {
+  AUTH_FAILED = "AUTH_FAILED",
+  RATE_LIMITED = "RATE_LIMITED",
+  NOT_FOUND = "NOT_FOUND",
+  VALIDATION_ERROR = "VALIDATION_ERROR",
+  BACKEND_ERROR = "BACKEND_ERROR",
+  SYNC_CONFLICT = "SYNC_CONFLICT",
+  CONFIG_MISSING = "CONFIG_MISSING",
+  BACKEND_NOT_CONFIGURED = "BACKEND_NOT_CONFIGURED",
+}
+
+export interface BuchPilotError {
+  code: ErrorCode;
+  message: string;
+  details?: Record<string, unknown>;
+  retry_after_ms?: number;
+}
+
+export function createError(
+  code: ErrorCode,
+  message: string,
+  details?: Record<string, unknown>,
+): BuchPilotError {
+  return {
+    code,
+    message,
+    ...(details && { details }),
+    ...(code === ErrorCode.RATE_LIMITED && { retry_after_ms: 500 }),
+  };
+}
+
+export function isRetryable(error: BuchPilotError): boolean {
+  return error.code === ErrorCode.RATE_LIMITED || error.code === ErrorCode.BACKEND_ERROR;
+}

package/src/index.ts

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { loadConfig } from "./config.js";
+import { ErrorCode, createError } from "./errors.js";
+import { LexofficeBackend } from "./backends/lexoffice.js";
+import type { IAccountingBackend } from "./backends/types.js";
+import { registerContactTools } from "./tools/contacts.js";
+import { registerInvoiceTools } from "./tools/invoices.js";
+import { registerVoucherTools } from "./tools/vouchers.js";
+import { registerQuotationTools } from "./tools/quotations.js";
+import { registerSyncTools } from "./tools/sync.js";
+
+// === Backend Registry ===
+
+const backends = new Map<string, IAccountingBackend>();
+
+function getBackend(name?: string): IAccountingBackend {
+  const config = loadConfig();
+  const backendName = name || config.default_backend;
+
+  // Lazy-initialize backends
+  if (!backends.has(backendName)) {
+    const backendConfig = config.backends[backendName];
+    if (!backendConfig) {
+      throw createError(
+        ErrorCode.BACKEND_NOT_CONFIGURED,
+        `Backend "${backendName}" is not configured. Available: ${Object.keys(config.backends).join(", ")}`,
+      );
+    }
+
+    switch (backendName) {
+      case "lexoffice":
+        backends.set(backendName, new LexofficeBackend(backendConfig.api_key));
+        break;
+      default:
+        throw createError(
+          ErrorCode.BACKEND_NOT_CONFIGURED,
+          `Unknown backend type: "${backendName}". Supported: lexoffice`,
+        );
+    }
+  }
+
+  return backends.get(backendName)!;
+}
+
+// === MCP Server ===
+
+const server = new McpServer({
+  name: "buchpilot",
+  version: "0.1.1",
+});
+
+// Register all tools
+registerContactTools(server, getBackend);
+registerInvoiceTools(server, getBackend);
+registerVoucherTools(server, getBackend);
+registerQuotationTools(server, getBackend);
+registerSyncTools(server, getBackend);
+
+// === Start ===
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("BuchPilot MCP Server running (stdio)");
+}
+
+main().catch((error) => {
+  console.error("Fatal error:", error);
+  process.exit(1);
+});