younium-mcp 1.0.0

package/README.md

@@ -0,0 +1,66 @@
+# younium-mcp
+
+MCP server for the [Younium](https://younium.com) subscription management API. Exposes all 159 Younium API operations as tools for Claude Desktop and other MCP clients.
+
+## Setup for Claude Desktop
+
+1. Find your Claude Desktop config file:
+   - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+   - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+2. Add the `younium` entry to `mcpServers` (merge with any existing config):
+
+```json
+{
+  "mcpServers": {
+    "younium": {
+      "command": "npx",
+      "args": ["-y", "younium-mcp"],
+      "env": {
+        "YOUNIUM_USERNAME": "user@yourcompany.com",
+        "YOUNIUM_PASSWORD": "your-younium-password",
+        "YOUNIUM_CLIENT_ID": "your-client-id",
+        "YOUNIUM_CLIENT_SECRET": "your-client-secret"
+      }
+    }
+  }
+}
+```
+
+3. Restart Claude Desktop. You should now be able to ask things like:
+   - "List all active subscriptions in Younium"
+   - "Get account details for customer X"
+   - "Show me invoices from the past 30 days"
+   - "Create a new quote for account Y"
+
+## Credentials
+
+| Env var | Description |
+|---|---|
+| `YOUNIUM_USERNAME` | Your Younium login email |
+| `YOUNIUM_PASSWORD` | Your Younium password |
+| `YOUNIUM_CLIENT_ID` | OAuth2 client ID (from Younium settings) |
+| `YOUNIUM_CLIENT_SECRET` | OAuth2 client secret |
+| `YOUNIUM_LEGAL_ENTITY` | *(optional)* Legal entity ID for multi-tenant setups |
+
+## Available tools
+
+All 159 Younium API v2.1 endpoints are exposed. Resources include:
+
+- **Accounts** — CRUD, payment details, GoCardless/Stripe requests
+- **Subscriptions** — CRUD, amend, cancel, move, charge
+- **Invoices** — list, get, create, post, void, credit notes
+- **Payments** — list, get, create, post
+- **Products / SimpleProducts** — CRUD
+- **Orders / SalesOrders** — CRUD, charges, versions
+- **Quotes** — CRUD, convert to order
+- **Reports** — list, get data
+- **Usage / Measurements** — list, get, import
+- **Webhooks** — list, get, create, delete
+- **Users** — list, get, invite, deactivate
+- **Journals** — list, get, book, reverse
+- And more: Bookings, Metrics, ChartOfAccounts, Currency, PaymentTerms, TaxTemplates, etc.
+
+## Requirements
+
+- Node.js 18+

package/dist/auth.d.ts

@@ -0,0 +1 @@
+export declare function getToken(): Promise<string>;

package/dist/auth.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getToken = getToken;
+const TOKEN_URL = "https://auth.younium.com/connect/token";
+const REFRESH_BUFFER_SECS = 60;
+let cached = null;
+function getEnv(name) {
+    const val = process.env[name];
+    if (!val)
+        throw new Error(`Missing required env var: ${name}`);
+    return val;
+}
+async function getToken() {
+    const now = Date.now() / 1000;
+    if (cached && cached.expiresAt > now + REFRESH_BUFFER_SECS) {
+        return cached.value;
+    }
+    const body = new URLSearchParams({
+        grant_type: "password",
+        scope: "youniumapi",
+        username: getEnv("YOUNIUM_USERNAME"),
+        password: getEnv("YOUNIUM_PASSWORD"),
+        client_id: getEnv("YOUNIUM_CLIENT_ID"),
+        client_secret: getEnv("YOUNIUM_CLIENT_SECRET"),
+    });
+    const res = await fetch(TOKEN_URL, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: body.toString(),
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`Younium auth failed (${res.status}): ${text}`);
+    }
+    const data = (await res.json());
+    cached = { value: data.access_token, expiresAt: now + data.expires_in };
+    return cached.value;
+}

package/dist/client.d.ts

@@ -0,0 +1 @@
+export declare function request(method: string, path: string, query: Record<string, string>, body: unknown | null, idempotencyKey?: string): Promise<unknown>;

package/dist/client.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.request = request;
+const auth_js_1 = require("./auth.js");
+const BASE_URL = "https://api.younium.com";
+const API_VERSION = "2.1";
+async function request(method, path, query, body, idempotencyKey) {
+    const token = await (0, auth_js_1.getToken)();
+    const url = new URL(BASE_URL + path);
+    for (const [k, v] of Object.entries(query)) {
+        if (v !== undefined && v !== null && v !== "") {
+            url.searchParams.set(k, String(v));
+        }
+    }
+    const headers = {
+        Authorization: `Bearer ${token}`,
+        "api-version": API_VERSION,
+        Accept: "application/json",
+    };
+    if (body !== null) {
+        headers["Content-Type"] = "application/json";
+    }
+    if (idempotencyKey) {
+        headers["younium-idempotency-key"] = idempotencyKey;
+    }
+    const legalEntity = process.env.YOUNIUM_LEGAL_ENTITY;
+    if (legalEntity) {
+        headers["legal-entity"] = legalEntity;
+    }
+    const res = await fetch(url.toString(), {
+        method: method.toUpperCase(),
+        headers,
+        body: body !== null ? JSON.stringify(body) : undefined,
+    });
+    const text = await res.text();
+    if (!res.ok) {
+        return { error: true, status: res.status, body: text };
+    }
+    if (!text)
+        return { success: true };
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}

package/dist/executor.d.ts

@@ -0,0 +1,2 @@
+import type { ToolDefinition } from "./spec-loader.js";
+export declare function execute(tool: ToolDefinition, args: Record<string, unknown>): Promise<string>;

package/dist/executor.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.execute = execute;
+const client_js_1 = require("./client.js");
+async function execute(tool, args) {
+    // Substitute path parameters
+    let urlPath = tool.pathTemplate;
+    for (const param of tool.pathParams) {
+        const val = args[param];
+        if (val === undefined || val === null) {
+            return JSON.stringify({ error: `Missing required path parameter: ${param}` });
+        }
+        urlPath = urlPath.replace(`{${param}}`, encodeURIComponent(String(val)));
+    }
+    // Collect query params
+    const query = {};
+    for (const param of tool.queryParams) {
+        const val = args[param];
+        if (val !== undefined && val !== null) {
+            query[param] = String(val);
+        }
+    }
+    // Build body: everything that isn't a path or query param
+    let body = null;
+    if (tool.hasBody) {
+        const paramSet = new Set([...tool.pathParams, ...tool.queryParams]);
+        const bodyFields = {};
+        for (const [k, v] of Object.entries(args)) {
+            if (!paramSet.has(k) && v !== undefined) {
+                bodyFields[k] = v;
+            }
+        }
+        body = Object.keys(bodyFields).length > 0 ? bodyFields : null;
+    }
+    const idempotencyKey = typeof args["younium-idempotency-key"] === "string"
+        ? args["younium-idempotency-key"]
+        : undefined;
+    try {
+        const result = await (0, client_js_1.request)(tool.method, urlPath, query, body, idempotencyKey);
+        return JSON.stringify(result, null, 2);
+    }
+    catch (err) {
+        return JSON.stringify({ error: String(err) });
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+const spec_loader_js_1 = require("./spec-loader.js");
+const executor_js_1 = require("./executor.js");
+const tools = (0, spec_loader_js_1.loadTools)();
+// Build a fast lookup map
+const toolMap = new Map(tools.map((t) => [t.name, t]));
+const server = new index_js_1.Server({ name: "younium-mcp", version: "1.0.0" }, { capabilities: { tools: {} } });
+server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
+    tools: tools.map((t) => ({
+        name: t.name,
+        description: t.description,
+        inputSchema: t.inputSchema,
+    })),
+}));
+server.setRequestHandler(types_js_1.CallToolRequestSchema, async (req) => {
+    const { name, arguments: args = {} } = req.params;
+    const tool = toolMap.get(name);
+    if (!tool) {
+        return {
+            content: [{ type: "text", text: JSON.stringify({ error: `Unknown tool: ${name}` }) }],
+            isError: true,
+        };
+    }
+    const result = await (0, executor_js_1.execute)(tool, args);
+    return { content: [{ type: "text", text: result }] };
+});
+async function main() {
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    process.stderr.write(`Fatal: ${err}\n`);
+    process.exit(1);
+});

package/dist/spec-loader.d.ts

@@ -0,0 +1,27 @@
+interface JsonSchema {
+    type?: string;
+    format?: string;
+    description?: string;
+    nullable?: boolean;
+    properties?: Record<string, JsonSchema>;
+    items?: JsonSchema;
+    required?: string[];
+    additionalProperties?: JsonSchema | boolean;
+    allOf?: JsonSchema[];
+    oneOf?: JsonSchema[];
+    anyOf?: JsonSchema[];
+    $ref?: string;
+    enum?: unknown[];
+}
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: JsonSchema;
+    method: string;
+    pathTemplate: string;
+    pathParams: string[];
+    queryParams: string[];
+    hasBody: boolean;
+}
+export declare function loadTools(): ToolDefinition[];
+export {};

package/dist/spec-loader.js

@@ -0,0 +1,196 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadTools = loadTools;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const HTTP_METHODS = ["get", "post", "put", "patch", "delete"];
+function operationIdToName(operationId) {
+    return operationId
+        .replace(/[^a-zA-Z0-9]+/g, "_")
+        .replace(/([a-z])([A-Z])/g, "$1_$2")
+        .toLowerCase()
+        .replace(/^_+|_+$/g, "");
+}
+function resolveRef(ref, spec) {
+    const parts = ref.replace(/^#\//, "").split("/");
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    let cur = spec;
+    for (const p of parts) {
+        cur = cur[p];
+        if (cur === undefined)
+            return {};
+    }
+    return cur;
+}
+function resolveSchema(schema, spec, depth = 0) {
+    if (depth > 6)
+        return { type: "object" };
+    if (schema.$ref) {
+        return resolveSchema(resolveRef(schema.$ref, spec), spec, depth + 1);
+    }
+    const out = { ...schema };
+    delete out.$ref;
+    if (out.nullable) {
+        delete out.nullable;
+    }
+    if (out.properties) {
+        const resolved = {};
+        for (const [k, v] of Object.entries(out.properties)) {
+            resolved[k] = resolveSchema(v, spec, depth + 1);
+        }
+        out.properties = resolved;
+    }
+    if (out.items) {
+        out.items = resolveSchema(out.items, spec, depth + 1);
+    }
+    if (out.allOf) {
+        const merged = mergeAllOf(out.allOf, spec, depth);
+        delete out.allOf;
+        Object.assign(out, merged);
+    }
+    if (out.oneOf) {
+        out.oneOf = out.oneOf.map((s) => resolveSchema(s, spec, depth + 1));
+    }
+    if (out.anyOf) {
+        out.anyOf = out.anyOf.map((s) => resolveSchema(s, spec, depth + 1));
+    }
+    return out;
+}
+function mergeAllOf(schemas, spec, depth) {
+    const merged = { type: "object", properties: {}, required: [] };
+    for (const s of schemas) {
+        const resolved = resolveSchema(s, spec, depth + 1);
+        if (resolved.properties) {
+            Object.assign(merged.properties, resolved.properties);
+        }
+        if (resolved.required) {
+            merged.required = [...(merged.required ?? []), ...resolved.required];
+        }
+        if (resolved.type && resolved.type !== "object") {
+            merged.type = resolved.type;
+        }
+    }
+    if (!merged.properties || Object.keys(merged.properties).length === 0) {
+        delete merged.properties;
+    }
+    if (!merged.required || merged.required.length === 0) {
+        delete merged.required;
+    }
+    return merged;
+}
+function paramSchema(param, spec) {
+    const base = param.schema ? resolveSchema(param.schema, spec) : { type: "string" };
+    if (param.description) {
+        base.description = param.description;
+    }
+    return base;
+}
+function loadTools() {
+    const specPath = path.join(__dirname, "..", "spec", "youniumv2-prod.json");
+    const raw = fs.readFileSync(specPath, "utf-8");
+    const spec = JSON.parse(raw);
+    const tools = [];
+    const seen = new Set();
+    for (const [pathTemplate, methods] of Object.entries(spec.paths)) {
+        for (const method of HTTP_METHODS) {
+            const op = methods[method];
+            if (!op)
+                continue;
+            const rawId = op.operationId ?? `${method}_${pathTemplate.replace(/[^a-zA-Z0-9]/g, "_")}`;
+            let name = operationIdToName(rawId);
+            // Deduplicate
+            if (seen.has(name)) {
+                name = `${name}_${method}`;
+            }
+            seen.add(name);
+            const description = [op.summary, op.description]
+                .filter(Boolean)
+                .join(" — ")
+                .slice(0, 400);
+            const params = (op.parameters ?? []).filter((p) => p.in !== "header");
+            const pathParams = params
+                .filter((p) => p.in === "path")
+                .map((p) => p.name);
+            const queryParams = params
+                .filter((p) => p.in === "query")
+                .map((p) => p.name);
+            // Build combined input schema
+            const properties = {};
+            const required = [];
+            for (const p of params) {
+                properties[p.name] = paramSchema(p, spec);
+                if (p.required)
+                    required.push(p.name);
+            }
+            let hasBody = false;
+            if (op.requestBody?.content) {
+                const jsonContent = op.requestBody.content["application/json"] ??
+                    op.requestBody.content["application/merge-patch+json"] ??
+                    Object.values(op.requestBody.content)[0];
+                if (jsonContent?.schema) {
+                    const bodySchema = resolveSchema(jsonContent.schema, spec);
+                    if (bodySchema.properties) {
+                        for (const [k, v] of Object.entries(bodySchema.properties)) {
+                            properties[k] = v;
+                        }
+                        if (bodySchema.required) {
+                            required.push(...bodySchema.required.filter((r) => !required.includes(r)));
+                        }
+                    }
+                    else {
+                        // Scalar or array body — wrap it
+                        properties["body"] = bodySchema;
+                    }
+                    hasBody = true;
+                }
+            }
+            const inputSchema = { type: "object", properties };
+            if (required.length > 0)
+                inputSchema.required = required;
+            tools.push({
+                name,
+                description,
+                inputSchema,
+                method,
+                pathTemplate,
+                pathParams,
+                queryParams,
+                hasBody,
+            });
+        }
+    }
+    return tools;
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "younium-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for the Younium subscription management API",
+  "main": "dist/index.js",
+  "bin": "dist/index.js",
+  "files": [
+    "dist",
+    "spec"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "ts-node src/index.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.5.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "younium",
+    "mcp",
+    "claude",
+    "subscription-management"
+  ]
+}