qontoctl 0.0.0

package/README.md

@@ -0,0 +1,111 @@
+# QontoCtl: The Complete CLI & MCP for Qonto
+
+[![CI](https://github.com/alexey-pelykh/qontoctl/actions/workflows/ci.yml/badge.svg)](https://github.com/alexey-pelykh/qontoctl/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/qontoctl?logo=npm)](https://www.npmjs.com/package/qontoctl)
+[![npm downloads](https://img.shields.io/npm/dm/qontoctl?logo=npm)](https://www.npmjs.com/package/qontoctl)
+[![GitHub Repo stars](https://img.shields.io/github/stars/alexey-pelykh/qontoctl?style=flat&logo=github)](https://github.com/alexey-pelykh/qontoctl)
+[![License](https://img.shields.io/github/license/alexey-pelykh/qontoctl)](LICENSE)
+
+CLI and MCP server for the [Qonto](https://qonto.com) banking API.
+
+This project is brought to you by [Alexey Pelykh](https://github.com/alexey-pelykh).
+
+## What It Does
+
+QontoCtl lets AI assistants (Claude, etc.) interact with Qonto through the [Model Context Protocol](https://modelcontextprotocol.io). It can:
+
+- **Organizations** — retrieve organization details and settings
+- **Transactions** — list, search, and filter bank transactions
+- **Labels** — manage transaction labels and categories
+- **Memberships** — view team members and permissions
+- **Invoices** — upload, list, and manage supplier invoices
+- **Attachments** — manage transaction attachments and receipts
+
+## Prerequisites
+
+- **Node.js** >= 24
+- A **Qonto** business account with API access
+
+## Installation
+
+```sh
+npm install -g qontoctl
+```
+
+Or run directly with npx:
+
+```sh
+npx qontoctl --help
+```
+
+Or install via Homebrew:
+
+```sh
+brew install qontoctl/tap/qontoctl
+```
+
+## Usage with Claude Desktop
+
+Add to your Claude Desktop configuration (`claude_desktop_config.json`):
+
+```json
+{
+    "mcpServers": {
+        "qontoctl": {
+            "command": "npx",
+            "args": ["qontoctl", "mcp"]
+        }
+    }
+}
+```
+
+## CLI Usage
+
+```sh
+qontoctl --help
+qontoctl mcp    # Start MCP server on stdio
+```
+
+## Configuration
+
+QontoCtl supports two authentication methods: **API Key** and **OAuth 2.0**.
+
+### Profile Format
+
+All configuration files use the same YAML format:
+
+```yaml
+api-key:
+  organization_slug: acme-corp-4821
+  secret_key: your-secret-key
+
+oauth:
+  client_id: app-id
+  client_secret: app-secret
+  access_token: eyJ...              # auto-managed
+  refresh_token: dGhp...            # auto-managed
+  expires_at: 2026-02-26T18:30:00Z  # auto-managed
+```
+
+### Resolution Order
+
+**Without `--profile`:**
+1. `QONTOCTL_*` environment variables (highest priority)
+2. `.qontoctl.yaml` in current directory
+3. `~/.qontoctl.yaml` (home default)
+
+**With `--profile acme`:**
+1. `QONTOCTL_ACME_*` environment variables (highest priority)
+2. `~/.qontoctl/acme.yaml`
+
+OAuth takes precedence over API Key when tokens are valid. Expired tokens are refreshed automatically and written back to the source file.
+
+## Disclaimer
+
+`qontoctl` is an **independent project** not affiliated with, endorsed by, or officially connected to **Qonto** or Qonto SAS.
+
+Qonto is a trademark of Qonto SAS.
+
+## License
+
+[AGPL-3.0-only](LICENSE) — For commercial licensing, contact the maintainer.

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 Oleksii PELYKH
+import { createProgram } from "@qontoctl/cli";
+import { runStdioServer } from "@qontoctl/mcp/stdio";
+const program = createProgram();
+program
+    .command("mcp")
+    .description("Start MCP server on stdio (for Claude Desktop, Cursor, etc.)")
+    .action(async () => {
+    await runStdioServer();
+});
+program.parse();
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,yCAAyC;AACzC,oCAAoC;AAEpC,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAErD,MAAM,OAAO,GAAG,aAAa,EAAE,CAAC;AAEhC,OAAO;KACJ,OAAO,CAAC,KAAK,CAAC;KACd,WAAW,CAAC,8DAA8D,CAAC;KAC3E,MAAM,CAAC,KAAK,IAAI,EAAE;IACjB,MAAM,cAAc,EAAE,CAAC;AACzB,CAAC,CAAC,CAAC;AAEL,OAAO,CAAC,KAAK,EAAE,CAAC"}

package/dist/cli.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cli.test.d.ts.map

package/dist/cli.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.test.d.ts","sourceRoot":"","sources":["../src/cli.test.ts"],"names":[],"mappings":""}

package/dist/cli.test.js

@@ -0,0 +1,19 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 Oleksii PELYKH
+import { describe, expect, it } from "vitest";
+import { createProgram } from "@qontoctl/cli";
+describe("qontoctl CLI", () => {
+    it("creates program with correct name", () => {
+        const program = createProgram();
+        expect(program.name()).toBe("qontoctl");
+    });
+    it("registers mcp subcommand", () => {
+        const program = createProgram();
+        program
+            .command("mcp")
+            .description("Start MCP server on stdio (for Claude Desktop, Cursor, etc.)");
+        const commandNames = program.commands.map((c) => c.name());
+        expect(commandNames).toContain("mcp");
+    });
+});
+//# sourceMappingURL=cli.test.js.map

package/dist/cli.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.test.js","sourceRoot":"","sources":["../src/cli.test.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,oCAAoC;AAEpC,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAE9C,QAAQ,CAAC,cAAc,EAAE,GAAG,EAAE;IAC5B,EAAE,CAAC,mCAAmC,EAAE,GAAG,EAAE;QAC3C,MAAM,OAAO,GAAG,aAAa,EAAE,CAAC;QAChC,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAC1C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,0BAA0B,EAAE,GAAG,EAAE;QAClC,MAAM,OAAO,GAAG,aAAa,EAAE,CAAC;QAEhC,OAAO;aACJ,OAAO,CAAC,KAAK,CAAC;aACd,WAAW,CACV,8DAA8D,CAC/D,CAAC;QAEJ,MAAM,YAAY,GAAG,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;QAC3D,MAAM,CAAC,YAAY,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IACxC,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "qontoctl",
+  "version": "0.0.0",
+  "description": "The complete CLI & MCP for Qonto",
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "license": "AGPL-3.0-only",
+  "author": "Alexey Pelykh (https://github.com/alexey-pelykh)",
+  "homepage": "https://github.com/alexey-pelykh/qontoctl",
+  "bugs": "https://github.com/alexey-pelykh/qontoctl/issues",
+  "funding": "https://github.com/sponsors/alexey-pelykh",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/alexey-pelykh/qontoctl.git",
+    "directory": "packages/qontoctl"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/cli.d.ts",
+      "import": "./dist/cli.js"
+    }
+  },
+  "bin": {
+    "qontoctl": "./dist/cli.js"
+  },
+  "mcpName": "io.github.alexey-pelykh/qontoctl",
+  "keywords": [
+    "qonto",
+    "banking",
+    "fintech",
+    "mcp",
+    "cli"
+  ],
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "prepack": "cp ../../README.md .",
+    "build": "tsc",
+    "test": "vitest run",
+    "lint": "eslint src/",
+    "dev": "tsc --watch"
+  },
+  "dependencies": {
+    "@qontoctl/cli": "workspace:^",
+    "@qontoctl/mcp": "workspace:^"
+  },
+  "devDependencies": {
+    "@types/node": "catalog:",
+    "eslint": "catalog:",
+    "typescript": "catalog:",
+    "vitest": "catalog:"
+  }
+}