@creditsync-pro/mcp 1.0.0

package/README.md

@@ -0,0 +1,43 @@
+# CreditSync MCP Server
+
+MCP server for connecting Claude Desktop to your CreditSync account. Requires a CreditSync Pro subscription.
+
+## Setup
+
+1. In CreditSync, go to **Settings > API** and create an API key
+2. Copy the key (it's only shown once)
+3. Add to your Claude Desktop config (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "creditsync": {
+      "command": "npx",
+      "args": ["@creditsync-pro/mcp"],
+      "env": {
+        "CREDITSYNC_API_KEY": "cs_your_key_here"
+      }
+    }
+  }
+}
+```
+
+4. Restart Claude Desktop
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `list_benefits` | List all tracked benefits with status, amounts, expiry dates |
+| `get_benefit` | Get detailed info for a specific benefit with all periods |
+| `mark_benefit_used` | Mark a benefit as used, partial, or unused |
+| `get_dashboard` | Dashboard metrics: expiring, captured, available, ROI |
+| `list_cards` | List all cards with fees, renewal months, benefit counts |
+
+## Examples
+
+Ask Claude:
+- "What benefits are expiring this week?"
+- "Show me my dashboard"
+- "Mark my Uber Cash as used"
+- "What cards do I have and when do their fees post?"

package/dist/api-client.d.ts

@@ -0,0 +1,8 @@
+export declare class CreditSyncClient {
+    private baseUrl;
+    private apiKey;
+    constructor(apiKey: string, baseUrl?: string);
+    private request;
+    get(path: string, params?: Record<string, string>): Promise<unknown>;
+    patch(path: string, body: unknown): Promise<unknown>;
+}

package/dist/api-client.js

@@ -0,0 +1,32 @@
+export class CreditSyncClient {
+    baseUrl;
+    apiKey;
+    constructor(apiKey, baseUrl = "https://www.creditsync.pro") {
+        this.apiKey = apiKey;
+        this.baseUrl = baseUrl.replace(/\/$/, "");
+    }
+    async request(method, path, body) {
+        const url = `${this.baseUrl}${path}`;
+        const res = await fetch(url, {
+            method,
+            headers: {
+                "Authorization": `Bearer ${this.apiKey}`,
+                "Content-Type": "application/json",
+            },
+            ...(body ? { body: JSON.stringify(body) } : {}),
+        });
+        const data = await res.json();
+        if (!res.ok) {
+            const message = data.error ?? `API error: ${res.status}`;
+            throw new Error(message);
+        }
+        return data;
+    }
+    async get(path, params) {
+        const query = params ? "?" + new URLSearchParams(params).toString() : "";
+        return this.request("GET", path + query);
+    }
+    async patch(path, body) {
+        return this.request("PATCH", path, body);
+    }
+}

package/dist/index.d.ts

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

package/dist/index.js

@@ -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 { z } from "zod";
+import { CreditSyncClient } from "./api-client.js";
+const apiKey = process.env.CREDITSYNC_API_KEY;
+if (!apiKey) {
+    console.error("CREDITSYNC_API_KEY environment variable is required");
+    process.exit(1);
+}
+const baseUrl = process.env.CREDITSYNC_API_URL ?? "https://www.creditsync.pro";
+const client = new CreditSyncClient(apiKey, baseUrl);
+const server = new McpServer({
+    name: "creditsync",
+    version: "1.0.0",
+});
+// ─── list_benefits ─────────────────────────────────
+server.tool("list_benefits", "List all tracked credit card benefits with current period status, amounts, and expiry dates. Filter by status (unused/partial/used), card nickname, or expiring within N days.", {
+    status: z.enum(["unused", "partial", "used"]).optional().describe("Filter by usage status"),
+    card: z.string().optional().describe("Filter by card nickname (partial match)"),
+    expiring_within_days: z.number().int().positive().optional().describe("Only return benefits expiring within this many days"),
+}, async ({ status, card, expiring_within_days }) => {
+    const params = {};
+    if (status)
+        params.status = status;
+    if (card)
+        params.card = card;
+    if (expiring_within_days)
+        params.expiring_within_days = String(expiring_within_days);
+    const data = await client.get("/api/v1/benefits", params);
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+});
+// ─── get_benefit ───────────────────────────────────
+server.tool("get_benefit", "Get detailed information about a specific benefit including all historical periods.", {
+    id: z.string().describe("The benefit ID from list_benefits"),
+}, async ({ id }) => {
+    const data = await client.get(`/api/v1/benefits/${id}`);
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+});
+// ─── mark_benefit_used ─────────────────────────────
+server.tool("mark_benefit_used", "Mark a benefit period as used, partially used, or unused. Use the period_id from list_benefits or get_benefit.", {
+    period_id: z.string().describe("The period ID to update"),
+    status: z.enum(["unused", "partial", "used"]).describe("New usage status"),
+    amount_used: z.number().positive().optional().describe("Dollar amount used (required for partial status)"),
+    notes: z.string().optional().describe("Optional note about usage"),
+}, async ({ period_id, status, amount_used, notes }) => {
+    const body = { usageStatus: status };
+    if (amount_used !== undefined)
+        body.usedAmount = amount_used;
+    if (notes !== undefined)
+        body.notes = notes;
+    const data = await client.patch(`/api/v1/benefits/${period_id}/use`, body);
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+});
+// ─── get_dashboard ─────────────────────────────────
+server.tool("get_dashboard", "Get dashboard metrics: benefits expiring in 30 days, captured this month, total available, and net ROI value (captured vs annual fees).", {}, async () => {
+    const data = await client.get("/api/v1/dashboard");
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+});
+// ─── list_cards ────────────────────────────────────
+server.tool("list_cards", "List all credit cards with issuer, annual fee, renewal month, owner, and benefit count.", {}, async () => {
+    const data = await client.get("/api/v1/cards");
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+});
+// ─── Start server ──────────────────────────────────
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error("MCP server error:", err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@creditsync-pro/mcp",
+  "version": "1.0.0",
+  "description": "CreditSync MCP server for Claude Desktop",
+  "type": "module",
+  "bin": {
+    "creditsync-mcp": "dist/index.js",
+    "creditsync-pro-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^3.24.4"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.3"
+  }
+}

package/src/api-client.ts

@@ -0,0 +1,39 @@
+export class CreditSyncClient {
+  private baseUrl: string;
+  private apiKey: string;
+
+  constructor(apiKey: string, baseUrl = "https://www.creditsync.pro") {
+    this.apiKey = apiKey;
+    this.baseUrl = baseUrl.replace(/\/$/, "");
+  }
+
+  private async request(method: string, path: string, body?: unknown): Promise<unknown> {
+    const url = `${this.baseUrl}${path}`;
+    const res = await fetch(url, {
+      method,
+      headers: {
+        "Authorization": `Bearer ${this.apiKey}`,
+        "Content-Type": "application/json",
+      },
+      ...(body ? { body: JSON.stringify(body) } : {}),
+    });
+
+    const data = await res.json();
+
+    if (!res.ok) {
+      const message = (data as { error?: string }).error ?? `API error: ${res.status}`;
+      throw new Error(message);
+    }
+
+    return data;
+  }
+
+  async get(path: string, params?: Record<string, string>): Promise<unknown> {
+    const query = params ? "?" + new URLSearchParams(params).toString() : "";
+    return this.request("GET", path + query);
+  }
+
+  async patch(path: string, body: unknown): Promise<unknown> {
+    return this.request("PATCH", path, body);
+  }
+}

package/src/index.ts

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { CreditSyncClient } from "./api-client.js";
+
+const apiKey = process.env.CREDITSYNC_API_KEY;
+if (!apiKey) {
+  console.error("CREDITSYNC_API_KEY environment variable is required");
+  process.exit(1);
+}
+
+const baseUrl = process.env.CREDITSYNC_API_URL ?? "https://www.creditsync.pro";
+const client = new CreditSyncClient(apiKey, baseUrl);
+
+const server = new McpServer({
+  name: "creditsync",
+  version: "1.0.0",
+});
+
+// ─── list_benefits ─────────────────────────────────
+
+server.tool(
+  "list_benefits",
+  "List all tracked credit card benefits with current period status, amounts, and expiry dates. Filter by status (unused/partial/used), card nickname, or expiring within N days.",
+  {
+    status: z.enum(["unused", "partial", "used"]).optional().describe("Filter by usage status"),
+    card: z.string().optional().describe("Filter by card nickname (partial match)"),
+    expiring_within_days: z.number().int().positive().optional().describe("Only return benefits expiring within this many days"),
+  },
+  async ({ status, card, expiring_within_days }) => {
+    const params: Record<string, string> = {};
+    if (status) params.status = status;
+    if (card) params.card = card;
+    if (expiring_within_days) params.expiring_within_days = String(expiring_within_days);
+
+    const data = await client.get("/api/v1/benefits", params);
+    return { content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }] };
+  },
+);
+
+// ─── get_benefit ───────────────────────────────────
+
+server.tool(
+  "get_benefit",
+  "Get detailed information about a specific benefit including all historical periods.",
+  {
+    id: z.string().describe("The benefit ID from list_benefits"),
+  },
+  async ({ id }) => {
+    const data = await client.get(`/api/v1/benefits/${id}`);
+    return { content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }] };
+  },
+);
+
+// ─── mark_benefit_used ─────────────────────────────
+
+server.tool(
+  "mark_benefit_used",
+  "Mark a benefit period as used, partially used, or unused. Use the period_id from list_benefits or get_benefit.",
+  {
+    period_id: z.string().describe("The period ID to update"),
+    status: z.enum(["unused", "partial", "used"]).describe("New usage status"),
+    amount_used: z.number().positive().optional().describe("Dollar amount used (required for partial status)"),
+    notes: z.string().optional().describe("Optional note about usage"),
+  },
+  async ({ period_id, status, amount_used, notes }) => {
+    const body: Record<string, unknown> = { usageStatus: status };
+    if (amount_used !== undefined) body.usedAmount = amount_used;
+    if (notes !== undefined) body.notes = notes;
+
+    const data = await client.patch(`/api/v1/benefits/${period_id}/use`, body);
+    return { content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }] };
+  },
+);
+
+// ─── get_dashboard ─────────────────────────────────
+
+server.tool(
+  "get_dashboard",
+  "Get dashboard metrics: benefits expiring in 30 days, captured this month, total available, and net ROI value (captured vs annual fees).",
+  {},
+  async () => {
+    const data = await client.get("/api/v1/dashboard");
+    return { content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }] };
+  },
+);
+
+// ─── list_cards ────────────────────────────────────
+
+server.tool(
+  "list_cards",
+  "List all credit cards with issuer, annual fee, renewal month, owner, and benefit count.",
+  {},
+  async () => {
+    const data = await client.get("/api/v1/cards");
+    return { content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }] };
+  },
+);
+
+// ─── Start server ──────────────────────────────────
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch((err) => {
+  console.error("MCP server error:", err);
+  process.exit(1);
+});

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true
+  },
+  "include": ["src"]
+}